Use traceparent from window for initial load context (#34)

Author: draffensperger

packages/opencensus-web-all/package.json

@@ -66,7 +66,8 @@
   "dependencies": {
     "@opencensus/web-core": "^0.0.1",
     "@opencensus/web-exporter-ocagent": "^0.0.1",
-    "@opencensus/web-instrumentation-perf": "^0.0.1"
+    "@opencensus/web-instrumentation-perf": "^0.0.1",
+    "@opencensus/web-propagation-tracecontext": "^0.0.1"
   },
   "sideEffects": [
     "./src/entrypoints/*.ts"

packages/opencensus-web-all/src/export-initial-load.ts

@@ -14,10 +14,11 @@
  * limitations under the License.
  */
 
-import {tracing} from '@opencensus/web-core';
+import {isSampled, tracing} from '@opencensus/web-core';
 import {OCAgentExporter} from '@opencensus/web-exporter-ocagent';
 import {clearPerfEntries, getInitialLoadRootSpan, getPerfEntries} from '@opencensus/web-instrumentation-perf';
 
+import {getInitialLoadSpanContext} from './initial-load-context';
 import {WindowWithOcwGlobals} from './types';
 
 const windowWithOcwGlobals = window as WindowWithOcwGlobals;
@@ -57,9 +58,13 @@ export function exportRootSpanAfterLoadEvent() {
 
 function exportInitialLoadSpans() {
   setTimeout(() => {
+    const spanContext = getInitialLoadSpanContext();
+    if (!isSampled(spanContext)) return;  // Don't export if not sampled.
+
     const perfEntries = getPerfEntries();
 
-    const root = getInitialLoadRootSpan(tracing.tracer, perfEntries);
+    const root = getInitialLoadRootSpan(
+        tracing.tracer, perfEntries, spanContext.spanId, spanContext.traceId);
 
     clearPerfEntries();
     // Notify that the span has ended to trigger export.

packages/opencensus-web-all/src/initial-load-context.ts

@@ -0,0 +1,47 @@
+/**
+ * Copyright 2019, OpenCensus 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
+ *
+ *      http://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 {randomSpanId, randomTraceId, SpanContext} from '@opencensus/web-core';
+import {traceParentToSpanContext} from '@opencensus/web-propagation-tracecontext';
+
+import {WindowWithOcwGlobals} from './types';
+
+const windowWithOcwGlobals = window as WindowWithOcwGlobals;
+
+/**
+ * Gets a span context for the initial page load from the `window.traceparent`,
+ * or generates a new random span context if it is missing. For now the new
+ * random span context generated if `window.traceparent` is missing is always
+ * marked sampled.
+ */
+export function getInitialLoadSpanContext(): SpanContext {
+  if (!windowWithOcwGlobals.traceparent) return alwaysSampledSpanContext();
+  const spanContext =
+      traceParentToSpanContext(windowWithOcwGlobals.traceparent);
+  if (!spanContext) {
+    console.log(`Invalid traceparent: ${windowWithOcwGlobals.traceparent}`);
+    return alwaysSampledSpanContext();
+  }
+  return spanContext;
+}
+
+function alwaysSampledSpanContext() {
+  return {
+    traceId: randomTraceId(),
+    spanId: randomSpanId(),
+    options: 0x1,  // Sampled
+  };
+}

packages/opencensus-web-all/test/index.ts

@@ -15,3 +15,4 @@
  */
 
 import './test-export-initial-load';
+import './test-initial-load-context';

packages/opencensus-web-all/test/test-export-initial-load.ts

@@ -19,23 +19,48 @@ import {WindowWithOcwGlobals} from '../src/types';
 
 const windowWithOcwGlobals = window as WindowWithOcwGlobals;
 
+/**
+ * Converts bytes in a hexadecimal encoded string to base64 encoded string.
+ * This is needed because the JSON proto formatting that the OC agent expects
+ * (via grpc-gateway) formats trace and span IDs in base64. This helper function
+ * allows matching trace/span IDs that are sent in the XHR body to the agent.
+ */
+function hexToBase64(hexString: string): string {
+  const match = hexString.match(/\w{2}/g);
+  if (!match) return '';
+  return window.btoa(
+      match
+          .map(
+              (hexByteChars) =>
+                  // tslint:disable-next-line:ban Needed to parse hexadecimal.
+              String.fromCharCode(parseInt(hexByteChars, 16)))
+          .join(''));
+}
+
 describe('exportRootSpanAfterLoadEvent', () => {
   let realOcwAgent: string|undefined;
+  let realTraceparent: string|undefined;
+  let sendSpy: jasmine.Spy;
   beforeEach(() => {
     jasmine.clock().install();
     spyOn(XMLHttpRequest.prototype, 'open');
-    spyOn(XMLHttpRequest.prototype, 'send');
+    sendSpy = spyOn(XMLHttpRequest.prototype, 'send');
     spyOn(XMLHttpRequest.prototype, 'setRequestHeader');
     realOcwAgent = windowWithOcwGlobals.ocwAgent;
+    realTraceparent = windowWithOcwGlobals.traceparent;
   });
   afterEach(() => {
     jasmine.clock().uninstall();
     windowWithOcwGlobals.ocwAgent = realOcwAgent;
+    windowWithOcwGlobals.traceparent = realTraceparent;
   });
 
   it('exports spans to agent if agent is configured', () => {
     windowWithOcwGlobals.ocwAgent = 'http://agent';
+    windowWithOcwGlobals.traceparent = undefined;
+
     exportRootSpanAfterLoadEvent();
+
     jasmine.clock().tick(300000);
     expect(XMLHttpRequest.prototype.open)
         .toHaveBeenCalledWith('POST', 'http://agent/v1/trace');
@@ -44,7 +69,40 @@ describe('exportRootSpanAfterLoadEvent', () => {
 
   it('does not export if agent not configured', () => {
     windowWithOcwGlobals.ocwAgent = undefined;
+    windowWithOcwGlobals.traceparent = undefined;
+
     exportRootSpanAfterLoadEvent();
+
+    jasmine.clock().tick(300000);
+    expect(XMLHttpRequest.prototype.open).not.toHaveBeenCalled();
+    expect(XMLHttpRequest.prototype.send).not.toHaveBeenCalled();
+  });
+
+  it('uses trace and span ID from window.traceparent if specified', () => {
+    windowWithOcwGlobals.ocwAgent = 'http://agent';
+    const traceId = '0af7651916cd43dd8448eb211c80319c';
+    const spanId = 'b7ad6b7169203331';
+    windowWithOcwGlobals.traceparent = `00-${traceId}-${spanId}-01`;
+
+    exportRootSpanAfterLoadEvent();
+
+    jasmine.clock().tick(300000);
+    expect(XMLHttpRequest.prototype.open)
+        .toHaveBeenCalledWith('POST', 'http://agent/v1/trace');
+    expect(XMLHttpRequest.prototype.send).toHaveBeenCalledTimes(1);
+    // Check that trace and span ID from `window.traceparent` are in body sent.
+    const sendBody = sendSpy.calls.argsFor(0)[0];
+    expect(sendBody).toContain(hexToBase64(traceId));
+    expect(sendBody).toContain(hexToBase64(traceId));
+  });
+
+  it('does not export spans if traceparent sampling hint not set', () => {
+    windowWithOcwGlobals.ocwAgent = 'http://agent';
+    windowWithOcwGlobals.traceparent =
+        '00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-00';
+
+    exportRootSpanAfterLoadEvent();
+
     jasmine.clock().tick(300000);
     expect(XMLHttpRequest.prototype.open).not.toHaveBeenCalled();
     expect(XMLHttpRequest.prototype.send).not.toHaveBeenCalled();

packages/opencensus-web-all/test/test-initial-load-context.ts

@@ -0,0 +1,59 @@
+/**
+ * Copyright 2019, OpenCensus 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
+ *
+ *      http://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 {getInitialLoadSpanContext} from '../src/initial-load-context';
+import {WindowWithOcwGlobals} from '../src/types';
+
+const windowWithOcwGlobals = window as WindowWithOcwGlobals;
+
+const SPAN_ID_REGEX = /[0-9a-f]{16}/;
+const TRACE_ID_REGEX = /[0-9a-f]{32}/;
+
+describe('getInitialLoadSpanContext', () => {
+  let realTraceparent: string|undefined;
+  beforeEach(() => {
+    realTraceparent = windowWithOcwGlobals.traceparent;
+  });
+  afterEach(() => {
+    windowWithOcwGlobals.traceparent = realTraceparent;
+  });
+
+  it('sets trace and span ID from global `traceparent` when specified', () => {
+    windowWithOcwGlobals.traceparent =
+        `00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-00`;
+    expect(getInitialLoadSpanContext()).toEqual({
+      traceId: '0af7651916cd43dd8448eb211c80319c',
+      spanId: 'b7ad6b7169203331',
+      options: 0,
+    });
+  });
+
+  it('generates a new random span context if `traceparent` unspecified', () => {
+    windowWithOcwGlobals.traceparent = undefined;
+    const spanContext = getInitialLoadSpanContext();
+    expect(spanContext.traceId).toMatch(TRACE_ID_REGEX);
+    expect(spanContext.spanId).toMatch(SPAN_ID_REGEX);
+    expect(spanContext.options).toBe(1);
+  });
+
+  it('generates a new random span context if `traceparent` is invalid', () => {
+    windowWithOcwGlobals.traceparent = 'invalid trace parent header!';
+    const spanContext = getInitialLoadSpanContext();
+    expect(spanContext.traceId).toMatch(TRACE_ID_REGEX);
+    expect(spanContext.spanId).toMatch(SPAN_ID_REGEX);
+    expect(spanContext.options).toBe(1);
+  });
+});

packages/opencensus-web-core/src/index.ts

@@ -19,6 +19,7 @@ export {RootSpan} from './trace/model/root-span';
 export {Span} from './trace/model/span';
 export {Tracer} from './trace/model/tracer';
 export {Tracing} from './trace/model/tracing';
+export * from './trace/model/util';
 export * from './trace/model/attribute-keys';
 
 // Re-export types this uses from @opencensus/web-types.

packages/opencensus-web-core/src/trace/model/util.ts

@@ -0,0 +1,26 @@
+/**
+ * Copyright 2019, OpenCensus 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
+ *
+ *      http://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} from '@opencensus/web-types';
+
+const IS_SAMPLED_BIT = 0x1;
+
+/** Returns whether sampling hint bit of the span context `options` is set. */
+export function isSampled(spanContext: SpanContext) {
+  const options = spanContext.options;
+  if (!options) return false;
+  return !!(options & IS_SAMPLED_BIT);
+}

packages/opencensus-web-core/test/index.ts

@@ -21,6 +21,7 @@ import './test-id-util';
 import './test-root-span';
 import './test-span';
 import './test-time-util';
+import './test-trace-model-util';
 import './test-tracer';
 import './test-tracing';
 import './test-url-util';

packages/opencensus-web-core/test/test-trace-model-util.ts

@@ -0,0 +1,28 @@
+/**
+ * Copyright 2019, OpenCensus 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
+ *
+ *      http://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 {isSampled} from '../src/trace/model/util';
+
+describe('isSampled', () => {
+  it('returns true if sampling bit is set', () => {
+    expect(isSampled({traceId: '', spanId: '', options: 1})).toBe(true);
+    expect(isSampled({traceId: '', spanId: '', options: 5})).toBe(true);
+  });
+  it('returns false if sampling bit is not set', () => {
+    expect(isSampled({traceId: '', spanId: '', options: 0})).toBe(false);
+    expect(isSampled({traceId: '', spanId: '', options: 4})).toBe(false);
+  });
+});