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

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";
 
@@ -29,6 +30,10 @@ var createId = () => Math.random().toString(36).slice(2);
 var __dxlog_file = "/__w/dxos/dxos/packages/common/tracing/src/diagnostic.ts";
 var DIAGNOSTICS_TIMEOUT = 1e4;
 var TraceDiagnosticImpl = class {
+  id;
+  fetch;
+  name;
+  _onUnregister;
   constructor(id, fetch, name, _onUnregister) {
     this.id = id;
     this.fetch = fetch;
@@ -40,11 +45,9 @@ var TraceDiagnosticImpl = class {
   }
 };
 var DiagnosticsManager = class {
-  constructor() {
-    this.instanceId = createId();
-    this.registry = /* @__PURE__ */ new Map();
-    this._instanceTag = null;
-  }
+  instanceId = createId();
+  registry = /* @__PURE__ */ new Map();
+  _instanceTag = null;
   get instanceTag() {
     return this._instanceTag;
   }
@@ -117,17 +120,19 @@ var __dxlog_file2 = "/__w/dxos/dxos/packages/common/tracing/src/diagnostics-chan
 var DEFAULT_CHANNEL_NAME = "dxos-diagnostics";
 var DISCOVER_TIME = 500;
 var DiagnosticsChannel = class _DiagnosticsChannel {
+  _channelName;
   static get supported() {
     return globalThis.BroadcastChannel != null;
   }
+  _ctx = new Context(void 0, {
+    F: __dxlog_file2,
+    L: 46
+  });
+  // Separate channels becauase the client and server may be in the same process.
+  _serveChannel = void 0;
+  _clientChannel = void 0;
   constructor(_channelName = DEFAULT_CHANNEL_NAME) {
     this._channelName = _channelName;
-    this._ctx = new Context(void 0, {
-      F: __dxlog_file2,
-      L: 46
-    });
-    this._serveChannel = void 0;
-    this._clientChannel = void 0;
     if (_DiagnosticsChannel.supported) {
       this._serveChannel = new BroadcastChannel(_channelName);
       this._clientChannel = new BroadcastChannel(_channelName);
@@ -262,9 +267,7 @@ var DiagnosticsChannel = class _DiagnosticsChannel {
 
 // src/remote/metrics.ts
 var RemoteMetrics = class {
-  constructor() {
-    this._metrics = /* @__PURE__ */ new Set();
-  }
+  _metrics = /* @__PURE__ */ new Set();
   registerProcessor(processor) {
     this._metrics.add(processor);
   }
@@ -283,30 +286,132 @@ var RemoteMetrics = class {
 };
 
 // src/remote/tracing.ts
+var MAX_ENDED_CONTEXTS = 1e4;
 var RemoteTracing = class {
-  constructor() {
-    this._spanMap = /* @__PURE__ */ new Map();
-  }
+  _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 {
-      const remoteSpan = this._spanMap.get(span2);
-      if (remoteSpan) {
-        remoteSpan.end();
-        this._spanMap.delete(span2);
+      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 {
+      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);
     }
   }
 };
@@ -314,6 +419,7 @@ var RemoteTracing = class {
 // src/trace-sender.ts
 import { Stream } from "@dxos/codec-protobuf/stream";
 var TraceSender = class {
+  _traceProcessor;
   constructor(_traceProcessor) {
     this._traceProcessor = _traceProcessor;
   }
@@ -414,6 +520,15 @@ var WeakRef = globalThis.WeakRef ?? WeakRefMock;
 // src/trace-processor.ts
 var __dxlog_file3 = "/__w/dxos/dxos/packages/common/tracing/src/trace-processor.ts";
 var ResourceEntry = class {
+  data;
+  instance;
+  annotation;
+  /**
+  * Sometimes bundlers mangle class names: WebFile -> WebFile2.
+  *
+  * We use a heuristic to remove the suffix.
+  */
+  sanitizedClassName;
   constructor(data, instance, annotation) {
     this.data = data;
     this.instance = instance;
@@ -431,53 +546,22 @@ var REFRESH_INTERVAL = 1e3;
 var MAX_INFO_OBJECT_DEPTH = 8;
 var IS_CLOUDFLARE_WORKERS = !!globalThis?.navigator?.userAgent?.includes("Cloudflare-Workers");
 var TraceProcessor = class {
+  diagnostics = new DiagnosticsManager();
+  diagnosticsChannel = new DiagnosticsChannel();
+  remoteMetrics = new RemoteMetrics();
+  remoteTracing = new RemoteTracing();
+  subscriptions = /* @__PURE__ */ new Set();
+  resources = /* @__PURE__ */ new Map();
+  resourceInstanceIndex = /* @__PURE__ */ new WeakMap();
+  resourceIdList = [];
+  spans = /* @__PURE__ */ new Map();
+  spanIdList = [];
+  logs = [];
+  _instanceTag = null;
   constructor() {
-    this.diagnostics = new DiagnosticsManager();
-    this.diagnosticsChannel = new DiagnosticsChannel();
-    this.remoteMetrics = new RemoteMetrics();
-    this.remoteTracing = new RemoteTracing();
-    this.subscriptions = /* @__PURE__ */ new Set();
-    this.resources = /* @__PURE__ */ new Map();
-    this.resourceInstanceIndex = /* @__PURE__ */ new WeakMap();
-    this.resourceIdList = [];
-    this.spans = /* @__PURE__ */ new Map();
-    this.spanIdList = [];
-    this.logs = [];
-    this._instanceTag = null;
-    this._logProcessor = (config, entry) => {
-      switch (entry.level) {
-        case LogLevel.ERROR:
-        case LogLevel.WARN:
-        case LogLevel.TRACE: {
-          const scope = entry.meta?.S;
-          const resource2 = this.resourceInstanceIndex.get(scope);
-          if (!resource2) {
-            return;
-          }
-          const context = getContextFromEntry(entry) ?? {};
-          for (const key of Object.keys(context)) {
-            context[key] = sanitizeValue(context[key], 0, this);
-          }
-          const entryToPush = {
-            level: entry.level,
-            message: entry.message ?? (entry.error ? entry.error.message ?? String(entry.error) : ""),
-            context,
-            timestamp: /* @__PURE__ */ new Date(),
-            meta: {
-              file: entry.meta?.F ?? "",
-              line: entry.meta?.L ?? 0,
-              resourceId: resource2.data.id
-            }
-          };
-          this._pushLog(entryToPush);
-          break;
-        }
-        default:
-      }
-    };
     log.addProcessor(this._logProcessor.bind(this), void 0, {
       F: __dxlog_file3,
-      L: 103,
+      L: 104,
       S: this,
       C: (f, a) => f(...a)
     });
@@ -658,31 +742,73 @@ var TraceProcessor = class {
       subscription.newLogs.push(log2);
     }
   }
+  _logProcessor = (config, entry) => {
+    switch (entry.level) {
+      case LogLevel.ERROR:
+      case LogLevel.WARN:
+      case LogLevel.TRACE: {
+        const scope = entry.meta?.S;
+        const resource2 = this.resourceInstanceIndex.get(scope);
+        if (!resource2) {
+          return;
+        }
+        const context = getContextFromEntry(entry) ?? {};
+        for (const key of Object.keys(context)) {
+          context[key] = sanitizeValue(context[key], 0, this);
+        }
+        const entryToPush = {
+          level: entry.level,
+          message: entry.message ?? (entry.error ? entry.error.message ?? String(entry.error) : ""),
+          context,
+          timestamp: /* @__PURE__ */ new Date(),
+          meta: {
+            file: entry.meta?.F ?? "",
+            line: entry.meta?.L ?? 0,
+            resourceId: resource2.data.id
+          }
+        };
+        this._pushLog(entryToPush);
+        break;
+      }
+      default:
+    }
+  };
 };
 var TracingSpan = class _TracingSpan {
-  static {
-    this.nextId = 0;
-  }
+  _traceProcessor;
+  static nextId = 0;
+  id;
+  parentId = null;
+  methodName;
+  resourceId = null;
+  op;
+  attributes;
+  startTs;
+  endTs = null;
+  error = null;
+  _showInBrowserTimeline;
+  _showInRemoteTracing;
+  _ctx;
   constructor(_traceProcessor, params) {
     this._traceProcessor = _traceProcessor;
-    this.parentId = null;
-    this.resourceId = null;
-    this.endTs = null;
-    this.error = null;
-    this._ctx = null;
     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 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;
@@ -693,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);
@@ -802,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";
@@ -838,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();
@@ -903,6 +1040,11 @@ var trace = {
 
 // src/metrics/base.ts
 var BaseCounter = class {
+  /**
+  * @internal
+  */
+  _instance;
+  name;
   /**
   * @internal
   */
@@ -916,9 +1058,10 @@ var BaseCounter = class {
 
 // src/metrics/unary-counter.ts
 var UnaryCounter = class extends BaseCounter {
+  value = 0;
+  units;
   constructor({ units } = {}) {
     super();
-    this.value = 0;
     this.units = units;
   }
   inc(by = 1) {
@@ -938,11 +1081,12 @@ var UnaryCounter = class extends BaseCounter {
 // src/metrics/time-series-counter.ts
 var MAX_BUCKETS = 60;
 var TimeSeriesCounter = class extends BaseCounter {
+  _currentValue = 0;
+  _totalValue = 0;
+  _buckets = [];
+  units;
   constructor({ units } = {}) {
     super();
-    this._currentValue = 0;
-    this._totalValue = 0;
-    this._buckets = [];
     this.units = units;
   }
   inc(by = 1) {
@@ -978,13 +1122,10 @@ var TimeSeriesCounter = class extends BaseCounter {
 // src/metrics/time-usage-counter.ts
 var MAX_BUCKETS2 = 60;
 var TimeUsageCounter = class extends BaseCounter {
-  constructor() {
-    super(...arguments);
-    this._currentValue = 0;
-    this._totalValue = 0;
-    this._buckets = [];
-    this._lastTickTime = performance.now();
-  }
+  _currentValue = 0;
+  _totalValue = 0;
+  _buckets = [];
+  _lastTickTime = performance.now();
   record(time) {
     this._currentValue += time;
     this._totalValue += time;
@@ -1029,9 +1170,10 @@ var TimeUsageCounter = class extends BaseCounter {
 
 // src/metrics/map-counter.ts
 var MapCounter = class extends BaseCounter {
+  values = /* @__PURE__ */ new Map();
+  units;
   constructor({ units } = {}) {
     super();
-    this.values = /* @__PURE__ */ new Map();
     this.units = units;
   }
   inc(key, by = 1) {
@@ -1054,6 +1196,7 @@ var MapCounter = class extends BaseCounter {
 
 // src/metrics/custom-counter.ts
 var CustomCounter = class extends BaseCounter {
+  _getData;
   constructor(_getData) {
     super(), this._getData = _getData;
   }