@dxos/tracing 0.8.3 → 0.8.4-main.05e74ebcff

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

@@ -1,34 +1,122 @@
 import { createRequire } from 'node:module';const require = createRequire(import.meta.url);
 
-// packages/common/tracing/src/api.ts
-import { Context as Context2 } from "@dxos/context";
+// src/api.ts
+import { Context as Context2, LifecycleState, Resource, TRACE_SPAN_ATTRIBUTE } from "@dxos/context";
 
-// packages/common/tracing/src/symbols.ts
-var symbolTracingContext = Symbol("dxos.tracing.context");
+// src/symbols.ts
+var symbolTracingContext = /* @__PURE__ */ Symbol("dxos.tracing.context");
 var getTracingContext = (target) => {
   return target[symbolTracingContext] ??= {
     infoProperties: {},
     metricsProperties: {}
   };
 };
-var TRACE_SPAN_ATTRIBUTE = "dxos.trace-span";
 
-// packages/common/tracing/src/trace-processor.ts
-import { unrefTimeout } from "@dxos/async";
-import { LogLevel, getContextFromEntry, log } from "@dxos/log";
+// src/trace-processor.ts
+import { LogLevel, log } from "@dxos/log";
 import { getPrototypeSpecificInstanceId } from "@dxos/util";
 
-// packages/common/tracing/src/diagnostic.ts
+// src/buffering-backend.ts
+var BUFFERED_PREFIX = "buffered-";
+var BufferedSpan = class {
+  options;
+  spanContext;
+  startTime;
+  delegate;
+  #ended = false;
+  #endTime;
+  #error;
+  #hasError = false;
+  constructor(options, id) {
+    this.options = options;
+    this.spanContext = {
+      traceparent: `${BUFFERED_PREFIX}${id}`
+    };
+    this.startTime = Date.now();
+  }
+  end(endTime) {
+    if (this.delegate) {
+      this.delegate.end(endTime);
+      return;
+    }
+    this.#endTime = endTime ?? Date.now();
+    this.#ended = true;
+  }
+  setError(err) {
+    if (this.delegate) {
+      this.delegate.setError?.(err);
+      return;
+    }
+    this.#error = err;
+    this.#hasError = true;
+  }
+  replay(real) {
+    if (this.#hasError) {
+      real.setError?.(this.#error);
+    }
+    if (this.#ended) {
+      real.end(this.#endTime);
+    } else {
+      this.delegate = real;
+    }
+  }
+};
+var BufferingTracingBackend = class {
+  #pending = [];
+  #counter = 0;
+  startSpan(options) {
+    const span2 = new BufferedSpan(options, ++this.#counter);
+    this.#pending.push(span2);
+    return span2;
+  }
+  /** Discard all buffered spans without replaying them. */
+  clear() {
+    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) {
+    const idMap = /* @__PURE__ */ new Map();
+    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;
+  }
+};
+
+// src/diagnostic.ts
 import { asyncTimeout } from "@dxos/async";
 import { invariant } from "@dxos/invariant";
 
-// packages/common/tracing/src/util.ts
+// src/util.ts
 var createId = () => Math.random().toString(36).slice(2);
 
-// packages/common/tracing/src/diagnostic.ts
-var __dxlog_file = "/home/runner/work/dxos/dxos/packages/common/tracing/src/diagnostic.ts";
+// src/diagnostic.ts
+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 +128,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;
   }
@@ -70,27 +156,11 @@ var DiagnosticsManager = class {
   }
   async fetch(request) {
     if (request.instanceId != null) {
-      invariant(request.instanceId === this.instanceId, "Invalid instance id", {
-        F: __dxlog_file,
-        L: 82,
-        S: this,
-        A: [
-          "request.instanceId === this.instanceId",
-          "'Invalid instance id'"
-        ]
-      });
+      invariant(request.instanceId === this.instanceId, "Invalid instance id", { "~LogMeta": "~LogMeta", F: __dxlog_file, L: 52, S: this, A: ["request.instanceId === this.instanceId", "'Invalid instance id'"] });
     }
     const { id } = request;
     const diagnostic2 = this.registry.get(id);
-    invariant(diagnostic2, "Diagnostic not found", {
-      F: __dxlog_file,
-      L: 86,
-      S: this,
-      A: [
-        "diagnostic",
-        "'Diagnostic not found'"
-      ]
-    });
+    invariant(diagnostic2, "Diagnostic not found", { "~LogMeta": "~LogMeta", F: __dxlog_file, L: 56, S: this, A: ["diagnostic", "'Diagnostic not found'"] });
     try {
       const data = await asyncTimeout(diagnostic2.fetch(), DIAGNOSTICS_TIMEOUT);
       return {
@@ -109,25 +179,24 @@ var DiagnosticsManager = class {
   }
 };
 
-// packages/common/tracing/src/diagnostics-channel.ts
+// src/diagnostics-channel.ts
 import { Trigger, sleep } from "@dxos/async";
 import { Context } from "@dxos/context";
 import { invariant as invariant2 } from "@dxos/invariant";
-var __dxlog_file2 = "/home/runner/work/dxos/dxos/packages/common/tracing/src/diagnostics-channel.ts";
+var __dxlog_file2 = "/__w/dxos/dxos/packages/common/tracing/src/diagnostics-channel.ts";
 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, { "~LogMeta": "~LogMeta", F: __dxlog_file2, L: 16 });
+  // 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);
@@ -150,15 +219,7 @@ var DiagnosticsChannel = class _DiagnosticsChannel {
     }
   }
   serve(manager) {
-    invariant2(this._serveChannel, void 0, {
-      F: __dxlog_file2,
-      L: 78,
-      S: this,
-      A: [
-        "this._serveChannel",
-        ""
-      ]
-    });
+    invariant2(this._serveChannel, void 0, { "~LogMeta": "~LogMeta", F: __dxlog_file2, L: 43, S: this, A: ["this._serveChannel", ""] });
     const listener = async (event) => {
       switch (event.data.type) {
         case "DIAGNOSTICS_DISCOVER": {
@@ -190,15 +251,7 @@ var DiagnosticsChannel = class _DiagnosticsChannel {
     this._ctx.onDispose(() => this._serveChannel.removeEventListener("message", listener));
   }
   async discover() {
-    invariant2(this._clientChannel, void 0, {
-      F: __dxlog_file2,
-      L: 114,
-      S: this,
-      A: [
-        "this._clientChannel",
-        ""
-      ]
-    });
+    invariant2(this._clientChannel, void 0, { "~LogMeta": "~LogMeta", F: __dxlog_file2, L: 77, S: this, A: ["this._clientChannel", ""] });
     const diagnostics = [];
     const collector = (event) => {
       const data = event.data;
@@ -226,15 +279,7 @@ var DiagnosticsChannel = class _DiagnosticsChannel {
     }
   }
   async fetch(request) {
-    invariant2(this._clientChannel, void 0, {
-      F: __dxlog_file2,
-      L: 147,
-      S: this,
-      A: [
-        "this._clientChannel",
-        ""
-      ]
-    });
+    invariant2(this._clientChannel, void 0, { "~LogMeta": "~LogMeta", F: __dxlog_file2, L: 106, S: this, A: ["this._clientChannel", ""] });
     const requestId = createId();
     const trigger = new Trigger();
     const listener = (event) => {
@@ -260,11 +305,9 @@ var DiagnosticsChannel = class _DiagnosticsChannel {
   }
 };
 
-// packages/common/tracing/src/remote/metrics.ts
+// src/remote/metrics.ts
 var RemoteMetrics = class {
-  constructor() {
-    this._metrics = /* @__PURE__ */ new Set();
-  }
+  _metrics = /* @__PURE__ */ new Set();
   registerProcessor(processor) {
     this._metrics.add(processor);
   }
@@ -282,125 +325,7 @@ var RemoteMetrics = class {
   }
 };
 
-// packages/common/tracing/src/remote/tracing.ts
-var RemoteTracing = class {
-  constructor() {
-    this._spanMap = /* @__PURE__ */ new Map();
-  }
-  registerProcessor(processor) {
-    this._tracing = processor;
-  }
-  flushSpan(span2) {
-    if (!this._tracing) {
-      return;
-    }
-    if (!span2.endTs) {
-      const remoteSpan = this._tracing.startSpan({
-        name: span2.methodName,
-        op: span2.op ?? "function",
-        attributes: span2.attributes
-      });
-      this._spanMap.set(span2, remoteSpan);
-    } else {
-      const remoteSpan = this._spanMap.get(span2);
-      if (remoteSpan) {
-        remoteSpan.end();
-        this._spanMap.delete(span2);
-      }
-    }
-  }
-};
-
-// packages/common/tracing/src/trace-sender.ts
-import { Stream } from "@dxos/codec-protobuf/stream";
-var TraceSender = class {
-  constructor(_traceProcessor) {
-    this._traceProcessor = _traceProcessor;
-  }
-  streamTrace(request) {
-    return new Stream(({ ctx, next }) => {
-      const flushEvents = (resources, spans2, logs) => {
-        const event = {
-          resourceAdded: [],
-          resourceRemoved: [],
-          spanAdded: [],
-          logAdded: []
-        };
-        if (resources) {
-          for (const id of resources) {
-            const entry = this._traceProcessor.resources.get(id);
-            if (entry) {
-              event.resourceAdded.push({
-                resource: entry.data
-              });
-            } else {
-              event.resourceRemoved.push({
-                id
-              });
-            }
-          }
-        } else {
-          for (const entry of this._traceProcessor.resources.values()) {
-            event.resourceAdded.push({
-              resource: entry.data
-            });
-          }
-        }
-        if (spans2) {
-          for (const id of spans2) {
-            const span2 = this._traceProcessor.spans.get(id);
-            if (span2) {
-              event.spanAdded.push({
-                span: span2
-              });
-            }
-          }
-        } else {
-          for (const span2 of this._traceProcessor.spans.values()) {
-            event.spanAdded.push({
-              span: span2
-            });
-          }
-        }
-        if (logs) {
-          for (const log2 of logs) {
-            event.logAdded.push({
-              log: log2
-            });
-          }
-        } else {
-          for (const log2 of this._traceProcessor.logs) {
-            event.logAdded.push({
-              log: log2
-            });
-          }
-        }
-        if (event.resourceAdded.length > 0 || event.resourceRemoved.length > 0 || event.spanAdded.length > 0) {
-          next(event);
-        }
-      };
-      const flush = () => {
-        flushEvents(subscription.dirtyResources, subscription.dirtySpans, subscription.newLogs);
-        subscription.dirtyResources.clear();
-        subscription.dirtySpans.clear();
-        subscription.newLogs.length = 0;
-      };
-      const subscription = {
-        flush,
-        dirtyResources: /* @__PURE__ */ new Set(),
-        dirtySpans: /* @__PURE__ */ new Set(),
-        newLogs: []
-      };
-      this._traceProcessor.subscriptions.add(subscription);
-      ctx.onDispose(() => {
-        this._traceProcessor.subscriptions.delete(subscription);
-      });
-      flushEvents(null, null, null);
-    });
-  }
-};
-
-// packages/common/tracing/src/weak-ref.ts
+// src/weak-ref.ts
 var WeakRefMock = class {
   // eslint-disable-next-line @typescript-eslint/no-useless-constructor
   constructor(target) {
@@ -411,9 +336,18 @@ var WeakRefMock = class {
 };
 var WeakRef = globalThis.WeakRef ?? WeakRefMock;
 
-// packages/common/tracing/src/trace-processor.ts
-var __dxlog_file3 = "/home/runner/work/dxos/dxos/packages/common/tracing/src/trace-processor.ts";
+// 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;
@@ -425,66 +359,56 @@ var ResourceEntry = class {
   }
 };
 var MAX_RESOURCE_RECORDS = 2e3;
-var MAX_SPAN_RECORDS = 1e3;
 var MAX_LOG_RECORDS = 1e3;
-var REFRESH_INTERVAL = 1e3;
 var MAX_INFO_OBJECT_DEPTH = 8;
-var IS_CLOUDFLARE_WORKERS = !!globalThis?.navigator?.userAgent?.includes("Cloudflare-Workers");
 var TraceProcessor = class {
-  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);
+  diagnostics = new DiagnosticsManager();
+  diagnosticsChannel = new DiagnosticsChannel();
+  remoteMetrics = new RemoteMetrics();
+  #bufferingBackend = new BufferingTracingBackend();
+  #activeBackend = this.#bufferingBackend;
+  /**
+  * Tracing backend. Initially a buffering backend that records spans;
+  * once the observability package sets a real backend, the buffer is drained
+  * and a thin translating wrapper is installed that resolves stale buffered
+  * parent IDs still held by in-flight {@link Context} objects.
+  *
+  * The wrapper only allocates when a `buffered-*` parent is actually encountered;
+  * the common path is a single `startsWith` check and direct passthrough.
+  */
+  get tracingBackend() {
+    return this.#activeBackend;
+  }
+  set tracingBackend(backend) {
+    if (!backend || backend === this.#bufferingBackend) {
+      this.#bufferingBackend.clear();
+      this.#activeBackend = this.#bufferingBackend;
+      return;
+    }
+    const idMap = this.#bufferingBackend.drain(backend);
+    this.#activeBackend = {
+      startSpan: (options) => {
+        const parent = options.parentContext;
+        if (parent?.traceparent.startsWith(BUFFERED_PREFIX)) {
+          const translated = idMap.get(parent.traceparent);
+          if (translated) {
+            return backend.startSpan({
+              ...options,
+              parentContext: translated
+            });
           }
-          const entryToPush = {
-            level: entry.level,
-            message: entry.message,
-            context,
-            timestamp: /* @__PURE__ */ new Date(),
-            meta: {
-              file: entry.meta?.F ?? "",
-              line: entry.meta?.L ?? 0,
-              resourceId: resource2.data.id
-            }
-          };
-          this._pushLog(entryToPush);
-          break;
         }
-        default:
+        return backend.startSpan(options);
       }
     };
-    log.addProcessor(this._logProcessor.bind(this), void 0, {
-      F: __dxlog_file3,
-      L: 103,
-      S: this,
-      C: (f, a) => f(...a)
-    });
-    if (!IS_CLOUDFLARE_WORKERS) {
-      const refreshInterval = setInterval(this.refresh.bind(this), REFRESH_INTERVAL);
-      unrefTimeout(refreshInterval);
-    }
+  }
+  resources = /* @__PURE__ */ new Map();
+  resourceInstanceIndex = /* @__PURE__ */ new WeakMap();
+  resourceIdList = [];
+  logs = [];
+  _instanceTag = null;
+  constructor() {
+    log.addProcessor(this._logProcessor.bind(this), void 0, { "~LogMeta": "~LogMeta", F: __dxlog_file3, L: 80, S: this });
     if (DiagnosticsChannel.supported) {
       this.diagnosticsChannel.serve(this.diagnostics);
     }
@@ -494,10 +418,7 @@ var TraceProcessor = class {
     this._instanceTag = tag;
     this.diagnostics.setInstanceTag(tag);
   }
-  /**
-  * @internal
-  */
-  // TODO(burdon): Comment.
+  /** @internal */
   createTraceResource(params) {
     const id = this.resources.size;
     const tracingContext = getTracingContext(Object.getPrototypeOf(params.instance));
@@ -518,24 +439,10 @@ var TraceProcessor = class {
     if (this.resourceIdList.length > MAX_RESOURCE_RECORDS) {
       this._clearResources();
     }
-    this._markResourceDirty(id);
-  }
-  createTraceSender() {
-    return new TraceSender(this);
-  }
-  traceSpan(params) {
-    const span2 = new TracingSpan(this, params);
-    this._flushSpan(span2);
-    return span2;
   }
   // TODO(burdon): Not implemented.
   addLink(parent, child, opts) {
   }
-  //
-  // Getters
-  //
-  // TODO(burdon): Define type.
-  // TODO(burdon): Reconcile with system service.
   getDiagnostics() {
     this.refresh();
     return {
@@ -543,7 +450,6 @@ var TraceProcessor = class {
         `${entry.sanitizedClassName}#${entry.data.instanceId}`,
         entry.data
       ])),
-      spans: Array.from(this.spans.values()),
       logs: this.logs.filter((log2) => log2.level >= LogLevel.INFO)
     };
   }
@@ -598,43 +504,8 @@ var TraceProcessor = class {
       for (const key of Object.keys(tracingContext.metricsProperties)) {
         instance[key]._tick?.(time);
       }
-      let _changed = false;
-      const oldInfo = resource2.data.info;
       resource2.data.info = this.getResourceInfo(instance);
-      _changed ||= !areEqualShallow(oldInfo, resource2.data.info);
-      const oldMetrics = resource2.data.metrics;
       resource2.data.metrics = this.getResourceMetrics(instance);
-      _changed ||= !areEqualShallow(oldMetrics, resource2.data.metrics);
-      this._markResourceDirty(resource2.data.id);
-    }
-    for (const subscription of this.subscriptions) {
-      subscription.flush();
-    }
-  }
-  //
-  // Implementation
-  //
-  /**
-  * @internal
-  */
-  _flushSpan(runtimeSpan) {
-    const span2 = runtimeSpan.serialize();
-    this.spans.set(span2.id, span2);
-    this.spanIdList.push(span2.id);
-    if (this.spanIdList.length > MAX_SPAN_RECORDS) {
-      this._clearSpans();
-    }
-    this._markSpanDirty(span2.id);
-    this.remoteTracing.flushSpan(runtimeSpan);
-  }
-  _markResourceDirty(id) {
-    for (const subscription of this.subscriptions) {
-      subscription.dirtyResources.add(id);
-    }
-  }
-  _markSpanDirty(id) {
-    for (const subscription of this.subscriptions) {
-      subscription.dirtySpans.add(id);
     }
   }
   _clearResources() {
@@ -643,103 +514,45 @@ var TraceProcessor = class {
       this.resources.delete(id);
     }
   }
-  _clearSpans() {
-    while (this.spanIdList.length > MAX_SPAN_RECORDS) {
-      const id = this.spanIdList.shift();
-      this.spans.delete(id);
-    }
-  }
   _pushLog(log2) {
     this.logs.push(log2);
     if (this.logs.length > MAX_LOG_RECORDS) {
       this.logs.shift();
     }
-    for (const subscription of this.subscriptions) {
-      subscription.newLogs.push(log2);
-    }
   }
-};
-var TracingSpan = class _TracingSpan {
-  static {
-    this.nextId = 0;
-  }
-  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.op = params.op;
-    this.attributes = params.attributes ?? {};
-    if (params.parentCtx) {
-      this._ctx = params.parentCtx.derive({
-        attributes: {
-          [TRACE_SPAN_ATTRIBUTE]: this.id
+  _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 parentId = params.parentCtx.getAttribute(TRACE_SPAN_ATTRIBUTE);
-      if (typeof parentId === "number") {
-        this.parentId = parentId;
+        const context = {
+          ...entry.computedContext
+        };
+        if (entry.computedError !== void 0) {
+          context.error = entry.computedError;
+        }
+        const { filename, line } = entry.computedMeta;
+        const entryToPush = {
+          level: entry.level,
+          message: entry.message ?? entry.computedError ?? "",
+          context,
+          timestamp: new Date(entry.timestamp),
+          meta: {
+            file: filename ?? "",
+            line: line ?? 0,
+            resourceId: resource2.data.id
+          }
+        };
+        this._pushLog(entryToPush);
+        break;
       }
+      default:
     }
-  }
-  get name() {
-    const resource2 = this._traceProcessor.resources.get(this.resourceId);
-    return resource2 ? `${resource2.sanitizedClassName}#${resource2.data.instanceId}.${this.methodName}` : this.methodName;
-  }
-  get ctx() {
-    return this._ctx;
-  }
-  markSuccess() {
-    this.endTs = performance.now();
-    this._traceProcessor._flushSpan(this);
-    if (this._showInBrowserTimeline) {
-      this._markInBrowserTimeline();
-    }
-  }
-  markError(err) {
-    this.endTs = performance.now();
-    this.error = serializeError(err);
-    this._traceProcessor._flushSpan(this);
-    if (this._showInBrowserTimeline) {
-      this._markInBrowserTimeline();
-    }
-  }
-  serialize() {
-    return {
-      id: this.id,
-      resourceId: this.resourceId ?? void 0,
-      methodName: this.methodName,
-      parentId: this.parentId ?? void 0,
-      startTs: this.startTs.toFixed(3),
-      endTs: this.endTs?.toFixed(3) ?? void 0,
-      error: this.error ?? void 0
-    };
-  }
-  _markInBrowserTimeline() {
-    if (typeof globalThis?.performance?.measure === "function") {
-      performance.measure(this.name, {
-        start: this.startTs,
-        end: this.endTs
-      });
-    }
-  }
-};
-var serializeError = (err) => {
-  if (err instanceof Error) {
-    return {
-      name: err.name,
-      message: err.message
-    };
-  }
-  return {
-    message: String(err)
   };
 };
 var TRACE_PROCESSOR = globalThis.TRACE_PROCESSOR ??= new TraceProcessor();
@@ -788,33 +601,46 @@ var sanitizeValue = (value, depth, traceProcessor) => {
       return value.toString();
   }
 };
-var areEqualShallow = (a, b) => {
-  for (const key in a) {
-    if (!(key in b) || a[key] !== b[key]) {
-      return false;
-    }
-  }
-  for (const key in b) {
-    if (!(key in a) || a[key] !== b[key]) {
-      return false;
-    }
-  }
-  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";
 
-// packages/common/tracing/src/api.ts
+// src/api.ts
+var __dxlog_file4 = "/__w/dxos/dxos/packages/common/tracing/src/api.ts";
+var LIFECYCLE_SPAN = /* @__PURE__ */ Symbol("dxos.tracing.lifecycle-span");
+var TRACE_ALL_KEY = "dxos.debug.traceAll";
+var collectSpanAttributes = (instance, spanAttributes) => {
+  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 {
+    }
+  }
+};
 var resource = (options) => (constructor) => {
+  if (options?.lifecycle && !(constructor.prototype instanceof Resource)) {
+    throw new Error(`@trace.resource({ lifecycle: true }) requires ${constructor.name} to extend Resource`);
+  }
   const klass = /* @__PURE__ */ (() => class extends constructor {
     constructor(...rest) {
       super(...rest);
@@ -825,6 +651,65 @@ var resource = (options) => (constructor) => {
       });
     }
   })();
+  if (options?.lifecycle) {
+    const sanitizedName = sanitizeClassName(constructor.name);
+    const proto = klass.prototype;
+    const originalOpen = proto.open;
+    const originalClose = proto.close;
+    proto.open = async function(ctx) {
+      const self = this;
+      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 = {};
+      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 Context2({
+          attributes: traceAttrs
+        }, { "~LogMeta": "~LogMeta", F: __dxlog_file4, L: 79 });
+      }
+      try {
+        return await originalOpen.call(this, openCtx);
+      } catch (err) {
+        remoteSpan?.setError?.(err);
+        remoteSpan?.end();
+        self[LIFECYCLE_SPAN] = void 0;
+        throw err;
+      }
+    };
+    proto.close = async function(ctx) {
+      const self = this;
+      const remoteSpan = 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] = void 0;
+        }
+      }
+    };
+  }
   Object.defineProperty(klass, "name", {
     value: constructor.name
   });
@@ -838,45 +723,117 @@ 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 span2 = TRACE_PROCESSOR.traceSpan({
-      parentCtx,
-      methodName: propertyKey,
-      instance: this,
-      showInBrowserTimeline,
-      op,
-      attributes
-    });
-    const callArgs = span2.ctx ? [
-      span2.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 = {};
+    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
+    }) : void 0;
+    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) {
-      span2.markError(err);
+      remoteSpan?.setError?.(err);
       throw err;
     } finally {
-      span2.markSuccess();
+      remoteSpan?.end();
+      if (showInBrowserTimeline && typeof globalThis?.performance?.measure === "function") {
+        performance.measure(spanName, {
+          start: startTs,
+          end: performance.now()
+        });
+      }
     }
   };
 };
-var spans = /* @__PURE__ */ new Map();
+var manualSpans = /* @__PURE__ */ new Map();
+var manualSpanTimestamps = /* @__PURE__ */ new Map();
 var spanStart = (params) => {
-  if (spans.has(params.id)) {
-    return;
+  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 = {};
+  if (resourceEntry) {
+    spanAttributes.entryPoint = resourceEntry.sanitizedClassName;
   }
-  const span2 = TRACE_PROCESSOR.traceSpan(params);
-  spans.set(params.id, span2);
+  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 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;
 };
 var spanEnd = (id) => {
-  const span2 = spans.get(id);
-  if (span2) {
-    span2.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);
   }
 };
 var metricsCounter = () => (target, propertyKey, descriptor) => {
@@ -901,8 +858,13 @@ var trace = {
   metrics: TRACE_PROCESSOR.remoteMetrics
 };
 
-// packages/common/tracing/src/metrics/base.ts
+// src/metrics/base.ts
 var BaseCounter = class {
+  /**
+  * @internal
+  */
+  _instance;
+  name;
   /**
   * @internal
   */
@@ -914,11 +876,12 @@ var BaseCounter = class {
   }
 };
 
-// packages/common/tracing/src/metrics/unary-counter.ts
+// 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) {
@@ -935,14 +898,15 @@ var UnaryCounter = class extends BaseCounter {
   }
 };
 
-// packages/common/tracing/src/metrics/time-series-counter.ts
+// 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) {
@@ -975,16 +939,13 @@ var TimeSeriesCounter = class extends BaseCounter {
   }
 };
 
-// packages/common/tracing/src/metrics/time-usage-counter.ts
+// 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;
@@ -1027,11 +988,12 @@ var TimeUsageCounter = class extends BaseCounter {
   }
 };
 
-// packages/common/tracing/src/metrics/map-counter.ts
+// 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) {
@@ -1052,8 +1014,9 @@ var MapCounter = class extends BaseCounter {
   }
 };
 
-// packages/common/tracing/src/metrics/custom-counter.ts
+// src/metrics/custom-counter.ts
 var CustomCounter = class extends BaseCounter {
+  _getData;
   constructor(_getData) {
     super(), this._getData = _getData;
   }
@@ -1067,7 +1030,7 @@ var CustomCounter = class extends BaseCounter {
   }
 };
 
-// packages/common/tracing/src/index.ts
+// src/index.ts
 trace.diagnostic({
   id: "process-info",
   name: "Process Info",
@@ -1088,16 +1051,13 @@ export {
   DiagnosticsManager,
   MapCounter,
   RemoteMetrics,
-  RemoteTracing,
   ResourceEntry,
+  TRACE_ALL_KEY,
   TRACE_PROCESSOR,
-  TRACE_SPAN_ATTRIBUTE,
   TimeSeriesCounter,
   TimeUsageCounter,
   TraceDiagnosticImpl,
   TraceProcessor,
-  TraceSender,
-  TracingSpan,
   UnaryCounter,
   getTracingContext,
   sanitizeClassName,