Exporter/Stackdriver: Support Exemplar in Stackdriver TimeSeries (#520)

* Add Exporter/Stackdriver: Support Exemplar in Stackdriver TimeSeries.

* Add helper function to convert OC attachments to SD

* update CHANGELOG

Author: mayurkale22

CHANGELOG.md

@@ -4,6 +4,8 @@ All notable changes to this project will be documented in this file.
 
 ## Unreleased
 
+- Exporter/Stats/Stackdriver: Add support for exemplar
+
 ## 0.0.13 - 2019-05-20
 - Exporter/Stats/Prometheus: Fix missing tags for HTTP metrics
 - http-instrumentation: add support for the addition of custom attributes to spans

packages/opencensus-exporter-stackdriver/src/stackdriver-monitoring-utils.ts

@@ -14,15 +14,26 @@
  * limitations under the License.
  */
 
-import {BucketOptions, DistributionBucket, DistributionValue, LabelKey, LabelValue, Metric, MetricDescriptor as OCMetricDescriptor, MetricDescriptorType, TimeSeriesPoint, Timestamp} from '@opencensus/core';
+import {BucketOptions, DistributionBucket, DistributionValue, Exemplar as OCExemplar, LabelKey, LabelValue, Metric, MetricDescriptor as OCMetricDescriptor, MetricDescriptorType, TimeSeriesPoint, Timestamp} from '@opencensus/core';
 import * as os from 'os';
 import * as path from 'path';
-import {Distribution, LabelDescriptor, MetricDescriptor, MetricKind, MonitoredResource, Point, TimeSeries, ValueType} from './types';
+import {Any, Distribution, Exemplar, LabelDescriptor, MetricDescriptor, MetricKind, MonitoredResource, Point, TimeSeries, ValueType} from './types';
 
 const OPENCENSUS_TASK = 'opencensus_task';
 const OPENCENSUS_TASK_DESCRIPTION = 'Opencensus task identifier';
 export const OPENCENSUS_TASK_VALUE_DEFAULT = generateDefaultTaskValue();
 
+const EXEMPLAR_ATTACHMENT_TYPE_STRING =
+    'type.googleapis.com/google.protobuf.StringValue';
+// TODO: add support for SpanContext attachment.
+// const EXEMPLAR_ATTACHMENT_TYPE_SPAN_CONTEXT =
+//     'type.googleapis.com/google.monitoring.v3.SpanContext';
+const ATTACHMENT_KEY_SPAN_CONTEXT = 'SpanContext';
+
+// TODO: add support for dropped label attachment.
+// const EXEMPLAR_ATTACHMENT_TYPE_DROPPED_LABELS =
+// 'type.googleapis.com/google.monitoring.v3.DroppedLabels';
+
 /** Converts a OpenCensus MetricDescriptor to a StackDriver MetricDescriptor. */
 export function createMetricDescriptorData(
     metricDescriptor: OCMetricDescriptor, metricPrefix: string,
@@ -189,7 +200,8 @@ function createDistribution(distribution: DistributionValue): Distribution {
       explicitBuckets:
           {bounds: createExplicitBucketOptions(distribution.bucketOptions)}
     },
-    bucketCounts: createBucketCounts(distribution.buckets)
+    bucketCounts: createBucketCounts(distribution.buckets),
+    exemplars: createExemplars(distribution.buckets)
   };
 }
 
@@ -216,6 +228,36 @@ function createBucketCounts(buckets: DistributionBucket[]): number[] {
   return bucketCounts;
 }
 
+/** Converts a OpenCensus Buckets to a list of proto Exemplars. */
+function createExemplars(buckets: DistributionBucket[]): Exemplar[] {
+  return buckets.filter((bucket => !!bucket.exemplar))
+      .map((bucket) => ({
+             value: bucket.exemplar!.value,
+             timestamp: toISOString(bucket.exemplar!.timestamp),
+             attachments: _createAttachments(bucket.exemplar!)
+           }))
+      .filter((exemplar) => exemplar.attachments.length > 0);
+}
+
+function _createAttachments(exemplar: OCExemplar): Any[] {
+  return Object.keys(exemplar.attachments)
+             .map((key) => {
+               if (key === ATTACHMENT_KEY_SPAN_CONTEXT) {
+                 // TODO: add support for SpanContext
+                 // attachment.
+                 return null;
+               } else {
+                 // Everything else will be treated as plain
+                 // strings for now.
+                 return {
+                   '@type': EXEMPLAR_ATTACHMENT_TYPE_STRING,
+                   value: exemplar.attachments[key]
+                 };
+               }
+             })
+             .filter(attachment => !!attachment) as Any[];
+}
+
 /** Returns a task label value in the format of 'nodejs-<pid>@<hostname>'. */
 function generateDefaultTaskValue(): string {
   const pid = process.pid;

packages/opencensus-exporter-stackdriver/src/types.ts

@@ -195,6 +195,7 @@ export interface Distribution {
   sumOfSquaredDeviation: number;
   bucketOptions: {explicitBuckets: {bounds: Bucket[];}};
   bucketCounts: number[];
+  exemplars?: Exemplar[];
 }
 
 export interface Point {
@@ -224,3 +225,32 @@ export interface MonitoredResource {
   /** Set of labels that describe the resource. */
   labels: {[key: string]: string};
 }
+
+/**
+ * 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 Exemplar {
+  /** Value of the exemplar point. */
+  value: number;
+  /** The observation (sampling) time of the above value. */
+  timestamp: string;
+  /** Contextual information about the example value. */
+  attachments: Any[];
+}
+
+/**
+ * `Any` contains an arbitrary serialized protocol buffer message along with a
+ * URL that describes the type of the serialized message.
+ */
+export interface Any {
+  /**
+   * A URL/resource name that uniquely identifies the type of the serialized
+   * protocol buffer message.
+   */
+  '@type': string;
+
+  /** Must be a valid serialized protocol buffer of the above specified type. */
+  value: string;
+}

packages/opencensus-exporter-stackdriver/test/test-stackdriver-monitoring-utils.ts

@@ -157,12 +157,35 @@ describe('Stackdriver Stats Exporter Utils', () => {
   });
 
   describe('createDistribution()', () => {
+    const attachments = {'k1': 'v1'};
+    const spanContext = {
+      traceId: '3ad17e665f514aabb896341f670179ed',
+      spanId: '3aaeb440a89d9e82',
+      options: 0x1
+    };
     const distributionValue: DistributionValue = {
       count: 3,
       sum: 2,
       sumOfSquaredDeviation: 14,
       bucketOptions: {explicit: {bounds: [1.0, 3.0, 5.0]}},
-      buckets: [{count: 3}, {count: 1}, {count: 2}, {count: 4}],
+      buckets: [
+        {
+          count: 3,
+          exemplar: {
+            value: 5,
+            timestamp: {seconds: 1450000000, nanos: 0},
+            attachments
+          }
+        },
+        {count: 1}, {count: 2}, {
+          count: 4,
+          exemplar: {
+            value: 5,
+            timestamp: {seconds: 1450000000, nanos: 0},
+            attachments: {'SpanContext': `'${spanContext}'`}
+          }
+        }
+      ],
     };
     it('should return a Stackdriver Distribution', () => {
       const distribution: Distribution =
@@ -175,6 +198,15 @@ describe('Stackdriver Stats Exporter Utils', () => {
           distribution.bucketOptions,
           {explicitBuckets: {bounds: [0, 1, 3, 5]}});
       assert.deepStrictEqual(distribution.bucketCounts, [0, 3, 1, 2, 4]);
+      assert.deepStrictEqual(
+          distribution.exemplars, [{
+            'attachments': [{
+              '@type': 'type.googleapis.com/google.protobuf.StringValue',
+              'value': 'v1'
+            }],
+            'timestamp': '2015-12-13T09:46:40.Z',
+            'value': 5
+          }]);
     });
   });
 
@@ -290,7 +322,8 @@ describe('Stackdriver Stats Exporter Utils', () => {
             mean: 0.6666666666666666,
             sumOfSquaredDeviation: 14,
             bucketOptions: {explicitBuckets: {bounds: [0, 1.2, 3.2, 5.2]}},
-            bucketCounts: [0, 3, 1, 2, 4]
+            bucketCounts: [0, 3, 1, 2, 4],
+            exemplars: []
           }
         },
         interval: {