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

package/src/api.ts

@@ -0,0 +1,204 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import { Context, TRACE_SPAN_ATTRIBUTE } from '@dxos/context';
+import { type MaybePromise } from '@dxos/util';
+
+import { TRACE_PROCESSOR, sanitizeClassName } from './trace-processor';
+import type { RemoteSpan } from './tracing-types';
+
+/** localStorage key that switches the browser OTEL sampler from 30% to 100%. */
+export const TRACE_ALL_KEY = 'dxos.debug.traceAll';
+
+const mark = (name: string) => {
+  performance.mark(name);
+};
+
+export type SpanOptions = {
+  showInBrowserTimeline?: boolean;
+  /** When false the span is not exported to remote OTLP collectors. Defaults to true. */
+  showInRemoteTracing?: boolean;
+  op?: string;
+  attributes?: Record<string, any>;
+};
+
+/**
+ * Decorator that creates a span for the execution duration of the decorated method.
+ * Calls the TracingBackend directly; no custom TracingSpan objects.
+ */
+const span =
+  ({ showInBrowserTimeline = false, showInRemoteTracing = true, op, attributes }: SpanOptions = {}) =>
+  (target: any, propertyKey: string, descriptor: TypedPropertyDescriptor<(...args: any) => any>) => {
+    const method = descriptor.value!;
+
+    descriptor.value = async function (this: any, ...args: any) {
+      const parentCtx = args[0] instanceof Context ? args[0] : null;
+      const startTs = performance.now();
+
+      const parentSpanContext = parentCtx?.getAttribute(TRACE_SPAN_ATTRIBUTE);
+
+      const className = sanitizeClassName(target.constructor?.name ?? 'unknown');
+      const spanName = `${className}.${propertyKey}`;
+
+      const spanAttributes: Record<string, any> = {};
+      if (attributes) {
+        for (const [key, value] of Object.entries(attributes)) {
+          spanAttributes[key.startsWith('ctx.') ? key : `ctx.${key}`] = value;
+        }
+      }
+
+      const remoteSpan = showInRemoteTracing
+        ? TRACE_PROCESSOR.tracingBackend?.startSpan({
+            name: spanName,
+            op: op ?? 'function',
+            attributes: spanAttributes,
+            parentContext: parentSpanContext,
+          })
+        : undefined;
+
+      let callArgs = args;
+      if (parentCtx) {
+        const childCtx =
+          remoteSpan?.spanContext != null
+            ? parentCtx.derive({ attributes: { [TRACE_SPAN_ATTRIBUTE]: remoteSpan.spanContext } })
+            : parentCtx.derive();
+        callArgs = [childCtx, ...args.slice(1)];
+      }
+
+      try {
+        return await method.apply(this, callArgs);
+      } catch (err) {
+        remoteSpan?.setError?.(err);
+        throw err;
+      } finally {
+        remoteSpan?.end();
+        if (showInBrowserTimeline && typeof globalThis?.performance?.measure === 'function') {
+          performance.measure(spanName, { start: startTs, end: performance.now() });
+        }
+      }
+    };
+  };
+
+const manualSpans = new Map<string, RemoteSpan>();
+const manualSpanTimestamps = new Map<string, { name: string; startTs: number }>();
+
+export type ManualSpanParams = {
+  id: string;
+  instance: any;
+  methodName: string;
+  parentCtx: Context | null;
+  showInBrowserTimeline?: boolean;
+  showInRemoteTracing?: boolean;
+  op?: string;
+  attributes?: Record<string, any>;
+};
+
+/**
+ * Creates a span that must be ended manually.
+ *
+ * Returns a child Context that carries the new span's `TRACE_SPAN_ATTRIBUTE`.
+ * Callers should use the returned ctx for downstream work so that nested
+ * `@trace.span` methods and RPC calls inherit this span as their parent
+ * and land in the same trace (rather than starting a new root).
+ *
+ * When the new span cannot be created (duplicate id, no backend, or
+ * `showInRemoteTracing: false`), the parentCtx is returned unchanged.
+ */
+const spanStart = (params: ManualSpanParams): Context | null => {
+  if (manualSpans.has(params.id) || manualSpanTimestamps.has(params.id)) {
+    return params.parentCtx;
+  }
+
+  const className = sanitizeClassName(params.instance?.constructor?.name ?? 'unknown');
+  const spanName = `${className}.${params.methodName}`;
+
+  if (params.showInBrowserTimeline) {
+    manualSpanTimestamps.set(params.id, { name: spanName, startTs: performance.now() });
+  }
+
+  if (params.showInRemoteTracing === false || !TRACE_PROCESSOR.tracingBackend) {
+    return params.parentCtx;
+  }
+
+  const parentSpanContext = params.parentCtx?.getAttribute(TRACE_SPAN_ATTRIBUTE);
+
+  const spanAttributes: Record<string, any> = {};
+  if (params.attributes) {
+    for (const [key, value] of Object.entries(params.attributes)) {
+      spanAttributes[key.startsWith('ctx.') ? key : `ctx.${key}`] = value;
+    }
+  }
+
+  const remoteSpan = TRACE_PROCESSOR.tracingBackend.startSpan({
+    name: spanName,
+    op: params.op ?? 'function',
+    attributes: spanAttributes,
+    parentContext: parentSpanContext,
+  });
+  manualSpans.set(params.id, remoteSpan);
+
+  if (params.parentCtx && remoteSpan.spanContext != null) {
+    return params.parentCtx.derive({ attributes: { [TRACE_SPAN_ATTRIBUTE]: remoteSpan.spanContext } });
+  }
+  return params.parentCtx;
+};
+
+/**
+ * Ends a span that was started manually.
+ */
+const spanEnd = (id: string) => {
+  const remoteSpan = manualSpans.get(id);
+  if (remoteSpan) {
+    remoteSpan.end();
+    manualSpans.delete(id);
+  }
+
+  const timestamps = manualSpanTimestamps.get(id);
+  if (timestamps && typeof globalThis?.performance?.measure === 'function') {
+    performance.measure(timestamps.name, { start: timestamps.startTs, end: performance.now() });
+    manualSpanTimestamps.delete(id);
+  }
+};
+
+export type AddLinkOptions = {};
+
+const addLink = (parent: any, child: any, opts: AddLinkOptions = {}) => {
+  TRACE_PROCESSOR.addLink(parent, child, opts);
+};
+
+export type TraceDiagnosticProps<T> = {
+  /** Unique ID. */
+  id: string;
+
+  /**
+   * Human-readable name.
+   * @defaults Defaults to `id`
+   */
+  name?: string;
+
+  /** Function that will be called to fetch the diagnostic data. */
+  fetch: () => MaybePromise<T>;
+};
+
+export interface TraceDiagnostic {
+  id: string;
+  unregister(): void;
+}
+
+/**
+ * Register a diagnostic that could be queried.
+ */
+const diagnostic = <T>(params: TraceDiagnosticProps<T>): TraceDiagnostic => {
+  return TRACE_PROCESSOR.diagnostics.registerDiagnostic(params);
+};
+
+export const trace = {
+  addLink,
+  diagnostic,
+  mark,
+  span,
+  spanStart,
+  spanEnd,
+  metrics: TRACE_PROCESSOR.remoteMetrics,
+};

package/src/buffering-backend.ts

@@ -0,0 +1,112 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { type TraceContextData } from '@dxos/context';
+
+import type { RemoteSpan, StartSpanOptions, TracingBackend } from './tracing-types';
+
+export const BUFFERED_PREFIX = 'buffered-';
+
+/**
+ * Span handle that records operations while no real OTEL backend is available.
+ * Once a real backend is registered, the buffered span is replayed and a
+ * {@link delegate} is set so future calls forward to the real span.
+ */
+class BufferedSpan implements RemoteSpan {
+  readonly spanContext: TraceContextData;
+  readonly startTime: number;
+  delegate?: RemoteSpan;
+
+  #ended = false;
+  #endTime?: number;
+  #error?: unknown;
+  #hasError = false;
+
+  constructor(
+    readonly options: StartSpanOptions,
+    id: number,
+  ) {
+    this.spanContext = { traceparent: `${BUFFERED_PREFIX}${id}` };
+    this.startTime = Date.now();
+  }
+
+  end(endTime?: number): void {
+    if (this.delegate) {
+      this.delegate.end(endTime);
+      return;
+    }
+    this.#endTime = endTime ?? Date.now();
+    this.#ended = true;
+  }
+
+  setError(err: unknown): void {
+    if (this.delegate) {
+      this.delegate.setError?.(err);
+      return;
+    }
+    this.#error = err;
+    this.#hasError = true;
+  }
+
+  replay(real: RemoteSpan): void {
+    if (this.#hasError) {
+      real.setError?.(this.#error);
+    }
+    if (this.#ended) {
+      real.end(this.#endTime);
+    } else {
+      this.delegate = real;
+    }
+  }
+}
+
+/**
+ * A {@link TracingBackend} that buffers span operations until a real backend
+ * registers. On {@link drain}, buffered spans are replayed in FIFO order with
+ * parent IDs translated from synthetic `buffered-*` traceparents to real OTEL
+ * IDs, preserving the trace hierarchy.
+ */
+export class BufferingTracingBackend implements TracingBackend {
+  readonly #pending: BufferedSpan[] = [];
+  #counter = 0;
+
+  startSpan(options: StartSpanOptions): RemoteSpan {
+    const span = new BufferedSpan(options, ++this.#counter);
+    this.#pending.push(span);
+    return span;
+  }
+
+  /** Discard all buffered spans without replaying them. */
+  clear(): void {
+    this.#pending.length = 0;
+  }
+
+  /**
+   * Replay all buffered spans into {@link backend}.
+   *
+   * @returns Map from synthetic buffered traceparent to real {@link TraceContextData},
+   *   used by the post-drain translating wrapper to resolve stale buffered IDs
+   *   still present on in-flight {@link Context} objects.
+   */
+  drain(backend: TracingBackend): Map<string, TraceContextData> {
+    const idMap = new Map<string, TraceContextData>();
+
+    for (const buffered of this.#pending) {
+      let parentContext = buffered.options.parentContext;
+      if (parentContext && parentContext.traceparent.startsWith(BUFFERED_PREFIX)) {
+        parentContext = idMap.get(parentContext.traceparent) ?? parentContext;
+      }
+
+      const real = backend.startSpan({ ...buffered.options, parentContext, startTime: buffered.startTime });
+
+      if (real.spanContext) {
+        idMap.set(buffered.spanContext.traceparent, real.spanContext);
+      }
+
+      buffered.replay(real);
+    }
+    this.#pending.length = 0;
+    return idMap;
+  }
+}

package/src/diagnostic.ts

@@ -0,0 +1,103 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { asyncTimeout } from '@dxos/async';
+import { invariant } from '@dxos/invariant';
+
+import { type TraceDiagnostic, type TraceDiagnosticProps } from './api';
+import { createId } from './util';
+
+export const DIAGNOSTICS_TIMEOUT = 10_000;
+
+export type DiagnosticMetadata = {
+  id: string;
+  instanceId: string;
+  instanceTag: string | null;
+  name: string;
+};
+
+export type DiagnosticsRequest = {
+  id: string;
+  instanceId?: string;
+  instanceTag?: string | null;
+};
+
+export type DiagnosticsData = {
+  id: string;
+  instanceId: string;
+  data: any;
+  error?: string;
+};
+
+export class TraceDiagnosticImpl implements TraceDiagnostic {
+  constructor(
+    public id: string,
+    public fetch: () => any,
+    public name: string,
+    private readonly _onUnregister: () => void,
+  ) {}
+
+  unregister(): void {
+    this._onUnregister();
+  }
+}
+
+export class DiagnosticsManager {
+  readonly instanceId = createId();
+
+  readonly registry = new Map<string, TraceDiagnosticImpl>();
+
+  private _instanceTag: string | null = null;
+
+  get instanceTag(): string | null {
+    return this._instanceTag;
+  }
+
+  setInstanceTag(tag: string): void {
+    this._instanceTag = tag;
+  }
+
+  registerDiagnostic(params: TraceDiagnosticProps<any>): TraceDiagnostic {
+    const impl = new TraceDiagnosticImpl(params.id, params.fetch, params.name ?? params.id, () => {
+      if (this.registry.get(params.id) === impl) {
+        this.registry.delete(params.id);
+      }
+    });
+    this.registry.set(params.id, impl);
+    return impl;
+  }
+
+  list(): DiagnosticMetadata[] {
+    return Array.from(this.registry.values()).map((diagnostic) => ({
+      id: diagnostic.id,
+      instanceId: this.instanceId,
+      instanceTag: this._instanceTag,
+      name: diagnostic.name,
+    }));
+  }
+
+  async fetch(request: DiagnosticsRequest): Promise<DiagnosticsData> {
+    if (request.instanceId != null) {
+      invariant(request.instanceId === this.instanceId, 'Invalid instance id');
+    }
+    const { id } = request;
+    const diagnostic = this.registry.get(id);
+    invariant(diagnostic, 'Diagnostic not found');
+    try {
+      const data = await asyncTimeout(diagnostic.fetch(), DIAGNOSTICS_TIMEOUT);
+      return {
+        id,
+        instanceId: this.instanceId,
+        data,
+      };
+    } catch (err: any) {
+      return {
+        id,
+        instanceId: this.instanceId,
+        data: null,
+        error: err.stack,
+      };
+    }
+  }
+}

package/src/diagnostics-channel.ts

@@ -0,0 +1,174 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { Trigger, sleep } from '@dxos/async';
+import { Context } from '@dxos/context';
+import { invariant } from '@dxos/invariant';
+
+import {
+  type DiagnosticMetadata,
+  DIAGNOSTICS_TIMEOUT,
+  type DiagnosticsData,
+  type DiagnosticsManager,
+  type DiagnosticsRequest,
+} from './diagnostic';
+import { createId } from './util';
+
+const DEFAULT_CHANNEL_NAME = 'dxos-diagnostics';
+
+const DISCOVER_TIME = 500;
+
+export type DiagnosticChannelMessage =
+  | {
+      type: 'DIAGNOSTICS_DISCOVER';
+    }
+  | {
+      type: 'DIAGNOSTICS_ANNOUNCE';
+      diagnostics: DiagnosticMetadata[];
+    }
+  | {
+      type: 'DIAGNOSTICS_FETCH';
+      requestId: string;
+      request: DiagnosticsRequest;
+    }
+  | {
+      type: 'DIAGNOSTICS_RESPONSE';
+      requestId: string;
+      data: DiagnosticsData;
+    };
+
+export class DiagnosticsChannel {
+  static get supported() {
+    return globalThis.BroadcastChannel != null;
+  }
+
+  private _ctx = new Context();
+
+  // Separate channels becauase the client and server may be in the same process.
+  private readonly _serveChannel?: BroadcastChannel = undefined;
+  private readonly _clientChannel?: BroadcastChannel = undefined;
+
+  constructor(private readonly _channelName: string = DEFAULT_CHANNEL_NAME) {
+    if (DiagnosticsChannel.supported) {
+      this._serveChannel = new BroadcastChannel(_channelName);
+      this._clientChannel = new BroadcastChannel(_channelName);
+    }
+  }
+
+  destroy(): void {
+    void this._ctx.dispose();
+    this._serveChannel?.close();
+    this._clientChannel?.close();
+  }
+
+  /**
+   * In node.js, the channel will keep the process alive.
+   * This method allows the process to exit.
+   * Noop in the browser.
+   */
+  unref(): void {
+    if (this._serveChannel && typeof (this._serveChannel as any).unref === 'function') {
+      (this._serveChannel as any).unref();
+      (this._clientChannel as any).unref();
+    }
+  }
+
+  serve(manager: DiagnosticsManager): void {
+    invariant(this._serveChannel);
+    const listener = async (event: MessageEvent) => {
+      switch (event.data.type) {
+        case 'DIAGNOSTICS_DISCOVER': {
+          const diagnostics = manager.list();
+          this._serveChannel!.postMessage({
+            type: 'DIAGNOSTICS_ANNOUNCE',
+            diagnostics,
+          } satisfies DiagnosticChannelMessage);
+          break;
+        }
+        case 'DIAGNOSTICS_FETCH': {
+          const { requestId, request } = event.data;
+
+          if (request.instanceId != null && request.instanceId !== manager.instanceId) {
+            break;
+          } else if (request.instanceTag != null && request.instanceTag !== manager.instanceTag) {
+            break;
+          }
+
+          const data = await manager.fetch(request);
+          this._serveChannel!.postMessage({
+            type: 'DIAGNOSTICS_RESPONSE',
+            requestId,
+            data,
+          } satisfies DiagnosticChannelMessage);
+          break;
+        }
+      }
+    };
+
+    this._serveChannel.addEventListener('message', listener);
+    this._ctx.onDispose(() => this._serveChannel!.removeEventListener('message', listener));
+  }
+
+  async discover(): Promise<DiagnosticMetadata[]> {
+    invariant(this._clientChannel);
+    const diagnostics: DiagnosticMetadata[] = [];
+
+    const collector = (event: MessageEvent) => {
+      const data = event.data as DiagnosticChannelMessage;
+      switch (data.type) {
+        case 'DIAGNOSTICS_ANNOUNCE':
+          diagnostics.push(...data.diagnostics);
+          break;
+      }
+    };
+
+    try {
+      this._clientChannel.addEventListener('message', collector);
+      this._clientChannel.postMessage({ type: 'DIAGNOSTICS_DISCOVER' } satisfies DiagnosticChannelMessage);
+
+      await sleep(DISCOVER_TIME);
+
+      // Dedup.
+      const result: DiagnosticMetadata[] = [];
+      for (const diagnostic of diagnostics) {
+        if (!result.some((d) => d.id === diagnostic.id && d.instanceId === diagnostic.instanceId)) {
+          result.push(diagnostic);
+        }
+      }
+
+      return diagnostics;
+    } finally {
+      this._clientChannel.removeEventListener('message', collector);
+    }
+  }
+
+  async fetch(request: DiagnosticsRequest): Promise<DiagnosticsData> {
+    invariant(this._clientChannel);
+    const requestId = createId();
+
+    const trigger = new Trigger<DiagnosticsData>();
+    const listener = (event: MessageEvent) => {
+      const data = event.data as DiagnosticChannelMessage;
+      if (data.type === 'DIAGNOSTICS_RESPONSE' && data.requestId === requestId) {
+        trigger.wake(data.data);
+      }
+    };
+
+    try {
+      this._clientChannel.addEventListener('message', listener);
+      this._clientChannel.postMessage({
+        type: 'DIAGNOSTICS_FETCH',
+        requestId,
+        request,
+      } satisfies DiagnosticChannelMessage);
+
+      // NOTE: Must have await keyword in this block.
+      const result = await trigger.wait({ timeout: DIAGNOSTICS_TIMEOUT });
+
+      return result;
+    } finally {
+      this._clientChannel.removeEventListener('message', listener);
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,25 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import { trace } from './api';
+
+export * from './api';
+export * from './trace-processor';
+export * from './tracing-types';
+export * from './diagnostic';
+export * from './diagnostics-channel';
+export * from './remote/metrics';
+
+trace.diagnostic({
+  id: 'process-info',
+  name: 'Process Info',
+  fetch: async () => {
+    return {
+      platform: globalThis.process?.platform,
+      arch: globalThis.process?.arch,
+      versions: globalThis.process?.versions,
+      href: globalThis.location?.href,
+    };
+  },
+});

package/src/remote/index.ts

@@ -0,0 +1,5 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+export * from './metrics';

package/src/remote/metrics.ts

@@ -0,0 +1,57 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+type TagType = number | string | boolean | null | undefined;
+
+export interface MetricData {
+  unit?: string;
+  tags?: Record<string, TagType>;
+  timestamp?: number;
+}
+
+interface MetricsMethods {
+  /**
+   * Adds a value to a counter metric
+   */
+  increment(name: string, value?: number, data?: MetricData): void;
+  /**
+   * Adds a value to a distribution metric
+   */
+  distribution(name: string, value: number, data?: MetricData): void;
+  /**
+   * Adds a value to a set metric. Value must be a string or integer.
+   */
+  set(name: string, value: number | string, data?: MetricData): void;
+  /**
+   * Adds a value to a gauge metric
+   */
+  gauge(name: string, value: number, data?: MetricData): void;
+}
+
+/**
+ * Allows metrics to be recorded within SDK code without requiring specific consumers.
+ */
+export class RemoteMetrics implements MetricsMethods {
+  private _metrics = new Set<MetricsMethods>();
+
+  registerProcessor(processor: MetricsMethods): void {
+    this._metrics.add(processor);
+  }
+
+  increment(name: string, value?: number, data?: MetricData): void[] {
+    return Array.from(this._metrics.values()).map((processor) => processor.increment(name, value, data));
+  }
+
+  distribution(name: string, value: number, data?: MetricData): void[] {
+    return Array.from(this._metrics.values()).map((processor) => processor.distribution(name, value, data));
+  }
+
+  set(name: string, value: number | string, data?: MetricData): void[] {
+    return Array.from(this._metrics.values()).map((processor) => processor.set(name, value, data));
+  }
+
+  gauge(name: string, value: number, data?: MetricData): void[] {
+    return Array.from(this._metrics.values()).map((processor) => processor.gauge(name, value, data));
+  }
+}