Update @opencensus/web-types with @opencensus/core on commit 27de0b1 (#76)

Author: Cristian González

packages/opencensus-web-types/package.json

@@ -7,7 +7,7 @@
   "scripts": {
     "build": "npm run compile",
     "clean": "rimraf build/*",
-    "copytypes": "node scripts/copy-types.js '36f63e6dee9e6ad9af5ece9c5458b47786d41f06' && npm run fix",
+    "copytypes": "node scripts/copy-types.js '27de0b1e3422df31af936a0dba457728ff4bffc2' && npm run fix",
     "check": "gts check",
     "compile": "tsc -p .",
     "fix": "gts fix",

packages/opencensus-web-types/scripts/copy-types.js

@@ -105,6 +105,8 @@ async function logAndExec(cmd, options) {
 function getPatchedContents(srcFile, contents) {
   contents = updateCopyright(srcFile, contents);
   contents = fixNodeJsEventEmitterType(srcFile, contents);
+  contents = fixStatsImportInternalLibrary(srcFile, contents);
+  contents = fixSemicolonError(srcFile, contents);
   return contents;
 }
 
@@ -146,3 +148,43 @@ function fixNodeJsEventEmitterType(srcFile, contents) {
   contents = lines.join('\n');
   return contents;
 }
+
+/**
+ * Replaces the `cls` import and usage and adds a new type to use instead of that import.
+ * This function might be provisional until @opencensus/core updates with this change.
+ * 
+ */
+function fixStatsImportInternalLibrary(srcFile, contents){
+  if(contents.indexOf('import * as cls from \'../internal/cls\';') === -1){
+    return contents;
+  }
+  
+  console.log(`  Using Fix stats import internal library for: ${srcFile}`);
+  
+  const contentToAdd = [
+    "/** Default type for functions */",
+    "// tslint:disable:no-any",
+    "export type Func<T> = (...args: any[]) => T;",
+    "\n",
+    "/** Main interface for stats. */"
+  ].join('\n');
+
+  contents = contents.replace("import * as cls from '../internal/cls';\n", "");
+  contents = contents.replace('/** Main interface for stats. */', contentToAdd);
+  contents = contents.replace('cls.Func', 'Func');
+  return contents;
+}
+
+/**
+ * Adds a Semicolon in a specific location in order to perform `npm run fix` automatically without errors.
+ * This function might be provisional until @opencensus/core updates with this change.
+ */
+function fixSemicolonError(srcFile, contents){
+  if(contents.indexOf('[pluginName: string]: string\n') === -1){
+    return contents;
+  }
+  
+  console.log(`  Using fix semicolon error for: ${srcFile}`);
+  
+  return contents.replace('[pluginName: string]: string\n', '[pluginName: string]: string;\n');
+}

packages/opencensus-web-types/src/common/types.ts

@@ -17,7 +17,7 @@
 // tslint:disable:no-any
 export type LogFunction = (message: any, ...args: any[]) => void;
 
-/** Defines an logger interface. */
+/** Defines a logger interface. */
 export interface Logger {
   /** Logger verbosity level. If omitted, `debug` level is assumed. */
   level?: string;
@@ -28,7 +28,7 @@ export interface Logger {
   debug: LogFunction;
 }
 
-/** Defines an logger options interface. */
+/** Defines a logger options interface. */
 export interface LoggerOptions {
   level?: string;
 }

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

@@ -39,11 +39,13 @@ export interface StatsEventListener {
    * @param view The registered view
    */
   onRegisterView(view: View): void;
+
   /**
    * Is called whenever a new measurement is recorded.
    * @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[],

packages/opencensus-web-types/src/metrics/export/types.ts

@@ -1,7 +1,7 @@
 /**
  * Copyright 2019, OpenCensus Authors
  *
- * Licensed under the Apache License, Version 2.0 the "License";
+ * 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
  *

packages/opencensus-web-types/src/stats/types.ts

@@ -19,6 +19,10 @@ import { Metric } from '../metrics/export/types';
 import { TagMap } from '../tags/tag-map';
 import { TagKey, TagValue } from '../tags/types';
 
+/** Default type for functions */
+// tslint:disable:no-any
+export type Func<T> = (...args: any[]) => T;
+
 /** Main interface for stats. */
 export interface Stats {
   /**
@@ -29,7 +33,7 @@ export interface Stats {
    * @param tagKeys The view columns (tag keys)
    * @param description The view description
    * @param bucketBoundaries The view bucket boundaries for a distribution
-   * aggregation type
+   *     aggregation type
    */
   createView(
     name: string,
@@ -75,10 +79,17 @@ export interface Stats {
    * Updates all views with the new measurements.
    * @param measurements A list of measurements to record
    * @param tags optional The tags to which the value is applied.
-   *  tags could either be explicitly passed to the method, or implicitly
-   *  read from current execution context.
+   *     tags could either be explicitly passed to the method, or implicitly
+   *     read from current execution context.
+   * @param attachments optional The contextual information associated with an
+   *     example value. The contextual information is represented as key - value
+   *     string pairs.
    */
-  record(measurements: Measurement[], tags?: TagMap): void;
+  record(
+    measurements: Measurement[],
+    tags?: TagMap,
+    attachments?: { [key: string]: string }
+  ): void;
 
   /**
    * Remove all registered Views and exporters from the stats.
@@ -103,6 +114,18 @@ export interface Stats {
    * @param exporter An stats exporter
    */
   unregisterExporter(exporter: StatsEventListener): void;
+
+  /**
+   * 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.
+   */
+  withTagContext<T>(tags: TagMap, fn: Func<T>): T;
+
+  /** Gets the current tag context. */
+  getCurrentTagContext(): TagMap;
 }
 
 /**
@@ -181,7 +204,7 @@ export interface View {
   /**
    * The end time for this view - represents the last time a value was recorded
    */
-  endTime: number;
+  endTime?: number;
   /** true if the view was registered */
   registered: boolean;
   /**
@@ -191,13 +214,20 @@ export interface View {
    * Measurements with measurement type INT64 will have its value truncated.
    * @param measurement The measurement to record
    * @param tags The tags to which the value is applied
+   * @param attachments optional The contextual information associated with an
+   *     example value. THe contextual information is represented as key - value
+   *     string pairs.
    */
-  recordMeasurement(measurement: Measurement, tags: TagMap): void;
+  recordMeasurement(
+    measurement: Measurement,
+    tags: TagMap,
+    attachments?: { [key: string]: string }
+  ): void;
   /**
    * Returns a snapshot of an AggregationData for that tags/labels values.
    * @param tagValues The desired data's tag values.
    */
-  getSnapshot(tagValues: TagValue[]): AggregationData;
+  getSnapshot(tagValues: Array<TagValue | null>): AggregationData;
   /** Gets the view's tag keys */
   getColumns(): TagKey[];
   /** Gets view`s metric */
@@ -220,7 +250,7 @@ export interface AggregationMetadata {
   /** The aggregation type of the aggregation data */
   readonly type: AggregationType;
   /** The tagValues that this AggregationData collects and aggregates */
-  readonly tagValues: TagValue[];
+  readonly tagValues: Array<TagValue | null>;
   /** The latest timestamp a new data point was recorded */
   timestamp: number;
 }
@@ -279,6 +309,25 @@ export interface DistributionData extends AggregationMetadata {
   buckets: Bucket[];
   /** Buckets count */
   bucketCounts?: number[];
+  /** If the distribution does not have a histogram, then omit this field. */
+  exemplars?: StatsExemplar[];
+}
+
+/**
+ * Exemplars are example points that may be used to annotate aggregated
+ * Distribution values. They are metadata that gives information about a
+ * particular value added to a Distribution bucket.
+ */
+export interface StatsExemplar {
+  /**
+   * Value of the exemplar point. It determines which bucket the exemplar
+   * belongs to.
+   */
+  readonly value: number;
+  /** The observation (sampling) time of the above value. */
+  readonly timestamp: number;
+  /** Contextual information about the example value. */
+  readonly attachments: { [key: string]: string };
 }
 
 export type Bucket = number;

packages/opencensus-web-types/src/tags/tag-map.ts

@@ -1,7 +1,7 @@
 /**
  * Copyright 2019, OpenCensus Authors
  *
- * Licensed under the Apache License, Version 2.0 the "License";
+ * 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
  *
@@ -14,33 +14,86 @@
  * 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}`);
     }
-    this.registeredTags.set(tagKey, tagValue);
+    let existingKey;
+    for (const key of this.registeredTags.keys()) {
+      if (key.name === tagKey.name) {
+        existingKey = key;
+        break;
+      }
+    }
+    if (existingKey) this.registeredTags.delete(existingKey);
+    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-web-types/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-web-types/src/tags/validation.ts

@@ -1,7 +1,7 @@
 /**
  * Copyright 2019, OpenCensus Authors
  *
- * Licensed under the Apache License, Version 2.0 the "License";
+ * 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
  *