@dxos/tracing 0.8.4-main.9be5663bfe → 0.8.4-main.abd8ff62ef

package/src/trace-processor.ts

@@ -2,26 +2,23 @@
 // Copyright 2023 DXOS.org
 //
 
-import { unrefTimeout } from '@dxos/async';
-import { Context } from '@dxos/context';
-import { LogLevel, type LogProcessor, getContextFromEntry, log } from '@dxos/log';
+import { LogLevel, type LogProcessor, log } from '@dxos/log';
 import { type LogEntry } from '@dxos/protocols/proto/dxos/client/services';
-import { type Error as SerializedError } from '@dxos/protocols/proto/dxos/error';
-import { type Metric, type Resource, type Span } from '@dxos/protocols/proto/dxos/tracing';
+import { type Metric, type Resource } from '@dxos/protocols/proto/dxos/tracing';
 import { getPrototypeSpecificInstanceId } from '@dxos/util';
 
 import type { AddLinkOptions, TimeAware } from './api';
+import { BUFFERED_PREFIX, BufferingTracingBackend } from './buffering-backend';
 import { DiagnosticsManager } from './diagnostic';
 import { DiagnosticsChannel } from './diagnostics-channel';
 import { type BaseCounter } from './metrics';
-import { RemoteMetrics, RemoteTracing } from './remote';
-import { TRACE_SPAN_ATTRIBUTE, getTracingContext } from './symbols';
-import { TraceSender } from './trace-sender';
+import { RemoteMetrics } from './remote/metrics';
+import { getTracingContext } from './symbols';
+import type { RemoteSpan, StartSpanOptions, TracingBackend } from './tracing-types';
 import { WeakRef } from './weak-ref';
 
 export type Diagnostics = {
   resources: Record<string, Resource>;
-  spans: Span[];
   logs: LogEntry[];
 };
 
@@ -31,17 +28,6 @@ export type TraceResourceConstructorProps = {
   annotation?: symbol;
 };
 
-export type TraceSpanProps = {
-  instance: any;
-  // TODO(wittjosiah): Rename to `name`.
-  methodName: string;
-  parentCtx: Context | null;
-  showInBrowserTimeline: boolean;
-  showInRemoteTracing?: boolean;
-  op?: string;
-  attributes?: Record<string, any>;
-};
-
 export class ResourceEntry {
   /**
    * Sometimes bundlers mangle class names: WebFile -> WebFile2.
@@ -63,39 +49,57 @@ export class ResourceEntry {
   }
 }
 
-export type TraceSubscription = {
-  flush: () => void;
-
-  dirtyResources: Set<number>;
-  dirtySpans: Set<number>;
-  newLogs: LogEntry[];
-};
-
 const MAX_RESOURCE_RECORDS = 2_000;
-const MAX_SPAN_RECORDS = 1_000;
 const MAX_LOG_RECORDS = 1_000;
 
-const REFRESH_INTERVAL = 1_000;
-
 const MAX_INFO_OBJECT_DEPTH = 8;
 
-const IS_CLOUDFLARE_WORKERS = !!globalThis?.navigator?.userAgent?.includes('Cloudflare-Workers');
-
 export class TraceProcessor {
   public readonly diagnostics = new DiagnosticsManager();
   public readonly diagnosticsChannel = new DiagnosticsChannel();
   public readonly remoteMetrics = new RemoteMetrics();
-  public readonly remoteTracing = new RemoteTracing();
 
-  readonly subscriptions: Set<TraceSubscription> = new Set();
+  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);
+      },
+    };
+  }
 
   readonly resources = new Map<number, ResourceEntry>();
   readonly resourceInstanceIndex = new WeakMap<any, ResourceEntry>();
   readonly resourceIdList: number[] = [];
 
-  readonly spans = new Map<number, Span>();
-  readonly spanIdList: number[] = [];
-
   readonly logs: LogEntry[] = [];
 
   private _instanceTag: string | null = null;
@@ -103,11 +107,6 @@ export class TraceProcessor {
   constructor() {
     log.addProcessor(this._logProcessor.bind(this));
 
-    if (!IS_CLOUDFLARE_WORKERS) {
-      const refreshInterval = setInterval(this.refresh.bind(this), REFRESH_INTERVAL);
-      unrefTimeout(refreshInterval);
-    }
-
     if (DiagnosticsChannel.supported) {
       this.diagnosticsChannel.serve(this.diagnostics);
     }
@@ -119,14 +118,10 @@ export class TraceProcessor {
     this.diagnostics.setInstanceTag(tag);
   }
 
-  /**
-   * @internal
-   */
-  // TODO(burdon): Comment.
+  /** @internal */
   createTraceResource(params: TraceResourceConstructorProps): void {
     const id = this.resources.size;
 
-    // Init metrics counters.
     const tracingContext = getTracingContext(Object.getPrototypeOf(params.instance));
     for (const key of Object.keys(tracingContext.metricsProperties)) {
       (params.instance[key] as BaseCounter)._assign(params.instance, key);
@@ -151,29 +146,11 @@ export class TraceProcessor {
     if (this.resourceIdList.length > MAX_RESOURCE_RECORDS) {
       this._clearResources();
     }
-
-    this._markResourceDirty(id);
-  }
-
-  createTraceSender(): TraceSender {
-    return new TraceSender(this);
-  }
-
-  traceSpan(params: TraceSpanProps): TracingSpan {
-    const span = new TracingSpan(this, params);
-    this._flushSpan(span);
-    return span;
   }
 
   // TODO(burdon): Not implemented.
   addLink(parent: any, child: any, opts: AddLinkOptions): void {}
 
-  //
-  // Getters
-  //
-
-  // TODO(burdon): Define type.
-  // TODO(burdon): Reconcile with system service.
   getDiagnostics(): Diagnostics {
     this.refresh();
 
@@ -184,7 +161,6 @@ export class TraceProcessor {
           entry.data,
         ]),
       ),
-      spans: Array.from(this.spans.values()),
       logs: this.logs.filter((log) => log.level >= LogLevel.INFO),
     };
   }
@@ -251,81 +227,23 @@ export class TraceProcessor {
         (instance[key] as BaseCounter)._tick?.(time);
       }
 
-      let _changed = false;
-
-      const oldInfo = resource.data.info;
       resource.data.info = this.getResourceInfo(instance);
-      _changed ||= !areEqualShallow(oldInfo, resource.data.info);
-
-      const oldMetrics = resource.data.metrics;
       resource.data.metrics = this.getResourceMetrics(instance);
-      _changed ||= !areEqualShallow(oldMetrics, resource.data.metrics);
-
-      // TODO(dmaretskyi): Test if works and enable.
-      // if (changed) {
-      this._markResourceDirty(resource.data.id);
-      // }
-    }
-
-    for (const subscription of this.subscriptions) {
-      subscription.flush();
-    }
-  }
-
-  //
-  // Implementation
-  //
-
-  /**
-   * @internal
-   */
-  _flushSpan(runtimeSpan: TracingSpan): void {
-    const span = runtimeSpan.serialize();
-    this.spans.set(span.id, span);
-    this.spanIdList.push(span.id);
-    if (this.spanIdList.length > MAX_SPAN_RECORDS) {
-      this._clearSpans();
-    }
-    this._markSpanDirty(span.id);
-    this.remoteTracing.flushSpan(runtimeSpan);
-  }
-
-  private _markResourceDirty(id: number): void {
-    for (const subscription of this.subscriptions) {
-      subscription.dirtyResources.add(id);
-    }
-  }
-
-  private _markSpanDirty(id: number): void {
-    for (const subscription of this.subscriptions) {
-      subscription.dirtySpans.add(id);
     }
   }
 
   private _clearResources(): void {
-    // TODO(dmaretskyi): Use FinalizationRegistry to delete finalized resources first.
     while (this.resourceIdList.length > MAX_RESOURCE_RECORDS) {
       const id = this.resourceIdList.shift()!;
       this.resources.delete(id);
     }
   }
 
-  private _clearSpans(): void {
-    while (this.spanIdList.length > MAX_SPAN_RECORDS) {
-      const id = this.spanIdList.shift()!;
-      this.spans.delete(id);
-    }
-  }
-
   private _pushLog(log: LogEntry): void {
     this.logs.push(log);
     if (this.logs.length > MAX_LOG_RECORDS) {
       this.logs.shift();
     }
-
-    for (const subscription of this.subscriptions) {
-      subscription.newLogs.push(log);
-    }
   }
 
   private _logProcessor: LogProcessor = (config, entry) => {
@@ -339,19 +257,20 @@ export class TraceProcessor {
           return;
         }
 
-        const context = getContextFromEntry(entry) ?? {};
-        for (const key of Object.keys(context)) {
-          context[key] = sanitizeValue(context[key], 0, this);
+        const context: Record<string, any> = { ...entry.computedContext };
+        if (entry.computedError !== undefined) {
+          context.error = entry.computedError;
         }
 
+        const { filename, line } = entry.computedMeta;
         const entryToPush: LogEntry = {
           level: entry.level,
-          message: entry.message ?? (entry.error ? (entry.error.message ?? String(entry.error)) : ''),
+          message: entry.message ?? entry.computedError ?? '',
           context,
-          timestamp: new Date(),
+          timestamp: new Date(entry.timestamp),
           meta: {
-            file: entry.meta?.F ?? '',
-            line: entry.meta?.L ?? 0,
+            file: filename ?? '',
+            line: line ?? 0,
             resourceId: resource.data.id,
           },
         };
@@ -363,121 +282,6 @@ export class TraceProcessor {
   };
 }
 
-// TODO(burdon): Comment.
-export class TracingSpan {
-  static nextId = 0;
-
-  readonly id: number;
-  readonly parentId: number | null = null;
-  readonly methodName: string;
-  readonly resourceId: number | null = null;
-  readonly op: string | undefined;
-  readonly attributes: Record<string, any>;
-  startTs: number;
-  endTs: number | null = null;
-  error: SerializedError | null = null;
-
-  private _showInBrowserTimeline: boolean;
-  private _showInRemoteTracing: boolean;
-  private readonly _ctx: Context;
-
-  constructor(
-    private _traceProcessor: TraceProcessor,
-    params: TraceSpanProps,
-  ) {
-    this.id = TracingSpan.nextId++;
-    this.methodName = params.methodName;
-    this.resourceId = _traceProcessor.getResourceId(params.instance);
-    this.startTs = performance.now();
-    this._showInBrowserTimeline = params.showInBrowserTimeline;
-    this._showInRemoteTracing = params.showInRemoteTracing ?? true;
-    this.op = params.op;
-    this.attributes = params.attributes ?? {};
-
-    const baseCtx = params.parentCtx ?? new Context();
-    this._ctx = this._showInRemoteTracing
-      ? baseCtx.derive({ attributes: { [TRACE_SPAN_ATTRIBUTE]: this.id } })
-      : baseCtx.derive();
-    if (params.parentCtx) {
-      const parentId = params.parentCtx.getAttribute(TRACE_SPAN_ATTRIBUTE);
-      if (typeof parentId === 'number') {
-        this.parentId = parentId;
-      }
-    }
-  }
-
-  get name() {
-    const resource = this._traceProcessor.resources.get(this.resourceId!);
-    return resource ? `${resource.sanitizedClassName}#${resource.data.instanceId}.${this.methodName}` : this.methodName;
-  }
-
-  /** Sanitized class name of the owning resource, if available. */
-  get sanitizedClassName(): string | undefined {
-    const resource = this.resourceId != null ? this._traceProcessor.resources.get(this.resourceId) : undefined;
-    return resource?.sanitizedClassName;
-  }
-
-  get ctx(): Context {
-    return this._ctx;
-  }
-
-  get showInRemoteTracing(): boolean {
-    return this._showInRemoteTracing;
-  }
-
-  markSuccess(): void {
-    this.endTs = performance.now();
-    this._traceProcessor._flushSpan(this);
-
-    if (this._showInBrowserTimeline) {
-      this._markInBrowserTimeline();
-    }
-  }
-
-  markError(err: unknown): void {
-    this.endTs = performance.now();
-    this.error = serializeError(err);
-    this._traceProcessor._flushSpan(this);
-
-    if (this._showInBrowserTimeline) {
-      this._markInBrowserTimeline();
-    }
-  }
-
-  serialize(): Span {
-    return {
-      id: this.id,
-      resourceId: this.resourceId ?? undefined,
-      methodName: this.methodName,
-      parentId: this.parentId ?? undefined,
-      startTs: this.startTs.toFixed(3),
-      endTs: this.endTs?.toFixed(3) ?? undefined,
-      error: this.error ?? undefined,
-    };
-  }
-
-  private _markInBrowserTimeline(): void {
-    if (typeof globalThis?.performance?.measure === 'function') {
-      performance.measure(this.name, { start: this.startTs, end: this.endTs! });
-    }
-  }
-}
-
-// TODO(burdon): Log cause.
-const serializeError = (err: unknown): SerializedError => {
-  if (err instanceof Error) {
-    return {
-      name: err.name,
-      message: err.message,
-    };
-  }
-
-  return {
-    message: String(err),
-  };
-};
-
-// TODO(burdon): Rename singleton and move out of package.
 export const TRACE_PROCESSOR: TraceProcessor = ((globalThis as any).TRACE_PROCESSOR ??= new TraceProcessor());
 
 const sanitizeValue = (value: any, depth: number, traceProcessor: TraceProcessor): any => {
@@ -501,7 +305,6 @@ const sanitizeValue = (value: any, depth: number, traceProcessor: TraceProcessor
       }
 
       if (typeof value.toJSON === 'function') {
-        // TODO(dmaretskyi): This has potential to cause infinite recursion.
         return sanitizeValue(value.toJSON(), depth, traceProcessor);
       }
 
@@ -525,7 +328,6 @@ const sanitizeValue = (value: any, depth: number, traceProcessor: TraceProcessor
         }
       }
 
-      // TODO(dmaretskyi): Expose trait.
       if (typeof value.truncate === 'function') {
         return value.truncate();
       }
@@ -534,20 +336,6 @@ const sanitizeValue = (value: any, depth: number, traceProcessor: TraceProcessor
   }
 };
 
-const areEqualShallow = (a: any, b: any) => {
-  for (const key in a) {
-    if (!(key in b) || a[key] !== b[key]) {
-      return false;
-    }
-  }
-  for (const key in b) {
-    if (!(key in a) || a[key] !== b[key]) {
-      return false;
-    }
-  }
-  return true;
-};
-
 export const sanitizeClassName = (className: string) => {
   let name = className.replace(/^_+/, '');
   const SANITIZE_REGEX = /[^_](\d+)$/;

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;
+}