diff --git a/README.md b/README.md index 364b3a38..a38e5f8f 100644 --- a/README.md +++ b/README.md @@ -198,6 +198,118 @@ As a convenience the SDK also accepts a plain object or array as an extension va when the event is sent in binary mode. This is not spec-conformant: a receiver gets a plain string and has to know to parse it, and other SDKs may reject the event. Prefer the explicit form above. +### Trace context with OpenTelemetry + +Use `cloudevents/otel` to carry an OpenTelemetry trace context in the CloudEvents +[Distributed Tracing extension](https://github.com/cloudevents/spec/blob/main/cloudevents/extensions/distributed-tracing.md). +Install the OpenTelemetry dependencies: + +```console +npm install @opentelemetry/api @opentelemetry/core +``` + +Within an active OpenTelemetry span, attach its context to an event and send it +over HTTP: + +```js +import { context } from "@opentelemetry/api"; +import { CloudEvent, emitterFor, httpTransport } from "cloudevents"; +import { injectDistributedTracingExtension } from "cloudevents/otel"; + +const emit = emitterFor(httpTransport("https://events.example.com/orders")); +const event = new CloudEvent({ + type: "com.example.order.created", + source: "/stores/store-42", + data: { orderId: "order-123" }, +}); +const tracedEvent = injectDistributedTracingExtension(context.active(), event); +await emit(tracedEvent); +``` + +`injectDistributedTracingExtension()` returns an event copy with the supplied +tracing extension, replacing any existing `traceparent` and `tracestate`. It returns +the original event when the supplied context lacks a valid span context. + +To read an event's creation context directly, call +`extractDistributedTracingExtension(baseContext, event)`. The returned context +combines the event's span context with the other values in `baseContext`. A missing +or invalid extension returns `baseContext`. + +#### CloudEvents attributes and links + +After decoding an order event, use `getCloudEventSpanOptions()` to supply its +attributes and creation-context link when creating the processing span. The +processing span is a child of the active span, such as the HTTP server span: + +```js +import { SpanKind, SpanStatusCode, trace } from "@opentelemetry/api"; +import { getCloudEventSpanOptions } from "cloudevents/otel"; + +const tracer = trace.getTracer("orders"); + +await tracer.startActiveSpan( + "process order", + { + kind: SpanKind.CONSUMER, + ...getCloudEventSpanOptions(receivedEvent), + }, + async (processingSpan) => { + try { + await handleOrder(receivedEvent); + } catch (error) { + processingSpan.setStatus({ code: SpanStatusCode.ERROR }); + throw error; + } finally { + processingSpan.end(); + } + }, +); +``` + +For a batch, pass an array of events: common attributes go on the span and +event-specific attributes go on links. Passing the options at span creation makes +the attributes and links available to head samplers. + +#### HTTP auto-instrumentation + +`CloudEventPropagator` lets HTTP instrumentation continue a trace from CloudEvents +binary-mode headers. It reads a valid `traceparent` first, then falls back to +`ce-traceparent`. The corresponding `tracestate` or `ce-tracestate` accompanies the +selected context. Outgoing requests use W3C trace headers. + +Install the tracing SDK and HTTP instrumentation: + +```console +npm install @opentelemetry/sdk-trace @opentelemetry/context-async-hooks \ + @opentelemetry/instrumentation @opentelemetry/instrumentation-http +``` + +Configure the provider in `telemetry.mjs`: + +```js +import { context, propagation, trace } from "@opentelemetry/api"; +import { AsyncLocalStorageContextManager } from "@opentelemetry/context-async-hooks"; +import { CompositePropagator, W3CBaggagePropagator } from "@opentelemetry/core"; +import { HttpInstrumentation } from "@opentelemetry/instrumentation-http"; +import { TracerProvider } from "@opentelemetry/sdk-trace"; +import { CloudEventPropagator } from "cloudevents/otel"; + +trace.setGlobalTracerProvider(new TracerProvider()); +context.setGlobalContextManager(new AsyncLocalStorageContextManager().enable()); +propagation.setGlobalPropagator(new CompositePropagator({ + propagators: [new CloudEventPropagator(), new W3CBaggagePropagator()], +})); +new HttpInstrumentation().enable(); +``` + +For ESM, load the OpenTelemetry module hook and telemetry before the application: + +```console +node --experimental-loader=@opentelemetry/instrumentation/hook.mjs --import ./telemetry.mjs app.mjs +``` + +For structured and batch messages, use the helpers above after decoding the event body. + ### A Note About Big Integers When parsing JSON data, if a JSON field value is a number, and that number diff --git a/package-lock.json b/package-lock.json index 673f8a81..50adfef2 100644 --- a/package-lock.json +++ b/package-lock.json @@ -18,6 +18,11 @@ }, "devDependencies": { "@cucumber/cucumber": "^13.3.0", + "@opentelemetry/api": "^1.10.0", + "@opentelemetry/context-async-hooks": "^3.1.1", + "@opentelemetry/core": "^3.1.1", + "@opentelemetry/instrumentation-http": "^0.301.2", + "@opentelemetry/sdk-trace": "^3.1.1", "@types/chai": "^4.2.11", "@types/got": "^9.6.11", "@types/json-bigint": "^1.0.1", @@ -54,6 +59,18 @@ }, "engines": { "node": ">=22 <=24" + }, + "peerDependencies": { + "@opentelemetry/api": ">=1.7.0 <2", + "@opentelemetry/core": "^1.0.0 || ^2.0.0 || ^3.0.0" + }, + "peerDependenciesMeta": { + "@opentelemetry/api": { + "optional": true + }, + "@opentelemetry/core": { + "optional": true + } } }, "node_modules/@babel/code-frame": { @@ -1039,6 +1056,126 @@ "node": ">= 8" } }, + "node_modules/@opentelemetry/api": { + "version": "1.10.0", + "resolved": "https://registry.npmjs.org/@opentelemetry/api/-/api-1.10.0.tgz", + "integrity": "sha512-lMkyes8iHrG+mk6WH7X70MdCLI2RS0FwNBY1PyQ8UemaijE2m5mv5A0Niy3HtbYTFrgkUEQjFMXmSAk2hQDuPQ==", + "dev": true, + "license": "Apache-2.0", + "engines": { + "node": ">=8.0.0" + } + }, + "node_modules/@opentelemetry/context-async-hooks": { + "version": "3.1.1", + "resolved": "https://registry.npmjs.org/@opentelemetry/context-async-hooks/-/context-async-hooks-3.1.1.tgz", + "integrity": "sha512-xOosgbes1+6bHPhVnYCd3EihFN8MpafEQwzmxeZ2zKXwWwV4F4780Pb097E326RZjCHTvUkwOYnXOALTfRfHVg==", + "dev": true, + "license": "Apache-2.0", + "engines": { + "node": ">=22.15.0" + }, + "peerDependencies": { + "@opentelemetry/api": ">=1.0.0 <1.11.0" + } + }, + "node_modules/@opentelemetry/core": { + "version": "3.1.1", + "resolved": "https://registry.npmjs.org/@opentelemetry/core/-/core-3.1.1.tgz", + "integrity": "sha512-6wc9r0zrTsAVOd/5UrZBsrHhXWNfwisolgWxd8o3Eu1HKIz8cAxQjOdGrrJB406ceFiGV+ckTcLdXzB+y/QVTA==", + "dev": true, + "license": "Apache-2.0", + "dependencies": { + "@opentelemetry/semantic-conventions": "^1.29.0" + }, + "engines": { + "node": ">=22.15.0" + }, + "peerDependencies": { + "@opentelemetry/api": ">=1.10.0 <1.11.0" + } + }, + "node_modules/@opentelemetry/instrumentation": { + "version": "0.301.2", + "resolved": "https://registry.npmjs.org/@opentelemetry/instrumentation/-/instrumentation-0.301.2.tgz", + "integrity": "sha512-14ZUepvK+YiMfhy3Hugh4UuY5THEfVOcsY0+L+DertoVmdh4MTR5H0JvD1IT2jGLKPZiIg+apDCM2CTuGh6UzQ==", + "dev": true, + "license": "Apache-2.0", + "dependencies": { + "import-in-the-middle": "^3.0.0", + "require-in-the-middle": "^8.0.0" + }, + "engines": { + "node": ">=22.15.0" + }, + "peerDependencies": { + "@opentelemetry/api": ">=1.10.0 <1.11.0" + } + }, + "node_modules/@opentelemetry/instrumentation-http": { + "version": "0.301.2", + "resolved": "https://registry.npmjs.org/@opentelemetry/instrumentation-http/-/instrumentation-http-0.301.2.tgz", + "integrity": "sha512-IgxJ5R639ouwlGkK8Lv4AJykTeo63n5hR5g91VvABY1dc60oBLPUef8Z91jM25XFNEPzGMPufTuVWxeQshM1aw==", + "dev": true, + "license": "Apache-2.0", + "dependencies": { + "@opentelemetry/core": "3.1.1", + "@opentelemetry/instrumentation": "0.301.2", + "@opentelemetry/semantic-conventions": "^1.29.0", + "forwarded-parse": "2.2.0" + }, + "engines": { + "node": ">=22.15.0" + }, + "peerDependencies": { + "@opentelemetry/api": "^1.10.0" + } + }, + "node_modules/@opentelemetry/resources": { + "version": "3.1.1", + "resolved": "https://registry.npmjs.org/@opentelemetry/resources/-/resources-3.1.1.tgz", + "integrity": "sha512-dSd0FI1rfl+WHeaZxCTCEvwv6vcmUqkOHHTGWMkmyHg+PyL/wLbCqgsGKgI0wOwT0KGy9IMPAvY85hT8IPwApA==", + "dev": true, + "license": "Apache-2.0", + "dependencies": { + "@opentelemetry/core": "3.1.1", + "@opentelemetry/semantic-conventions": "^1.29.0" + }, + "engines": { + "node": ">=22.15.0" + }, + "peerDependencies": { + "@opentelemetry/api": ">=1.10.0 <1.11.0" + } + }, + "node_modules/@opentelemetry/sdk-trace": { + "version": "3.1.1", + "resolved": "https://registry.npmjs.org/@opentelemetry/sdk-trace/-/sdk-trace-3.1.1.tgz", + "integrity": "sha512-DJZXZJu1H3kek9Kh9SqJ46yN3faiNiabnqkEtl9eVnBvs4KuK+ynmk9jOyB0NfWAXWGZlTivCf46uwiXyr2PGA==", + "dev": true, + "license": "Apache-2.0", + "dependencies": { + "@opentelemetry/core": "3.1.1", + "@opentelemetry/resources": "3.1.1", + "@opentelemetry/semantic-conventions": "^1.29.0" + }, + "engines": { + "node": ">=22.15.0" + }, + "peerDependencies": { + "@opentelemetry/api": ">=1.10.0 <1.11.0" + } + }, + "node_modules/@opentelemetry/semantic-conventions": { + "version": "1.44.0", + "resolved": "https://registry.npmjs.org/@opentelemetry/semantic-conventions/-/semantic-conventions-1.44.0.tgz", + "integrity": "sha512-E3JkOlMBi3N8OGGkbl7tFyqk2MAS6/lySRZBK3Mu7AzjF1fT8oIChH9ChE48SUWzDn9Kdwta+G/p5LJ4xW4CLQ==", + "dev": true, + "license": "Apache-2.0", + "engines": { + "node": ">=14" + } + }, "node_modules/@paralleldrive/cuid2": { "version": "2.3.1", "resolved": "https://registry.npmjs.org/@paralleldrive/cuid2/-/cuid2-2.3.1.tgz", @@ -2670,6 +2807,13 @@ "node": ">=6.0" } }, + "node_modules/cjs-module-lexer": { + "version": "2.3.0", + "resolved": "https://registry.npmjs.org/cjs-module-lexer/-/cjs-module-lexer-2.3.0.tgz", + "integrity": "sha512-lmNyBzi6iYiqyrExTctfmjd8tInx+dHu9PBomTfH5RXS53c27JMFJgzNv5TyAnm3PgGf+MLy0+Ws41/HlVxdKQ==", + "dev": true, + "license": "MIT" + }, "node_modules/clean-stack": { "version": "2.2.0", "resolved": "https://registry.npmjs.org/clean-stack/-/clean-stack-2.2.0.tgz", @@ -4322,6 +4466,13 @@ "url": "https://ko-fi.com/tunnckoCore/commissions" } }, + "node_modules/forwarded-parse": { + "version": "2.2.0", + "resolved": "https://registry.npmjs.org/forwarded-parse/-/forwarded-parse-2.2.0.tgz", + "integrity": "sha512-jYQDJm+NayL3VZVE+tydz/Ja3dy8xurckRr9R1mmVkpdOdQlTqJktv4ZVDThu2iZj3mLZL/qpL3CKfJe1eS7Cw==", + "dev": true, + "license": "MIT" + }, "node_modules/fromentries": { "version": "1.3.2", "resolved": "https://registry.npmjs.org/fromentries/-/fromentries-1.3.2.tgz", @@ -4912,6 +5063,28 @@ "url": "https://github.com/sponsors/sindresorhus" } }, + "node_modules/import-in-the-middle": { + "version": "3.6.0", + "resolved": "https://registry.npmjs.org/import-in-the-middle/-/import-in-the-middle-3.6.0.tgz", + "integrity": "sha512-xRU7hI24S2FhucXtuZXn8EpcOjfVP6iiEQyR0USayPeaOroEmSsNlqnl95866iRdRtkHrd6Q/Z4D14R60au0+A==", + "dev": true, + "license": "Apache-2.0", + "dependencies": { + "cjs-module-lexer": "^2.2.0", + "es-module-lexer": "^3.0.4", + "module-details-from-path": "^1.0.4" + }, + "engines": { + "node": ">=18" + } + }, + "node_modules/import-in-the-middle/node_modules/es-module-lexer": { + "version": "3.0.4", + "resolved": "https://registry.npmjs.org/es-module-lexer/-/es-module-lexer-3.0.4.tgz", + "integrity": "sha512-BldNY5mwkVu+cQ5Ymn3e6hB9Sx8XHx4ZevWbiUyZbfKxJxYO27Hf0wfzkxIaD5CAJMaGl3YspKELj0ff/7nCMA==", + "dev": true, + "license": "MIT" + }, "node_modules/import-local": { "version": "3.2.0", "resolved": "https://registry.npmjs.org/import-local/-/import-local-3.2.0.tgz", @@ -7232,6 +7405,13 @@ "url": "https://github.com/sponsors/sindresorhus" } }, + "node_modules/module-details-from-path": { + "version": "1.0.4", + "resolved": "https://registry.npmjs.org/module-details-from-path/-/module-details-from-path-1.0.4.tgz", + "integrity": "sha512-EGWKgxALGMgzvxYF1UyGTy0HXX/2vHLkw6+NvDKW2jypWbHpjQuj4UMcqQWXHERJhVGKikolT06G3bcKe4fi7w==", + "dev": true, + "license": "MIT" + }, "node_modules/mri": { "version": "1.2.0", "resolved": "https://registry.npmjs.org/mri/-/mri-1.2.0.tgz", @@ -8920,6 +9100,20 @@ "node": ">=0.10.0" } }, + "node_modules/require-in-the-middle": { + "version": "8.0.1", + "resolved": "https://registry.npmjs.org/require-in-the-middle/-/require-in-the-middle-8.0.1.tgz", + "integrity": "sha512-QT7FVMXfWOYFbeRBF6nu+I6tr2Tf3u0q8RIEjNob/heKY/nh7drD/k7eeMFmSQgnTtCzLDcCu/XEnpW2wk4xCQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "debug": "^4.3.5", + "module-details-from-path": "^1.0.3" + }, + "engines": { + "node": ">=9.3.0 || >=8.10.0 <9.0.0" + } + }, "node_modules/require-main-filename": { "version": "2.0.0", "resolved": "https://registry.npmjs.org/require-main-filename/-/require-main-filename-2.0.0.tgz", diff --git a/package.json b/package.json index 4a588f90..89ca38c6 100644 --- a/package.json +++ b/package.json @@ -127,8 +127,25 @@ "util": "^0.12.4", "uuid": "^11.1.1" }, + "peerDependencies": { + "@opentelemetry/api": ">=1.7.0 <2", + "@opentelemetry/core": "^1.0.0 || ^2.0.0 || ^3.0.0" + }, + "peerDependenciesMeta": { + "@opentelemetry/api": { + "optional": true + }, + "@opentelemetry/core": { + "optional": true + } + }, "devDependencies": { "@cucumber/cucumber": "^13.3.0", + "@opentelemetry/api": "^1.10.0", + "@opentelemetry/context-async-hooks": "^3.1.1", + "@opentelemetry/core": "^3.1.1", + "@opentelemetry/instrumentation-http": "^0.301.2", + "@opentelemetry/sdk-trace": "^3.1.1", "@types/chai": "^4.2.11", "@types/got": "^9.6.11", "@types/json-bigint": "^1.0.1", @@ -170,6 +187,23 @@ "access": "public" }, "types": "./dist/index.d.ts", + "exports": { + ".": { + "types": "./dist/index.d.ts", + "default": "./dist/index.js" + }, + "./otel": { + "types": "./dist/otel/index.d.ts", + "default": "./dist/otel/index.js" + } + }, + "typesVersions": { + "*": { + "otel": [ + "dist/otel/index.d.ts" + ] + } + }, "engines": { "node": ">=22 <=24" } diff --git a/src/otel/enrichment.ts b/src/otel/enrichment.ts new file mode 100644 index 00000000..b5c36f6e --- /dev/null +++ b/src/otel/enrichment.ts @@ -0,0 +1,76 @@ +/* + Copyright 2021 The CloudEvents Authors + SPDX-License-Identifier: Apache-2.0 +*/ + +import { Attributes, INVALID_SPAN_CONTEXT, Link, ROOT_CONTEXT, SpanContext, trace } from "@opentelemetry/api"; +import { CloudEventV1 } from ".."; +import { extractDistributedTracingExtension } from "./propagation"; + +/** + * Prepare CloudEvents attributes and links for an event or batch. + * For batches, common attributes belong on the span and per-event attributes on links. + * @param {CloudEventV1 | CloudEventV1[]} events a decoded event or batch + * @returns {object} span attributes and event links + */ +export function getCloudEventSpanOptions(events: CloudEventV1 | CloudEventV1[]): { + attributes: Attributes; links: Link[]; +} { + if (Array.isArray(events)) { + return batchSpanOptions(events.map((event) => ({ + creation: eventSpanContext(event), attributes: cloudEventAttributes(event), + }))); + } + const creation = eventSpanContext(events); + return { attributes: cloudEventAttributes(events), links: creation ? [{ context: creation }] : [] }; +} + +export function eventSpanContext(event: CloudEventV1): SpanContext | undefined { + return trace.getSpanContext(extractDistributedTracingExtension(ROOT_CONTEXT, event)); +} + +export function cloudEventAttributes(event: CloudEventV1): Attributes { + const attributes: Attributes = { + "cloudevents.event_id": event.id, + "cloudevents.event_source": event.source, + "cloudevents.event_spec_version": event.specversion, + "cloudevents.event_type": event.type, + }; + if (event.subject) { + attributes["cloudevents.event_subject"] = event.subject; + } + return attributes; +} + +export function batchSpanOptions(events: Array<{ creation?: SpanContext; attributes: Attributes }>): { + attributes: Attributes; links: Link[]; +} { + const shared: Attributes = {}; + if (events.length > 0) { + for (const [name, value] of Object.entries(events[0].attributes)) { + if (events.every(({ attributes }) => attributes[name] === value)) { + shared[name] = value; + } + } + } + + const withCreation: Link[] = []; + const withoutCreation: Link[] = []; + for (const { creation, attributes } of events) { + const own: Attributes = {}; + for (const [name, value] of Object.entries(attributes)) { + if (!(name in shared)) { + own[name] = value; + } + } + if (creation) { + withCreation.push({ context: creation, attributes: own }); + } else if (Object.keys(own).length > 0) { + // A link without a valid context can still carry per-event attributes. + withoutCreation.push({ context: INVALID_SPAN_CONTEXT, attributes: own }); + } + } + + // JS tracing SDKs drop the oldest links over their limit; keep creation contexts last. + return { attributes: shared, links: [...withoutCreation, ...withCreation] }; +} diff --git a/src/otel/index.ts b/src/otel/index.ts new file mode 100644 index 00000000..311d8171 --- /dev/null +++ b/src/otel/index.ts @@ -0,0 +1,8 @@ +/* + Copyright 2021 The CloudEvents Authors + SPDX-License-Identifier: Apache-2.0 +*/ + +export { injectDistributedTracingExtension, extractDistributedTracingExtension } from "./propagation"; +export { CloudEventPropagator } from "./propagator"; +export { getCloudEventSpanOptions } from "./enrichment"; diff --git a/src/otel/propagation.ts b/src/otel/propagation.ts new file mode 100644 index 00000000..6721f1a8 --- /dev/null +++ b/src/otel/propagation.ts @@ -0,0 +1,48 @@ +/* + Copyright 2021 The CloudEvents Authors + SPDX-License-Identifier: Apache-2.0 +*/ + +import { Context, TextMapGetter, defaultTextMapSetter } from "@opentelemetry/api"; +import { CloudEventPropagator } from "./propagator"; + +// The package root loads the bindings in the order they depend on each other. +import { CloudEvent, CloudEventV1 } from ".."; + +const propagator = new CloudEventPropagator(); +const getter: TextMapGetter> = { + get: (event, key) => typeof event[key] === "string" ? event[key] as string : undefined, + keys: (event) => Object.keys(event), +}; + +/** + * Copy a valid span context into a new CloudEvent, replacing its tracing extension. + * @param {Context} context the trace context to inject + * @param {CloudEvent} event the event to copy + * @returns {CloudEvent} an event copy for a valid span context, otherwise the original event + */ +export function injectDistributedTracingExtension(context: Context, event: CloudEvent): CloudEvent { + const extension: Record = {}; + propagator.inject(context, extension, defaultTextMapSetter); + if (!extension.traceparent) { + return event; + } + + // cloneWith() merges properties, so remove the previous tracestate before copying the extension. + const properties: Partial> = { ...event }; + delete properties.traceparent; + delete properties.tracestate; + Object.assign(properties, extension); + // Preserve events that were constructed without validation. + return new CloudEvent(properties, false); +} + +/** + * Extract the event's trace context while preserving other values from the supplied context. + * @param {Context} context the base context + * @param {CloudEventV1} event the event to read + * @returns {Context} the combined context, or the supplied context for a missing or invalid extension + */ +export function extractDistributedTracingExtension(context: Context, event: CloudEventV1): Context { + return propagator.extract(context, event, getter); +} diff --git a/src/otel/propagator.ts b/src/otel/propagator.ts new file mode 100644 index 00000000..32238cc4 --- /dev/null +++ b/src/otel/propagator.ts @@ -0,0 +1,58 @@ +/* + Copyright 2021 The CloudEvents Authors + SPDX-License-Identifier: Apache-2.0 +*/ + +import { + Context, ROOT_CONTEXT, TextMapGetter, TextMapPropagator, TextMapSetter, defaultTextMapGetter, trace, +} from "@opentelemetry/api"; +import { W3CTraceContextPropagator } from "@opentelemetry/core"; + +const w3c = new W3CTraceContextPropagator(); + +/** + * Propagate W3C trace context with a CloudEvents HTTP-header fallback. + */ +export class CloudEventPropagator implements TextMapPropagator { + /** + * Write W3C trace context into a mutable carrier. + * @param {Context} context the trace context to inject + * @param {object} carrier the destination carrier + * @param {TextMapSetter} setter the carrier's field writer + * @returns {void} + */ + inject(context: Context, carrier: T, setter: TextMapSetter): void { + w3c.inject(context, carrier, setter); + } + + /** + * Read W3C trace context, falling back to CloudEvents HTTP headers. + * @param {Context} context the base context + * @param {object} carrier the source carrier + * @param {TextMapGetter} getter the carrier's field reader + * @returns {Context} the extracted context, or the base context when both formats are absent or invalid + */ + extract(context: Context, carrier: T, getter: TextMapGetter): Context { + // Determine validity from the carrier, independently of the base context's span. + let extracted = w3c.extract(ROOT_CONTEXT, carrier, getter); + const primary = trace.getSpanContext(extracted); + if (!primary || !trace.isSpanContextValid(primary)) { + extracted = w3c.extract(ROOT_CONTEXT, { + traceparent: getter.get(carrier, "ce-traceparent"), + tracestate: getter.get(carrier, "ce-tracestate"), + }, defaultTextMapGetter); + } + const spanContext = trace.getSpanContext(extracted); + return spanContext && trace.isSpanContextValid(spanContext) + ? trace.setSpanContext(context, spanContext) + : context; + } + + /** + * List the W3C headers written by inject. + * @returns {string[]} propagation field names + */ + fields(): string[] { + return w3c.fields(); + } +} diff --git a/test/fixtures/otel_http.ts b/test/fixtures/otel_http.ts new file mode 100644 index 00000000..c0ea41fb --- /dev/null +++ b/test/fixtures/otel_http.ts @@ -0,0 +1,125 @@ +/* + Copyright 2021 The CloudEvents Authors + SPDX-License-Identifier: Apache-2.0 +*/ + +import assert from "assert"; +import { AddressInfo } from "net"; +import { IncomingHttpHeaders } from "http"; +import { ROOT_CONTEXT, SpanContext, SpanKind, TraceFlags, context, propagation, trace } from "@opentelemetry/api"; +import { AsyncLocalStorageContextManager } from "@opentelemetry/context-async-hooks"; +import { CompositePropagator, W3CBaggagePropagator } from "@opentelemetry/core"; +import { HttpInstrumentation } from "@opentelemetry/instrumentation-http"; +import { InMemorySpanExporter, SimpleSpanProcessor, TracerProvider } from "@opentelemetry/sdk-trace"; +import { CloudEventPropagator, extractDistributedTracingExtension } from "../../src/otel"; + +async function main() { + const scenario = process.argv[2]; + const exporter = new InMemorySpanExporter(); + const provider = new TracerProvider({ spanProcessors: [new SimpleSpanProcessor({ exporter })] }); + trace.setGlobalTracerProvider(provider); + context.setGlobalContextManager(new AsyncLocalStorageContextManager().enable()); + propagation.setGlobalPropagator(new CompositePropagator({ + propagators: [new CloudEventPropagator(), new W3CBaggagePropagator()], + })); + const instrumentation = new HttpInstrumentation(); + instrumentation.enable(); + + const http = await import("http"); + const { CloudEvent, HTTP, emitterFor, httpTransport } = await import("../../src"); + const creationTrace = "3".repeat(32); + const creationSpan = "4".repeat(16); + const creation = `00-${creationTrace}-${creationSpan}-01`; + const transportTrace = "1".repeat(32); + const transportSpan = "2".repeat(16); + const event = new CloudEvent({ + id: "order-1", type: "order.created", source: "/orders", data: { orderId: 1 }, + traceparent: creation, tracestate: "vendor=creation", + }); + let received: { headers: IncomingHttpHeaders; body: string; span?: SpanContext } | undefined; + const server = http.createServer((req, res) => { + const span = trace.getSpanContext(context.active()); + let body = ""; + req.setEncoding("utf8"); + req.on("data", (chunk) => { body += chunk; }); + req.on("end", () => { + received = { headers: req.headers, body, span }; + res.end("ok"); + }); + }); + try { + await new Promise((resolve) => server.listen(0, "127.0.0.1", resolve)); + const url = `http://127.0.0.1:${(server.address() as AddressInfo).port}/events`; + let senderSpanId: string | undefined; + if (scenario === "send") { + const parent = trace.setSpanContext(ROOT_CONTEXT, { + traceId: transportTrace, spanId: transportSpan, traceFlags: TraceFlags.SAMPLED, + }); + await provider.getTracer("test").startActiveSpan("sender", {}, parent, async (span) => { + senderSpanId = span.spanContext().spanId; + try { + await emitterFor(httpTransport(url))(event); + } finally { + span.end(); + } + }); + } else { + const message = scenario === "structured" ? HTTP.structured(event) : HTTP.binary(event); + const headers = new Headers(); + for (const [name, value] of Object.entries(message.headers)) { + assert.ok(typeof value === "string"); + headers.set(name, value); + } + if (scenario === "transport") { + headers.set("traceparent", `00-${transportTrace}-${transportSpan}-01`); + headers.set("tracestate", "vendor=transport"); + } else if (scenario === "fallback") { + headers.set("traceparent", "invalid"); + headers.set("tracestate", "vendor=transport"); + } + // Fetch uses Undici, so this sender does not get the HTTP module's automatic injection. + const response = await fetch(url, { method: "POST", headers, body: message.body as string }); + assert.equal(await response.text(), "ok"); + } + await provider.forceFlush(); + assert.ok(received?.span); + const servers = exporter.getFinishedSpans().filter((span) => span.kind === SpanKind.SERVER); + assert.equal(servers.length, 1); + const serverSpan = servers[0]; + assert.equal(received.span.spanId, serverSpan.spanContext().spanId); + + if (scenario === "send") { + const clients = exporter.getFinishedSpans().filter((span) => span.kind === SpanKind.CLIENT); + assert.equal(clients.length, 1); + const client = clients[0]; + assert.equal(client.spanContext().traceId, transportTrace); + assert.equal(client.parentSpanContext?.spanId, senderSpanId); + assert.equal(serverSpan.parentSpanContext?.spanId, client.spanContext().spanId); + assert.equal(received.headers.traceparent, `00-${transportTrace}-${client.spanContext().spanId}-01`); + assert.equal(received.headers["ce-traceparent"], creation); + assert.equal(received.headers["ce-tracestate"], "vendor=creation"); + assert.equal(event.traceparent, creation); + } else if (scenario === "structured") { + assert.equal(serverSpan.parentSpanContext, undefined); + const decoded = HTTP.toEvent({ headers: received.headers, body: received.body }); + assert.ok(!Array.isArray(decoded)); + const extracted = extractDistributedTracingExtension(ROOT_CONTEXT, decoded); + assert.equal(trace.getSpanContext(extracted)?.traceId, creationTrace); + } else { + const useTransport = scenario === "transport"; + assert.equal(serverSpan.spanContext().traceId, useTransport ? transportTrace : creationTrace); + assert.equal(serverSpan.parentSpanContext?.spanId, useTransport ? transportSpan : creationSpan); + assert.equal(serverSpan.parentSpanContext?.isRemote, true); + assert.equal(received.span.traceState?.serialize(), useTransport ? "vendor=transport" : "vendor=creation"); + } + } finally { + await new Promise((resolve, reject) => server.close((error) => error ? reject(error) : resolve())); + instrumentation.disable(); + await provider.shutdown(); + } +} + +main().catch((error) => { + console.error(error); + process.exitCode = 1; +}); diff --git a/test/integration/otel_enrichment_test.ts b/test/integration/otel_enrichment_test.ts new file mode 100644 index 00000000..8ac27d40 --- /dev/null +++ b/test/integration/otel_enrichment_test.ts @@ -0,0 +1,81 @@ +/* + Copyright 2021 The CloudEvents Authors + SPDX-License-Identifier: Apache-2.0 +*/ + +import "mocha"; +import { expect } from "chai"; +import { INVALID_SPAN_CONTEXT, context } from "@opentelemetry/api"; +import { CloudEvent } from "../../src"; +import { getCloudEventSpanOptions } from "../../src/otel"; + +const traceparent = `00-${"1".repeat(32)}-${"2".repeat(16)}-01`; +function event(extensions: Record = {}) { + return new CloudEvent({ id: "order-1", source: "/orders", type: "order.created", ...extensions }); +} + +describe("getCloudEventSpanOptions()", () => { + it("Describes a single event and links to its creation context without changing it", () => { + const original = event({ traceparent, subject: "orders/1" }); + const active = context.active(); + const result = getCloudEventSpanOptions(original); + expect(result.attributes).to.deep.equal({ + "cloudevents.event_id": "order-1", "cloudevents.event_source": "/orders", + "cloudevents.event_type": "order.created", "cloudevents.event_spec_version": "1.0", + "cloudevents.event_subject": "orders/1", + }); + expect(result.links).to.have.length(1); + expect(result.links[0].context).to.include({ traceId: "1".repeat(32), spanId: "2".repeat(16), isRemote: true }); + expect(original.traceparent).to.equal(traceparent); + expect(context.active()).to.equal(active); + }); + + it("Keeps attributes for a single event without a valid creation context", () => { + for (const extensions of [{}, { traceparent: "invalid" }]) { + const result = getCloudEventSpanOptions(event(extensions)); + expect(result.attributes["cloudevents.event_id"]).to.equal("order-1"); + expect(result.links).to.have.length(0); + } + }); + + it("Separates shared and per-event batch attributes, including events without context", () => { + const result = getCloudEventSpanOptions([ + event({ traceparent, subject: "orders/1" }), + event({ id: "order-2", traceparent: `00-${"3".repeat(32)}-${"4".repeat(16)}-01` }), + event({ id: "order-3" }), + ]); + expect(result.attributes).to.deep.equal({ + "cloudevents.event_source": "/orders", "cloudevents.event_type": "order.created", + "cloudevents.event_spec_version": "1.0", + }); + expect(result.links.map(({ context, attributes }) => [context.spanId, attributes])).to.deep.equal([ + [INVALID_SPAN_CONTEXT.spanId, { "cloudevents.event_id": "order-3" }], + ["2".repeat(16), { "cloudevents.event_id": "order-1", "cloudevents.event_subject": "orders/1" }], + ["4".repeat(16), { "cloudevents.event_id": "order-2" }], + ]); + }); + + it("Retains separate event links when events share a creation context", () => { + const result = getCloudEventSpanOptions([event({ traceparent }), event({ id: "order-2", traceparent })]); + expect(result.links).to.have.length(2); + expect(result.links.map((link) => link.attributes?.["cloudevents.event_id"])) + .to.deep.equal(["order-1", "order-2"]); + }); + + it("Keeps the creation link of a one-event batch with all attributes shared", () => { + const result = getCloudEventSpanOptions([event({ traceparent })]); + expect(result.attributes["cloudevents.event_id"]).to.equal("order-1"); + expect(result.links).to.have.length(1); + expect(result.links[0].attributes).to.deep.equal({}); + }); + + it("Does not invent a context link when all attributes can go on the span", () => { + const result = getCloudEventSpanOptions([event(), event()]); + expect(result.attributes["cloudevents.event_id"]).to.equal("order-1"); + expect(result.links).to.have.length(0); + }); + + it("Returns no attributes or links for an empty batch", () => { + expect(getCloudEventSpanOptions([])).to.deep.equal({ attributes: {}, links: [] }); + }); +}); diff --git a/test/integration/otel_http_test.ts b/test/integration/otel_http_test.ts new file mode 100644 index 00000000..4602d56c --- /dev/null +++ b/test/integration/otel_http_test.ts @@ -0,0 +1,32 @@ +/* + Copyright 2021 The CloudEvents Authors + SPDX-License-Identifier: Apache-2.0 +*/ + +import "mocha"; +import { execFile } from "child_process"; +import { join } from "path"; +import { promisify } from "util"; + +const run = promisify(execFile); + +describe("CloudEventPropagator with HTTP instrumentation", function() { + this.timeout(20000); + + const cases = { + creation: "Uses the CloudEvents creation context as the HTTP server span's parent", + transport: "Prefers the HTTP transport context over the event's creation context", + fallback: "Falls back to CloudEvents when the HTTP traceparent is invalid", + structured: "Extracts a structured event's context after decoding its body", + send: "Propagates the active send context while retaining the event's creation context", + }; + for (const [scenario, description] of Object.entries(cases)) { + it(description, async () => { + // Isolate module hooks and global OTel registration from the other integration tests. + await run(process.execPath, [ + "--require", require.resolve("ts-node/register"), + join(__dirname, "../fixtures/otel_http.ts"), scenario, + ], { timeout: 15000 }); + }); + } +}); diff --git a/test/integration/otel_propagation_test.ts b/test/integration/otel_propagation_test.ts new file mode 100644 index 00000000..6b857875 --- /dev/null +++ b/test/integration/otel_propagation_test.ts @@ -0,0 +1,104 @@ +/* + Copyright 2021 The CloudEvents Authors + SPDX-License-Identifier: Apache-2.0 +*/ + +import "mocha"; +import { expect } from "chai"; +import { ROOT_CONTEXT, TraceFlags, context, createTraceState, propagation, trace } from "@opentelemetry/api"; +import { CloudEvent } from "../../src"; +import { extractDistributedTracingExtension, injectDistributedTracingExtension } from "../../src/otel"; + +const traceId = "1".repeat(32); +const spanId = "2".repeat(16); +const traceparent = `00-${traceId}-${spanId}-01`; +const source = trace.setSpanContext(ROOT_CONTEXT, { + traceId, spanId, traceFlags: TraceFlags.SAMPLED, traceState: createTraceState("vendor=value"), +}); + +function event(extensions: Record = {}) { + return new CloudEvent({ + id: "order-1", type: "com.example.order.created", source: "/orders", data: { orderId: 1 }, ...extensions, + }); +} + +describe("CloudEvents trace context propagation without an OpenTelemetry SDK", () => { + it("Round-trips the supplied trace context without activating it or changing the event", () => { + const original = event({ custom: "kept" }); + const active = context.active(); + const injected = injectDistributedTracingExtension(source, original); + const extracted = extractDistributedTracingExtension(ROOT_CONTEXT, injected); + const result = trace.getSpanContext(extracted); + + expect(injected).not.to.equal(original); + expect(injected.traceparent).to.equal(traceparent); + expect(injected.tracestate).to.equal("vendor=value"); + expect(injected.data).to.equal(original.data); + expect(injected.custom).to.equal("kept"); + expect(original).not.to.have.property("traceparent"); + expect(original).not.to.have.property("tracestate"); + expect(result).to.include({ traceId, spanId, traceFlags: TraceFlags.SAMPLED, isRemote: true }); + expect(result?.traceState?.serialize()).to.equal("vendor=value"); + expect(context.active()).to.equal(active); + expect(trace.getSpanContext(ROOT_CONTEXT)).to.equal(undefined); + }); + + it("Explicitly replaces an existing extension and removes stale tracestate", () => { + const original = event({ traceparent: `00-${"3".repeat(32)}-${"4".repeat(16)}-00`, tracestate: "old=value" }); + const withoutState = trace.setSpanContext(ROOT_CONTEXT, { traceId, spanId, traceFlags: TraceFlags.SAMPLED }); + const injected = injectDistributedTracingExtension(withoutState, original); + + expect(injected.traceparent).to.equal(traceparent); + expect(injected).not.to.have.property("tracestate"); + expect(original.tracestate).to.equal("old=value"); + expect(original.traceparent).not.to.equal(traceparent); + }); + + it("Preserves the sampled flag when it is unset", () => { + const unsampled = trace.setSpanContext(ROOT_CONTEXT, { traceId, spanId, traceFlags: TraceFlags.NONE }); + const injected = injectDistributedTracingExtension(unsampled, event()); + expect(trace.getSpanContext(extractDistributedTracingExtension(ROOT_CONTEXT, injected))?.traceFlags) + .to.equal(TraceFlags.NONE); + }); + + for (const base of [ROOT_CONTEXT, trace.setSpanContext(ROOT_CONTEXT, { + traceId: "0".repeat(32), spanId, traceFlags: TraceFlags.SAMPLED, + })]) { + it("Returns the original event when the supplied context has no valid span context", () => { + const original = event({ traceparent, tracestate: "vendor=value" }); + expect(injectDistributedTracingExtension(base, original)).to.equal(original); + }); + } + + it("Does not revalidate an event constructed with validation disabled", () => { + const original = new CloudEvent({ id: "order-1", type: "example", source: "" }, false); + expect(injectDistributedTracingExtension(source, original).source).to.equal(""); + }); + + for (const extension of [undefined, "invalid", 42, [traceparent], `00-${"0".repeat(32)}-${spanId}-01`]) { + it(`Preserves the input context for an absent or invalid extension (${String(extension)})`, () => { + const original = event(extension === undefined ? {} : { traceparent: extension, tracestate: "vendor=value" }); + expect(extractDistributedTracingExtension(source, original)).to.equal(source); + }); + } + + it("Replaces only the trace context and preserves other context values", () => { + const baggage = propagation.createBaggage({ tenant: { value: "store-42" } }); + const base = propagation.setBaggage(source, baggage); + const otherTraceId = "3".repeat(32); + const extracted = extractDistributedTracingExtension(base, event({ + traceparent: `00-${otherTraceId}-${spanId}-01`, + })); + + expect(trace.getSpanContext(extracted)?.traceId).to.equal(otherTraceId); + expect(trace.getSpanContext(base)?.traceId).to.equal(traceId); + expect(propagation.getBaggage(extracted)).to.equal(baggage); + }); + + it("Accepts a plain event and ignores a non-string tracestate", () => { + const original = { ...event(), traceparent, tracestate: 42 }; + const extracted = extractDistributedTracingExtension(ROOT_CONTEXT, original); + expect(trace.getSpanContext(extracted)?.traceId).to.equal(traceId); + expect(trace.getSpanContext(extracted)?.traceState).to.equal(undefined); + }); +}); diff --git a/test/integration/otel_propagator_test.ts b/test/integration/otel_propagator_test.ts new file mode 100644 index 00000000..c6fc94c7 --- /dev/null +++ b/test/integration/otel_propagator_test.ts @@ -0,0 +1,129 @@ +/* + Copyright 2021 The CloudEvents Authors + SPDX-License-Identifier: Apache-2.0 +*/ + +import "mocha"; +import { expect } from "chai"; +import { + ROOT_CONTEXT, TraceFlags, createTraceState, defaultTextMapGetter, defaultTextMapSetter, propagation, trace, +} from "@opentelemetry/api"; +import { CompositePropagator, W3CBaggagePropagator, suppressTracing } from "@opentelemetry/core"; +import { CloudEventPropagator } from "../../src/otel"; + +const traceId = "1".repeat(32); +const spanId = "2".repeat(16); +const traceparent = `00-${traceId}-${spanId}-01`; +const creation = `00-${"3".repeat(32)}-${"4".repeat(16)}-00`; +const source = trace.setSpanContext(ROOT_CONTEXT, { + traceId, spanId, traceFlags: TraceFlags.SAMPLED, traceState: createTraceState("vendor=transport"), +}); +const propagator = new CloudEventPropagator(); + +describe("CloudEventPropagator", () => { + it("Prefers W3C context and its tracestate over CloudEvents headers", () => { + const result = propagator.extract(ROOT_CONTEXT, { + traceparent, tracestate: "vendor=transport", + "ce-traceparent": creation, "ce-tracestate": "vendor=creation", + }, defaultTextMapGetter); + expect(trace.getSpanContext(result)).to.include({ + traceId, spanId, isRemote: true, traceFlags: TraceFlags.SAMPLED, + }); + expect(trace.getSpanContext(result)?.traceState?.serialize()).to.equal("vendor=transport"); + }); + + it("Keeps tracestate paired with the selected traceparent", () => { + const result = propagator.extract(ROOT_CONTEXT, { + traceparent, "ce-traceparent": creation, "ce-tracestate": "vendor=creation", + }, defaultTextMapGetter); + expect(trace.getSpanContext(result)?.traceState).to.equal(undefined); + }); + + for (const primary of [undefined, "invalid", 42, `00-${"0".repeat(32)}-${spanId}-01`]) { + it(`Falls back to CloudEvents when W3C context is unusable (${String(primary)})`, () => { + const result = propagator.extract(ROOT_CONTEXT, { + traceparent: primary, tracestate: "vendor=transport", + "ce-traceparent": creation, "ce-tracestate": "vendor=creation", + }, defaultTextMapGetter); + expect(trace.getSpanContext(result)).to.include({ + traceId: "3".repeat(32), spanId: "4".repeat(16), traceFlags: TraceFlags.NONE, isRemote: true, + }); + expect(trace.getSpanContext(result)?.traceState?.serialize()).to.equal("vendor=creation"); + }); + } + + it("Extracts the creation context even when the base already has a valid span", () => { + const baggage = propagation.createBaggage({ tenant: { value: "store-42" } }); + const base = propagation.setBaggage(source, baggage); + const result = propagator.extract(base, { "ce-traceparent": creation }, defaultTextMapGetter); + expect(trace.getSpanContext(result)?.traceId).to.equal("3".repeat(32)); + expect(propagation.getBaggage(result)).to.equal(baggage); + expect(trace.getSpanContext(base)?.traceId).to.equal(traceId); + }); + + for (const value of [undefined, "invalid", 42, `00-${traceId}-${"0".repeat(16)}-01`]) { + it(`Returns the base context when neither format is usable (${String(value)})`, () => { + const result = propagator.extract(source, { + traceparent: value, "ce-traceparent": value, + }, defaultTextMapGetter); + expect(result).to.equal(source); + }); + } + + it("Accepts HTTP header arrays using the W3C parsing rules", () => { + const result = propagator.extract(ROOT_CONTEXT, { + "ce-traceparent": [creation], "ce-tracestate": ["vendor=creation", "other=value"], + }, defaultTextMapGetter); + expect(trace.getSpanContext(result)?.traceId).to.equal("3".repeat(32)); + expect(trace.getSpanContext(result)?.traceState?.serialize()).to.equal("vendor=creation,other=value"); + }); + + it("Uses the provided getter and setter for custom carriers and header casing", () => { + const carrier = new Map(); + const getter = { + get: (map: Map, key: string) => map.get(key.toUpperCase()), + keys: (map: Map) => [...map.keys()], + }; + const setter = { + set: (map: Map, key: string, value: string) => map.set(key.toUpperCase(), value), + }; + propagator.inject(source, carrier, setter); + expect(trace.getSpanContext(propagator.extract(ROOT_CONTEXT, carrier, getter))?.traceId).to.equal(traceId); + carrier.clear(); + carrier.set("CE-TRACEPARENT", creation); + expect(trace.getSpanContext(propagator.extract(ROOT_CONTEXT, carrier, getter))?.traceId).to.equal("3".repeat(32)); + }); + + it("Reuses a transport carrier while preserving its CloudEvents creation context", () => { + const carrier: Record = { + traceparent: creation, tracestate: "old=value", + "ce-traceparent": creation, "ce-tracestate": "vendor=creation", + }; + for (const field of propagator.fields()) delete carrier[field]; + const withoutState = trace.setSpanContext(ROOT_CONTEXT, { traceId, spanId, traceFlags: TraceFlags.SAMPLED }); + propagator.inject(withoutState, carrier, defaultTextMapSetter); + expect(carrier).to.deep.equal({ + traceparent, "ce-traceparent": creation, "ce-tracestate": "vendor=creation", + }); + }); + + it("Preserves the carrier when injection has no valid span or tracing is suppressed", () => { + for (const context of [ROOT_CONTEXT, suppressTracing(source)]) { + const carrier = { "ce-traceparent": creation }; + propagator.inject(context, carrier, defaultTextMapSetter); + expect(carrier).to.deep.equal({ "ce-traceparent": creation }); + } + }); + + it("Composes with W3C Baggage propagation", () => { + const combined = new CompositePropagator({ propagators: [propagator, new W3CBaggagePropagator()] }); + const result = combined.extract(ROOT_CONTEXT, { + "ce-traceparent": creation, baggage: "tenant=store-42", + }, defaultTextMapGetter); + expect(trace.getSpanContext(result)?.traceId).to.equal("3".repeat(32)); + expect(propagation.getBaggage(result)?.getEntry("tenant")?.value).to.equal("store-42"); + const carrier: Record = {}; + combined.inject(result, carrier, defaultTextMapSetter); + expect(carrier).to.deep.equal({ traceparent: creation, baggage: "tenant=store-42" }); + }); +});