@dxos/tracing 0.8.4-main.72ec0f3 → 0.8.4-main.74a063c4e0

package/package.json

@@ -1,9 +1,13 @@
 {
   "name": "@dxos/tracing",
-  "version": "0.8.4-main.72ec0f3",
+  "version": "0.8.4-main.74a063c4e0",
   "description": "Async utilities.",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dxos/dxos"
+  },
   "license": "MIT",
   "author": "DXOS.org",
   "sideEffects": true,
@@ -27,14 +31,14 @@
     "src"
   ],
   "dependencies": {
-    "@dxos/async": "0.8.4-main.72ec0f3",
-    "@dxos/codec-protobuf": "0.8.4-main.72ec0f3",
-    "@dxos/context": "0.8.4-main.72ec0f3",
-    "@dxos/invariant": "0.8.4-main.72ec0f3",
-    "@dxos/log": "0.8.4-main.72ec0f3",
-    "@dxos/node-std": "0.8.4-main.72ec0f3",
-    "@dxos/protocols": "0.8.4-main.72ec0f3",
-    "@dxos/util": "0.8.4-main.72ec0f3"
+    "@dxos/async": "0.8.4-main.74a063c4e0",
+    "@dxos/codec-protobuf": "0.8.4-main.74a063c4e0",
+    "@dxos/context": "0.8.4-main.74a063c4e0",
+    "@dxos/invariant": "0.8.4-main.74a063c4e0",
+    "@dxos/log": "0.8.4-main.74a063c4e0",
+    "@dxos/util": "0.8.4-main.74a063c4e0",
+    "@dxos/protocols": "0.8.4-main.74a063c4e0",
+    "@dxos/node-std": "0.8.4-main.74a063c4e0"
   },
   "publishConfig": {
     "access": "public"

package/src/api.ts

@@ -6,7 +6,7 @@ import { Context } from '@dxos/context';
 import { type MaybePromise } from '@dxos/util';
 
 import { getTracingContext } from './symbols';
-import { TRACE_PROCESSOR, type TraceSpanParams, type TracingSpan } from './trace-processor';
+import { TRACE_PROCESSOR, type TraceSpanProps, type TracingSpan } from './trace-processor';
 
 /**
  * Annotates a class as a tracked resource.
@@ -68,6 +68,8 @@ const mark = (name: string) => {
 
 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>;
 };
@@ -76,30 +78,35 @@ export type SpanOptions = {
  * Decorator that creates a span for the execution duration of the decorated method.
  */
 const span =
-  ({ showInBrowserTimeline = false, op, attributes }: SpanOptions = {}) =>
+  ({ 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 explicitCtx = args[0] instanceof Context ? args[0] : null;
+
       const span = TRACE_PROCESSOR.traceSpan({
-        parentCtx,
+        parentCtx: explicitCtx,
         methodName: propertyKey,
         instance: this,
         showInBrowserTimeline,
+        showInRemoteTracing,
         op,
         attributes,
       });
 
-      const callArgs = span.ctx ? [span.ctx, ...args.slice(1)] : args;
-      try {
-        return await method.apply(this, callArgs);
-      } catch (err) {
-        span.markError(err);
-        throw err;
-      } finally {
-        span.markSuccess();
-      }
+      const callArgs = explicitCtx ? [span.ctx, ...args.slice(1)] : args;
+
+      return TRACE_PROCESSOR.remoteTracing.wrapExecution(span, async () => {
+        try {
+          return await method.apply(this, callArgs);
+        } catch (err) {
+          span.markError(err);
+          throw err;
+        } finally {
+          span.markSuccess();
+        }
+      });
     };
   };
 
@@ -108,7 +115,7 @@ const spans = new Map<string, TracingSpan>();
 /**
  * Creates a span that must be ended manually.
  */
-const spanStart = (params: TraceSpanParams & { id: string }) => {
+const spanStart = (params: TraceSpanProps & { id: string }) => {
   if (spans.has(params.id)) {
     return;
   }
@@ -141,7 +148,7 @@ const addLink = (parent: any, child: any, opts: AddLinkOptions = {}) => {
   TRACE_PROCESSOR.addLink(parent, child, opts);
 };
 
-export type TraceDiagnosticParams<T> = {
+export type TraceDiagnosticProps<T> = {
   /**
    * Unique ID.
    */
@@ -167,7 +174,7 @@ export interface TraceDiagnostic {
 /**
  * Register a diagnostic that could be queried.
  */
-const diagnostic = <T>(params: TraceDiagnosticParams<T>): TraceDiagnostic => {
+const diagnostic = <T>(params: TraceDiagnosticProps<T>): TraceDiagnostic => {
   return TRACE_PROCESSOR.diagnostics.registerDiagnostic(params);
 };
 

package/src/diagnostic.ts

@@ -5,7 +5,7 @@
 import { asyncTimeout } from '@dxos/async';
 import { invariant } from '@dxos/invariant';
 
-import { type TraceDiagnostic, type TraceDiagnosticParams } from './api';
+import { type TraceDiagnostic, type TraceDiagnosticProps } from './api';
 import { createId } from './util';
 
 export const DIAGNOSTICS_TIMEOUT = 10_000;
@@ -58,7 +58,7 @@ export class DiagnosticsManager {
     this._instanceTag = tag;
   }
 
-  registerDiagnostic(params: TraceDiagnosticParams<any>): TraceDiagnostic {
+  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);

package/src/remote/tracing.ts

@@ -6,48 +6,170 @@ import { type TracingSpan } from '../trace-processor';
 
 type RemoteSpan = {
   end: () => void;
+  /** Wraps execution so that this span becomes the active parent for child spans. */
+  wrapExecution?: <T>(fn: () => T) => T;
+  /** Opaque context object for the backend (e.g., OTEL Context with this span active). */
+  spanContext?: unknown;
 };
 
 export type StartSpanOptions = {
   name: string;
   op?: string;
   attributes?: Record<string, any>;
+  /** Opaque parent context from a parent RemoteSpan (bridges async DXOS Context to OTEL). */
+  parentContext?: unknown;
 };
 
 interface TracingMethods {
   startSpan: (options: StartSpanOptions) => RemoteSpan;
 }
 
+const MAX_ENDED_CONTEXTS = 10_000;
+
 /**
  * Allows traces to be recorded within SDK code without requiring specific consumers.
+ *
+ * Preserves OTEL span contexts after spans end so that long-lived DXOS Contexts
+ * (e.g., `this._ctx` stored during `open()`) can still serve as parents for
+ * later child spans and outbound trace-context injection.
  */
-// TODO(wittjosiah): Should probably just use otel. Use `any` for now to not depend on Sentry directly.
 export class RemoteTracing {
   private _tracing: TracingMethods | undefined;
   private _spanMap = new Map<TracingSpan, RemoteSpan>();
+  private _idToSpan = new Map<number, TracingSpan>();
+
+  /**
+   * Retains OTEL span contexts after spans end so that periodic/background
+   * operations referencing a completed parent (via `this._ctx`) still produce
+   * correlated child spans instead of orphaned root traces.
+   */
+  private _endedSpanContexts = new Map<number, unknown>();
+
+  /**
+   * Buffers flushSpan calls that arrive before a processor is registered,
+   * so early startup spans are not silently dropped.
+   */
+  private _pendingFlushes: Array<{ span: TracingSpan; isEnd: boolean }> | null = [];
 
   registerProcessor(processor: TracingMethods): void {
     this._tracing = processor;
+
+    const pending = this._pendingFlushes;
+    this._pendingFlushes = null;
+    if (pending) {
+      for (const { span, isEnd } of pending) {
+        this._replayFlush(span, isEnd);
+      }
+    }
+  }
+
+  /** Returns the opaque OTEL context for the given DXOS span ID, if one exists. */
+  getSpanContext(spanId: number): unknown | undefined {
+    const tracingSpan = this._idToSpan.get(spanId);
+    if (tracingSpan) {
+      return this._spanMap.get(tracingSpan)?.spanContext;
+    }
+    return this._endedSpanContexts.get(spanId);
+  }
+
+  /** Wraps execution so that the remote span is active as parent context. */
+  wrapExecution<T>(span: TracingSpan, fn: () => T): T {
+    const remoteSpan = this._spanMap.get(span);
+    if (remoteSpan?.wrapExecution) {
+      return remoteSpan.wrapExecution(fn);
+    }
+    return fn();
   }
 
   flushSpan(span: TracingSpan): void {
+    if (!span.showInRemoteTracing) {
+      return;
+    }
+
     if (!this._tracing) {
+      this._pendingFlushes?.push({ span, isEnd: !!span.endTs });
       return;
     }
 
     if (!span.endTs) {
-      const remoteSpan = this._tracing.startSpan({
-        name: span.methodName,
-        op: span.op ?? 'function',
-        attributes: span.attributes,
-      });
-      this._spanMap.set(span, remoteSpan);
+      this._startRemoteSpan(span);
     } else {
-      const remoteSpan = this._spanMap.get(span);
-      if (remoteSpan) {
-        remoteSpan.end();
-        this._spanMap.delete(span);
+      this._endRemoteSpan(span);
+    }
+  }
+
+  private _startRemoteSpan(span: TracingSpan): void {
+    let parentContext: unknown;
+    if (span.parentId != null) {
+      const parentTracingSpan = this._idToSpan.get(span.parentId);
+      if (parentTracingSpan) {
+        parentContext = this._spanMap.get(parentTracingSpan)?.spanContext;
+      }
+      if (parentContext == null) {
+        parentContext = this._endedSpanContexts.get(span.parentId);
+      }
+    }
+
+    const attributes: Record<string, any> = {};
+    if (span.sanitizedClassName) {
+      attributes.entryPoint = span.sanitizedClassName;
+    }
+    for (const [key, value] of Object.entries(span.attributes)) {
+      attributes[key.startsWith('ctx.') ? key : `ctx.${key}`] = value;
+    }
+
+    const remoteSpan = this._tracing!.startSpan({
+      name: span.name,
+      op: span.op ?? 'function',
+      attributes,
+      parentContext,
+    });
+    this._spanMap.set(span, remoteSpan);
+    this._idToSpan.set(span.id, span);
+  }
+
+  private _endRemoteSpan(span: TracingSpan): void {
+    const remoteSpan = this._spanMap.get(span);
+    if (remoteSpan) {
+      if (remoteSpan.spanContext != null) {
+        this._endedSpanContexts.set(span.id, remoteSpan.spanContext);
+        this._evictEndedContexts();
+      }
+      remoteSpan.end();
+      this._spanMap.delete(span);
+      this._idToSpan.delete(span.id);
+    }
+  }
+
+  /**
+   * Replays a buffered flush that was queued before the processor was registered.
+   * For spans that started AND ended before registration, replays both events.
+   */
+  private _replayFlush(span: TracingSpan, isEnd: boolean): void {
+    if (!isEnd) {
+      this._startRemoteSpan(span);
+      if (span.endTs != null) {
+        this._endRemoteSpan(span);
+      }
+    } else {
+      if (!this._spanMap.has(span)) {
+        this._startRemoteSpan(span);
+      }
+      this._endRemoteSpan(span);
+    }
+  }
+
+  private _evictEndedContexts(): void {
+    if (this._endedSpanContexts.size <= MAX_ENDED_CONTEXTS) {
+      return;
+    }
+    const iterator = this._endedSpanContexts.keys();
+    while (this._endedSpanContexts.size > MAX_ENDED_CONTEXTS) {
+      const oldest = iterator.next();
+      if (oldest.done) {
+        break;
       }
+      this._endedSpanContexts.delete(oldest.value);
     }
   }
 }

package/src/trace-processor.ts

@@ -3,7 +3,7 @@
 //
 
 import { unrefTimeout } from '@dxos/async';
-import { type Context } from '@dxos/context';
+import { Context } from '@dxos/context';
 import { LogLevel, type LogProcessor, getContextFromEntry, 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';
@@ -25,18 +25,19 @@ export type Diagnostics = {
   logs: LogEntry[];
 };
 
-export type TraceResourceConstructorParams = {
+export type TraceResourceConstructorProps = {
   constructor: { new (...args: any[]): {} };
   instance: any;
   annotation?: symbol;
 };
 
-export type TraceSpanParams = {
+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>;
 };
@@ -122,7 +123,7 @@ export class TraceProcessor {
    * @internal
    */
   // TODO(burdon): Comment.
-  createTraceResource(params: TraceResourceConstructorParams): void {
+  createTraceResource(params: TraceResourceConstructorProps): void {
     const id = this.resources.size;
 
     // Init metrics counters.
@@ -158,7 +159,7 @@ export class TraceProcessor {
     return new TraceSender(this);
   }
 
-  traceSpan(params: TraceSpanParams): TracingSpan {
+  traceSpan(params: TraceSpanProps): TracingSpan {
     const span = new TracingSpan(this, params);
     this._flushSpan(span);
     return span;
@@ -377,26 +378,27 @@ export class TracingSpan {
   error: SerializedError | null = null;
 
   private _showInBrowserTimeline: boolean;
-  private readonly _ctx: Context | null = null;
+  private _showInRemoteTracing: boolean;
+  private readonly _ctx: Context;
 
   constructor(
     private _traceProcessor: TraceProcessor,
-    params: TraceSpanParams,
+    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) {
-      this._ctx = params.parentCtx.derive({
-        attributes: {
-          [TRACE_SPAN_ATTRIBUTE]: this.id,
-        },
-      });
       const parentId = params.parentCtx.getAttribute(TRACE_SPAN_ATTRIBUTE);
       if (typeof parentId === 'number') {
         this.parentId = parentId;
@@ -409,10 +411,20 @@ export class TracingSpan {
     return resource ? `${resource.sanitizedClassName}#${resource.data.instanceId}.${this.methodName}` : this.methodName;
   }
 
-  get ctx(): Context | null {
+  /** 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);
@@ -537,13 +549,13 @@ const areEqualShallow = (a: any, b: any) => {
 };
 
 export const sanitizeClassName = (className: string) => {
+  let name = className.replace(/^_+/, '');
   const SANITIZE_REGEX = /[^_](\d+)$/;
-  const m = className.match(SANITIZE_REGEX);
-  if (!m) {
-    return className;
-  } else {
-    return className.slice(0, -m[1].length);
+  const m = name.match(SANITIZE_REGEX);
+  if (m) {
+    name = name.slice(0, -m[1].length);
   }
+  return name;
 };
 
 const isSetLike = (value: any): value is Set<any> =>