From 4f48357b7d1dea246a67ef1a0e071fc64aa10e26 Mon Sep 17 00:00:00 2001 From: Bartlomiej Obecny Date: Fri, 8 Nov 2019 22:08:21 +0100 Subject: [PATCH] feat(traceparent): setting parent span from server (#477) * feat(traceparent): setting parent span from server * chore: exposing the parse functionality * chore: refactored to use existing functionality * chore: adding jsdoc to exported function * chore: updating readme with example for traceparent * chore: moving the traceparent to meta instead of window * chore: updating the jsdoc * chore: updating the copy as suggested --- examples/tracer-web/index.html | 11 +++++ .../context/propagation/HttpTraceContext.ts | 14 +++++- .../README.md | 29 +++++++++++ .../src/documentLoad.ts | 16 +++++- .../test/documentLoad.test.ts | 49 ++++++++++++++++++- 5 files changed, 114 insertions(+), 5 deletions(-) diff --git a/examples/tracer-web/index.html b/examples/tracer-web/index.html index 08bab8e1b0..4e9afa7bd6 100644 --- a/examples/tracer-web/index.html +++ b/examples/tracer-web/index.html @@ -6,6 +6,17 @@ Web Tracer Example + + + diff --git a/packages/opentelemetry-core/src/context/propagation/HttpTraceContext.ts b/packages/opentelemetry-core/src/context/propagation/HttpTraceContext.ts index f964f2273e..b003572f2b 100644 --- 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 the [traceparent] span tag and converts it into {@link SpanContext} + * @param traceParent - A meta 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 index cfc8346618..a3a8d30533 100644 --- a/packages/opentelemetry-plugin-document-load/README.md +++ b/packages/opentelemetry-plugin-document-load/README.md @@ -29,6 +29,34 @@ 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 meta tag *traceparent* . The *traceparent* meta tag should be in the [trace context W3C draft format][trace-context-url] . For example: + +```html + ... + + + + + + ... + + +``` + ## Useful links - For more information on OpenTelemetry, visit: - For more about OpenTelemetry JavaScript: @@ -48,3 +76,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 index 9770decd46..0ffea50d31 100644 --- a/packages/opentelemetry-plugin-document-load/src/documentLoad.ts +++ b/packages/opentelemetry-plugin-document-load/src/documentLoad.ts @@ -14,7 +14,12 @@ * limitations under the License. */ -import { BasePlugin, otperformance } from '@opentelemetry/core'; +import { + BasePlugin, + otperformance, + parseTraceParent, + TRACE_PARENT_HEADER, +} from '@opentelemetry/core'; import { PluginConfig, Span, SpanOptions } from '@opentelemetry/types'; import { AttributeNames } from './enums/AttributeNames'; import { PerformanceTimingNames as PTN } from './enums/PerformanceTimingNames'; @@ -106,12 +111,19 @@ export class DocumentLoad extends BasePlugin { * Collects information about performance and creates appropriate spans */ private _collectPerformance() { + const metaElement = [...document.getElementsByTagName('meta')].find( + e => e.getAttribute('name') === TRACE_PARENT_HEADER + ); + const serverContext = + parseTraceParent((metaElement && metaElement.content) || '') || undefined; + 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/test/documentLoad.test.ts b/packages/opentelemetry-plugin-document-load/test/documentLoad.test.ts index 3c317286c4..5446adc613 100644 --- a/packages/opentelemetry-plugin-document-load/test/documentLoad.test.ts +++ b/packages/opentelemetry-plugin-document-load/test/documentLoad.test.ts @@ -21,7 +21,7 @@ import * as assert from 'assert'; import * as sinon from 'sinon'; -import { ConsoleLogger } from '@opentelemetry/core'; +import { ConsoleLogger, TRACE_PARENT_HEADER } from '@opentelemetry/core'; import { BasicTracer, ReadableSpan, @@ -306,6 +306,53 @@ describe('DocumentLoad Plugin', () => { done(); }); }); + + describe('AND window has information about server root span', () => { + let spyGetElementsByTagName: any; + beforeEach(() => { + const element = { + content: '00-ab42124a3c573678d4d8b21ba52df3bf-d21f7bc17caa5aba-01', + getAttribute: (value: string) => { + if (value === 'name') { + return TRACE_PARENT_HEADER; + } + return undefined; + }, + }; + + spyGetElementsByTagName = sinon.stub( + window.document, + 'getElementsByTagName' + ); + spyGetElementsByTagName.withArgs('meta').returns([element]); + }); + afterEach(() => { + spyGetElementsByTagName.restore(); + }); + + 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); + }); + }); }); describe('when resource entries are available', () => {