Stats: Record against implicit (current) tag context (#418)

* Stats: Record against implicit (current) context

* update index.ts

* Add example, record withTagContext

* Add test on clear

Author: mayurkale22

examples/tags/tag-context-example.js

@@ -0,0 +1,62 @@
+/**
+ * Copyright 2019, OpenCensus Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+const core = require('@opencensus/core');
+
+const K1 = { name: 'k1' };
+const K2 = { name: 'k2' };
+const V1 = { value: 'v1' };
+const V2 = { value: 'v2' };
+
+const mLatencyMs = core.globalStats.createMeasureDouble(
+  'm1', core.MeasureUnit.MS, '1st test metric'
+);
+
+/** Main method. */
+function main () {
+  const tags1 = new core.TagMap();
+  tags1.set(K1, V1);
+
+  core.withTagContext(tags1, () => {
+    console.log('Enter Scope 1');
+    printMap('Add Tags', tags1.tags);
+    printMap('Current Tags == Default + tags1:', core.getCurrentTagContext().tags);
+
+    const tags2 = new core.TagMap();
+    tags2.set(K2, V2);
+    core.withTagContext(tags2, () => {
+      console.log('Enter Scope 2');
+      printMap('Add Tags', tags2.tags);
+      printMap('Current Tags == Default + tags1 + tags2:', core.getCurrentTagContext().tags);
+
+      const measurement = { measure: mLatencyMs, value: 10 };
+      core.globalStats.record([measurement]);
+      console.log('Close Scope 2');
+    });
+    printMap('Current Tags == Default + tags1:', core.getCurrentTagContext().tags);
+    console.log('Close Scope 1');
+  });
+}
+
+function printMap (message, myMap) {
+  var tags = `    ${message}`;
+  for (var [key, value] of myMap) {
+    tags += ` ${key.name} = ${value.value}`;
+  }
+  console.log(tags);
+}
+
+main();

packages/opencensus-core/src/index.ts

@@ -71,6 +71,7 @@ export * from './stats/recorder';
 export * from './stats/bucket-boundaries';
 export * from './stats/metric-utils';
 export * from './tags/tag-map';
+export * from './tags/tagger';
 export * from './resource/resource';
 
 // interfaces

packages/opencensus-core/src/internal/cls-ah.ts

@@ -22,12 +22,15 @@ import {Context, Func, Namespace as CLSNamespace} from 'continuation-local-stora
 import {EventEmitter} from 'events';
 import * as shimmer from 'shimmer';
 
-const wrappedSymbol = Symbol('context_wrapped');
+const WRAPPED = Symbol('context_wrapped');
+/** A map of AsyncResource IDs to Context objects. */
 let contexts: {[asyncId: number]: Context;} = {};
 let current: Context = {};
 
+// Create the hook.
 asyncHook.createHook({init, before, destroy}).enable();
 
+// A list of well-known EventEmitter methods that add event listeners.
 const EVENT_EMITTER_METHODS: Array<keyof EventEmitter> =
     ['addListener', 'on', 'once', 'prependListener', 'prependOnceListener'];
 
@@ -70,7 +73,7 @@ class AsyncHooksNamespace implements CLSNamespace {
     // TODO(kjin): Monitor https://github.com/Microsoft/TypeScript/pull/15473.
     // When it's landed and released, we can remove these `any` casts.
     // tslint:disable-next-line:no-any
-    if ((cb as any)[wrappedSymbol] as boolean || !current) {
+    if ((cb as any)[WRAPPED] as boolean || !current) {
       return cb;
     }
     const boundContext = current;
@@ -82,7 +85,7 @@ class AsyncHooksNamespace implements CLSNamespace {
       return res;
     };
     // tslint:disable-next-line:no-any
-    (contextWrapper as any)[wrappedSymbol] = true;
+    (contextWrapper as any)[WRAPPED] = true;
     Object.defineProperty(contextWrapper, 'length', {
       enumerable: false,
       configurable: true,
@@ -115,17 +118,23 @@ const namespace = new AsyncHooksNamespace();
 
 // AsyncWrap Hooks
 
+/** init is called during object construction. */
 function init(
     uid: number, provider: string, parentUid: number, parentHandle: {}) {
   contexts[uid] = current;
 }
 
+/** before is called just before the resource's callback is called. */
 function before(uid: number) {
   if (contexts[uid]) {
     current = contexts[uid];
   }
 }
 
+/**
+ * destroy is called when the object is no longer used, so also delete
+ * its entry in the map.
+ */
 function destroy(uid: number) {
   delete contexts[uid];
 }

packages/opencensus-core/src/stats/stats.ts

@@ -20,8 +20,8 @@ import {StatsEventListener} from '../exporters/types';
 import {Metric} from '../metrics/export/types';
 import {Metrics} from '../metrics/metrics';
 import {TagMap} from '../tags/tag-map';
+import {getCurrentTagContext} from '../tags/tagger';
 import {TagKey} from '../tags/types';
-
 import {MetricProducerForStats} from './metric-producer';
 import {AggregationType, Measure, Measurement, MeasureType, MeasureUnit, Stats, View} from './types';
 import {BaseView} from './view';
@@ -80,8 +80,8 @@ export class BaseStats implements Stats {
    * @param aggregation The view aggregation type
    * @param tagKeys The view columns (tag keys)
    * @param description The view description
-   * @param bucketBoundaries The view bucket boundaries for a distribution
-   * aggregation type
+   * @param bucketBoundaries optional The view bucket boundaries for a
+   *     distribution aggregation type
    */
   createView(
       name: string, measure: Measure, aggregation: AggregationType,
@@ -188,8 +188,8 @@ export class BaseStats implements Stats {
     }
 
     if (!tags) {
-      // TODO(mayurkale): read tags current execution context
-      tags = new TagMap();
+      // Record against implicit (current) context
+      tags = getCurrentTagContext();
     }
 
     for (const measurement of measurements) {

packages/opencensus-core/src/tags/tag-map.ts

@@ -31,6 +31,14 @@ export class TagMap {
     if (!isValidTagValue(tagValue)) {
       throw new Error(`Invalid TagValue: ${tagValue.value}`);
     }
+    let existingKey;
+    for (const key of this.registeredTags.keys()) {
+      if (key.name === tagKey.name) {
+        existingKey = key;
+        break;
+      }
+    }
+    if (existingKey) this.registeredTags.delete(existingKey);
     this.registeredTags.set(tagKey, tagValue);
   }
 

packages/opencensus-core/src/tags/tagger.ts

@@ -0,0 +1,66 @@
+/**
+ * Copyright 2019, OpenCensus Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import * as cls from '../internal/cls';
+import {TagMap} from './tag-map';
+
+const contextManager = cls.createNamespace();
+export const EMPTY_TAG_MAP = new TagMap();
+const CURRENT_TAG_MAP_KEY = 'current_tag_map';
+
+/** Gets the current tag context. */
+export function getCurrentTagContext(): TagMap {
+  const tagsFromContext = contextManager.get(CURRENT_TAG_MAP_KEY);
+  if (tagsFromContext) {
+    return tagsFromContext as TagMap;
+  }
+  return EMPTY_TAG_MAP;
+}
+
+/**
+ * Sets the current tag context.
+ * @param tags The TagMap.
+ */
+export function setCurrentTagContext(tags: TagMap) {
+  contextManager.set(CURRENT_TAG_MAP_KEY, tags);
+}
+
+/**
+ * Enters the scope of code where the given `TagMap` is in the current context
+ * (replacing the previous `TagMap`).
+ * @param tags The TagMap to be set to the current context.
+ * @param fn Callback function.
+ * @returns The callback return.
+ */
+export function withTagContext<T>(tags: TagMap, fn: cls.Func<T>): T {
+  const oldContext = getCurrentTagContext();
+  return contextManager.runAndReturn(() => {
+    const newContext = new TagMap();
+    for (const [tagKey, tagValue] of oldContext.tags) {
+      newContext.set(tagKey, tagValue);
+    }
+    for (const [tagKey, tagValue] of tags.tags) {
+      newContext.set(tagKey, tagValue);
+    }
+    setCurrentTagContext(newContext);
+    return fn();
+  });
+}
+
+/** Clear the current tag context. */
+export function clear() {
+  contextManager.set(CURRENT_TAG_MAP_KEY, EMPTY_TAG_MAP);
+}

packages/opencensus-core/test/test-stats.ts

@@ -17,6 +17,7 @@
 import * as assert from 'assert';
 import {BaseView, globalStats, StatsEventListener, TagKey, TagMap, TagValue} from '../src';
 import {AggregationType, LastValueData, Measure, Measurement, MeasureType, MeasureUnit, View} from '../src/stats/types';
+import * as tagger from '../src/tags/tagger';
 
 class TestExporter implements StatsEventListener {
   registeredViews: View[] = [];
@@ -225,5 +226,40 @@ describe('Stats', () => {
          globalStats.record(measurments, tagMap);
          assert.equal(testExporter.recordedMeasurements.length, 0);
        });
+
+    it('should record against implicit context when set', () => {
+      const tags = new TagMap();
+      tags.set(tagKeys[0], {value: 'value1'});
+      tags.set(tagKeys[1], {value: 'value2'});
+      const measurement = {measure, value: 1};
+      tagger.withTagContext(tags, () => {
+        globalStats.record([measurement]);
+      });
+
+      assert.strictEqual(testExporter.recordedMeasurements.length, 1);
+      assert.deepEqual(testExporter.recordedMeasurements[0], measurement);
+      aggregationData =
+          testExporter.registeredViews[0].getSnapshot(
+              [{value: 'value1'}, {value: 'value2'}]) as LastValueData;
+      assert.strictEqual(aggregationData.value, measurement.value);
+      assert.deepStrictEqual(
+          aggregationData.tagValues, [{value: 'value1'}, {value: 'value2'}]);
+    });
+
+    it('should record against implicit context when not set or empty', () => {
+      const UNKNOWN_TAG_VALUE: TagValue = null;
+      globalStats.registerExporter(testExporter);
+      const measurement = {measure, value: 2211};
+      tagger.withTagContext(tagger.EMPTY_TAG_MAP, () => {
+        globalStats.record([measurement]);
+      });
+
+      aggregationData =
+          testExporter.registeredViews[0].getSnapshot(
+              [UNKNOWN_TAG_VALUE, UNKNOWN_TAG_VALUE]) as LastValueData;
+      assert.strictEqual(aggregationData.value, measurement.value);
+      assert.deepStrictEqual(
+          aggregationData.tagValues, [UNKNOWN_TAG_VALUE, UNKNOWN_TAG_VALUE]);
+    });
   });
 });