Tags: Add support for TagMetadata (#424)

* Tags: Add TagMetadata

* fix review comments

Author: mayurkale22

CHANGELOG.md

@@ -21,6 +21,7 @@ All notable changes to this project will be documented in this file.
 - Add support for overriding sampling for a span.
 - Enforce `--strictNullChecks` and `--noUnusedLocals` Compiler Options on [opencensus-exporter-jaeger] packages.
 - Add support for recording Exemplars.
+- Add `TagMetadata` that defines the properties associated with a `Tag`.
 
 ## 0.0.9 - 2019-02-12
 - Add Metrics API.

packages/opencensus-core/src/exporters/console-exporter.ts

@@ -93,6 +93,7 @@ export class ConsoleStatsExporter implements types.StatsEventListener {
    * Event called when a measurement is recorded
    * @param view recorded view from measurement
    * @param measurement recorded measurement
+   * @param tags The tags to which the value is applied
    */
   onRecord(
       views: View[], measurement: Measurement, tags: Map<TagKey, TagValue>) {

packages/opencensus-core/src/exporters/types.ts

@@ -44,6 +44,7 @@ export interface StatsEventListener {
    * @deprecated since version 0.0.9 - use {@link start} instead
    * @param views The views related to the measurement
    * @param measurement The recorded measurement
+   * @param tags The tags to which the value is applied
    */
   onRecord(
       views: View[], measurement: Measurement,

packages/opencensus-core/src/index.ts

@@ -76,7 +76,7 @@ export * from './resource/resource';
 
 // interfaces
 export * from './stats/types';
-export * from './tags/types';
+export {TagKey, TagValue, TagMetadata, TagTtl} from './tags/types';
 export * from './resource/types';
 
 // logger

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

@@ -14,20 +14,29 @@
  * limitations under the License.
  */
 
-import {TagKey, TagValue} from './types';
+import {TagKey, TagMetadata, TagTtl, TagValue, TagValueWithMetadata} from './types';
 import {isValidTagKey, isValidTagValue} from './validation';
 
-/** TagMap is maps of TagKey -> TagValue */
+const UNLIMITED_PROPAGATION_MD = {
+  tagTtl: TagTtl.UNLIMITED_PROPAGATION
+};
+
+/** TagMap is maps of TagKey -> TagValueWithMetadata */
 export class TagMap {
-  // A map mapping TagKey to to its respective TagValue.
-  private readonly registeredTags: Map<TagKey, TagValue> = new Map();
+  // A map mapping TagKey to to its respective TagValueWithMetadata.
+  private readonly registeredTags: Map<TagKey, TagValueWithMetadata> =
+      new Map();
 
-  /** Adds the key/value pair regardless of whether the key is present. */
-  set(tagKey: TagKey, tagValue: TagValue): void {
+  /**
+   * Adds the key/value pair regardless of whether the key is present.
+   * @param tagKey The TagKey which will be set.
+   * @param tagValue The TagValue to set for the given key.
+   * @param tagMetadata The TagMetadata associated with this Tag.
+   */
+  set(tagKey: TagKey, tagValue: TagValue, tagMetadata?: TagMetadata): void {
     if (!isValidTagKey(tagKey)) {
       throw new Error(`Invalid TagKey name: ${tagKey.name}`);
     }
-
     if (!isValidTagValue(tagValue)) {
       throw new Error(`Invalid TagValue: ${tagValue.value}`);
     }
@@ -39,16 +48,42 @@ export class TagMap {
       }
     }
     if (existingKey) this.registeredTags.delete(existingKey);
-    this.registeredTags.set(tagKey, tagValue);
+    const valueWithMetadata = this.getValueWithMetadata(tagValue, tagMetadata);
+    this.registeredTags.set(tagKey, valueWithMetadata);
   }
 
-  /** Deletes a tag from the map if the key is in the map. */
+  /**
+   * Deletes a tag from the map if the key is in the map.
+   * @param tagKey The TagKey which will be removed.
+   */
   delete(tagKey: TagKey): void {
     this.registeredTags.delete(tagKey);
   }
 
-  /** Gets the tags map. */
+  /** Gets the tags map without metadata. */
   get tags() {
+    const tagsWithoutMetadata: Map<TagKey, TagValue> = new Map();
+    for (const [tagKey, valueWithMetadata] of this.registeredTags) {
+      tagsWithoutMetadata.set(tagKey, valueWithMetadata.tagValue);
+    }
+    return tagsWithoutMetadata;
+  }
+
+  /** Gets the tags map with metadata. */
+  get tagsWithMetadata() {
     return this.registeredTags;
   }
+
+  /**
+   * Constructs a new TagValueWithMetadata using tagValue and tagMetadata.
+   * For backwards-compatibility this method still produces propagating Tags
+   * (UNLIMITED_PROPAGATION) if tagMetadata is not provided or missing.
+   */
+  private getValueWithMetadata(tagValue: TagValue, tagMetadata?: TagMetadata):
+      TagValueWithMetadata {
+    if (tagMetadata) {
+      return {tagValue, tagMetadata};
+    }
+    return {tagValue, tagMetadata: UNLIMITED_PROPAGATION_MD};
+  }
 }

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

@@ -25,3 +25,38 @@ export interface TagValue {
   /** The value of a tag. */
   readonly value: string;
 }
+
+/** TagValueWithMetadata holds a TagValue and a TagMetadata. */
+export interface TagValueWithMetadata {
+  /** The tag value */
+  readonly tagValue: TagValue;
+  /** The metadata for the tag */
+  readonly tagMetadata: TagMetadata;
+}
+
+/**
+ * TagMetadata contains properties associated with a Tag.
+ * Anytime a sender serializes a tag, sends it over the wire and receiver
+ * deserializes the tag then the tag is considered to have travelled one hop.
+ * There could be one or more proxy(ies) between sender and receiver. Proxies
+ * are treated as transparent entities and they do not create additional hops.
+ */
+export interface TagMetadata {
+  /**
+   * For now, only special values of TagTtl are supported. In future,
+   * additional properties may be added to address specific situations.
+   */
+  readonly tagTtl: number;
+}
+
+/** TagTtl is an integer that represents number of hops a tag can propagate */
+export enum TagTtl {
+  /**
+   * NO_PROPAGATION is considered to have local scope and is used within the
+   * process it created.
+   */
+  NO_PROPAGATION = 0,
+
+  /** UNLIMITED_PROPAGATION can propagate unlimited hops. */
+  UNLIMITED_PROPAGATION = -1
+}

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

@@ -15,7 +15,7 @@
  */
 
 import * as assert from 'assert';
-import {Recorder, TagMap} from '../src';
+import {Recorder, TagMap, TagTtl} from '../src';
 import {AggregationType, CountData, DistributionData, LastValueData, Measure, Measurement, MeasureType, MeasureUnit, SumData} from '../src/stats/types';
 
 /** The order of how close values must be to be considerated almost equal */
@@ -218,6 +218,8 @@ describe('Recorder', () => {
       const CALLER_V = {value: 'some caller'};
       const METHOD_V = {value: 'some method'};
       const ORIGINATOR_V = {value: 'some originator'};
+      const NO_PROPAGATION_MD = {tagTtl: TagTtl.NO_PROPAGATION};
+      const UNLIMITED_PROPAGATION_MD = {tagTtl: TagTtl.UNLIMITED_PROPAGATION};
       let tagMap: TagMap;
 
       beforeEach(() => {
@@ -233,6 +235,16 @@ describe('Recorder', () => {
         assert.deepStrictEqual(tagValues, [CALLER_V, METHOD_V]);
       });
 
+      it('should return tag values from tags and columns when using metadata',
+         () => {
+           const columns = [CALLER, METHOD];
+           tagMap.set(CALLER, CALLER_V, NO_PROPAGATION_MD);
+           tagMap.set(METHOD, METHOD_V, UNLIMITED_PROPAGATION_MD);
+           const tagValues = Recorder.getTagValues(tagMap.tags, columns);
+           assert.equal(tagValues.length, 2);
+           assert.deepStrictEqual(tagValues, [CALLER_V, METHOD_V]);
+         });
+
       it('should return tag values from tags and columns with extra keys',
          () => {
            const columns = [CALLER, METHOD, ORIGINATOR];

packages/opencensus-core/test/test-tag-map.ts

@@ -16,6 +16,7 @@
 
 import * as assert from 'assert';
 import {TagMap} from '../src/tags/tag-map';
+import {TagTtl} from '../src/tags/types';
 
 describe('TagMap()', () => {
   let tagMap: TagMap;
@@ -25,19 +26,56 @@ describe('TagMap()', () => {
   const value1 = {value: 'value1'};
   const value2 = {value: 'value2'};
   const invalidValue1 = {value: 'a'.repeat(256)};
+  const NO_PROPAGATION_MD = {tagTtl: TagTtl.NO_PROPAGATION};
+  const UNLIMITED_PROPAGATION_MD = {tagTtl: TagTtl.UNLIMITED_PROPAGATION};
+
+  const expectedTagValueWithMetadata1 = {
+    tagValue: {value: 'value1'},
+    tagMetadata: {tagTtl: -1}
+  };
+
+  const expectedTagValueWithMetadata2 = {
+    tagValue: {value: 'value2'},
+    tagMetadata: {tagTtl: -1}
+  };
 
   beforeEach(() => {
     tagMap = new TagMap();
   });
 
   describe('set()', () => {
-    it('should set tagkey and tagvalue', () => {
+    it('should set tagkey and tagvalue with default TagMetadata', () => {
       tagMap.set(key1, value1);
-      const tags = tagMap.tags;
+      const tags = tagMap.tagsWithMetadata;
+      assert.equal(tags.size, 1);
+      assert.deepStrictEqual(tags.get(key1), expectedTagValueWithMetadata1);
+    });
+
+    it('should set tagkey and tagvalue with NO_PROPAGATION TagTtl', () => {
+      const expectedTagValueWithMetadata = {
+        tagValue: {value: 'value1'},
+        tagMetadata: {tagTtl: 0}
+      };
+
+      tagMap.set(key1, value1, NO_PROPAGATION_MD);
+      const tags = tagMap.tagsWithMetadata;
       assert.equal(tags.size, 1);
-      assert.deepStrictEqual(tags.get(key1), value1);
+      assert.deepStrictEqual(tags.get(key1), expectedTagValueWithMetadata);
     });
 
+    it('should set tagkey and tagvalue with UNLIMITED_PROPAGATION TagTtl',
+       () => {
+         const expectedTagValueWithMetadata = {
+           tagValue: {value: 'value1'},
+           tagMetadata: {tagTtl: -1}
+         };
+
+         tagMap.set(key1, value1, UNLIMITED_PROPAGATION_MD);
+         const tags = tagMap.tagsWithMetadata;
+         assert.equal(tags.size, 1);
+         assert.deepStrictEqual(tags.get(key1), expectedTagValueWithMetadata);
+       });
+
     it('should throw an error when invalid tagKey', () => {
       assert.throws(() => {
         tagMap.set(invalidKey1, value1);
@@ -52,34 +90,34 @@ describe('TagMap()', () => {
 
     it('should not set duplicate tagkey and tagvalue', () => {
       tagMap.set(key1, value1);
-      const tags = tagMap.tags;
+      const tags = tagMap.tagsWithMetadata;
       assert.equal(tags.size, 1);
-      assert.deepStrictEqual(tags.get(key1), value1);
+      assert.deepStrictEqual(tags.get(key1), expectedTagValueWithMetadata1);
       tagMap.set(key1, value1);
       assert.equal(tags.size, 1);
     });
 
     it('should update existing tagkey', () => {
       tagMap.set(key1, value1);
-      const tags = tagMap.tags;
+      const tags = tagMap.tagsWithMetadata;
       assert.equal(tags.size, 1);
-      assert.deepStrictEqual(tags.get(key1), value1);
+      assert.deepStrictEqual(tags.get(key1), expectedTagValueWithMetadata1);
       tagMap.set(key1, value2);
       assert.equal(tags.size, 1);
-      assert.deepStrictEqual(tags.get(key1), value2);
+      assert.deepStrictEqual(tags.get(key1), expectedTagValueWithMetadata2);
     });
   });
   describe('delete()', () => {
     it('should delete tagkey', () => {
       tagMap.set(key1, value1);
-      const tags = tagMap.tags;
+      const tags = tagMap.tagsWithMetadata;
       assert.equal(tags.size, 1);
       tagMap.delete(key1);
       assert.equal(tags.size, 0);
     });
     it('should delete missing tagkey1', () => {
       tagMap.set(key1, value1);
-      const tags = tagMap.tags;
+      const tags = tagMap.tagsWithMetadata;
       assert.equal(tags.size, 1);
       tagMap.delete(key2);
       assert.equal(tags.size, 1);

packages/opencensus-instrumentation-grpc/src/grpc.ts

@@ -14,7 +14,7 @@
  * limitations under the License.
  */
 
-import {BasePlugin, CanonicalCode, PluginInternalFiles, RootSpan, Span, SpanContext, SpanKind, TagMap, TraceOptions} from '@opencensus/core';
+import {BasePlugin, CanonicalCode, PluginInternalFiles, RootSpan, Span, SpanContext, SpanKind, TagMap, TagTtl, TraceOptions} from '@opencensus/core';
 import {deserializeSpanContext, serializeSpanContext} from '@opencensus/propagation-binaryformat';
 import {EventEmitter} from 'events';
 import * as grpcTypes from 'grpc';
@@ -72,18 +72,19 @@ let Metadata: any;
 // tslint:disable-next-line:no-any
 let GrpcClientModule: any;
 
+const UNLIMITED_PROPAGATION_MD = {
+  tagTtl: TagTtl.UNLIMITED_PROPAGATION
+};
+
 /** gRPC instrumentation plugin for Opencensus */
 export class GrpcPlugin extends BasePlugin {
-  /**
-   * Span grpc attributes
-   */
+  /** Span grpc attributes */
   static readonly ATTRIBUTE_GRPC_KIND = 'grpc.kind';  // SERVER or CLIENT
   static readonly ATTRIBUTE_GRPC_METHOD = 'grpc.method';
   static readonly ATTRIBUTE_GRPC_STATUS_CODE = 'grpc.status_code';
   static readonly ATTRIBUTE_GRPC_ERROR_NAME = 'grpc.error_name';
   static readonly ATTRIBUTE_GRPC_ERROR_MESSAGE = 'grpc.error_message';
 
-
   protected readonly internalFileList: PluginInternalFiles = {
     '0.13 - 1.6': {
       'client': 'src/node/src/client.js',
@@ -92,15 +93,12 @@ export class GrpcPlugin extends BasePlugin {
     '^1.7': {'client': 'src/client.js', 'metadata': 'src/metadata.js'}
   };
 
-
   /** Constructs a new GrpcPlugin instance. */
   constructor() {
     super('grpc');
   }
 
-  /**
-   * Patches gRPC incoming and outcoming request functions.
-   */
+  /** Patches gRPC incoming and outcoming request functions. */
   protected applyPatch() {
     this.logger.debug('applying patch to %s@%s', this.moduleName, this.version);
 
@@ -138,7 +136,7 @@ export class GrpcPlugin extends BasePlugin {
   private getPatchServer() {
     return (originalRegister: RegisterMethod) => {
       const plugin = this;
-      plugin.logger.debug('pathcServer');
+      plugin.logger.debug('patched server');
       return function register<RequestType, ResponseType>(
           // tslint:disable-next-line:no-any
           this: grpcTypes.Server&{handlers: any}, name: string,
@@ -232,7 +230,9 @@ export class GrpcPlugin extends BasePlugin {
 
       // record stats
       const tags = new TagMap();
-      tags.set(serverStats.GRPC_SERVER_METHOD, {value: rootSpan.name});
+      tags.set(
+          serverStats.GRPC_SERVER_METHOD, {value: rootSpan.name},
+          UNLIMITED_PROPAGATION_MD);
       const req = call.hasOwnProperty('request') ? call.request : {};
       GrpcPlugin.recordStats(
           rootSpan.kind, tags, value, req, Date.now() - startTime);
@@ -377,7 +377,9 @@ export class GrpcPlugin extends BasePlugin {
 
         // record stats
         const tags = new TagMap();
-        tags.set(clientStats.GRPC_CLIENT_METHOD, {value: span.name});
+        tags.set(
+            clientStats.GRPC_CLIENT_METHOD, {value: span.name},
+            UNLIMITED_PROPAGATION_MD);
         GrpcPlugin.recordStats(
             span.kind, tags, originalArgs, res, Date.now() - startTime);