@ohos-ports/dxos-tracing 0.11.1-beta.0

package/dist/types/src/api.d.ts

@@ -0,0 +1,47 @@
+import { Context } from '@dxos/context';
+import { type MaybePromise } from '@dxos/util';
+/** localStorage key that switches the browser OTEL sampler from 30% to 100%. */
+export declare const TRACE_ALL_KEY = "dxos.debug.traceAll";
+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>;
+};
+export type ManualSpanParams = {
+    id: string;
+    instance: any;
+    methodName: string;
+    parentCtx: Context | null;
+    showInBrowserTimeline?: boolean;
+    showInRemoteTracing?: boolean;
+    op?: string;
+    attributes?: Record<string, any>;
+};
+export type AddLinkOptions = {};
+export type TraceDiagnosticProps<T> = {
+    /** Unique ID. */
+    id: string;
+    /**
+     * Human-readable name.
+     * @defaults Defaults to `id`
+     */
+    name?: string;
+    /** Function that will be called to fetch the diagnostic data. */
+    fetch: () => MaybePromise<T>;
+};
+export interface TraceDiagnostic {
+    id: string;
+    unregister(): void;
+}
+export declare const trace: {
+    addLink: (parent: any, child: any, opts?: AddLinkOptions) => void;
+    diagnostic: <T>(params: TraceDiagnosticProps<T>) => TraceDiagnostic;
+    mark: (name: string) => void;
+    span: ({ showInBrowserTimeline, showInRemoteTracing, op, attributes }?: SpanOptions) => (target: any, propertyKey: string, descriptor: TypedPropertyDescriptor<(...args: any) => any>) => void;
+    spanStart: (params: ManualSpanParams) => Context | null;
+    spanEnd: (id: string) => void;
+    metrics: import(".").RemoteMetrics;
+};
+//# sourceMappingURL=api.d.ts.map

package/dist/types/src/api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../../../src/api.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,OAAO,EAAwB,MAAM,eAAe,CAAC;AAC9D,OAAO,EAAE,KAAK,YAAY,EAAE,MAAM,YAAY,CAAC;AAK/C,gFAAgF;AAChF,eAAO,MAAM,aAAa,wBAAwB,CAAC;AAMnD,MAAM,MAAM,WAAW,GAAG;IACxB,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC,uFAAuF;IACvF,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CAClC,CAAC;AA8DF,MAAM,MAAM,gBAAgB,GAAG;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,GAAG,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,OAAO,GAAG,IAAI,CAAC;IAC1B,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CAClC,CAAC;AAqEF,MAAM,MAAM,cAAc,GAAG,EAAE,CAAC;AAMhC,MAAM,MAAM,oBAAoB,CAAC,CAAC,IAAI;IACpC,iBAAiB;IACjB,EAAE,EAAE,MAAM,CAAC;IAEX;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd,iEAAiE;IACjE,KAAK,EAAE,MAAM,YAAY,CAAC,CAAC,CAAC,CAAC;CAC9B,CAAC;AAEF,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,UAAU,IAAI,IAAI,CAAC;CACpB;AASD,eAAO,MAAM,KAAK;sBA9BO,GAAG,SAAS,GAAG,SAAQ,cAAc;iBA0B1C,CAAC,UAAU,oBAAoB,CAAC,CAAC,CAAC,KAAG,eAAe;iBAlLpD,MAAM;4EAiBwD,WAAW,cAClF,GAAG,eAAe,MAAM,cAAc,uBAAuB,CAAC,CAAC,GAAG,IAAI,EAAE,GAAG,KAAK,GAAG,CAAC;wBA4EpE,gBAAgB,KAAG,OAAO,GAAG,IAAI;kBA0CvC,MAAM;;CAsD1B,CAAC"}

package/dist/types/src/buffering-backend.d.ts

@@ -0,0 +1,24 @@
+import { type TraceContextData } from '@dxos/context';
+import type { RemoteSpan, StartSpanOptions, TracingBackend } from './tracing-types';
+export declare const BUFFERED_PREFIX = "buffered-";
+/**
+ * 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 declare class BufferingTracingBackend implements TracingBackend {
+    #private;
+    startSpan(options: StartSpanOptions): RemoteSpan;
+    /** Discard all buffered spans without replaying them. */
+    clear(): void;
+    /**
+     * 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>;
+}
+//# sourceMappingURL=buffering-backend.d.ts.map

package/dist/types/src/buffering-backend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"buffering-backend.d.ts","sourceRoot":"","sources":["../../../src/buffering-backend.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,KAAK,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAEtD,OAAO,KAAK,EAAE,UAAU,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAEpF,eAAO,MAAM,eAAe,cAAc,CAAC;AAuD3C;;;;;GAKG;AACH,qBAAa,uBAAwB,YAAW,cAAc;;IAI5D,SAAS,CAAC,OAAO,EAAE,gBAAgB,GAAG,UAAU,CAI/C;IAED,yDAAyD;IACzD,KAAK,IAAI,IAAI,CAEZ;IAED;;;;;;OAMG;IACH,KAAK,CAAC,OAAO,EAAE,cAAc,GAAG,GAAG,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAmB5D;CACF"}

package/dist/types/src/diagnostic.d.ts

@@ -0,0 +1,38 @@
+import { type TraceDiagnostic, type TraceDiagnosticProps } from './api';
+export declare const DIAGNOSTICS_TIMEOUT = 10000;
+export type DiagnosticMetadata = {
+    id: string;
+    instanceId: string;
+    instanceTag: string | null;
+    name: string;
+};
+export type DiagnosticsRequest = {
+    id: string;
+    instanceId?: string;
+    instanceTag?: string | null;
+};
+export type DiagnosticsData = {
+    id: string;
+    instanceId: string;
+    data: any;
+    error?: string;
+};
+export declare class TraceDiagnosticImpl implements TraceDiagnostic {
+    id: string;
+    fetch: () => any;
+    name: string;
+    private readonly _onUnregister;
+    constructor(id: string, fetch: () => any, name: string, _onUnregister: () => void);
+    unregister(): void;
+}
+export declare class DiagnosticsManager {
+    readonly instanceId: string;
+    readonly registry: Map<string, TraceDiagnosticImpl>;
+    private _instanceTag;
+    get instanceTag(): string | null;
+    setInstanceTag(tag: string): void;
+    registerDiagnostic(params: TraceDiagnosticProps<any>): TraceDiagnostic;
+    list(): DiagnosticMetadata[];
+    fetch(request: DiagnosticsRequest): Promise<DiagnosticsData>;
+}
+//# sourceMappingURL=diagnostic.d.ts.map

package/dist/types/src/diagnostic.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnostic.d.ts","sourceRoot":"","sources":["../../../src/diagnostic.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,KAAK,eAAe,EAAE,KAAK,oBAAoB,EAAE,MAAM,OAAO,CAAC;AAGxE,eAAO,MAAM,mBAAmB,QAAS,CAAC;AAE1C,MAAM,MAAM,kBAAkB,GAAG;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,GAAG,CAAC;IACV,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,qBAAa,mBAAoB,YAAW,eAAe;IAEhD,EAAE,EAAE,MAAM;IACV,KAAK,EAAE,MAAM,GAAG;IAChB,IAAI,EAAE,MAAM;IACnB,OAAO,CAAC,QAAQ,CAAC,aAAa;IAJhC,YACS,EAAE,EAAE,MAAM,EACV,KAAK,EAAE,MAAM,GAAG,EAChB,IAAI,EAAE,MAAM,EACF,aAAa,EAAE,MAAM,IAAI,EACxC;IAEJ,UAAU,IAAI,IAAI,CAEjB;CACF;AAED,qBAAa,kBAAkB;IAC7B,QAAQ,CAAC,UAAU,SAAc;IAEjC,QAAQ,CAAC,QAAQ,mCAA0C;IAE3D,OAAO,CAAC,YAAY,CAAuB;IAE3C,IAAI,WAAW,IAAI,MAAM,GAAG,IAAI,CAE/B;IAED,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAEhC;IAED,kBAAkB,CAAC,MAAM,EAAE,oBAAoB,CAAC,GAAG,CAAC,GAAG,eAAe,CAQrE;IAED,IAAI,IAAI,kBAAkB,EAAE,CAO3B;IAEK,KAAK,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,eAAe,CAAC,CAsBjE;CACF"}

package/dist/types/src/diagnostics-channel.d.ts

@@ -0,0 +1,34 @@
+import { type DiagnosticMetadata, type DiagnosticsData, type DiagnosticsManager, type DiagnosticsRequest } from './diagnostic';
+export type DiagnosticChannelMessage = {
+    type: 'DIAGNOSTICS_DISCOVER';
+} | {
+    type: 'DIAGNOSTICS_ANNOUNCE';
+    diagnostics: DiagnosticMetadata[];
+} | {
+    type: 'DIAGNOSTICS_FETCH';
+    requestId: string;
+    request: DiagnosticsRequest;
+} | {
+    type: 'DIAGNOSTICS_RESPONSE';
+    requestId: string;
+    data: DiagnosticsData;
+};
+export declare class DiagnosticsChannel {
+    private readonly _channelName;
+    static get supported(): boolean;
+    private _ctx;
+    private readonly _serveChannel?;
+    private readonly _clientChannel?;
+    constructor(_channelName?: string);
+    destroy(): void;
+    /**
+     * In node.js, the channel will keep the process alive.
+     * This method allows the process to exit.
+     * Noop in the browser.
+     */
+    unref(): void;
+    serve(manager: DiagnosticsManager): void;
+    discover(): Promise<DiagnosticMetadata[]>;
+    fetch(request: DiagnosticsRequest): Promise<DiagnosticsData>;
+}
+//# sourceMappingURL=diagnostics-channel.d.ts.map

package/dist/types/src/diagnostics-channel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnostics-channel.d.ts","sourceRoot":"","sources":["../../../src/diagnostics-channel.ts"],"names":[],"mappings":"AAQA,OAAO,EACL,KAAK,kBAAkB,EAEvB,KAAK,eAAe,EACpB,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,EACxB,MAAM,cAAc,CAAC;AAOtB,MAAM,MAAM,wBAAwB,GAChC;IACE,IAAI,EAAE,sBAAsB,CAAC;CAC9B,GACD;IACE,IAAI,EAAE,sBAAsB,CAAC;IAC7B,WAAW,EAAE,kBAAkB,EAAE,CAAC;CACnC,GACD;IACE,IAAI,EAAE,mBAAmB,CAAC;IAC1B,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,kBAAkB,CAAC;CAC7B,GACD;IACE,IAAI,EAAE,sBAAsB,CAAC;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,eAAe,CAAC;CACvB,CAAC;AAEN,qBAAa,kBAAkB;IAWjB,OAAO,CAAC,QAAQ,CAAC,YAAY;IAVzC,MAAM,KAAK,SAAS,YAEnB;IAED,OAAO,CAAC,IAAI,CAAiB;IAG7B,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAC,CAA+B;IAC9D,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAC,CAA+B;IAE/D,YAA6B,YAAY,GAAE,MAA6B,EAKvE;IAED,OAAO,IAAI,IAAI,CAId;IAED;;;;OAIG;IACH,KAAK,IAAI,IAAI,CAKZ;IAED,KAAK,CAAC,OAAO,EAAE,kBAAkB,GAAG,IAAI,CAkCvC;IAEK,QAAQ,IAAI,OAAO,CAAC,kBAAkB,EAAE,CAAC,CA+B9C;IAEK,KAAK,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,eAAe,CAAC,CA2BjE;CACF"}

package/dist/types/src/index.d.ts

@@ -0,0 +1,7 @@
+export * from './api';
+export * from './trace-processor';
+export * from './tracing-types';
+export * from './diagnostic';
+export * from './diagnostics-channel';
+export * from './remote/metrics';
+//# sourceMappingURL=index.d.ts.map

package/dist/types/src/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/index.ts"],"names":[],"mappings":"AAMA,cAAc,OAAO,CAAC;AACtB,cAAc,mBAAmB,CAAC;AAClC,cAAc,iBAAiB,CAAC;AAChC,cAAc,cAAc,CAAC;AAC7B,cAAc,uBAAuB,CAAC;AACtC,cAAc,kBAAkB,CAAC"}

package/dist/types/src/remote/index.d.ts

@@ -0,0 +1,2 @@
+export * from './metrics';
+//# sourceMappingURL=index.d.ts.map

package/dist/types/src/remote/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/remote/index.ts"],"names":[],"mappings":"AAIA,cAAc,WAAW,CAAC"}

package/dist/types/src/remote/metrics.d.ts

@@ -0,0 +1,37 @@
+type TagType = number | string | boolean | null | undefined;
+export interface MetricData {
+    unit?: string;
+    tags?: Record<string, TagType>;
+    timestamp?: number;
+}
+interface MetricsMethods {
+    /**
+     * Adds a value to a counter metric
+     */
+    increment(name: string, value?: number, data?: MetricData): void;
+    /**
+     * Adds a value to a distribution metric
+     */
+    distribution(name: string, value: number, data?: MetricData): void;
+    /**
+     * Adds a value to a set metric. Value must be a string or integer.
+     */
+    set(name: string, value: number | string, data?: MetricData): void;
+    /**
+     * Adds a value to a gauge metric
+     */
+    gauge(name: string, value: number, data?: MetricData): void;
+}
+/**
+ * Allows metrics to be recorded within SDK code without requiring specific consumers.
+ */
+export declare class RemoteMetrics implements MetricsMethods {
+    private _metrics;
+    registerProcessor(processor: MetricsMethods): void;
+    increment(name: string, value?: number, data?: MetricData): void[];
+    distribution(name: string, value: number, data?: MetricData): void[];
+    set(name: string, value: number | string, data?: MetricData): void[];
+    gauge(name: string, value: number, data?: MetricData): void[];
+}
+export {};
+//# sourceMappingURL=metrics.d.ts.map

package/dist/types/src/remote/metrics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.d.ts","sourceRoot":"","sources":["../../../../src/remote/metrics.ts"],"names":[],"mappings":"AAIA,KAAK,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,GAAG,SAAS,CAAC;AAE5D,MAAM,WAAW,UAAU;IACzB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,UAAU,cAAc;IACtB;;OAEG;IACH,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,UAAU,GAAG,IAAI,CAAC;IACjE;;OAEG;IACH,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,UAAU,GAAG,IAAI,CAAC;IACnE;;OAEG;IACH,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,IAAI,CAAC,EAAE,UAAU,GAAG,IAAI,CAAC;IACnE;;OAEG;IACH,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,UAAU,GAAG,IAAI,CAAC;CAC7D;AAED;;GAEG;AACH,qBAAa,aAAc,YAAW,cAAc;IAClD,OAAO,CAAC,QAAQ,CAA6B;IAE7C,iBAAiB,CAAC,SAAS,EAAE,cAAc,GAAG,IAAI,CAEjD;IAED,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,UAAU,GAAG,IAAI,EAAE,CAEjE;IAED,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,UAAU,GAAG,IAAI,EAAE,CAEnE;IAED,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,IAAI,CAAC,EAAE,UAAU,GAAG,IAAI,EAAE,CAEnE;IAED,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,UAAU,GAAG,IAAI,EAAE,CAE5D;CACF"}

package/dist/types/src/trace-processor.d.ts

@@ -0,0 +1,29 @@
+import type { AddLinkOptions } from './api';
+import { DiagnosticsManager } from './diagnostic';
+import { DiagnosticsChannel } from './diagnostics-channel';
+import { RemoteMetrics } from './remote/metrics';
+import type { TracingBackend } from './tracing-types';
+export declare class TraceProcessor {
+    #private;
+    readonly diagnostics: DiagnosticsManager;
+    readonly diagnosticsChannel: DiagnosticsChannel;
+    readonly remoteMetrics: RemoteMetrics;
+    /**
+     * 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(): TracingBackend;
+    set tracingBackend(backend: TracingBackend | undefined);
+    private _instanceTag;
+    constructor();
+    setInstanceTag(tag: string): void;
+    addLink(parent: any, child: any, opts: AddLinkOptions): void;
+}
+export declare const TRACE_PROCESSOR: TraceProcessor;
+export declare const sanitizeClassName: (className: string) => string;
+//# sourceMappingURL=trace-processor.d.ts.map

package/dist/types/src/trace-processor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace-processor.d.ts","sourceRoot":"","sources":["../../../src/trace-processor.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,OAAO,CAAC;AAE5C,OAAO,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAC3D,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACjD,OAAO,KAAK,EAAgC,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAEpF,qBAAa,cAAc;;IACzB,SAAgB,WAAW,qBAA4B;IACvD,SAAgB,kBAAkB,qBAA4B;IAC9D,SAAgB,aAAa,gBAAuB;IAKpD;;;;;;;;OAQG;IACH,IAAI,cAAc,IAAI,cAAc,CAEnC;IAED,IAAI,cAAc,CAAC,OAAO,EAAE,cAAc,GAAG,SAAS,EAmBrD;IAED,OAAO,CAAC,YAAY,CAAuB;IAE3C,cAKC;IAED,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAGhC;IAGD,OAAO,CAAC,MAAM,EAAE,GAAG,EAAE,KAAK,EAAE,GAAG,EAAE,IAAI,EAAE,cAAc,GAAG,IAAI,CAAG;CAChE;AAED,eAAO,MAAM,eAAe,EAAE,cAA+E,CAAC;AAE9G,eAAO,MAAM,iBAAiB,cAAe,MAAM,WAQlD,CAAC"}

package/dist/types/src/tracing-types.d.ts

@@ -0,0 +1,67 @@
+import { type TraceContextData } from '@dxos/context';
+/**
+ * Opaque span handle returned by {@link TracingBackend.startSpan}.
+ *
+ * The `spanContext` field carries W3C trace context strings that are stored
+ * on the DXOS {@link Context} via `TRACE_SPAN_ATTRIBUTE`. Because these are
+ * plain strings (not live runtime objects), they survive after the span ends
+ * and across serialization boundaries.
+ */
+export type RemoteSpan = {
+    /** Signal that the span has ended. Must be called exactly once. */
+    end: (endTime?: number) => void;
+    /** Record an error on the span (e.g., OTEL `span.recordException` + `setStatus`). */
+    setError?: (err: unknown) => void;
+    /**
+     * W3C trace context identifying this span.
+     *
+     * Stored on the DXOS `Context` attribute (`TRACE_SPAN_ATTRIBUTE`) so that
+     * child `@trace.span()` methods can read it and pass it as
+     * {@link StartSpanOptions.parentContext} to create properly-parented spans.
+     */
+    spanContext?: TraceContextData;
+};
+/**
+ * Options passed to {@link TracingBackend.startSpan}.
+ */
+export type StartSpanOptions = {
+    /** Human-readable span name, typically `ClassName.methodName`. */
+    name: string;
+    /** Span category (e.g., `'function'`, `'rpc'`). */
+    op?: string;
+    /** Key-value attributes attached to the span. */
+    attributes?: Record<string, any>;
+    /**
+     * W3C trace context of the parent span.
+     *
+     * The backend extracts the trace/span IDs from these strings to establish
+     * parent-child relationships. When `undefined`, the backend creates a root span.
+     */
+    parentContext?: TraceContextData;
+    /**
+     * Epoch-millisecond timestamp for the span start.
+     * Used by the buffering backend to preserve original timing when replaying spans.
+     * When `undefined`, the backend uses the current time.
+     */
+    startTime?: number;
+};
+/**
+ * Backend-agnostic tracing interface implemented by the observability package
+ * and registered on `TRACE_PROCESSOR.tracingBackend`.
+ *
+ * The backend receives and returns {@link TraceContextData} (W3C strings) —
+ * no opaque runtime objects cross the interface boundary. The OTEL backend
+ * performs `propagation.extract/inject` internally in {@link startSpan}.
+ */
+export interface TracingBackend {
+    /**
+     * Create a new span.
+     *
+     * The backend should:
+     * 1. Extract the parent from `options.parentContext` (if present).
+     * 2. Create a span as a child of that parent.
+     * 3. Inject the new span's identity into the returned `spanContext`.
+     */
+    startSpan: (options: StartSpanOptions) => RemoteSpan;
+}
+//# sourceMappingURL=tracing-types.d.ts.map

package/dist/types/src/tracing-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracing-types.d.ts","sourceRoot":"","sources":["../../../src/tracing-types.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,KAAK,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAEtD;;;;;;;GAOG;AACH,MAAM,MAAM,UAAU,GAAG;IACvB,mEAAmE;IACnE,GAAG,EAAE,CAAC,OAAO,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;IAEhC,qFAAqF;IACrF,QAAQ,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,IAAI,CAAC;IAElC;;;;;;OAMG;IACH,WAAW,CAAC,EAAE,gBAAgB,CAAC;CAChC,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,kEAAkE;IAClE,IAAI,EAAE,MAAM,CAAC;IACb,mDAAmD;IACnD,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,iDAAiD;IACjD,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAEjC;;;;;OAKG;IACH,aAAa,CAAC,EAAE,gBAAgB,CAAC;IAEjC;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,WAAW,cAAc;IAC7B;;;;;;;OAOG;IACH,SAAS,EAAE,CAAC,OAAO,EAAE,gBAAgB,KAAK,UAAU,CAAC;CACtD"}

package/dist/types/src/tracing.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=tracing.test.d.ts.map

package/dist/types/src/tracing.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracing.test.d.ts","sourceRoot":"","sources":["../../../src/tracing.test.ts"],"names":[],"mappings":""}

package/dist/types/src/util.d.ts

@@ -0,0 +1,2 @@
+export declare const createId: () => string;
+//# sourceMappingURL=util.d.ts.map

package/dist/types/src/util.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"util.d.ts","sourceRoot":"","sources":["../../../src/util.ts"],"names":[],"mappings":"AAKA,eAAO,MAAM,QAAQ,cAA4C,CAAC"}