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

package/dist/lib/node-esm/index.mjs

@@ -1,10 +1,10 @@
 import { createRequire } from 'node:module';const require = createRequire(import.meta.url);
 
 // src/api.ts
-import { Context as Context2 } from "@dxos/context";
+import { Context as Context3 } from "@dxos/context";
 
 // src/symbols.ts
-var symbolTracingContext = Symbol("dxos.tracing.context");
+var symbolTracingContext = /* @__PURE__ */ Symbol("dxos.tracing.context");
 var getTracingContext = (target) => {
   return target[symbolTracingContext] ??= {
     infoProperties: {},
@@ -15,6 +15,7 @@ var TRACE_SPAN_ATTRIBUTE = "dxos.trace-span";
 
 // src/trace-processor.ts
 import { unrefTimeout } from "@dxos/async";
+import { Context as Context2 } from "@dxos/context";
 import { LogLevel, getContextFromEntry, log } from "@dxos/log";
 import { getPrototypeSpecificInstanceId } from "@dxos/util";
 
@@ -285,29 +286,132 @@ var RemoteMetrics = class {
 };
 
 // src/remote/tracing.ts
+var MAX_ENDED_CONTEXTS = 1e4;
 var RemoteTracing = class {
   _tracing;
   _spanMap = /* @__PURE__ */ new Map();
+  _idToSpan = /* @__PURE__ */ new Map();
+  /**
+  * 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.
+  */
+  _endedSpanContexts = /* @__PURE__ */ new Map();
+  /**
+  * Buffers flushSpan calls that arrive before a processor is registered,
+  * so early startup spans are not silently dropped.
+  */
+  _pendingFlushes = [];
   registerProcessor(processor) {
     this._tracing = processor;
+    const pending = this._pendingFlushes;
+    this._pendingFlushes = null;
+    if (pending) {
+      for (const { span: span2, isEnd } of pending) {
+        this._replayFlush(span2, isEnd);
+      }
+    }
+  }
+  /** Returns the opaque OTEL context for the given DXOS span ID, if one exists. */
+  getSpanContext(spanId) {
+    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(span2, fn) {
+    const remoteSpan = this._spanMap.get(span2);
+    if (remoteSpan?.wrapExecution) {
+      return remoteSpan.wrapExecution(fn);
+    }
+    return fn();
   }
   flushSpan(span2) {
+    if (!span2.showInRemoteTracing) {
+      return;
+    }
     if (!this._tracing) {
+      this._pendingFlushes?.push({
+        span: span2,
+        isEnd: !!span2.endTs
+      });
       return;
     }
     if (!span2.endTs) {
-      const remoteSpan = this._tracing.startSpan({
-        name: span2.methodName,
-        op: span2.op ?? "function",
-        attributes: span2.attributes
-      });
-      this._spanMap.set(span2, remoteSpan);
+      this._startRemoteSpan(span2);
+    } else {
+      this._endRemoteSpan(span2);
+    }
+  }
+  _startRemoteSpan(span2) {
+    let parentContext;
+    if (span2.parentId != null) {
+      const parentTracingSpan = this._idToSpan.get(span2.parentId);
+      if (parentTracingSpan) {
+        parentContext = this._spanMap.get(parentTracingSpan)?.spanContext;
+      }
+      if (parentContext == null) {
+        parentContext = this._endedSpanContexts.get(span2.parentId);
+      }
+    }
+    const attributes = {};
+    if (span2.sanitizedClassName) {
+      attributes.entryPoint = span2.sanitizedClassName;
+    }
+    for (const [key, value] of Object.entries(span2.attributes)) {
+      attributes[key.startsWith("ctx.") ? key : `ctx.${key}`] = value;
+    }
+    const remoteSpan = this._tracing.startSpan({
+      name: span2.name,
+      op: span2.op ?? "function",
+      attributes,
+      parentContext
+    });
+    this._spanMap.set(span2, remoteSpan);
+    this._idToSpan.set(span2.id, span2);
+  }
+  _endRemoteSpan(span2) {
+    const remoteSpan = this._spanMap.get(span2);
+    if (remoteSpan) {
+      if (remoteSpan.spanContext != null) {
+        this._endedSpanContexts.set(span2.id, remoteSpan.spanContext);
+        this._evictEndedContexts();
+      }
+      remoteSpan.end();
+      this._spanMap.delete(span2);
+      this._idToSpan.delete(span2.id);
+    }
+  }
+  /**
+  * Replays a buffered flush that was queued before the processor was registered.
+  * For spans that started AND ended before registration, replays both events.
+  */
+  _replayFlush(span2, isEnd) {
+    if (!isEnd) {
+      this._startRemoteSpan(span2);
+      if (span2.endTs != null) {
+        this._endRemoteSpan(span2);
+      }
     } else {
-      const remoteSpan = this._spanMap.get(span2);
-      if (remoteSpan) {
-        remoteSpan.end();
-        this._spanMap.delete(span2);
+      if (!this._spanMap.has(span2)) {
+        this._startRemoteSpan(span2);
       }
+      this._endRemoteSpan(span2);
+    }
+  }
+  _evictEndedContexts() {
+    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);
     }
   }
 };
@@ -457,7 +561,7 @@ var TraceProcessor = class {
   constructor() {
     log.addProcessor(this._logProcessor.bind(this), void 0, {
       F: __dxlog_file3,
-      L: 103,
+      L: 104,
       S: this,
       C: (f, a) => f(...a)
     });
@@ -683,7 +787,8 @@ var TracingSpan = class _TracingSpan {
   endTs = null;
   error = null;
   _showInBrowserTimeline;
-  _ctx = null;
+  _showInRemoteTracing;
+  _ctx;
   constructor(_traceProcessor, params) {
     this._traceProcessor = _traceProcessor;
     this.id = _TracingSpan.nextId++;
@@ -691,14 +796,19 @@ var TracingSpan = 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 Context2(void 0, {
+      F: __dxlog_file3,
+      L: 397
+    });
+    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;
@@ -709,9 +819,17 @@ var TracingSpan = class _TracingSpan {
     const resource2 = this._traceProcessor.resources.get(this.resourceId);
     return resource2 ? `${resource2.sanitizedClassName}#${resource2.data.instanceId}.${this.methodName}` : this.methodName;
   }
+  /** Sanitized class name of the owning resource, if available. */
+  get sanitizedClassName() {
+    const resource2 = this.resourceId != null ? this._traceProcessor.resources.get(this.resourceId) : void 0;
+    return resource2?.sanitizedClassName;
+  }
   get ctx() {
     return this._ctx;
   }
+  get showInRemoteTracing() {
+    return this._showInRemoteTracing;
+  }
   markSuccess() {
     this.endTs = performance.now();
     this._traceProcessor._flushSpan(this);
@@ -818,13 +936,13 @@ var areEqualShallow = (a, b) => {
   return true;
 };
 var sanitizeClassName = (className) => {
+  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;
 };
 var isSetLike = (value) => value instanceof Set || typeof value === "object" && value !== null && Object.getPrototypeOf(value).constructor.name === "ComplexSet";
 var isMapLike = (value) => value instanceof Map || typeof value === "object" && value !== null && Object.getPrototypeOf(value).constructor.name === "ComplexMap";
@@ -854,30 +972,33 @@ var info = (opts = {}) => (target, propertyKey, descriptor) => {
 var mark = (name) => {
   performance.mark(name);
 };
-var span = ({ showInBrowserTimeline = false, op, attributes } = {}) => (target, propertyKey, descriptor) => {
+var span = ({ showInBrowserTimeline = false, showInRemoteTracing = true, op, attributes } = {}) => (target, propertyKey, descriptor) => {
   const method = descriptor.value;
   descriptor.value = async function(...args) {
-    const parentCtx = args[0] instanceof Context2 ? args[0] : null;
+    const explicitCtx = args[0] instanceof Context3 ? args[0] : null;
     const span2 = TRACE_PROCESSOR.traceSpan({
-      parentCtx,
+      parentCtx: explicitCtx,
       methodName: propertyKey,
       instance: this,
       showInBrowserTimeline,
+      showInRemoteTracing,
       op,
       attributes
     });
-    const callArgs = span2.ctx ? [
+    const callArgs = explicitCtx ? [
       span2.ctx,
       ...args.slice(1)
     ] : args;
-    try {
-      return await method.apply(this, callArgs);
-    } catch (err) {
-      span2.markError(err);
-      throw err;
-    } finally {
-      span2.markSuccess();
-    }
+    return TRACE_PROCESSOR.remoteTracing.wrapExecution(span2, async () => {
+      try {
+        return await method.apply(this, callArgs);
+      } catch (err) {
+        span2.markError(err);
+        throw err;
+      } finally {
+        span2.markSuccess();
+      }
+    });
   };
 };
 var spans = /* @__PURE__ */ new Map();