@dxos/tracing 0.8.4-main.ae835ea → 0.8.4-main.bc2380dfbc

package/package.json

@@ -1,10 +1,14 @@
 {
   "name": "@dxos/tracing",
-  "version": "0.8.4-main.ae835ea",
+  "version": "0.8.4-main.bc2380dfbc",
   "description": "Async utilities.",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
-  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dxos/dxos"
+  },
+  "license": "FSL-1.1-Apache-2.0",
   "author": "DXOS.org",
   "sideEffects": true,
   "type": "module",
@@ -19,22 +23,19 @@
     }
   },
   "types": "dist/types/src/index.d.ts",
-  "typesVersions": {
-    "*": {}
-  },
   "files": [
     "dist",
     "src"
   ],
   "dependencies": {
-    "@dxos/async": "0.8.4-main.ae835ea",
-    "@dxos/context": "0.8.4-main.ae835ea",
-    "@dxos/log": "0.8.4-main.ae835ea",
-    "@dxos/node-std": "0.8.4-main.ae835ea",
-    "@dxos/codec-protobuf": "0.8.4-main.ae835ea",
-    "@dxos/protocols": "0.8.4-main.ae835ea",
-    "@dxos/util": "0.8.4-main.ae835ea",
-    "@dxos/invariant": "0.8.4-main.ae835ea"
+    "@dxos/codec-protobuf": "0.8.4-main.bc2380dfbc",
+    "@dxos/async": "0.8.4-main.bc2380dfbc",
+    "@dxos/context": "0.8.4-main.bc2380dfbc",
+    "@dxos/log": "0.8.4-main.bc2380dfbc",
+    "@dxos/invariant": "0.8.4-main.bc2380dfbc",
+    "@dxos/node-std": "0.8.4-main.bc2380dfbc",
+    "@dxos/protocols": "0.8.4-main.bc2380dfbc",
+    "@dxos/util": "0.8.4-main.bc2380dfbc"
   },
   "publishConfig": {
     "access": "public"

package/src/api.ts

@@ -2,19 +2,66 @@
 // Copyright 2023 DXOS.org
 //
 
-import { Context } from '@dxos/context';
+import { Context, LifecycleState, Resource, TRACE_SPAN_ATTRIBUTE } 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, sanitizeClassName } from './trace-processor';
+import type { RemoteSpan } from './tracing-types';
+
+const LIFECYCLE_SPAN = Symbol('dxos.tracing.lifecycle-span');
+
+/** localStorage key that switches the browser OTEL sampler from 30% to 100%. */
+export const TRACE_ALL_KEY = 'dxos.debug.traceAll';
+
+/**
+ * Reads `@trace.info({ spanAttribute: true })` properties from the instance
+ * and writes them into the span attributes map.
+ */
+const collectSpanAttributes = (instance: any, spanAttributes: Record<string, any>) => {
+  const proto = Object.getPrototypeOf(instance);
+  if (!proto) {
+    return;
+  }
+  const tracingContext = getTracingContext(proto);
+  for (const [key, { options }] of Object.entries(tracingContext.infoProperties)) {
+    if (!options.spanAttribute) {
+      continue;
+    }
+    try {
+      const value = typeof instance[key] === 'function' ? instance[key]() : instance[key];
+      if (value != null) {
+        const resolved = options.enum ? options.enum[value] : String(value);
+        spanAttributes[`ctx.${key}`] = resolved;
+      }
+    } catch {
+      // Skip properties that throw (e.g. uninitialized).
+    }
+  }
+};
+
+export type ResourceOptions = {
+  annotation?: symbol;
+  /**
+   * Start a lifecycle span on `open()` and end it on `close()`.
+   * `this._ctx` carries the lifecycle span's trace context, so background work
+   * (subscriptions, timers) becomes children of the lifecycle span.
+   * Direct calls within `_open` use the `_open` span's context as usual.
+   * Requires the class to extend {@link Resource}.
+   */
+  lifecycle?: boolean;
+};
 
 /**
  * Annotates a class as a tracked resource.
  */
 const resource =
-  (options?: { annotation?: symbol }) =>
+  (options?: ResourceOptions) =>
   <T extends { new (...args: any[]): {} }>(constructor: T) => {
-    // Wrapping class declaration into an IIFE so it doesn't capture the `klass` class name.
+    if (options?.lifecycle && !(constructor.prototype instanceof Resource)) {
+      throw new Error(`@trace.resource({ lifecycle: true }) requires ${constructor.name} to extend Resource`);
+    }
+
     const klass = (() =>
       class extends constructor {
         constructor(...rest: any[]) {
@@ -22,6 +69,68 @@ const resource =
           TRACE_PROCESSOR.createTraceResource({ constructor, annotation: options?.annotation, instance: this });
         }
       })();
+
+    if (options?.lifecycle) {
+      const sanitizedName = sanitizeClassName(constructor.name);
+      const proto = klass.prototype as any;
+      const originalOpen = proto.open;
+      const originalClose = proto.close;
+
+      proto.open = async function (ctx?: Context): Promise<any> {
+        const self = this as any;
+
+        if (self._lifecycleState !== LifecycleState.CLOSED) {
+          return originalOpen.call(this, ctx);
+        }
+
+        const parentSpanContext = ctx?.getAttribute(TRACE_SPAN_ATTRIBUTE);
+        const resourceEntry = TRACE_PROCESSOR.resourceInstanceIndex.get(this);
+        const spanAttributes: Record<string, any> = {};
+        if (resourceEntry) {
+          spanAttributes.entryPoint = resourceEntry.sanitizedClassName;
+        }
+
+        const remoteSpan = TRACE_PROCESSOR.tracingBackend?.startSpan({
+          name: `${sanitizedName}.lifecycle`,
+          op: 'lifecycle',
+          attributes: spanAttributes,
+          parentContext: parentSpanContext,
+        });
+        self[LIFECYCLE_SPAN] = remoteSpan;
+
+        let openCtx = ctx;
+        if (remoteSpan?.spanContext != null) {
+          const traceAttrs = { [TRACE_SPAN_ATTRIBUTE]: remoteSpan.spanContext };
+          openCtx = ctx ? ctx.derive({ attributes: traceAttrs }) : new Context({ attributes: traceAttrs });
+        }
+
+        try {
+          return await originalOpen.call(this, openCtx);
+        } catch (err) {
+          remoteSpan?.setError?.(err);
+          remoteSpan?.end();
+          self[LIFECYCLE_SPAN] = undefined;
+          throw err;
+        }
+      };
+
+      proto.close = async function (ctx?: Context): Promise<any> {
+        const self = this as any;
+        const remoteSpan: RemoteSpan | undefined = self[LIFECYCLE_SPAN];
+        try {
+          return await originalClose.call(this, ctx);
+        } catch (err) {
+          remoteSpan?.setError?.(err);
+          throw err;
+        } finally {
+          if (remoteSpan) {
+            remoteSpan.end();
+            self[LIFECYCLE_SPAN] = undefined;
+          }
+        }
+      };
+    }
+
     Object.defineProperty(klass, 'name', { value: constructor.name });
     return klass;
   };
@@ -51,6 +160,9 @@ export type InfoOptions = {
    * Default: 0 - objects will be stringified with toString.
    */
   depth?: number | null;
+
+  /** When true, the property value is also set as an OTEL span attribute on every span created by this resource. */
+  spanAttribute?: boolean;
 };
 
 /**
@@ -68,63 +180,157 @@ 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>;
 };
 
 /**
  * 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, 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 span = TRACE_PROCESSOR.traceSpan({
-        parentCtx,
-        methodName: propertyKey,
-        instance: this,
-        showInBrowserTimeline,
-        op,
-        attributes,
-      });
-
-      const callArgs = span.ctx ? [span.ctx, ...args.slice(1)] : args;
+      const startTs = performance.now();
+
+      const parentSpanContext = parentCtx?.getAttribute(TRACE_SPAN_ATTRIBUTE);
+
+      const resourceEntry = TRACE_PROCESSOR.resourceInstanceIndex.get(this);
+      const className = resourceEntry?.sanitizedClassName ?? sanitizeClassName(target.constructor?.name ?? 'unknown');
+      const spanName = `${className}.${propertyKey}`;
+
+      const spanAttributes: Record<string, any> = {};
+      if (resourceEntry) {
+        spanAttributes.entryPoint = resourceEntry.sanitizedClassName;
+      }
+      collectSpanAttributes(this, spanAttributes);
+      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) {
-        span.markError(err);
+        remoteSpan?.setError?.(err);
         throw err;
       } finally {
-        span.markSuccess();
+        remoteSpan?.end();
+        if (showInBrowserTimeline && typeof globalThis?.performance?.measure === 'function') {
+          performance.measure(spanName, { start: startTs, end: performance.now() });
+        }
       }
     };
   };
 
-const spans = new Map<string, TracingSpan>();
+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: TraceSpanParams & { id: string }) => {
-  if (spans.has(params.id)) {
-    return;
+const spanStart = (params: ManualSpanParams): Context | null => {
+  if (manualSpans.has(params.id) || manualSpanTimestamps.has(params.id)) {
+    return params.parentCtx;
+  }
+
+  const resourceEntry = TRACE_PROCESSOR.resourceInstanceIndex.get(params.instance);
+  const className = resourceEntry?.sanitizedClassName ?? '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 (resourceEntry) {
+    spanAttributes.entryPoint = resourceEntry.sanitizedClassName;
+  }
+  collectSpanAttributes(params.instance, spanAttributes);
+  if (params.attributes) {
+    for (const [key, value] of Object.entries(params.attributes)) {
+      spanAttributes[key.startsWith('ctx.') ? key : `ctx.${key}`] = value;
+    }
   }
 
-  const span = TRACE_PROCESSOR.traceSpan(params);
-  spans.set(params.id, span);
+  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 span = spans.get(id);
-  if (span) {
-    span.markSuccess();
-    spans.delete(id);
+  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);
   }
 };
 
@@ -141,10 +347,8 @@ const addLink = (parent: any, child: any, opts: AddLinkOptions = {}) => {
   TRACE_PROCESSOR.addLink(parent, child, opts);
 };
 
-export type TraceDiagnosticParams<T> = {
-  /**
-   * Unique ID.
-   */
+export type TraceDiagnosticProps<T> = {
+  /** Unique ID. */
   id: string;
 
   /**
@@ -153,9 +357,7 @@ export type TraceDiagnosticParams<T> = {
    */
   name?: string;
 
-  /**
-   * Function that will be called to fetch the diagnostic data.
-   */
+  /** Function that will be called to fetch the diagnostic data. */
   fetch: () => MaybePromise<T>;
 };
 
@@ -167,7 +369,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/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

@@ -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/index.ts

@@ -7,11 +7,10 @@ import { trace } from './api';
 export * from './api';
 export * from './symbols';
 export * from './trace-processor';
-export * from './trace-sender';
+export * from './tracing-types';
 export * from './metrics';
 export * from './diagnostic';
 export * from './diagnostics-channel';
-export * from './remote/tracing';
 export * from './remote/metrics';
 
 trace.diagnostic({

package/src/remote/index.ts

@@ -3,4 +3,3 @@
 //
 
 export * from './metrics';
-export * from './tracing';

package/src/symbols.ts

@@ -22,5 +22,3 @@ export const getTracingContext = (target: any): TracingContext => {
     metricsProperties: {},
   });
 };
-
-export const TRACE_SPAN_ATTRIBUTE = 'dxos.trace-span';