@ohos-ports/dxos-tracing 0.11.1-beta.0

package/src/trace-processor.ts

@@ -0,0 +1,82 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import type { AddLinkOptions } from './api';
+import { BUFFERED_PREFIX, BufferingTracingBackend } from './buffering-backend';
+import { DiagnosticsManager } from './diagnostic';
+import { DiagnosticsChannel } from './diagnostics-channel';
+import { RemoteMetrics } from './remote/metrics';
+import type { RemoteSpan, StartSpanOptions, TracingBackend } from './tracing-types';
+
+export class TraceProcessor {
+  public readonly diagnostics = new DiagnosticsManager();
+  public readonly diagnosticsChannel = new DiagnosticsChannel();
+  public readonly remoteMetrics = new RemoteMetrics();
+
+  readonly #bufferingBackend = new BufferingTracingBackend();
+  #activeBackend: TracingBackend = this.#bufferingBackend;
+
+  /**
+   * Tracing backend. Initially a buffering backend that records spans;
+   * once the observability package sets a real backend, the buffer is drained
+   * and a thin translating wrapper is installed that resolves stale buffered
+   * parent IDs still held by in-flight {@link Context} objects.
+   *
+   * The wrapper only allocates when a `buffered-*` parent is actually encountered;
+   * the common path is a single `startsWith` check and direct passthrough.
+   */
+  get tracingBackend(): TracingBackend {
+    return this.#activeBackend;
+  }
+
+  set tracingBackend(backend: TracingBackend | undefined) {
+    if (!backend || backend === this.#bufferingBackend) {
+      this.#bufferingBackend.clear();
+      this.#activeBackend = this.#bufferingBackend;
+      return;
+    }
+    const idMap = this.#bufferingBackend.drain(backend);
+    this.#activeBackend = {
+      startSpan: (options: StartSpanOptions): RemoteSpan => {
+        const parent = options.parentContext;
+        if (parent?.traceparent.startsWith(BUFFERED_PREFIX)) {
+          const translated = idMap.get(parent.traceparent);
+          if (translated) {
+            return backend.startSpan({ ...options, parentContext: translated });
+          }
+        }
+        return backend.startSpan(options);
+      },
+    };
+  }
+
+  private _instanceTag: string | null = null;
+
+  constructor() {
+    if (DiagnosticsChannel.supported) {
+      this.diagnosticsChannel.serve(this.diagnostics);
+    }
+    this.diagnosticsChannel.unref();
+  }
+
+  setInstanceTag(tag: string): void {
+    this._instanceTag = tag;
+    this.diagnostics.setInstanceTag(tag);
+  }
+
+  // TODO(burdon): Not implemented.
+  addLink(parent: any, child: any, opts: AddLinkOptions): void {}
+}
+
+export const TRACE_PROCESSOR: TraceProcessor = ((globalThis as any).TRACE_PROCESSOR ??= new TraceProcessor());
+
+export const sanitizeClassName = (className: string) => {
+  let name = className.replace(/^_+/, '');
+  const SANITIZE_REGEX = /[^_](\d+)$/;
+  const m = name.match(SANITIZE_REGEX);
+  if (m) {
+    name = name.slice(0, -m[1].length);
+  }
+  return name;
+};

package/src/tracing-types.ts

@@ -0,0 +1,77 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { type TraceContextData } from '@dxos/context';
+
+/**
+ * Opaque span handle returned by {@link TracingBackend.startSpan}.
+ *
+ * The `spanContext` field carries W3C trace context strings that are stored
+ * on the DXOS {@link Context} via `TRACE_SPAN_ATTRIBUTE`. Because these are
+ * plain strings (not live runtime objects), they survive after the span ends
+ * and across serialization boundaries.
+ */
+export type RemoteSpan = {
+  /** Signal that the span has ended. Must be called exactly once. */
+  end: (endTime?: number) => void;
+
+  /** Record an error on the span (e.g., OTEL `span.recordException` + `setStatus`). */
+  setError?: (err: unknown) => void;
+
+  /**
+   * W3C trace context identifying this span.
+   *
+   * Stored on the DXOS `Context` attribute (`TRACE_SPAN_ATTRIBUTE`) so that
+   * child `@trace.span()` methods can read it and pass it as
+   * {@link StartSpanOptions.parentContext} to create properly-parented spans.
+   */
+  spanContext?: TraceContextData;
+};
+
+/**
+ * Options passed to {@link TracingBackend.startSpan}.
+ */
+export type StartSpanOptions = {
+  /** Human-readable span name, typically `ClassName.methodName`. */
+  name: string;
+  /** Span category (e.g., `'function'`, `'rpc'`). */
+  op?: string;
+  /** Key-value attributes attached to the span. */
+  attributes?: Record<string, any>;
+
+  /**
+   * W3C trace context of the parent span.
+   *
+   * The backend extracts the trace/span IDs from these strings to establish
+   * parent-child relationships. When `undefined`, the backend creates a root span.
+   */
+  parentContext?: TraceContextData;
+
+  /**
+   * Epoch-millisecond timestamp for the span start.
+   * Used by the buffering backend to preserve original timing when replaying spans.
+   * When `undefined`, the backend uses the current time.
+   */
+  startTime?: number;
+};
+
+/**
+ * Backend-agnostic tracing interface implemented by the observability package
+ * and registered on `TRACE_PROCESSOR.tracingBackend`.
+ *
+ * The backend receives and returns {@link TraceContextData} (W3C strings) —
+ * no opaque runtime objects cross the interface boundary. The OTEL backend
+ * performs `propagation.extract/inject` internally in {@link startSpan}.
+ */
+export interface TracingBackend {
+  /**
+   * Create a new span.
+   *
+   * The backend should:
+   * 1. Extract the parent from `options.parentContext` (if present).
+   * 2. Create a span as a child of that parent.
+   * 3. Inject the new span's identity into the returned `spanContext`.
+   */
+  startSpan: (options: StartSpanOptions) => RemoteSpan;
+}

package/src/tracing.test.ts

@@ -0,0 +1,296 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import { afterEach, beforeEach, describe, test } from 'vitest';
+
+import { Context, TRACE_SPAN_ATTRIBUTE, type TraceContextData } from '@dxos/context';
+
+import { trace } from './api';
+import { TRACE_PROCESSOR } from './trace-processor';
+import type { RemoteSpan, StartSpanOptions, TracingBackend } from './tracing-types';
+
+type SpanRecord = {
+  options: StartSpanOptions;
+  ended: boolean;
+  endTime?: number;
+  error?: unknown;
+  spanContext: TraceContextData;
+};
+
+let spanCounter = 0;
+
+const createMockBackend = (): { backend: TracingBackend; spans: SpanRecord[] } => {
+  const spans: SpanRecord[] = [];
+
+  const backend: TracingBackend = {
+    startSpan: (options: StartSpanOptions): RemoteSpan => {
+      const record: SpanRecord = {
+        options,
+        ended: false,
+        spanContext: {
+          traceparent: `00-aaaa0000aaaa0000aaaa0000aaaa0000-${String(++spanCounter).padStart(16, '0')}-01`,
+        },
+      };
+      spans.push(record);
+      return {
+        end: (endTime?: number) => {
+          record.ended = true;
+          record.endTime = endTime;
+        },
+        setError: (err: unknown) => {
+          record.error = err;
+        },
+        spanContext: record.spanContext,
+      };
+    },
+  };
+
+  return { backend, spans };
+};
+
+//
+// Manual span tests
+//
+
+describe('manual spans', () => {
+  let savedBackend: typeof TRACE_PROCESSOR.tracingBackend;
+
+  beforeEach(() => {
+    savedBackend = TRACE_PROCESSOR.tracingBackend;
+    spanCounter = 0;
+  });
+
+  afterEach(() => {
+    TRACE_PROCESSOR.tracingBackend = savedBackend;
+  });
+
+  test('spanStart nests under the parent context and spanEnd ends the span', ({ expect }) => {
+    const { backend, spans } = createMockBackend();
+    TRACE_PROCESSOR.tracingBackend = backend;
+
+    const parentTrace: TraceContextData = {
+      traceparent: '00-bbbb0000bbbb0000bbbb0000bbbb0000-cccc0000cccc0000-01',
+    };
+    const parentCtx = new Context({ attributes: { [TRACE_SPAN_ATTRIBUTE]: parentTrace } });
+
+    const childCtx = trace.spanStart({ id: 'op-1', instance: {}, methodName: 'work', parentCtx });
+
+    const span = spans.find((record) => record.options.name.endsWith('.work'));
+    expect(span).toBeDefined();
+    expect(span!.options.parentContext?.traceparent).toBe(parentTrace.traceparent);
+
+    // The returned ctx carries the new span's trace context so downstream spans nest under it.
+    expect(childCtx?.getAttribute(TRACE_SPAN_ATTRIBUTE)?.traceparent).toBe(span!.spanContext.traceparent);
+
+    expect(span!.ended).toBe(false);
+    trace.spanEnd('op-1');
+    expect(span!.ended).toBe(true);
+  });
+
+  test('spanStart with showInRemoteTracing:false creates no remote span and returns parentCtx unchanged', ({
+    expect,
+  }) => {
+    const { backend, spans } = createMockBackend();
+    TRACE_PROCESSOR.tracingBackend = backend;
+
+    const parentCtx = new Context();
+    const result = trace.spanStart({
+      id: 'op-2',
+      instance: {},
+      methodName: 'work',
+      parentCtx,
+      showInRemoteTracing: false,
+    });
+
+    expect(result).toBe(parentCtx);
+    expect(spans.find((record) => record.options.name.endsWith('.work'))).toBeUndefined();
+  });
+
+  test('duplicate spanStart id returns parentCtx without starting a second span', ({ expect }) => {
+    const { backend, spans } = createMockBackend();
+    TRACE_PROCESSOR.tracingBackend = backend;
+
+    const parentCtx = new Context();
+    trace.spanStart({ id: 'op-3', instance: {}, methodName: 'work', parentCtx });
+    const secondResult = trace.spanStart({ id: 'op-3', instance: {}, methodName: 'work', parentCtx });
+
+    expect(secondResult).toBe(parentCtx);
+    expect(spans.filter((record) => record.options.name.endsWith('.work'))).toHaveLength(1);
+
+    trace.spanEnd('op-3');
+  });
+});
+
+//
+// Buffering backend tests
+//
+
+describe('buffering backend', () => {
+  let savedBackend: typeof TRACE_PROCESSOR.tracingBackend;
+
+  beforeEach(() => {
+    savedBackend = TRACE_PROCESSOR.tracingBackend;
+    TRACE_PROCESSOR.tracingBackend = undefined;
+    spanCounter = 0;
+  });
+
+  afterEach(() => {
+    TRACE_PROCESSOR.tracingBackend = savedBackend;
+  });
+
+  test('buffered spans are replayed into real backend on drain', async ({ expect }) => {
+    const parentCtx = new Context();
+
+    class Svc {
+      @trace.span()
+      async work(ctx: Context) {}
+    }
+
+    const svc = new Svc();
+    await svc.work(parentCtx);
+
+    const { backend, spans } = createMockBackend();
+    TRACE_PROCESSOR.tracingBackend = backend;
+
+    expect(spans.length).toBeGreaterThanOrEqual(1);
+    const workSpan = spans.find((span) => span.options.name === 'Svc.work');
+    expect(workSpan).toBeDefined();
+    expect(workSpan!.ended).toBe(true);
+  });
+
+  test('parent-child hierarchy is preserved across drain', ({ expect }) => {
+    class Svc {
+      @trace.span()
+      async parent(ctx: Context) {
+        await this.child(ctx);
+      }
+
+      @trace.span()
+      async child(ctx: Context) {}
+    }
+
+    const svc = new Svc();
+    void svc.parent(new Context());
+
+    const { backend, spans } = createMockBackend();
+    TRACE_PROCESSOR.tracingBackend = backend;
+
+    const parentSpan = spans.find((span) => span.options.name === 'Svc.parent');
+    const childSpan = spans.find((span) => span.options.name === 'Svc.child');
+    expect(parentSpan).toBeDefined();
+    expect(childSpan).toBeDefined();
+    expect(childSpan!.options.parentContext?.traceparent).toBe(parentSpan!.spanContext.traceparent);
+  });
+
+  test('stale buffered parent IDs on in-flight contexts are translated post-drain', async ({ expect }) => {
+    let capturedCtx: Context | undefined;
+
+    class Svc {
+      @trace.span()
+      async setup(ctx: Context) {
+        capturedCtx = ctx;
+      }
+
+      @trace.span()
+      async laterWork(ctx: Context) {}
+    }
+
+    const svc = new Svc();
+    await svc.setup(new Context());
+    expect(capturedCtx).toBeDefined();
+
+    // Now register the real backend.
+    const { backend, spans } = createMockBackend();
+    TRACE_PROCESSOR.tracingBackend = backend;
+
+    // The capturedCtx carries a buffered-* traceparent from the setup span.
+    // Calling laterWork with it should translate the stale buffered ID.
+    await svc.laterWork(capturedCtx!);
+
+    const setupSpan = spans.find((span) => span.options.name === 'Svc.setup');
+    const laterSpan = spans.find((span) => span.options.name === 'Svc.laterWork');
+    expect(setupSpan).toBeDefined();
+    expect(laterSpan).toBeDefined();
+    expect(laterSpan!.options.parentContext?.traceparent).toBe(setupSpan!.spanContext.traceparent);
+  });
+
+  test('errors and end() are replayed on drain', async ({ expect }) => {
+    const testError = new Error('boom');
+
+    class Svc {
+      @trace.span()
+      async failingWork(ctx: Context) {
+        throw testError;
+      }
+    }
+
+    const svc = new Svc();
+    await svc.failingWork(new Context()).catch(() => {});
+
+    const { backend, spans } = createMockBackend();
+    TRACE_PROCESSOR.tracingBackend = backend;
+
+    const failSpan = spans.find((span) => span.options.name === 'Svc.failingWork');
+    expect(failSpan).toBeDefined();
+    expect(failSpan!.error).toBe(testError);
+    expect(failSpan!.ended).toBe(true);
+  });
+
+  test('still-open spans forward end() to real backend after drain', async ({ expect }) => {
+    let resolveWork: () => void;
+    const workPromise = new Promise<void>((resolve) => {
+      resolveWork = resolve;
+    });
+
+    class Svc {
+      @trace.span()
+      async longWork(ctx: Context) {
+        await workPromise;
+      }
+    }
+
+    const svc = new Svc();
+    const done = svc.longWork(new Context());
+
+    const { backend, spans } = createMockBackend();
+    TRACE_PROCESSOR.tracingBackend = backend;
+
+    const longSpan = spans.find((span) => span.options.name === 'Svc.longWork');
+    expect(longSpan).toBeDefined();
+    expect(longSpan!.ended).toBe(false);
+
+    resolveWork!();
+    await done;
+
+    expect(longSpan!.ended).toBe(true);
+  });
+
+  test('replayed spans preserve original start and end timestamps', async ({ expect }) => {
+    const beforeStart = Date.now();
+
+    class Svc {
+      @trace.span()
+      async work(ctx: Context) {}
+    }
+
+    const svc = new Svc();
+    await svc.work(new Context());
+
+    const afterEnd = Date.now();
+
+    const { backend, spans } = createMockBackend();
+    TRACE_PROCESSOR.tracingBackend = backend;
+
+    const workSpan = spans.find((span) => span.options.name === 'Svc.work');
+    expect(workSpan).toBeDefined();
+
+    expect(workSpan!.options.startTime).toBeTypeOf('number');
+    expect(workSpan!.options.startTime).toBeGreaterThanOrEqual(beforeStart);
+    expect(workSpan!.options.startTime).toBeLessThanOrEqual(afterEnd);
+
+    expect(workSpan!.endTime).toBeTypeOf('number');
+    expect(workSpan!.endTime).toBeGreaterThanOrEqual(workSpan!.options.startTime!);
+    expect(workSpan!.endTime).toBeLessThanOrEqual(afterEnd);
+  });
+});

package/src/util.ts

@@ -0,0 +1,6 @@
+// TODO(dmaretskyi): Use UUID.
+//
+// Copyright 2024 DXOS.org
+//
+
+export const createId = () => Math.random().toString(36).slice(2);