@dxos/tracing 0.8.4-main.bc674ce → 0.8.4-main.bcb3aa67d6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dxos/tracing",
-  "version": "0.8.4-main.bc674ce",
+  "version": "0.8.4-main.bcb3aa67d6",
   "description": "Async utilities.",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
@@ -31,14 +31,14 @@
     "src"
   ],
   "dependencies": {
-    "@dxos/async": "0.8.4-main.bc674ce",
-    "@dxos/context": "0.8.4-main.bc674ce",
-    "@dxos/codec-protobuf": "0.8.4-main.bc674ce",
-    "@dxos/invariant": "0.8.4-main.bc674ce",
-    "@dxos/log": "0.8.4-main.bc674ce",
-    "@dxos/protocols": "0.8.4-main.bc674ce",
-    "@dxos/node-std": "0.8.4-main.bc674ce",
-    "@dxos/util": "0.8.4-main.bc674ce"
+    "@dxos/async": "0.8.4-main.bcb3aa67d6",
+    "@dxos/codec-protobuf": "0.8.4-main.bcb3aa67d6",
+    "@dxos/context": "0.8.4-main.bcb3aa67d6",
+    "@dxos/invariant": "0.8.4-main.bcb3aa67d6",
+    "@dxos/log": "0.8.4-main.bcb3aa67d6",
+    "@dxos/node-std": "0.8.4-main.bcb3aa67d6",
+    "@dxos/protocols": "0.8.4-main.bcb3aa67d6",
+    "@dxos/util": "0.8.4-main.bcb3aa67d6"
   },
   "publishConfig": {
     "access": "public"

package/src/api.ts

@@ -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();
+        }
+      });
     };
   };
 

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';
@@ -37,6 +37,7 @@ export type TraceSpanProps = {
   methodName: string;
   parentCtx: Context | null;
   showInBrowserTimeline: boolean;
+  showInRemoteTracing?: boolean;
   op?: string;
   attributes?: Record<string, any>;
 };
@@ -377,7 +378,8 @@ 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,
@@ -388,15 +390,15 @@ export class TracingSpan {
     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> =>