[Event Hubs] add tracing support when sending events

sdk/core/core-tracing/api-extractor.json

@@ -1,32 +1,31 @@
 {
-    "$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
-    "mainEntryPointFilePath": "types/index.d.ts",
-    "docModel": {
-      "enabled": false
-    },
-    "apiReport": {
-      "enabled": true,
-      "reportFolder": "./review"
-    },
-    "dtsRollup": {
-      "enabled": true,
-      "untrimmedFilePath": "",
-      "publicTrimmedFilePath": "./types/core-tracing.d.ts"
+  "$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
+  "mainEntryPointFilePath": "types/lib/index.d.ts",
+  "docModel": {
+    "enabled": false
+  },
+  "apiReport": {
+    "enabled": true,
+    "reportFolder": "./review"
+  },
+  "dtsRollup": {
+    "enabled": true,
+    "untrimmedFilePath": "",
+    "publicTrimmedFilePath": "./types/core-tracing.d.ts"
+  },
+  "messages": {
+    "tsdocMessageReporting": {
+      "default": {
+        "logLevel": "none"
+      }
     },
-    "messages": {
-      "tsdocMessageReporting": {
-        "default": {
-          "logLevel": "none"
-        }
+    "extractorMessageReporting": {
+      "ae-missing-release-tag": {
+        "logLevel": "none"
       },
-      "extractorMessageReporting": {
-        "ae-missing-release-tag": {
-          "logLevel": "none"
-        },
-        "ae-unresolved-link": {
-          "logLevel": "none"
-        }
+      "ae-unresolved-link": {
+        "logLevel": "none"
       }
     }
   }
-  
+}

sdk/core/core-tracing/lib/index.ts

@@ -30,6 +30,12 @@ export { TraceFlags } from "./interfaces/trace_flags";
 export { TraceState } from "./interfaces/trace_state";
 export { Tracer } from "./interfaces/tracer";
 
+// Utilities
+export {
+  extractSpanContextFromTraceParentHeader,
+  getTraceParentHeader
+} from "./utils/traceParentHeader";
+
 // OpenCensus Interfaces
 export {
   Tracer as OpenCensusTracer,

sdk/core/core-tracing/lib/tracers/opencensus/openCensusSpanWrapper.ts

@@ -7,7 +7,7 @@ import { Status } from "../../interfaces/status";
 import { OpenCensusTraceStateWrapper } from "./openCensusTraceStateWrapper";
 import { SpanOptions } from "../../interfaces/SpanOptions";
 import { OpenCensusTracerWrapper } from "./openCensusTracerWrapper";
-import { Attributes as OpenCensusAttributes, Span as OpenCensusSpan, LinkType } from "@opencensus/web-types";
+import { Attributes as OpenCensusAttributes, Span as OpenCensusSpan } from "@opencensus/web-types";
 
 function isWrappedSpan(span?: Span | SpanContext): span is OpenCensusSpanWrapper {
   return !!span && (span as OpenCensusSpanWrapper).getWrappedSpan !== undefined;
@@ -101,7 +101,12 @@ export class OpenCensusSpanWrapper implements Span {
   addLink(spanContext: SpanContext, attributes?: Attributes): this {
     // Since there is no way to specify the link relationship,
     // it is set as Unspecified.
-    this._span.addLink(spanContext.traceId, spanContext.spanId, 0 /* LinkType.UNSPECIFIED */, attributes as OpenCensusAttributes);
+    this._span.addLink(
+      spanContext.traceId,
+      spanContext.spanId,
+      0 /* LinkType.UNSPECIFIED */,
+      attributes as OpenCensusAttributes
+    );
     return this;
   }
 

sdk/core/core-tracing/lib/utils/log.ts

@@ -0,0 +1,28 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+import debug from "debug";
+
+/**
+ * @ignore
+ * Log statements for errors that the application is unlikely to recover from.
+ */
+export const error = debug("azure:core-tracing:error");
+
+/**
+ * @ignore
+ * Log statements for warnings when a function fails to perform its intended task.
+ */
+export const warning = debug("azure:core-tracing:warning");
+
+/**
+ * @ignore
+ * Log statements for info when a function operates normally.
+ */
+export const info = debug("azure:core-tracing:info");
+
+/**
+ * @ignore
+ * Log statements for verbose for troubleshooting scenarios.
+ */
+export const verbose = debug("azure:core-tracing:verbose");

sdk/core/core-tracing/lib/utils/traceParentHeader.ts

@@ -0,0 +1,68 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+import { SpanContext } from "../interfaces/span_context";
+import { TraceFlags } from "../interfaces/trace_flags";
+import * as log from "./log";
+
+const VERSION = "00";
+
+/**
+ * Generates a `SpanContext` given a `traceparent` header value.
+ * @param traceParent Serialized span context data as a `traceparent` header value.
+ * @returns The `SpanContext` generated from the `traceparent` value.
+ */
+export function extractSpanContextFromTraceParentHeader(
+  traceParentHeader: string
+): SpanContext | undefined {
+  const parts = traceParentHeader.split("-");
+
+  if (parts.length !== 4) {
+    log.warning(`Unable to extract span context from traceparent header "${traceParentHeader}".`);
+    return;
+  }
+
+  const [version, traceId, spanId, traceOptions] = parts;
+
+  if (version !== VERSION) {
+    log.warning(`Unexpected traceparent header version "${version}" found, expected "${VERSION}".`);
+    return;
+  }
+
+  const traceFlags = parseInt(traceOptions, 16);
+
+  const spanContext: SpanContext = {
+    spanId,
+    traceId,
+    traceFlags
+  };
+
+  return spanContext;
+}
+
+/**
+ * Generates a `traceparent` value given a span context.
+ * @param spanContext Contains context for a specific span.
+ * @returns The `spanContext` represented as a `traceparent` value.
+ */
+export function getTraceParentHeader(spanContext: SpanContext): string | undefined {
+  const missingFields: string[] = [];
+  if (!spanContext.traceId) {
+    missingFields.push("traceId");
+  }
+  if (!spanContext.spanId) {
+    missingFields.push("spanId");
+  }
+
+  if (missingFields.length) {
+    log.warning(`Missing required field(s) ${missingFields.join(", ")} from spanContext`);
+    return;
+  }
+
+  const flags = spanContext.traceFlags || TraceFlags.UNSAMPLED;
+  const hexFlags = flags.toString(16);
+  const traceFlags = hexFlags.length === 1 ? `0${hexFlags}` : hexFlags;
+
+  // https://www.w3.org/TR/trace-context/#traceparent-header-field-values
+  return `${VERSION}-${spanContext.traceId}-${spanContext.spanId}-${traceFlags}`;
+}

sdk/core/core-tracing/package.json

@@ -4,7 +4,7 @@
   "description": "Provides low-level interfaces and helper methods for tracing in Azure SDK",
   "sdk-type": "client",
   "main": "dist/index.js",
-  "module": "dist-esm/index.js",
+  "module": "dist-esm/lib/index.js",
   "browser": {
     "./dist/index.js": "./browser/index.js"
   },
@@ -37,7 +37,7 @@
   "files": [
     "browser/*.js*",
     "dist/",
-    "dist-esm/",
+    "dist-esm/lib/",
     "src/",
     "types/core-tracing.d.ts",
     "ThirdPartyNotices.txt"
@@ -59,11 +59,13 @@
   "sideEffects": false,
   "dependencies": {
     "@opencensus/web-types": "0.0.7",
+    "debug": "^4.1.1",
     "tslib": "^1.9.3"
   },
   "devDependencies": {
     "@azure/eslint-plugin-azure-sdk": "^2.0.1",
     "@microsoft/api-extractor": "^7.1.5",
+    "@types/debug": "^4.1.4",
     "@types/mocha": "^5.2.5",
     "@types/node": "^8.0.0",
     "@typescript-eslint/eslint-plugin": "^2.0.0",

sdk/core/core-tracing/review/core-tracing.api.md

@@ -45,6 +45,12 @@ export interface Event {
     name: string;
 }
 
+// @public
+export function extractSpanContextFromTraceParentHeader(traceParentHeader: string): SpanContext | undefined;
+
+// @public
+export function getTraceParentHeader(spanContext: SpanContext): string | undefined;
+
 // @public
 export function getTracer(): Tracer;
 

sdk/core/core-tracing/rollup.base.config.js

@@ -8,7 +8,7 @@ import viz from "rollup-plugin-visualizer";
 
 const pkg = require("./package.json");
 const depNames = Object.keys(pkg.dependencies);
-const input = "dist-esm/index.js";
+const input = "dist-esm/lib/index.js";
 const production = process.env.NODE_ENV === "production";
 
 export function nodeConfig(test = false) {

sdk/core/core-tracing/test/traceParentHeader.spec.ts

@@ -0,0 +1,128 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+import * as assert from "assert";
+import {
+  extractSpanContextFromTraceParentHeader,
+  TraceFlags,
+  SpanContext,
+  getTraceParentHeader
+} from "../lib";
+
+describe("traceParentHeader", () => {
+  describe("#extractSpanContextFromTraceParentHeader", () => {
+    it("should extract a SpanContext from a properly formatted traceparent", () => {
+      const traceId = "11111111111111111111111111111111";
+      const spanId = "2222222222222222";
+      const flags = "00";
+      const traceParentHeader = `00-${traceId}-${spanId}-${flags}`;
+
+      const spanContext = extractSpanContextFromTraceParentHeader(traceParentHeader);
+      if (!spanContext) {
+        assert.fail("Extracted spanContext should be defined.");
+        return;
+      }
+      assert.equal(spanContext.traceId, traceId, "Extracted traceId does not match expectation.");
+      assert.equal(spanContext.spanId, spanId, "Extracted spanId does not match expectation.");
+      assert.equal(
+        spanContext.traceFlags,
+        TraceFlags.UNSAMPLED,
+        "Extracted traceFlags do not match expectations."
+      );
+    });
+
+    describe("should return undefined", () => {
+      it("when traceparent contains an unknown version", () => {
+        const traceId = "11111111111111111111111111111111";
+        const spanId = "2222222222222222";
+        const flags = "00";
+        const traceParentHeader = `99-${traceId}-${spanId}-${flags}`;
+
+        const spanContext = extractSpanContextFromTraceParentHeader(traceParentHeader);
+
+        assert.strictEqual(
+          spanContext,
+          undefined,
+          "Invalid traceparent version should return undefined spanContext."
+        );
+      });
+
+      it("when traceparent is malformed", () => {
+        const traceParentHeader = `123abc`;
+
+        const spanContext = extractSpanContextFromTraceParentHeader(traceParentHeader);
+
+        assert.strictEqual(
+          spanContext,
+          undefined,
+          "Malformed traceparent should return undefined spanContext."
+        );
+      });
+    });
+  });
+
+  describe("#getTraceParentHeader", () => {
+    it("should return a traceparent header from a SpanContext", () => {
+      const spanContext: SpanContext = {
+        spanId: "2222222222222222",
+        traceId: "11111111111111111111111111111111",
+        traceFlags: TraceFlags.SAMPLED
+      };
+
+      const traceParentHeader = getTraceParentHeader(spanContext);
+
+      assert.strictEqual(
+        traceParentHeader,
+        `00-${spanContext.traceId}-${spanContext.spanId}-01`,
+        "TraceParentHeader does not match expectation."
+      );
+    });
+
+    it("should set the traceFlag to UNSAMPLED if not provided in SpanContext", () => {
+      const spanContext: SpanContext = {
+        spanId: "2222222222222222",
+        traceId: "11111111111111111111111111111111"
+      };
+
+      const traceParentHeader = getTraceParentHeader(spanContext);
+
+      assert.strictEqual(
+        traceParentHeader,
+        `00-${spanContext.traceId}-${spanContext.spanId}-00`,
+        "TraceParentHeader does not match expectation."
+      );
+    });
+
+    describe("should return undefined", () => {
+      it("when traceId is not defined", () => {
+        const spanContext: any = {
+          spanId: "2222222222222222",
+          traceFlags: TraceFlags.SAMPLED
+        };
+
+        const traceParentHeader = getTraceParentHeader(spanContext);
+
+        assert.strictEqual(
+          traceParentHeader,
+          undefined,
+          "Missing traceId should return undefined spanContext."
+        );
+      });
+
+      it("when spanId is not defined", () => {
+        const spanContext: any = {
+          traceId: "11111111111111111111111111111111",
+          traceFlags: TraceFlags.SAMPLED
+        };
+
+        const traceParentHeader = getTraceParentHeader(spanContext);
+
+        assert.strictEqual(
+          traceParentHeader,
+          undefined,
+          "Missing spanId should return undefined spanContext."
+        );
+      });
+    });
+  });
+});

sdk/eventhub/event-hubs/package.json

@@ -65,6 +65,7 @@
     "@azure/abort-controller": "1.0.0-preview.2",
     "@azure/core-amqp": "1.0.0-preview.4",
     "@azure/core-asynciterator-polyfill": "1.0.0-preview.1",
+    "@azure/core-tracing": "1.0.0-preview.3",
     "async-lock": "^1.1.3",
     "buffer": "^5.2.1",
     "debug": "^4.1.1",