@ddd-ts-kit/tracing 0.0.0-stage → 0.1.0

package/dist/testing/expected-span.d.ts

@@ -0,0 +1,17 @@
+import type { SpanNode } from './span-node.js';
+/**
+ * What a spec says of one span. The name and the children are exact: a span that is not
+ * listed is a mismatch, and so is a listed one that is missing. The rest is checked when
+ * given, except that a span is expected not to be an error unless `status` says so.
+ */
+export interface ExpectedSpan {
+    readonly name: string;
+    readonly kind?: SpanNode['kind'];
+    /** Default: anything but `ERROR`. */
+    readonly status?: SpanNode['status'];
+    /** The attributes that matter here. `undefined` expects the attribute to be absent. */
+    readonly attributes?: Readonly<Record<string, unknown>>;
+    /** In the order they start. Default: none. */
+    readonly children?: readonly ExpectedSpan[];
+}
+//# sourceMappingURL=expected-span.d.ts.map

package/dist/testing/expected-span.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"expected-span.d.ts","sourceRoot":"","sources":["../../src/testing/expected-span.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAE/C;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IACjC,qCAAqC;IACrC,QAAQ,CAAC,MAAM,CAAC,EAAE,QAAQ,CAAC,QAAQ,CAAC,CAAC;IACrC,uFAAuF;IACvF,QAAQ,CAAC,UAAU,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACxD,8CAA8C;IAC9C,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,YAAY,EAAE,CAAC;CAC7C"}

package/dist/testing/expected-span.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=expected-span.js.map

package/dist/testing/expected-span.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"expected-span.js","sourceRoot":"","sources":["../../src/testing/expected-span.ts"],"names":[],"mappings":""}

package/dist/testing/install-test-tracing.d.ts

@@ -0,0 +1,23 @@
+import { type Sampler, type SpanProcessor } from '@opentelemetry/sdk-trace-base';
+import type { SpanNode } from './span-node.js';
+export interface TestTracingOptions {
+    /** Run after the local root tracker and before the spans are collected, as `extraSpanProcessors` of `initTracing` are. */
+    readonly processors?: readonly SpanProcessor[];
+    /** Default: every trace is sampled. */
+    readonly sampler?: Sampler;
+}
+export interface TestTracing {
+    /** Runs the action and answers the spans that ended since it started, as trees. */
+    traceOf(action: () => unknown): Promise<SpanNode[]>;
+    /** Every span ended since the last `clear` or `traceOf`, as trees. */
+    spans(): SpanNode[];
+    clear(): void;
+    /** Gives the global tracer provider and context manager back. Call it when the spec is over. */
+    uninstall(): void;
+}
+/**
+ * Registers a real tracer provider that keeps the ended spans in memory, with the local root
+ * tracker of `initTracing`: what a spec then observes is what an exporter would be sent.
+ */
+export declare function installTestTracing(options?: TestTracingOptions): TestTracing;
+//# sourceMappingURL=install-test-tracing.d.ts.map

package/dist/testing/install-test-tracing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"install-test-tracing.d.ts","sourceRoot":"","sources":["../../src/testing/install-test-tracing.ts"],"names":[],"mappings":"AAEA,OAAO,EAIL,KAAK,OAAO,EACZ,KAAK,aAAa,EACnB,MAAM,+BAA+B,CAAC;AAEvC,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAI/C,MAAM,WAAW,kBAAkB;IACjC,0HAA0H;IAC1H,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,aAAa,EAAE,CAAC;IAC/C,uCAAuC;IACvC,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED,MAAM,WAAW,WAAW;IAC1B,mFAAmF;IACnF,OAAO,CAAC,MAAM,EAAE,MAAM,OAAO,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC;IACpD,sEAAsE;IACtE,KAAK,IAAI,QAAQ,EAAE,CAAC;IACpB,KAAK,IAAI,IAAI,CAAC;IACd,gGAAgG;IAChG,SAAS,IAAI,IAAI,CAAC;CACnB;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,GAAE,kBAAuB,GAAG,WAAW,CA6BhF"}

package/dist/testing/install-test-tracing.js

@@ -0,0 +1,48 @@
+import { context, trace } from '@opentelemetry/api';
+import { AsyncLocalStorageContextManager } from '@opentelemetry/context-async-hooks';
+import { BasicTracerProvider, InMemorySpanExporter, SimpleSpanProcessor, } from '@opentelemetry/sdk-trace-base';
+import { LocalRootTracker } from '../local-root/local-root-tracker.js';
+import { spanTreeOf } from './span-tree-of.js';
+import { StartOrder } from './start-order.js';
+/**
+ * Registers a real tracer provider that keeps the ended spans in memory, with the local root
+ * tracker of `initTracing`: what a spec then observes is what an exporter would be sent.
+ */
+export function installTestTracing(options = {}) {
+    const exporter = new InMemorySpanExporter();
+    const order = new StartOrder();
+    const provider = collectingProvider(options, order, exporter);
+    const spans = () => spanTreeOf(exporter.getFinishedSpans(), (spanId) => order.positionOf(spanId));
+    const clear = () => {
+        exporter.reset();
+        order.clear();
+    };
+    context.setGlobalContextManager(new AsyncLocalStorageContextManager().enable());
+    trace.setGlobalTracerProvider(provider);
+    return {
+        spans,
+        clear,
+        async traceOf(action) {
+            clear();
+            await action();
+            return spans();
+        },
+        uninstall() {
+            trace.disable();
+            context.disable();
+        },
+    };
+}
+function collectingProvider(options, order, exporter) {
+    const spanProcessors = [
+        new LocalRootTracker(),
+        order,
+        ...(options.processors ?? []),
+        new SimpleSpanProcessor(exporter),
+    ];
+    return new BasicTracerProvider({
+        spanProcessors,
+        ...(options.sampler === undefined ? {} : { sampler: options.sampler }),
+    });
+}
+//# sourceMappingURL=install-test-tracing.js.map

package/dist/testing/install-test-tracing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"install-test-tracing.js","sourceRoot":"","sources":["../../src/testing/install-test-tracing.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AACpD,OAAO,EAAE,+BAA+B,EAAE,MAAM,oCAAoC,CAAC;AACrF,OAAO,EACL,mBAAmB,EACnB,oBAAoB,EACpB,mBAAmB,GAGpB,MAAM,+BAA+B,CAAC;AACvC,OAAO,EAAE,gBAAgB,EAAE,MAAM,qCAAqC,CAAC;AAEvE,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC/C,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAmB9C;;;GAGG;AACH,MAAM,UAAU,kBAAkB,CAAC,OAAO,GAAuB,EAAE;IACjE,MAAM,QAAQ,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC5C,MAAM,KAAK,GAAG,IAAI,UAAU,EAAE,CAAC;IAE/B,MAAM,QAAQ,GAAG,kBAAkB,CAAC,OAAO,EAAE,KAAK,EAAE,QAAQ,CAAC,CAAC;IAC9D,MAAM,KAAK,GAAG,GAAe,EAAE,CAAC,UAAU,CAAC,QAAQ,CAAC,gBAAgB,EAAE,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,KAAK,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC;IAE9G,MAAM,KAAK,GAAG,GAAS,EAAE;QACvB,QAAQ,CAAC,KAAK,EAAE,CAAC;QACjB,KAAK,CAAC,KAAK,EAAE,CAAC;IAChB,CAAC,CAAC;IAEF,OAAO,CAAC,uBAAuB,CAAC,IAAI,+BAA+B,EAAE,CAAC,MAAM,EAAE,CAAC,CAAC;IAChF,KAAK,CAAC,uBAAuB,CAAC,QAAQ,CAAC,CAAC;IAExC,OAAO;QACL,KAAK;QACL,KAAK;QACL,KAAK,CAAC,OAAO,CAAC,MAAM;YAClB,KAAK,EAAE,CAAC;YACR,MAAM,MAAM,EAAE,CAAC;YAEf,OAAO,KAAK,EAAE,CAAC;QACjB,CAAC;QACD,SAAS;YACP,KAAK,CAAC,OAAO,EAAE,CAAC;YAChB,OAAO,CAAC,OAAO,EAAE,CAAC;QACpB,CAAC;KACF,CAAC;AACJ,CAAC;AAED,SAAS,kBAAkB,CACzB,OAA2B,EAC3B,KAAiB,EACjB,QAA8B;IAE9B,MAAM,cAAc,GAAG;QACrB,IAAI,gBAAgB,EAAE;QACtB,KAAK;QACL,GAAG,CAAC,OAAO,CAAC,UAAU,IAAI,EAAE,CAAC;QAC7B,IAAI,mBAAmB,CAAC,QAAQ,CAAC;KAClC,CAAC;IAEF,OAAO,IAAI,mBAAmB,CAAC;QAC7B,cAAc;QACd,GAAG,CAAC,OAAO,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE,CAAC;KACvE,CAAC,CAAC;AACL,CAAC"}

package/dist/testing/render-span-tree.d.ts

@@ -0,0 +1,8 @@
+import type { ExpectedSpan } from './expected-span.js';
+/**
+ * A tree as indented text, one span per line: `name [KIND] ERROR {key=value}`. Only the
+ * attributes named in `keys` are shown, so two trees rendered with the same keys compare line
+ * by line.
+ */
+export declare function renderSpanTree(spans: readonly ExpectedSpan[], keys?: readonly string[], depth?: number): string;
+//# sourceMappingURL=render-span-tree.d.ts.map

package/dist/testing/render-span-tree.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render-span-tree.d.ts","sourceRoot":"","sources":["../../src/testing/render-span-tree.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAEvD;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,SAAS,YAAY,EAAE,EAAE,IAAI,GAAE,SAAS,MAAM,EAAO,EAAE,KAAK,SAAI,GAAG,MAAM,CAK9G"}

package/dist/testing/render-span-tree.js

@@ -0,0 +1,23 @@
+/**
+ * A tree as indented text, one span per line: `name [KIND] ERROR {key=value}`. Only the
+ * attributes named in `keys` are shown, so two trees rendered with the same keys compare line
+ * by line.
+ */
+export function renderSpanTree(spans, keys = [], depth = 0) {
+    return spans
+        .flatMap((span) => [lineOf(span, keys, depth), renderSpanTree(span.children ?? [], keys, depth + 1)])
+        .filter((line) => line !== '')
+        .join('\n');
+}
+function lineOf(span, keys, depth) {
+    const attributes = keys
+        .filter((key) => span.attributes?.[key] !== undefined)
+        .map((key) => `${key}=${JSON.stringify(span.attributes?.[key])}`);
+    return [
+        `${'  '.repeat(depth)}${span.name}`,
+        ...(span.kind === undefined ? [] : [`[${span.kind}]`]),
+        ...(span.status === 'ERROR' ? ['ERROR'] : []),
+        ...(attributes.length === 0 ? [] : [`{${attributes.join(', ')}}`]),
+    ].join(' ');
+}
+//# sourceMappingURL=render-span-tree.js.map

package/dist/testing/render-span-tree.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"render-span-tree.js","sourceRoot":"","sources":["../../src/testing/render-span-tree.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,KAA8B,EAAE,IAAI,GAAsB,EAAE,EAAE,KAAK,GAAG,CAAC;IACpG,OAAO,KAAK;SACT,OAAO,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,MAAM,CAAC,IAAI,EAAE,IAAI,EAAE,KAAK,CAAC,EAAE,cAAc,CAAC,IAAI,CAAC,QAAQ,IAAI,EAAE,EAAE,IAAI,EAAE,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC;SACpG,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,KAAK,EAAE,CAAC;SAC7B,IAAI,CAAC,IAAI,CAAC,CAAC;AAChB,CAAC;AAED,SAAS,MAAM,CAAC,IAAkB,EAAE,IAAuB,EAAE,KAAa;IACxE,MAAM,UAAU,GAAG,IAAI;SACpB,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,IAAI,CAAC,UAAU,EAAE,CAAC,GAAG,CAAC,KAAK,SAAS,CAAC;SACrD,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,GAAG,IAAI,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,UAAU,EAAE,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC;IAEpE,OAAO;QACL,GAAG,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,IAAI,EAAE;QACnC,GAAG,CAAC,IAAI,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,IAAI,GAAG,CAAC,CAAC;QACtD,GAAG,CAAC,IAAI,CAAC,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QAC7C,GAAG,CAAC,UAAU,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;KACnE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACd,CAAC"}

package/dist/testing/span-mismatches.d.ts

@@ -0,0 +1,5 @@
+import type { ExpectedSpan } from './expected-span.js';
+import type { SpanNode } from './span-node.js';
+/** What differs between the spans found under one parent and the ones expected there, as sentences. */
+export declare function spanMismatches(actual: readonly SpanNode[], expected: readonly ExpectedSpan[], under?: string): string[];
+//# sourceMappingURL=span-mismatches.d.ts.map

package/dist/testing/span-mismatches.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"span-mismatches.d.ts","sourceRoot":"","sources":["../../src/testing/span-mismatches.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAE/C,uGAAuG;AACvG,wBAAgB,cAAc,CAC5B,MAAM,EAAE,SAAS,QAAQ,EAAE,EAC3B,QAAQ,EAAE,SAAS,YAAY,EAAE,EACjC,KAAK,SAAc,GAClB,MAAM,EAAE,CAeV"}

package/dist/testing/span-mismatches.js

@@ -0,0 +1,34 @@
+/** What differs between the spans found under one parent and the ones expected there, as sentences. */
+export function spanMismatches(actual, expected, under = 'the trace') {
+    const found = actual.map((span) => span.name).join(', ') || 'none';
+    const wanted = expected.map((span) => span.name).join(', ') || 'none';
+    if (found !== wanted) {
+        return [`under ${under}: expected the spans [${wanted}], found [${found}]`];
+    }
+    return expected.flatMap((span, index) => {
+        const node = actual[index];
+        return node === undefined
+            ? []
+            : [...ownMismatches(node, span), ...spanMismatches(node.children, span.children ?? [], `"${span.name}"`)];
+    });
+}
+function ownMismatches(actual, expected) {
+    const mismatches = [];
+    if (expected.kind !== undefined && expected.kind !== actual.kind) {
+        mismatches.push(`"${actual.name}": expected the kind ${expected.kind}, found ${actual.kind}`);
+    }
+    if (expected.status === undefined ? actual.status === 'ERROR' : expected.status !== actual.status) {
+        mismatches.push(`"${actual.name}": expected the status ${expected.status ?? 'not ERROR'}, found ${actual.status}`);
+    }
+    for (const [key, value] of Object.entries(expected.attributes ?? {})) {
+        const found = actual.attributes[key];
+        if (JSON.stringify(found) !== JSON.stringify(value)) {
+            mismatches.push(`"${actual.name}": expected ${key} to be ${shown(value)}, found ${shown(found)}`);
+        }
+    }
+    return mismatches;
+}
+function shown(value) {
+    return value === undefined ? 'absent' : JSON.stringify(value);
+}
+//# sourceMappingURL=span-mismatches.js.map

package/dist/testing/span-mismatches.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"span-mismatches.js","sourceRoot":"","sources":["../../src/testing/span-mismatches.ts"],"names":[],"mappings":"AAGA,uGAAuG;AACvG,MAAM,UAAU,cAAc,CAC5B,MAA2B,EAC3B,QAAiC,EACjC,KAAK,GAAG,WAAW;IAEnB,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,MAAM,CAAC;IACnE,MAAM,MAAM,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,MAAM,CAAC;IAEtE,IAAI,KAAK,KAAK,MAAM,EAAE,CAAC;QACrB,OAAO,CAAC,SAAS,KAAK,yBAAyB,MAAM,aAAa,KAAK,GAAG,CAAC,CAAC;IAC9E,CAAC;IAED,OAAO,QAAQ,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE;QACtC,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;QAE3B,OAAO,IAAI,KAAK,SAAS;YACvB,CAAC,CAAC,EAAE;YACJ,CAAC,CAAC,CAAC,GAAG,aAAa,CAAC,IAAI,EAAE,IAAI,CAAC,EAAE,GAAG,cAAc,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,QAAQ,IAAI,EAAE,EAAE,IAAI,IAAI,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC;IAC9G,CAAC,CAAC,CAAC;AACL,CAAC;AAED,SAAS,aAAa,CAAC,MAAgB,EAAE,QAAsB;IAC7D,MAAM,UAAU,GAAa,EAAE,CAAC;IAEhC,IAAI,QAAQ,CAAC,IAAI,KAAK,SAAS,IAAI,QAAQ,CAAC,IAAI,KAAK,MAAM,CAAC,IAAI,EAAE,CAAC;QACjE,UAAU,CAAC,IAAI,CAAC,IAAI,MAAM,CAAC,IAAI,wBAAwB,QAAQ,CAAC,IAAI,WAAW,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC;IAChG,CAAC;IAED,IAAI,QAAQ,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,QAAQ,CAAC,MAAM,KAAK,MAAM,CAAC,MAAM,EAAE,CAAC;QAClG,UAAU,CAAC,IAAI,CAAC,IAAI,MAAM,CAAC,IAAI,0BAA0B,QAAQ,CAAC,MAAM,IAAI,WAAW,WAAW,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC;IACrH,CAAC;IAED,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,UAAU,IAAI,EAAE,CAAC,EAAE,CAAC;QACrE,MAAM,KAAK,GAAG,MAAM,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC;QAErC,IAAI,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,KAAK,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,CAAC;YACpD,UAAU,CAAC,IAAI,CAAC,IAAI,MAAM,CAAC,IAAI,eAAe,GAAG,UAAU,KAAK,CAAC,KAAK,CAAC,WAAW,KAAK,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;QACpG,CAAC;IACH,CAAC;IAED,OAAO,UAAU,CAAC;AACpB,CAAC;AAED,SAAS,KAAK,CAAC,KAAc;IAC3B,OAAO,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;AAChE,CAAC"}

package/dist/testing/span-node.d.ts

@@ -0,0 +1,13 @@
+/** One span of a trace as plain data, with the spans it is the parent of in the order they started. */
+export interface SpanNode {
+    readonly name: string;
+    readonly kind: 'INTERNAL' | 'SERVER' | 'CLIENT' | 'PRODUCER' | 'CONSUMER';
+    readonly status: 'UNSET' | 'OK' | 'ERROR';
+    readonly attributes: Readonly<Record<string, unknown>>;
+    readonly traceId: string;
+    readonly spanId: string;
+    /** The trace ids the span links to. */
+    readonly links: readonly string[];
+    readonly children: readonly SpanNode[];
+}
+//# sourceMappingURL=span-node.d.ts.map

package/dist/testing/span-node.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"span-node.d.ts","sourceRoot":"","sources":["../../src/testing/span-node.ts"],"names":[],"mappings":"AAAA,uGAAuG;AACvG,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,UAAU,GAAG,QAAQ,GAAG,QAAQ,GAAG,UAAU,GAAG,UAAU,CAAC;IAC1E,QAAQ,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI,GAAG,OAAO,CAAC;IAC1C,QAAQ,CAAC,UAAU,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACvD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,uCAAuC;IACvC,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,QAAQ,CAAC,QAAQ,EAAE,SAAS,QAAQ,EAAE,CAAC;CACxC"}

package/dist/testing/span-node.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=span-node.js.map

package/dist/testing/span-node.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"span-node.js","sourceRoot":"","sources":["../../src/testing/span-node.ts"],"names":[],"mappings":""}

package/dist/testing/span-tree-of.d.ts

@@ -0,0 +1,8 @@
+import type { ReadableSpan } from '@opentelemetry/sdk-trace-base';
+import type { SpanNode } from './span-node.js';
+/**
+ * The ended spans as trees: a span whose parent is not among them (no parent, or one of
+ * another process) is a root. Roots and children come in the order given by `positionOf`.
+ */
+export declare function spanTreeOf(spans: readonly ReadableSpan[], positionOf: (spanId: string) => number): SpanNode[];
+//# sourceMappingURL=span-tree-of.d.ts.map

package/dist/testing/span-tree-of.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"span-tree-of.d.ts","sourceRoot":"","sources":["../../src/testing/span-tree-of.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAC;AAClE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAgB/C;;;GAGG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,SAAS,YAAY,EAAE,EAAE,UAAU,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,MAAM,GAAG,QAAQ,EAAE,CAiB7G"}

package/dist/testing/span-tree-of.js

@@ -0,0 +1,34 @@
+import { SpanKind, SpanStatusCode } from '@opentelemetry/api';
+const KINDS = {
+    [SpanKind.INTERNAL]: 'INTERNAL',
+    [SpanKind.SERVER]: 'SERVER',
+    [SpanKind.CLIENT]: 'CLIENT',
+    [SpanKind.PRODUCER]: 'PRODUCER',
+    [SpanKind.CONSUMER]: 'CONSUMER',
+};
+const STATUSES = {
+    [SpanStatusCode.UNSET]: 'UNSET',
+    [SpanStatusCode.OK]: 'OK',
+    [SpanStatusCode.ERROR]: 'ERROR',
+};
+/**
+ * The ended spans as trees: a span whose parent is not among them (no parent, or one of
+ * another process) is a root. Roots and children come in the order given by `positionOf`.
+ */
+export function spanTreeOf(spans, positionOf) {
+    const ordered = [...spans].sort((a, b) => positionOf(a.spanContext().spanId) - positionOf(b.spanContext().spanId));
+    const known = new Set(ordered.map((span) => span.spanContext().spanId));
+    const parentOf = (span) => span.parentSpanContext?.spanId;
+    const nodeOf = (span) => ({
+        name: span.name,
+        kind: KINDS[span.kind],
+        status: STATUSES[span.status.code],
+        attributes: { ...span.attributes },
+        traceId: span.spanContext().traceId,
+        spanId: span.spanContext().spanId,
+        links: span.links.map((link) => link.context.traceId),
+        children: ordered.filter((child) => parentOf(child) === span.spanContext().spanId).map(nodeOf),
+    });
+    return ordered.filter((span) => !known.has(parentOf(span) ?? '')).map(nodeOf);
+}
+//# sourceMappingURL=span-tree-of.js.map

package/dist/testing/span-tree-of.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"span-tree-of.js","sourceRoot":"","sources":["../../src/testing/span-tree-of.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAI9D,MAAM,KAAK,GAAiD;IAC1D,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,UAAU;IAC/B,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,QAAQ;IAC3B,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,QAAQ;IAC3B,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,UAAU;IAC/B,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,UAAU;CAChC,CAAC;AAEF,MAAM,QAAQ,GAAyD;IACrE,CAAC,cAAc,CAAC,KAAK,CAAC,EAAE,OAAO;IAC/B,CAAC,cAAc,CAAC,EAAE,CAAC,EAAE,IAAI;IACzB,CAAC,cAAc,CAAC,KAAK,CAAC,EAAE,OAAO;CAChC,CAAC;AAEF;;;GAGG;AACH,MAAM,UAAU,UAAU,CAAC,KAA8B,EAAE,UAAsC;IAC/F,MAAM,OAAO,GAAG,CAAC,GAAG,KAAK,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,UAAU,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,MAAM,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC;IACnH,MAAM,KAAK,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC;IACxE,MAAM,QAAQ,GAAG,CAAC,IAAkB,EAAsB,EAAE,CAAC,IAAI,CAAC,iBAAiB,EAAE,MAAM,CAAC;IAE5F,MAAM,MAAM,GAAG,CAAC,IAAkB,EAAY,EAAE,CAAC,CAAC;QAChD,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC;QACtB,MAAM,EAAE,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC;QAClC,UAAU,EAAE,EAAE,GAAG,IAAI,CAAC,UAAU,EAAE;QAClC,OAAO,EAAE,IAAI,CAAC,WAAW,EAAE,CAAC,OAAO;QACnC,MAAM,EAAE,IAAI,CAAC,WAAW,EAAE,CAAC,MAAM;QACjC,KAAK,EAAE,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC;QACrD,QAAQ,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,QAAQ,CAAC,KAAK,CAAC,KAAK,IAAI,CAAC,WAAW,EAAE,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC;KAC/F,CAAC,CAAC;IAEH,OAAO,OAAO,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;AAChF,CAAC"}

package/dist/testing/start-order.d.ts

@@ -0,0 +1,12 @@
+import type { Span } from '@opentelemetry/api';
+/** Span processor that remembers the order spans started in: start times alone can tie. */
+export declare class StartOrder {
+    private readonly positions;
+    onStart(span: Span): void;
+    onEnd(): void;
+    forceFlush(): Promise<void>;
+    shutdown(): Promise<void>;
+    positionOf(spanId: string): number;
+    clear(): void;
+}
+//# sourceMappingURL=start-order.d.ts.map

package/dist/testing/start-order.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"start-order.d.ts","sourceRoot":"","sources":["../../src/testing/start-order.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,oBAAoB,CAAC;AAE/C,2FAA2F;AAC3F,qBAAa,UAAU;IACrB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA6B;IAEvD,OAAO,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI,CAExB;IAED,KAAK,IAAI,IAAI,CAAG;IAEV,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CAAG;IAE9B,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,CAAG;IAElC,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAEjC;IAED,KAAK,IAAI,IAAI,CAEZ;CACF"}

package/dist/testing/start-order.js

@@ -0,0 +1,17 @@
+/** Span processor that remembers the order spans started in: start times alone can tie. */
+export class StartOrder {
+    positions = new Map();
+    onStart(span) {
+        this.positions.set(span.spanContext().spanId, this.positions.size);
+    }
+    onEnd() { }
+    async forceFlush() { }
+    async shutdown() { }
+    positionOf(spanId) {
+        return this.positions.get(spanId) ?? Number.MAX_SAFE_INTEGER;
+    }
+    clear() {
+        this.positions.clear();
+    }
+}
+//# sourceMappingURL=start-order.js.map

package/dist/testing/start-order.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"start-order.js","sourceRoot":"","sources":["../../src/testing/start-order.ts"],"names":[],"mappings":"AAEA,2FAA2F;AAC3F,MAAM,OAAO,UAAU;IACJ,SAAS,GAAG,IAAI,GAAG,EAAkB,CAAC;IAEvD,OAAO,CAAC,IAAU;QAChB,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,MAAM,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;IACrE,CAAC;IAED,KAAK,KAAU,CAAC;IAEhB,KAAK,CAAC,UAAU,KAAmB,CAAC;IAEpC,KAAK,CAAC,QAAQ,KAAmB,CAAC;IAElC,UAAU,CAAC,MAAc;QACvB,OAAO,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,MAAM,CAAC,gBAAgB,CAAC;IAC/D,CAAC;IAED,KAAK;QACH,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,CAAC;IACzB,CAAC;CACF"}

package/dist/testing.d.ts

@@ -0,0 +1,6 @@
+export type { ExpectedSpan } from './testing/expected-span.js';
+export { expectSpanTree } from './testing/expect-span-tree.js';
+export { installTestTracing, type TestTracing, type TestTracingOptions } from './testing/install-test-tracing.js';
+export { renderSpanTree } from './testing/render-span-tree.js';
+export type { SpanNode } from './testing/span-node.js';
+//# sourceMappingURL=testing.d.ts.map

package/dist/testing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"testing.d.ts","sourceRoot":"","sources":["../src/testing.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAC/D,OAAO,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAC/D,OAAO,EAAE,kBAAkB,EAAE,KAAK,WAAW,EAAE,KAAK,kBAAkB,EAAE,MAAM,mCAAmC,CAAC;AAClH,OAAO,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAC/D,YAAY,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC"}

package/dist/testing.js

@@ -0,0 +1,4 @@
+export { expectSpanTree } from './testing/expect-span-tree.js';
+export { installTestTracing } from './testing/install-test-tracing.js';
+export { renderSpanTree } from './testing/render-span-tree.js';
+//# sourceMappingURL=testing.js.map

package/dist/testing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"testing.js","sourceRoot":"","sources":["../src/testing.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAC/D,OAAO,EAAE,kBAAkB,EAA6C,MAAM,mCAAmC,CAAC;AAClH,OAAO,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC"}

package/dist/use-case/trace-use-cases.d.ts

@@ -0,0 +1,10 @@
+import { type BusMiddleware } from '@ddd-ts-kit/kernel';
+/**
+ * The bus middleware that makes one span per use case: `command PlaceOrder`, `query GetOrder`,
+ * with the bounded context of the handler and the outcome. A business refusal (`DomainError`)
+ * is an answer: the span says `refused` and the code, and is not an error. Anything else marks
+ * it failed. Put it after the authorization and outside the unit of work, as `kernelModule`
+ * does: a message refused by the guard never started, and the span covers the commit.
+ */
+export declare function traceUseCases(): BusMiddleware;
+//# sourceMappingURL=trace-use-cases.d.ts.map

package/dist/use-case/trace-use-cases.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace-use-cases.d.ts","sourceRoot":"","sources":["../../src/use-case/trace-use-cases.ts"],"names":[],"mappings":"AACA,OAAO,EAAqB,KAAK,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAM3E;;;;;;GAMG;AACH,wBAAgB,aAAa,IAAI,aAAa,CAsB7C"}

package/dist/use-case/trace-use-cases.js

@@ -0,0 +1,41 @@
+import { SpanKind } from '@opentelemetry/api';
+import { isUnexpectedError } from '@ddd-ts-kit/kernel';
+import { inSpan } from '../span/in-span.js';
+import { markSpanFailed } from '../span/mark-span-failed.js';
+import { OUTCOME_ATTRIBUTE } from '../span/outcome-attribute.js';
+import { refusalCode } from '../span/refusal-code.js';
+/**
+ * The bus middleware that makes one span per use case: `command PlaceOrder`, `query GetOrder`,
+ * with the bounded context of the handler and the outcome. A business refusal (`DomainError`)
+ * is an answer: the span says `refused` and the code, and is not an error. Anything else marks
+ * it failed. Put it after the authorization and outside the unit of work, as `kernelModule`
+ * does: a message refused by the guard never started, and the span covers the commit.
+ */
+export function traceUseCases() {
+    return (_message, next, info) => {
+        const attributes = {
+            'app.use_case.kind': info.kind,
+            'app.use_case.name': info.name,
+            ...(info.context === undefined ? {} : { 'app.context': info.context }),
+        };
+        const start = {
+            name: `${info.kind} ${info.name}`,
+            options: { kind: SpanKind.INTERNAL, attributes },
+            onFailure: refusedOrFailed,
+        };
+        return inSpan(start, async (span) => {
+            const result = await next();
+            span.setAttribute(OUTCOME_ATTRIBUTE, 'succeeded');
+            return result;
+        });
+    };
+}
+function refusedOrFailed(span, error) {
+    if (isUnexpectedError(error)) {
+        markSpanFailed(span, error);
+        span.setAttribute(OUTCOME_ATTRIBUTE, 'failed');
+        return;
+    }
+    span.setAttributes({ [OUTCOME_ATTRIBUTE]: 'refused', ...refusalCode(error) });
+}
+//# sourceMappingURL=trace-use-cases.js.map

package/dist/use-case/trace-use-cases.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace-use-cases.js","sourceRoot":"","sources":["../../src/use-case/trace-use-cases.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAa,MAAM,oBAAoB,CAAC;AACzD,OAAO,EAAE,iBAAiB,EAAsB,MAAM,oBAAoB,CAAC;AAC3E,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAC5C,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAC7D,OAAO,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AACjE,OAAO,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAEtD;;;;;;GAMG;AACH,MAAM,UAAU,aAAa;IAC3B,OAAO,CAAC,QAAQ,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE;QAC9B,MAAM,UAAU,GAAG;YACjB,mBAAmB,EAAE,IAAI,CAAC,IAAI;YAC9B,mBAAmB,EAAE,IAAI,CAAC,IAAI;YAC9B,GAAG,CAAC,IAAI,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,aAAa,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC;SACvE,CAAC;QAEF,MAAM,KAAK,GAAG;YACZ,IAAI,EAAE,GAAG,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,IAAI,EAAE;YACjC,OAAO,EAAE,EAAE,IAAI,EAAE,QAAQ,CAAC,QAAQ,EAAE,UAAU,EAAE;YAChD,SAAS,EAAE,eAAe;SAC3B,CAAC;QAEF,OAAO,MAAM,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE;YAClC,MAAM,MAAM,GAAG,MAAM,IAAI,EAAE,CAAC;YAE5B,IAAI,CAAC,YAAY,CAAC,iBAAiB,EAAE,WAAW,CAAC,CAAC;YAElD,OAAO,MAAM,CAAC;QAChB,CAAC,CAAC,CAAC;IACL,CAAC,CAAC;AACJ,CAAC;AAED,SAAS,eAAe,CAAC,IAAU,EAAE,KAAc;IACjD,IAAI,iBAAiB,CAAC,KAAK,CAAC,EAAE,CAAC;QAC7B,cAAc,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;QAC5B,IAAI,CAAC,YAAY,CAAC,iBAAiB,EAAE,QAAQ,CAAC,CAAC;QAE/C,OAAO;IACT,CAAC;IAED,IAAI,CAAC,aAAa,CAAC,EAAE,CAAC,iBAAiB,CAAC,EAAE,SAAS,EAAE,GAAG,WAAW,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;AAChF,CAAC"}

package/package.json

@@ -1,6 +1,77 @@
 {
   "name": "@ddd-ts-kit/tracing",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Non-invasive OpenTelemetry tracing: adapters are wrapped at the composition root, the domain never knows.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/gbourgeat/ddd-ts-kit.git",
+    "directory": "packages/tracing"
+  },
+  "homepage": "https://github.com/gbourgeat/ddd-ts-kit/tree/main/packages/tracing#readme",
+  "bugs": "https://github.com/gbourgeat/ddd-ts-kit/issues",
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./node": {
+      "types": "./dist/node.d.ts",
+      "default": "./dist/node.js"
+    },
+    "./testing": {
+      "types": "./dist/testing.d.ts",
+      "default": "./dist/testing.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@ddd-ts-kit/kernel": "0.1.0"
+  },
+  "peerDependencies": {
+    "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/auto-instrumentations-node": ">=0.60.0",
+    "@opentelemetry/context-async-hooks": ">=2.0.0",
+    "@opentelemetry/exporter-trace-otlp-http": ">=0.200.0",
+    "@opentelemetry/sdk-node": ">=0.200.0",
+    "@opentelemetry/sdk-trace-base": ">=2.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@opentelemetry/sdk-node": {
+      "optional": true
+    },
+    "@opentelemetry/auto-instrumentations-node": {
+      "optional": true
+    },
+    "@opentelemetry/exporter-trace-otlp-http": {
+      "optional": true
+    },
+    "@opentelemetry/sdk-trace-base": {
+      "optional": true
+    },
+    "@opentelemetry/context-async-hooks": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@ddd-ts-kit/audit": "0.1.0",
+    "@ddd-ts-kit/di": "0.1.0",
+    "@ddd-ts-kit/events": "0.1.0",
+    "@ddd-ts-kit/http": "0.1.0",
+    "@ddd-ts-kit/scheduling": "0.1.0",
+    "@opentelemetry/api": "^1.9.1",
+    "@opentelemetry/auto-instrumentations-node": "latest",
+    "@opentelemetry/context-async-hooks": "^2.0.0",
+    "@opentelemetry/exporter-trace-otlp-http": "^0.223.0",
+    "@opentelemetry/sdk-node": "^0.223.0",
+    "@opentelemetry/sdk-trace-base": "^2.0.0"
+  }
+}