@dxos/tracing 0.10.0 → 0.11.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dxos/tracing",
-  "version": "0.10.0",
+  "version": "0.11.1",
   "description": "Async utilities.",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
@@ -14,12 +14,9 @@
   "type": "module",
   "exports": {
     ".": {
+      "source": "./src/index.ts",
       "types": "./dist/types/src/index.d.ts",
-      "browser": "./dist/lib/browser/index.mjs",
-      "node": {
-        "require": "./dist/lib/node/index.cjs",
-        "default": "./dist/lib/node-esm/index.mjs"
-      }
+      "import": "./dist/lib/index.mjs"
     }
   },
   "types": "dist/types/src/index.d.ts",
@@ -28,13 +25,13 @@
     "src"
   ],
   "dependencies": {
-    "@dxos/async": "0.10.0",
-    "@dxos/invariant": "0.10.0",
-    "@dxos/log": "0.10.0",
-    "@dxos/context": "0.10.0",
-    "@dxos/node-std": "0.10.0",
-    "@dxos/protocols": "0.10.0",
-    "@dxos/util": "0.10.0"
+    "@dxos/async": "0.11.1",
+    "@dxos/context": "0.11.1",
+    "@dxos/invariant": "0.11.1",
+    "@dxos/log": "0.11.1",
+    "@dxos/node-std": "0.11.1",
+    "@dxos/protocols": "0.11.1",
+    "@dxos/util": "0.11.1"
   },
   "publishConfig": {
     "access": "public"

package/src/api.ts

@@ -2,178 +2,15 @@
 // Copyright 2023 DXOS.org
 //
 
-import { Context, LifecycleState, Resource, TRACE_SPAN_ATTRIBUTE } from '@dxos/context';
+import { Context, TRACE_SPAN_ATTRIBUTE } from '@dxos/context';
 import { type MaybePromise } from '@dxos/util';
 
-import { getTracingContext } from './symbols';
 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?: ResourceOptions) =>
-  <T extends { new (...args: any[]): {} }>(constructor: T) => {
-    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[]) {
-          super(...rest);
-          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;
-  };
-
-export interface TimeAware {
-  tick(timeMs: number): void;
-}
-
-export type InfoOptions = {
-  /**
-   * Value is of enum type and should be converted to string.
-   *
-   * Example:
-   *
-   * ```ts
-   * @trace.info({ enum: SpaceState })
-   * get state(): SpaceState { ... }
-   * ```
-   */
-  enum?: Record<string, any>;
-
-  /**
-   * Max depth of the object to be included in the resource info section.
-   *
-   * null means no limit (a limit of 8 nested objects is still imposed).
-   *
-   * 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;
-};
-
-/**
- * Marks a property or a method to be included in the resource info section.
- */
-const info =
-  (opts: InfoOptions = {}) =>
-  (target: any, propertyKey: string, descriptor?: PropertyDescriptor) => {
-    getTracingContext(target).infoProperties[propertyKey] = { options: opts };
-  };
-
 const mark = (name: string) => {
   performance.mark(name);
 };
@@ -201,15 +38,10 @@ const span =
 
       const parentSpanContext = parentCtx?.getAttribute(TRACE_SPAN_ATTRIBUTE);
 
-      const resourceEntry = TRACE_PROCESSOR.resourceInstanceIndex.get(this);
-      const className = resourceEntry?.sanitizedClassName ?? sanitizeClassName(target.constructor?.name ?? 'unknown');
+      const className = 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;
@@ -278,8 +110,7 @@ const spanStart = (params: ManualSpanParams): Context | null => {
     return params.parentCtx;
   }
 
-  const resourceEntry = TRACE_PROCESSOR.resourceInstanceIndex.get(params.instance);
-  const className = resourceEntry?.sanitizedClassName ?? 'unknown';
+  const className = sanitizeClassName(params.instance?.constructor?.name ?? 'unknown');
   const spanName = `${className}.${params.methodName}`;
 
   if (params.showInBrowserTimeline) {
@@ -293,10 +124,6 @@ const spanStart = (params: ManualSpanParams): Context | null => {
   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;
@@ -334,13 +161,6 @@ const spanEnd = (id: string) => {
   }
 };
 
-/**
- * Attaches metrics counter to the resource.
- */
-const metricsCounter = () => (target: any, propertyKey: string, descriptor?: PropertyDescriptor) => {
-  getTracingContext(target).metricsProperties[propertyKey] = {};
-};
-
 export type AddLinkOptions = {};
 
 const addLink = (parent: any, child: any, opts: AddLinkOptions = {}) => {
@@ -376,10 +196,7 @@ const diagnostic = <T>(params: TraceDiagnosticProps<T>): TraceDiagnostic => {
 export const trace = {
   addLink,
   diagnostic,
-  info,
   mark,
-  metricsCounter,
-  resource,
   span,
   spanStart,
   spanEnd,

package/src/index.ts

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

package/src/trace-processor.ts

@@ -2,57 +2,12 @@
 // Copyright 2023 DXOS.org
 //
 
-import { LogLevel, type LogProcessor, log } from '@dxos/log';
-import { type LogEntry } from '@dxos/protocols/proto/dxos/client/services';
-import { type Metric, type Resource } from '@dxos/protocols/proto/dxos/tracing';
-import { getPrototypeSpecificInstanceId } from '@dxos/util';
-
-import type { AddLinkOptions, TimeAware } from './api';
+import type { AddLinkOptions } from './api';
 import { BUFFERED_PREFIX, BufferingTracingBackend } from './buffering-backend';
 import { DiagnosticsManager } from './diagnostic';
 import { DiagnosticsChannel } from './diagnostics-channel';
-import { type BaseCounter } from './metrics';
 import { RemoteMetrics } from './remote/metrics';
-import { getTracingContext } from './symbols';
 import type { RemoteSpan, StartSpanOptions, TracingBackend } from './tracing-types';
-import { WeakRef } from './weak-ref';
-
-export type Diagnostics = {
-  resources: Record<string, Resource>;
-  logs: LogEntry[];
-};
-
-export type TraceResourceConstructorProps = {
-  constructor: { new (...args: any[]): {} };
-  instance: any;
-  annotation?: symbol;
-};
-
-export class ResourceEntry {
-  /**
-   * Sometimes bundlers mangle class names: WebFile -> WebFile2.
-   *
-   * We use a heuristic to remove the suffix.
-   */
-  public readonly sanitizedClassName: string;
-
-  constructor(
-    public readonly data: Resource,
-    public readonly instance: WeakRef<any>,
-    public readonly annotation?: symbol,
-  ) {
-    this.sanitizedClassName = sanitizeClassName(data.className);
-  }
-
-  getMetric(name: string): Metric | undefined {
-    return this.data.metrics?.find((metric) => metric.name === name);
-  }
-}
-
-const MAX_RESOURCE_RECORDS = 2_000;
-const MAX_LOG_RECORDS = 1_000;
-
-const MAX_INFO_OBJECT_DEPTH = 8;
 
 export class TraceProcessor {
   public readonly diagnostics = new DiagnosticsManager();
@@ -96,17 +51,9 @@ export class TraceProcessor {
     };
   }
 
-  readonly resources = new Map<number, ResourceEntry>();
-  readonly resourceInstanceIndex = new WeakMap<any, ResourceEntry>();
-  readonly resourceIdList: number[] = [];
-
-  readonly logs: LogEntry[] = [];
-
   private _instanceTag: string | null = null;
 
   constructor() {
-    log.addProcessor(this._logProcessor.bind(this));
-
     if (DiagnosticsChannel.supported) {
       this.diagnosticsChannel.serve(this.diagnostics);
     }
@@ -118,224 +65,12 @@ export class TraceProcessor {
     this.diagnostics.setInstanceTag(tag);
   }
 
-  /** @internal */
-  createTraceResource(params: TraceResourceConstructorProps): void {
-    const id = this.resources.size;
-
-    const tracingContext = getTracingContext(Object.getPrototypeOf(params.instance));
-    for (const key of Object.keys(tracingContext.metricsProperties)) {
-      (params.instance[key] as BaseCounter)._assign(params.instance, key);
-    }
-
-    const entry = new ResourceEntry(
-      {
-        id,
-        className: params.constructor.name,
-        instanceId: getPrototypeSpecificInstanceId(params.instance),
-        info: this.getResourceInfo(params.instance),
-        links: [],
-        metrics: this.getResourceMetrics(params.instance),
-      },
-      new WeakRef(params.instance),
-      params.annotation,
-    );
-
-    this.resources.set(id, entry);
-    this.resourceInstanceIndex.set(params.instance, entry);
-    this.resourceIdList.push(id);
-    if (this.resourceIdList.length > MAX_RESOURCE_RECORDS) {
-      this._clearResources();
-    }
-  }
-
   // TODO(burdon): Not implemented.
   addLink(parent: any, child: any, opts: AddLinkOptions): void {}
-
-  getDiagnostics(): Diagnostics {
-    this.refresh();
-
-    return {
-      resources: Object.fromEntries(
-        Array.from(this.resources.entries()).map(([id, entry]) => [
-          `${entry.sanitizedClassName}#${entry.data.instanceId}`,
-          entry.data,
-        ]),
-      ),
-      logs: this.logs.filter((log) => log.level >= LogLevel.INFO),
-    };
-  }
-
-  getResourceInfo(instance: any): Record<string, any> {
-    const res: Record<string, any> = {};
-    const tracingContext = getTracingContext(Object.getPrototypeOf(instance));
-    for (const [key, { options }] of Object.entries(tracingContext.infoProperties)) {
-      try {
-        const value = typeof instance[key] === 'function' ? instance[key]() : instance[key];
-        if (options.enum) {
-          res[key] = options.enum[value];
-        } else {
-          res[key] = sanitizeValue(
-            value,
-            options.depth === undefined ? 1 : (options.depth ?? MAX_INFO_OBJECT_DEPTH),
-            this,
-          );
-        }
-      } catch (err: any) {
-        res[key] = err.message;
-      }
-    }
-
-    return res;
-  }
-
-  getResourceMetrics(instance: any): Metric[] {
-    const res: Metric[] = [];
-    const tracingContext = getTracingContext(Object.getPrototypeOf(instance));
-    for (const [key, _opts] of Object.entries(tracingContext.metricsProperties)) {
-      res.push(instance[key].getData());
-    }
-
-    return res;
-  }
-
-  getResourceId(instance: any): number | null {
-    const entry = this.resourceInstanceIndex.get(instance);
-    return entry ? entry.data.id : null;
-  }
-
-  findResourcesByClassName(className: string): ResourceEntry[] {
-    return [...this.resources.values()].filter(
-      (res) => res.data.className === className || res.sanitizedClassName === className,
-    );
-  }
-
-  findResourcesByAnnotation(annotation: symbol): ResourceEntry[] {
-    return [...this.resources.values()].filter((res) => res.annotation === annotation);
-  }
-
-  refresh(): void {
-    for (const resource of this.resources.values()) {
-      const instance = resource.instance.deref();
-      if (!instance) {
-        continue;
-      }
-
-      const tracingContext = getTracingContext(Object.getPrototypeOf(instance));
-      const time = performance.now();
-      (instance as TimeAware).tick?.(time);
-      for (const key of Object.keys(tracingContext.metricsProperties)) {
-        (instance[key] as BaseCounter)._tick?.(time);
-      }
-
-      resource.data.info = this.getResourceInfo(instance);
-      resource.data.metrics = this.getResourceMetrics(instance);
-    }
-  }
-
-  private _clearResources(): void {
-    while (this.resourceIdList.length > MAX_RESOURCE_RECORDS) {
-      const id = this.resourceIdList.shift()!;
-      this.resources.delete(id);
-    }
-  }
-
-  private _pushLog(log: LogEntry): void {
-    this.logs.push(log);
-    if (this.logs.length > MAX_LOG_RECORDS) {
-      this.logs.shift();
-    }
-  }
-
-  private _logProcessor: LogProcessor = (config, entry) => {
-    switch (entry.level) {
-      case LogLevel.ERROR:
-      case LogLevel.WARN:
-      case LogLevel.TRACE: {
-        const scope = entry.meta?.S;
-        const resource = this.resourceInstanceIndex.get(scope);
-        if (!resource) {
-          return;
-        }
-
-        const context: Record<string, any> = { ...entry.computedContext };
-        if (entry.computedError !== undefined) {
-          context.error = entry.computedError;
-        }
-
-        const { filename, line } = entry.computedMeta;
-        const entryToPush: LogEntry = {
-          level: entry.level,
-          message: entry.message ?? entry.computedError ?? '',
-          context,
-          timestamp: new Date(entry.timestamp),
-          meta: {
-            file: filename ?? '',
-            line: line ?? 0,
-            resourceId: resource.data.id,
-          },
-        };
-        this._pushLog(entryToPush);
-        break;
-      }
-      default:
-    }
-  };
 }
 
 export const TRACE_PROCESSOR: TraceProcessor = ((globalThis as any).TRACE_PROCESSOR ??= new TraceProcessor());
 
-const sanitizeValue = (value: any, depth: number, traceProcessor: TraceProcessor): any => {
-  switch (typeof value) {
-    case 'string':
-    case 'number':
-    case 'boolean':
-    case 'undefined':
-      return value;
-    case 'object':
-    case 'function':
-      if (value === null) {
-        return value;
-      }
-
-      {
-        const resourceEntry = traceProcessor.resourceInstanceIndex.get(value);
-        if (resourceEntry) {
-          return `${resourceEntry.sanitizedClassName}#${resourceEntry.data.instanceId}`;
-        }
-      }
-
-      if (typeof value.toJSON === 'function') {
-        return sanitizeValue(value.toJSON(), depth, traceProcessor);
-      }
-
-      if (depth > 0) {
-        if (isSetLike(value)) {
-          return Object.fromEntries(
-            Array.from(value.entries()).map((value) => sanitizeValue(value, depth - 1, traceProcessor)),
-          );
-        } else if (isMapLike(value)) {
-          return Object.fromEntries(
-            Array.from(value.entries()).map(([key, value]) => [key, sanitizeValue(value, depth - 1, traceProcessor)]),
-          );
-        } else if (Array.isArray(value)) {
-          return value.map((item: any) => sanitizeValue(item, depth - 1, traceProcessor));
-        } else if (typeof value === 'object') {
-          const res: any = {};
-          for (const key of Object.keys(value)) {
-            res[key] = sanitizeValue(value[key], depth - 1, traceProcessor);
-          }
-          return res;
-        }
-      }
-
-      if (typeof value.truncate === 'function') {
-        return value.truncate();
-      }
-
-      return value.toString();
-  }
-};
-
 export const sanitizeClassName = (className: string) => {
   let name = className.replace(/^_+/, '');
   const SANITIZE_REGEX = /[^_](\d+)$/;
@@ -345,11 +80,3 @@ export const sanitizeClassName = (className: string) => {
   }
   return name;
 };
-
-const isSetLike = (value: any): value is Set<any> =>
-  value instanceof Set ||
-  (typeof value === 'object' && value !== null && Object.getPrototypeOf(value).constructor.name === 'ComplexSet');
-
-const isMapLike = (value: any): value is Map<any, any> =>
-  value instanceof Map ||
-  (typeof value === 'object' && value !== null && Object.getPrototypeOf(value).constructor.name === 'ComplexMap');