open-telemetry · mayurkale22 · Nov 8, 2019 · Nov 4, 2019 · Nov 4, 2019 · Nov 4, 2019
diff --git a/examples/tracer-web/index.html b/examples/tracer-web/index.html
@@ -10,6 +10,15 @@
 </head>
 
 <body>
+  <script>
+    // https://www.w3.org/TR/trace-context/
+    // Set the `traceparent` in the server's HTML template code. It should be
+    // dynamically generated server side to have the server's request trace Id,
+    // a parent span Id that was set on the server's request span, and the trace
+    // flags to indicate the server's sampling decision (01 = sampled, 00 = not
+    // sampled). '{version}-{traceId}-{spanId}-{sampleDecision}'
+    window.traceparent = '00-ab42124a3c573678d4d8b21ba52df3bf-d21f7bc17caa5aba-01';
+  </script>
   Example of using Web Tracer with document load plugin and console exporter
   <script type="text/javascript" src="/bundle.js"></script>
 </body>

diff --git a/packages/opentelemetry-core/src/context/propagation/HttpTraceContext.ts b/packages/opentelemetry-core/src/context/propagation/HttpTraceContext.ts
@@ -25,7 +25,17 @@ const VALID_SPANID_REGEX = /^[0-9a-f]{16}$/i;
 const INVALID_ID_REGEX = /^0+$/i;
 const VERSION = '00';
 
-function parse(traceParent: string): SpanContext | null {
+/**
+ * Parses information from [traceParent] window property and converts it into {@link SpanContext}
- * Parses information from [traceParent] window property and converts it into {@link SpanContext}
+ * Parses information from the [traceparent] span tag and converts it into {@link SpanContext}
- * Parses information from [traceParent] window property and converts it into {@link SpanContext}
+ * Parses information from the [traceparent] span tag and converts it into {@link SpanContext}
+ * @param traceParent - A window property that comes from server.
+ *     It should be dynamically generated server side to have the server's request trace Id,
+ *     a parent span Id that was set on the server's request span,
+ *     and the trace flags to indicate the server's sampling decision
+ *     (01 = sampled, 00 = not sampled).
+ *     for example: '{version}-{traceId}-{spanId}-{sampleDecision}'
+ *     For more information see {@link https://www.w3.org/TR/trace-context/}
+ */
+export function parseTraceParent(traceParent: string): SpanContext | null {
   const match = traceParent.match(VALID_TRACE_PARENT_REGEX);
   if (!match) return null;
   const parts = traceParent.split('-');
@@ -87,7 +97,7 @@ export class HttpTraceContext implements HttpTextFormat {
     const traceParent = Array.isArray(traceParentHeader)
       ? traceParentHeader[0]
       : traceParentHeader;
-    const spanContext = parse(traceParent);
+    const spanContext = parseTraceParent(traceParent);
     if (!spanContext) return null;
 
     spanContext.isRemote = true;

diff --git a/packages/opentelemetry-plugin-document-load/README.md b/packages/opentelemetry-plugin-document-load/README.md
@@ -29,6 +29,28 @@ const webTracer = new WebTracer({
 webTracer.addSpanProcessor(new SimpleSpanProcessor(new ConsoleSpanExporter()));
 ```
 
+## Optional: Send a trace parent from your server
+This plugin supports connecting the server side spans for the initial HTML load with the client side span for the load from the browser's timing API. This works by having the server send its parent trace context (trace ID, span ID and trace sampling decision) to the client.
+
+Because the browser does not send a trace context header for the initial page navigation, the server needs to fake a trace context header in a middleware and then send that trace context header back to the client as a global *traceparent* variable. The *traceparent* variable should be in the [trace context W3C draft format][trace-context-url] . For example:
+
+```html
+  ...
+  <script>
+    // https://www.w3.org/TR/trace-context/
+    // Set the `traceparent` in the server's HTML template code. It should be
+    // dynamically generated server side to have the server's request trace Id,
+    // a parent span Id that was set on the server's request span, and the trace
+    // flags to indicate the server's sampling decision (01 = sampled, 00 = not
+    // sampled). '{version}-{traceId}-{spanId}-{sampleDecision}'
+    window.traceparent = '00-ab42124a3c573678d4d8b21ba52df3bf-d21f7bc17caa5aba-01';
+
+    // and then initialise the WebTracer
+    // var webTracer = new WebTracer({ .......
+  </script>
+</body>
+```
+
 ## Useful links
 - For more information on OpenTelemetry, visit: <https://opentelemetry.io/>
 - For more about OpenTelemetry JavaScript: <https://github.com/open-telemetry/opentelemetry-js>
@@ -48,3 +70,4 @@ Apache 2.0 - See [LICENSE][license-url] for more information.
 [devDependencies-url]: https://david-dm.org/open-telemetry/opentelemetry-js?path=packages%2Fopentelemetry-plugin-document-load&type=dev
 [npm-url]: https://www.npmjs.com/package/@opentelemetry/plugin-document-load
 [npm-img]: https://badge.fury.io/js/%40opentelemetry%2Fplugin-document-load.svg
+[trace-context-url]: https://www.w3.org/TR/trace-context
diff --git a/packages/opentelemetry-plugin-document-load/src/documentLoad.ts b/packages/opentelemetry-plugin-document-load/src/documentLoad.ts
@@ -14,11 +14,19 @@
  * limitations under the License.
  */
 
-import { BasePlugin, otperformance } from '@opentelemetry/core';
+import {
+  BasePlugin,
+  otperformance,
+  parseTraceParent,
+} from '@opentelemetry/core';
 import { PluginConfig, Span, SpanOptions } from '@opentelemetry/types';
 import { AttributeNames } from './enums/AttributeNames';
 import { PerformanceTimingNames as PTN } from './enums/PerformanceTimingNames';
-import { PerformanceEntries, PerformanceLegacy } from './types';
+import {
+  PerformanceEntries,
+  PerformanceLegacy,
+  WindowWithTrace,
+} from './types';
 import { hasKey } from './utils';
 
 /**
@@ -76,12 +84,17 @@ export class DocumentLoad extends BasePlugin<unknown> {
    * Collects information about performance and creates appropriate spans
    */
   private _collectPerformance() {
+    const windowWithTrace: WindowWithTrace = (window as unknown) as WindowWithTrace;
+    const serverContext =
+      parseTraceParent(windowWithTrace.traceparent || '') || undefined;
 parent?: Span | SpanContext; 
 parent?: Span | SpanContext; 
+
     const entries = this._getEntries();
 
     const rootSpan = this._startSpan(
       AttributeNames.DOCUMENT_LOAD,
       PTN.FETCH_START,
-      entries
+      entries,
+      { parent: serverContext }
     );
     if (!rootSpan) {
       return;

diff --git a/packages/opentelemetry-plugin-document-load/src/types.ts b/packages/opentelemetry-plugin-document-load/src/types.ts
@@ -48,3 +48,10 @@ export type PerformanceEntries = {
 export interface PerformanceLegacy {
   timing?: PerformanceEntries;
 }
+
+/**
+ * A window object with traceparent information from server
+ */
+export interface WindowWithTrace {
+  traceparent?: string;
+}
diff --git a/packages/opentelemetry-plugin-document-load/test/documentLoad.test.ts b/packages/opentelemetry-plugin-document-load/test/documentLoad.test.ts
@@ -33,6 +33,7 @@ import { Logger, PluginConfig } from '@opentelemetry/types';
 import { ExportResult } from '../../opentelemetry-base/build/src';
 import { DocumentLoad } from '../src';
 import { PerformanceTimingNames as PTN } from '../src/enums/PerformanceTimingNames';
+import { WindowWithTrace } from '../src/types';
 
 export class DummyExporter implements SpanExporter {
   export(
@@ -238,6 +239,38 @@ describe('DocumentLoad Plugin', () => {
       });
     });
 
+    describe('AND window has information about server root span', () => {
+      beforeEach(() => {
+        ((window as unknown) as WindowWithTrace).traceparent =
+          '00-ab42124a3c573678d4d8b21ba52df3bf-d21f7bc17caa5aba-01';
+      });
+      it('should create a root span with server context traceId', done => {
+        const spyOnEnd = sinon.spy(dummyExporter, 'export');
+        plugin.enable(moduleExports, tracer, logger, config);
+        setTimeout(() => {
+          const rootSpan = spyOnEnd.args[0][0][0] as ReadableSpan;
+          const fetchSpan = spyOnEnd.args[1][0][0] as ReadableSpan;
+          assert.strictEqual(rootSpan.name, 'documentFetch');
+          assert.strictEqual(fetchSpan.name, 'documentLoad');
+
+          assert.strictEqual(
+            rootSpan.spanContext.traceId,
+            'ab42124a3c573678d4d8b21ba52df3bf'
+          );
+          assert.strictEqual(
+            fetchSpan.spanContext.traceId,
+            'ab42124a3c573678d4d8b21ba52df3bf'
+          );
+
+          assert.strictEqual(spyOnEnd.callCount, 2);
+          done();
+        }, 1);
+      });
+      afterEach(() => {
+        delete ((window as unknown) as WindowWithTrace).traceparent;
+      });
+    });
+
     afterEach(() => {
       spyExport.restore();
     });