feat: add jaeger http trace format (#696)

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

@@ -0,0 +1,76 @@
+/*!
+ * Copyright 2020, 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, TraceFlags } from '@opentelemetry/types';
+
+export const UBER_TRACE_ID_HEADER = 'uber-trace-id';
+
+/**
+ * Propagates {@link SpanContext} through Trace Context format propagation.
+ * {trace-id}:{span-id}:{parent-span-id}:{flags}
+ * {trace-id}
+ * 64-bit or 128-bit random number in base16 format
+ * Can be variable length, shorter values are 0-padded on the left
+ * Value of 0 is invalid
+ * {span-id}
+ * 64-bit random number in base16 format
+ * {parent-span-id} set to 0 because this field is deprecated
+ * {flags}
+ * One byte bitmap, as two hex digits
+ * Inspired by jaeger-client-node project
+ */
+export class JaegerHttpTraceFormat implements HttpTextFormat {
+  inject(
+    spanContext: SpanContext,
+    format: string,
+    carrier: { [key: string]: unknown }
+  ) {
+    const flags = TraceFlags.SAMPLED;
+
+    carrier[
+      UBER_TRACE_ID_HEADER
+    ] = `${spanContext.traceId}:${spanContext.spanId}:0:${flags}`;
+  }
+
+  extract(
+    format: string,
+    carrier: { [key: string]: unknown }
+  ): SpanContext | null {
+    const uberTraceIdHeader = carrier[UBER_TRACE_ID_HEADER];
+    if (!uberTraceIdHeader) return null;
+    const uberTraceId = Array.isArray(uberTraceIdHeader)
+      ? uberTraceIdHeader[0]
+      : uberTraceIdHeader;
+
+    return deserializeSpanContext(uberTraceId);
+  }
+}
+
+/**
+ * @param {string} serializedString - a serialized span context.
+ * @return {SpanContext} - returns a span context represented by the serializedString.
+ **/
+function deserializeSpanContext(serializedString: string): SpanContext | null {
+  let headers = serializedString.split(':');
+  if (headers.length !== 4) {
+    return null;
+  }
+  const [traceId, spanId, , flags] = headers;
+
+  const traceFlags = flags.match(/^[0-9a-f]{2}$/i) ? parseInt(flags) & 1 : 1;
+
+  return { traceId, spanId, isRemote: true, traceFlags };
+}

packages/opentelemetry-core/src/index.ts

@@ -22,6 +22,7 @@ export * from './version';
 export * from './context/propagation/B3Format';
 export * from './context/propagation/BinaryTraceContext';
 export * from './context/propagation/HttpTraceContext';
+export * from './context/propagation/JaegerHttpTraceFormat';
 export * from './platform';
 export * from './trace/globaltracer-utils';
 export * from './trace/instrumentation/BasePlugin';

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

@@ -0,0 +1,74 @@
+/*!
+ * Copyright 2020, 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 {
+  JaegerHttpTraceFormat,
+  UBER_TRACE_ID_HEADER,
+} from '../../src/context/propagation/JaegerHttpTraceFormat';
+import { SpanContext, TraceFlags } from '@opentelemetry/types';
+
+describe('JaegerHttpTraceFormat', () => {
+  const jaegerHttpTraceFormat = new JaegerHttpTraceFormat();
+  let carrier: { [key: string]: unknown };
+
+  beforeEach(() => {
+    carrier = {};
+  });
+
+  describe('.inject()', () => {
+    it('should set uber trace id header', () => {
+      const spanContext: SpanContext = {
+        traceId: 'd4cda95b652f4a1592b449d5929fda1b',
+        spanId: '6e0c63257de34c92',
+        traceFlags: TraceFlags.SAMPLED,
+      };
+
+      jaegerHttpTraceFormat.inject(spanContext, '', carrier);
+      assert.deepStrictEqual(
+        carrier[UBER_TRACE_ID_HEADER],
+        'd4cda95b652f4a1592b449d5929fda1b:6e0c63257de34c92:0:1'
+      );
+    });
+  });
+
+  describe('.extract()', () => {
+    it('should extract context of a sampled span from carrier', () => {
+      carrier[UBER_TRACE_ID_HEADER] =
+        'd4cda95b652f4a1592b449d5929fda1b:6e0c63257de34c92:0:1';
+      const extractedSpanContext = jaegerHttpTraceFormat.extract('', carrier);
+
+      assert.deepStrictEqual(extractedSpanContext, {
+        spanId: '6e0c63257de34c92',
+        traceId: 'd4cda95b652f4a1592b449d5929fda1b',
+        isRemote: true,
+        traceFlags: TraceFlags.SAMPLED,
+      });
+    });
+
+    it('returns null if UBER_TRACE_ID_HEADER header is missing', () => {
+      assert.deepStrictEqual(jaegerHttpTraceFormat.extract('', carrier), null);
+    });
+
+    it('returns null if UBER_TRACE_ID_HEADER header is invalid', () => {
+      carrier[UBER_TRACE_ID_HEADER] = 'invalid!';
+      assert.deepStrictEqual(
+        jaegerHttpTraceFormat.extract('HttpTraceContext', carrier),
+        null
+      );
+    });
+  });
+});