feat: Add B3format propagator (#208)

* feat: add b3 format implementation

* fix: add tests

* fix: review comments and add more tests

* fix: omit SAMPLED header if sampling decision is absent

packages/opentelemetry-core/src/context/propagation/B3Format.ts

@@ -0,0 +1,90 @@
+/**
+ * Copyright 2019, OpenTelemetry 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
+ *
+ *      https://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 {
+  SpanContext,
+  HttpTextFormat,
+  TraceOptions,
+} from '@opentelemetry/types';
+
+export const X_B3_TRACE_ID = 'x-b3-traceid';
+export const X_B3_SPAN_ID = 'x-b3-spanid';
+export const X_B3_SAMPLED = 'x-b3-sampled';
+const VALID_TRACEID_REGEX = /^[0-9a-f]{32}$/i;
+const VALID_SPANID_REGEX = /^[0-9a-f]{16}$/i;
+const INVALID_ID_REGEX = /^0+$/i;
+
+function isValidTraceId(traceId: string): boolean {
+  return VALID_TRACEID_REGEX.test(traceId) && !INVALID_ID_REGEX.test(traceId);
+}
+
+function isValidSpanId(spanId: string): boolean {
+  return VALID_SPANID_REGEX.test(spanId) && !INVALID_ID_REGEX.test(spanId);
+}
+
+/**
+ * Propagator for the B3 HTTP header format.
+ * Based on: https://github.com/openzipkin/b3-propagation
+ */
+export class B3Format implements HttpTextFormat {
+  inject(
+    spanContext: SpanContext,
+    format: string,
+    carrier: { [key: string]: unknown }
+  ): void {
+    if (
+      isValidTraceId(spanContext.traceId) &&
+      isValidSpanId(spanContext.spanId)
+    ) {
+      carrier[X_B3_TRACE_ID] = spanContext.traceId;
+      carrier[X_B3_SPAN_ID] = spanContext.spanId;
+
+      // We set the header only if there is an existing sampling decision.
+      // Otherwise we will omit it => Absent.
+      if (spanContext.traceOptions !== undefined) {
+        carrier[X_B3_SAMPLED] = Number(spanContext.traceOptions);
+      }
+    }
+  }
+
+  extract(
+    format: string,
+    carrier: { [key: string]: unknown }
+  ): SpanContext | null {
+    const traceIdHeader = carrier[X_B3_TRACE_ID];
+    const spanIdHeader = carrier[X_B3_SPAN_ID];
+    const sampledHeader = carrier[X_B3_SAMPLED];
+    if (!traceIdHeader || !spanIdHeader) return null;
+    const traceId = Array.isArray(traceIdHeader)
+      ? traceIdHeader[0]
+      : traceIdHeader;
+    const spanId = Array.isArray(spanIdHeader) ? spanIdHeader[0] : spanIdHeader;
+    const options = Array.isArray(sampledHeader)
+      ? sampledHeader[0]
+      : sampledHeader;
+
+    if (isValidTraceId(traceId) && isValidSpanId(spanId)) {
+      return {
+        traceId,
+        spanId,
+        traceOptions: isNaN(Number(options))
+          ? TraceOptions.UNSAMPLED
+          : Number(options),
+      };
+    }
+    return null;
+  }
+}

packages/opentelemetry-core/src/index.ts

@@ -17,6 +17,7 @@
 export * from './common/ConsoleLogger';
 export * from './common/NoopLogger';
 export * from './common/types';
+export * from './context/propagation/B3Format';
 export * from './context/propagation/BinaryTraceContext';
 export * from './context/propagation/HttpTraceContext';
 export * from './platform';

packages/opentelemetry-core/test/context/B3Format.test.ts

@@ -0,0 +1,225 @@
+/**
+ * Copyright 2019, OpenTelemetry 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
+ *
+ *      https://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 assert from 'assert';
+import {
+  B3Format,
+  X_B3_TRACE_ID,
+  X_B3_SPAN_ID,
+  X_B3_SAMPLED,
+} from '../../src/context/propagation/B3Format';
+import { SpanContext, TraceOptions } from '@opentelemetry/types';
+import { TraceState } from '../../src/trace/TraceState';
+
+describe('B3Format', () => {
+  const b3Format = new B3Format();
+  let carrier: { [key: string]: unknown };
+
+  beforeEach(() => {
+    carrier = {};
+  });
+
+  describe('.inject()', () => {
+    it('should set b3 traceId and spanId headers', () => {
+      const spanContext: SpanContext = {
+        traceId: 'd4cda95b652f4a1592b449d5929fda1b',
+        spanId: '6e0c63257de34c92',
+        traceOptions: TraceOptions.SAMPLED,
+      };
+
+      b3Format.inject(spanContext, 'B3Format', carrier);
+      assert.deepStrictEqual(
+        carrier[X_B3_TRACE_ID],
+        'd4cda95b652f4a1592b449d5929fda1b'
+      );
+      assert.deepStrictEqual(carrier[X_B3_SPAN_ID], '6e0c63257de34c92');
+      assert.deepStrictEqual(carrier[X_B3_SAMPLED], TraceOptions.SAMPLED);
+    });
+
+    it('should set b3 traceId and spanId headers - ignore tracestate', () => {
+      const spanContext: SpanContext = {
+        traceId: 'd4cda95b652f4a1592b449d5929fda1b',
+        spanId: '6e0c63257de34c92',
+        traceOptions: TraceOptions.UNSAMPLED,
+        traceState: new TraceState('foo=bar,baz=qux'),
+      };
+
+      b3Format.inject(spanContext, 'B3Format', carrier);
+      assert.deepStrictEqual(
+        carrier[X_B3_TRACE_ID],
+        'd4cda95b652f4a1592b449d5929fda1b'
+      );
+      assert.deepStrictEqual(carrier[X_B3_SPAN_ID], '6e0c63257de34c92');
+      assert.deepStrictEqual(carrier[X_B3_SAMPLED], TraceOptions.UNSAMPLED);
+    });
+
+    it('should not inject empty spancontext', () => {
+      const emptySpanContext = {
+        traceId: '',
+        spanId: '',
+      };
+      b3Format.inject(emptySpanContext, 'B3Format', carrier);
+      assert.deepStrictEqual(carrier[X_B3_TRACE_ID], undefined);
+      assert.deepStrictEqual(carrier[X_B3_SPAN_ID], undefined);
+    });
+
+    it('should handle absense of sampling decision', () => {
+      const spanContext: SpanContext = {
+        traceId: 'd4cda95b652f4a1592b449d5929fda1b',
+        spanId: '6e0c63257de34c92',
+      };
+
+      b3Format.inject(spanContext, 'B3Format', carrier);
+      assert.deepStrictEqual(
+        carrier[X_B3_TRACE_ID],
+        'd4cda95b652f4a1592b449d5929fda1b'
+      );
+      assert.deepStrictEqual(carrier[X_B3_SPAN_ID], '6e0c63257de34c92');
+      assert.deepStrictEqual(carrier[X_B3_SAMPLED], undefined);
+    });
+  });
+
+  describe('.extract()', () => {
+    it('should extract context of a unsampled span from carrier', () => {
+      carrier[X_B3_TRACE_ID] = '0af7651916cd43dd8448eb211c80319c';
+      carrier[X_B3_SPAN_ID] = 'b7ad6b7169203331';
+      const extractedSpanContext = b3Format.extract('B3Format', carrier);
+
+      assert.deepStrictEqual(extractedSpanContext, {
+        spanId: 'b7ad6b7169203331',
+        traceId: '0af7651916cd43dd8448eb211c80319c',
+        traceOptions: TraceOptions.UNSAMPLED,
+      });
+    });
+
+    it('should extract context of a sampled span from carrier', () => {
+      carrier[X_B3_TRACE_ID] = '0af7651916cd43dd8448eb211c80319c';
+      carrier[X_B3_SPAN_ID] = 'b7ad6b7169203331';
+      carrier[X_B3_SAMPLED] = '1';
+      const extractedSpanContext = b3Format.extract('B3Format', carrier);
+
+      assert.deepStrictEqual(extractedSpanContext, {
+        spanId: 'b7ad6b7169203331',
+        traceId: '0af7651916cd43dd8448eb211c80319c',
+        traceOptions: TraceOptions.SAMPLED,
+      });
+    });
+
+    it('should extract context of a sampled span from carrier when sampled is mentioned as boolean true flag', () => {
+      carrier[X_B3_TRACE_ID] = '0af7651916cd43dd8448eb211c80319c';
+      carrier[X_B3_SPAN_ID] = 'b7ad6b7169203331';
+      carrier[X_B3_SAMPLED] = true;
+      const extractedSpanContext = b3Format.extract('B3Format', carrier);
+
+      assert.deepStrictEqual(extractedSpanContext, {
+        spanId: 'b7ad6b7169203331',
+        traceId: '0af7651916cd43dd8448eb211c80319c',
+        traceOptions: TraceOptions.SAMPLED,
+      });
+    });
+
+    it('should extract context of a sampled span from carrier when sampled is mentioned as boolean false flag', () => {
+      carrier[X_B3_TRACE_ID] = '0af7651916cd43dd8448eb211c80319c';
+      carrier[X_B3_SPAN_ID] = 'b7ad6b7169203331';
+      carrier[X_B3_SAMPLED] = false;
+      const extractedSpanContext = b3Format.extract('B3Format', carrier);
+
+      assert.deepStrictEqual(extractedSpanContext, {
+        spanId: 'b7ad6b7169203331',
+        traceId: '0af7651916cd43dd8448eb211c80319c',
+        traceOptions: TraceOptions.UNSAMPLED,
+      });
+    });
+
+    it('should return null when traceId is undefined', () => {
+      carrier[X_B3_TRACE_ID] = undefined;
+      carrier[X_B3_SPAN_ID] = undefined;
+      assert.deepStrictEqual(b3Format.extract('B3Format', carrier), null);
+    });
+
+    it('should return null when options and spanId are undefined', () => {
+      carrier[X_B3_TRACE_ID] = '0af7651916cd43dd8448eb211c80319c';
+      carrier[X_B3_SPAN_ID] = undefined;
+      assert.deepStrictEqual(b3Format.extract('B3Format', carrier), null);
+    });
+
+    it('returns null if b3 header is missing', () => {
+      assert.deepStrictEqual(b3Format.extract('B3Format', carrier), null);
+    });
+
+    it('returns null if b3 header is invalid', () => {
+      carrier[X_B3_TRACE_ID] = 'invalid!';
+      assert.deepStrictEqual(b3Format.extract('B3Format', carrier), null);
+    });
+
+    it('extracts b3 from list of header', () => {
+      carrier[X_B3_TRACE_ID] = ['0af7651916cd43dd8448eb211c80319c'];
+      carrier[X_B3_SPAN_ID] = 'b7ad6b7169203331';
+      carrier[X_B3_SAMPLED] = '01';
+      const extractedSpanContext = b3Format.extract('B3Format', carrier);
+      assert.deepStrictEqual(extractedSpanContext, {
+        spanId: 'b7ad6b7169203331',
+        traceId: '0af7651916cd43dd8448eb211c80319c',
+        traceOptions: TraceOptions.SAMPLED,
+      });
+    });
+
+    it('should gracefully handle an invalid b3 header', () => {
+      // A set of test cases with different invalid combinations of a
+      // b3 header. These should all result in a `null` SpanContext
+      // value being extracted.
+
+      const testCases: Record<string, string> = {
+        invalidParts_tooShort: '00-ffffffffffffffffffffffffffffffff',
+        invalidParts_tooLong:
+          '00-ffffffffffffffffffffffffffffffff-ffffffffffffffff-00-01',
+
+        invalidVersion_notHex:
+          '0x-ffffffffffffffffffffffffffffffff-ffffffffffffffff-00',
+        invalidVersion_tooShort:
+          '0-ffffffffffffffffffffffffffffffff-ffffffffffffffff-00',
+        invalidVersion_tooLong:
+          '000-ffffffffffffffffffffffffffffffff-ffffffffffffffff-00',
+
+        invalidTraceId_empty: '00--ffffffffffffffff-01',
+        invalidTraceId_notHex:
+          '00-fffffffffffffffffffffffffffffffx-ffffffffffffffff-01',
+        invalidTraceId_allZeros:
+          '00-00000000000000000000000000000000-ffffffffffffffff-01',
+        invalidTraceId_tooShort: '00-ffffffff-ffffffffffffffff-01',
+        invalidTraceId_tooLong:
+          '00-ffffffffffffffffffffffffffffffff00-ffffffffffffffff-01',
+
+        invalidSpanId_empty: '00-ffffffffffffffffffffffffffffffff--01',
+        invalidSpanId_notHex:
+          '00-ffffffffffffffffffffffffffffffff-fffffffffffffffx-01',
+        invalidSpanId_allZeros:
+          '00-ffffffffffffffffffffffffffffffff-0000000000000000-01',
+        invalidSpanId_tooShort:
+          '00-ffffffffffffffffffffffffffffffff-ffffffff-01',
+        invalidSpanId_tooLong:
+          '00-ffffffffffffffffffffffffffffffff-ffffffffffffffff0000-01',
+      };
+
+      Object.getOwnPropertyNames(testCases).forEach(testCase => {
+        carrier[X_B3_TRACE_ID] = testCases[testCase];
+
+        const extractedSpanContext = b3Format.extract('B3Format', carrier);
+        assert.deepStrictEqual(extractedSpanContext, null, testCase);
+      });
+    });
+  });
+});