feat: Add B3format propagator (open-telemetry#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);
+ });
+ });
+ });
+});