@dxos/observability 0.8.4-main.72ec0f3 → 0.8.4-main.74a063c4e0

package/package.json

@@ -1,50 +1,29 @@
 {
   "name": "@dxos/observability",
-  "version": "0.8.4-main.72ec0f3",
+  "version": "0.8.4-main.74a063c4e0",
   "description": "Provides a common interface for app and platform observability",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dxos/dxos"
+  },
   "license": "MIT",
   "author": "DXOS.org",
-  "sideEffects": true,
+  "sideEffects": false,
   "type": "module",
   "exports": {
     ".": {
-      "source": "./src/index.ts",
       "types": "./dist/types/src/index.d.ts",
       "browser": "./dist/lib/browser/index.mjs",
       "node": "./dist/lib/node-esm/index.mjs"
-    },
-    "./segment": {
-      "source": "./src/segment/index.ts",
-      "types": "./dist/types/src/segment/index.d.ts",
-      "browser": "./dist/lib/browser/segment/index.mjs",
-      "node": "./dist/lib/node-esm/segment/index.mjs"
-    },
-    "./sentry": {
-      "source": "./src/sentry/index.ts",
-      "types": "./dist/types/src/sentry/index.d.ts",
-      "browser": "./dist/lib/browser/sentry/index.mjs",
-      "node": "./dist/lib/node-esm/sentry/index.mjs"
     }
   },
   "browser": {
-    "./src/segment/node.ts": "./src/segment/browser.ts",
-    "./src/sentry/node.ts": "./src/sentry/browser.ts",
-    "./testing/testkit/index.ts": "./testing/testkit/browser.ts",
-    "./src/otel/traces.ts": "./src/otel/traces-browser.ts"
+    "./src/storage/node.ts": "./src/storage/browser.ts",
+    "./src/extensions/otel/traces.ts": "./src/extensions/otel/traces-browser.ts"
   },
   "types": "dist/types/src/index.d.ts",
-  "typesVersions": {
-    "*": {
-      "segment": [
-        "dist/types/src/segment/index.d.ts"
-      ],
-      "sentry": [
-        "dist/types/src/sentry/index.d.ts"
-      ]
-    }
-  },
   "files": [
     "dist",
     "src"
@@ -53,6 +32,7 @@
     "@opentelemetry/api": "^1.9.0",
     "@opentelemetry/api-logs": "^0.203.0",
     "@opentelemetry/auto-instrumentations-web": "^0.51.0",
+    "@opentelemetry/core": "^2.1.0",
     "@opentelemetry/exporter-logs-otlp-http": "^0.203.0",
     "@opentelemetry/exporter-metrics-otlp-http": "^0.203.0",
     "@opentelemetry/exporter-trace-otlp-http": "^0.203.0",
@@ -63,35 +43,35 @@
     "@opentelemetry/sdk-trace-base": "^2.1.0",
     "@opentelemetry/sdk-trace-web": "^2.1.0",
     "@opentelemetry/semantic-conventions": "^1.37.0",
-    "@segment/analytics-node": "^2.1.0",
-    "@segment/snippet": "^4.15.3",
-    "@sentry/browser": "^8.8.0",
-    "@sentry/node": "^8.8.0",
     "debug": "^4.3.4",
-    "js-yaml": "^4.1.0",
+    "js-yaml": "4.1.1",
     "localforage": "^1.10.0",
+    "posthog-js": "^1.353.0",
     "uuid": "^9.0.0",
-    "@dxos/async": "0.8.4-main.72ec0f3",
-    "@dxos/client-protocol": "0.8.4-main.72ec0f3",
-    "@dxos/context": "0.8.4-main.72ec0f3",
-    "@dxos/client": "0.8.4-main.72ec0f3",
-    "@dxos/client-services": "0.8.4-main.72ec0f3",
-    "@dxos/debug": "0.8.4-main.72ec0f3",
-    "@dxos/invariant": "0.8.4-main.72ec0f3",
-    "@dxos/config": "0.8.4-main.72ec0f3",
-    "@dxos/log": "0.8.4-main.72ec0f3",
-    "@dxos/protocols": "0.8.4-main.72ec0f3",
-    "@dxos/node-std": "0.8.4-main.72ec0f3",
-    "@dxos/tracing": "0.8.4-main.72ec0f3",
-    "@dxos/util": "0.8.4-main.72ec0f3",
-    "@dxos/network-manager": "0.8.4-main.72ec0f3"
+    "zone.js": "^0.15.0",
+    "@dxos/async": "0.8.4-main.74a063c4e0",
+    "@dxos/client": "0.8.4-main.74a063c4e0",
+    "@dxos/client-protocol": "0.8.4-main.74a063c4e0",
+    "@dxos/client-services": "0.8.4-main.74a063c4e0",
+    "@dxos/context": "0.8.4-main.74a063c4e0",
+    "@dxos/debug": "0.8.4-main.74a063c4e0",
+    "@dxos/invariant": "0.8.4-main.74a063c4e0",
+    "@dxos/config": "0.8.4-main.74a063c4e0",
+    "@dxos/log": "0.8.4-main.74a063c4e0",
+    "@dxos/node-std": "0.8.4-main.74a063c4e0",
+    "@dxos/network-manager": "0.8.4-main.74a063c4e0",
+    "@dxos/protocols": "0.8.4-main.74a063c4e0",
+    "@dxos/util": "0.8.4-main.74a063c4e0",
+    "@dxos/tracing": "0.8.4-main.74a063c4e0"
   },
   "devDependencies": {
-    "@sentry/types": "^8.8.0",
+    "@effect/platform": "0.94.4",
     "@types/debug": "^4.1.10",
-    "@types/js-yaml": "^4.0.5",
-    "sentry-testkit": "^5.0.5",
-    "zone.js": ">=0.11.4 <0.12.0-0 || >=0.13.0 <0.14.0-0 || >=0.14.0 <0.15.0-0"
+    "@types/js-yaml": "^4.0.5"
+  },
+  "peerDependencies": {
+    "@effect/platform": "0.94.4",
+    "effect": "3.20.0"
   },
   "publishConfig": {
     "access": "public"

package/src/cli-observability-secrets.json

@@ -1,7 +1,6 @@
 {
-  "SENTRY_DESTINATION": "https://2647916221e643869965e78469479aa4@o4504012000067584.ingest.sentry.io/4504012027265029",
-  "TELEMETRY_API_KEY": "B00QG6PtJJrJ0VVFe0H5a6bcUUShKyZM",
+  "POSTHOG_API_KEY": null,
   "IPDATA_API_KEY": "73dfdecdf979c18f07d50cf841bbdd9e589f237256326ac8cca23786",
-  "OTEL_ENDPOINT": "https://otlp-proxy.dxos.workers.dev",
-  "OTEL_AUTHORIZATION": "Basic OTA3MzIzOmdsY19leUp2SWpvaU1URXdNVEl6TnlJc0ltNGlPaUp6ZEdGamF5MDVNRGN6TWpNdGFXNTBaV2R5WVhScGIyNHRZMnh2ZFdSbWJHRnlaUzF2ZEd4d0xYQnliM2g1SWl3aWF5STZJalZ2Tkd4cFYydE5iRmszTlRNMGJUVXpTemRTVjNBeVNpSXNJbTBpT25zaWNpSTZJbkJ5YjJRdGRYTXRaV0Z6ZEMwd0luMTk="
+  "OTEL_ENDPOINT": "https://ingest.eu.signoz.cloud:443",
+  "OTEL_HEADERS": "signoz-ingestion-key: 5300e0c9-a5e8-4a10-9c61-f473e539c0b7"
 }

package/src/extensions/index.ts

@@ -0,0 +1,6 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export * as Otel from './otel';
+export * as PostHog from './posthog';

package/src/extensions/otel/extension.ts

@@ -0,0 +1,178 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { defaultResource, resourceFromAttributes } from '@opentelemetry/resources';
+import { ATTR_SERVICE_NAME, ATTR_SERVICE_VERSION } from '@opentelemetry/semantic-conventions';
+import * as Effect from 'effect/Effect';
+import * as Match from 'effect/Match';
+import * as Option from 'effect/Option';
+import * as Ref from 'effect/Ref';
+
+import { type Config } from '@dxos/config';
+import { LogLevel, log } from '@dxos/log';
+import { isNode, isNonNullable } from '@dxos/util';
+
+import buildSecrets from '../../cli-observability-secrets.json';
+import { type Extension, type ExtensionApi } from '../../observability-extension';
+import { isObservabilityDisabled, storeObservabilityDisabled } from '../../storage';
+import { stubExtension } from '../stub';
+
+export type ExtensionsOptions = {
+  /** For the OTEL, the name of the entity for which signals (metrics or trace) are collected. */
+  serviceName: string;
+  /** For the OTEL, the version of the entity for which signals (metrics or trace) are collected. */
+  serviceVersion: string;
+  /** For the OTEL, the environment of the entity for which signals (metrics or trace) are collected. */
+  environment: string;
+  config: Config;
+  endpoint?: string;
+  headers?: Record<string, string>;
+  logs?: boolean;
+  /** Minimum log level to export. Defaults to INFO (i.e. info, warn, error). */
+  logLevel?: LogLevel;
+  metrics?: boolean;
+  traces?: boolean;
+};
+
+/** Create an OTEL-backed observability extension for logs, metrics, and/or traces. */
+export const extensions: (options: ExtensionsOptions) => Effect.Effect<Extension> = Effect.fn(function* ({
+  serviceName,
+  serviceVersion,
+  environment,
+  config,
+  endpoint: _endpoint,
+  headers: _headers,
+  // TODO(wittjosiah): Logging integration.
+  //   - logger should run even if observability is disabled
+  //   - logs should be cached locally in a circular buffer
+  //   - logs should be flushed to the server if user opts to include them in a bug report
+  logs: logsEnabled = false,
+  logLevel = LogLevel.INFO,
+  metrics: metricsEnabled = false,
+  traces: tracesEnabled = false,
+}) {
+  const { OtelLogs } = yield* Effect.promise(() => import('./logs'));
+  const { OtelMetrics } = yield* Effect.promise(() => import('./metrics'));
+  const { OtelTraces } = yield* Effect.promise(() => import('./traces'));
+
+  const cachedDisabled = yield* Effect.promise(() => isObservabilityDisabled(serviceName));
+  const enabledRef = yield* Ref.make(!cachedDisabled);
+  const tags = new Map<string, string>();
+
+  const endpoint = isNode()
+    ? (process.env.DX_OTEL_ENDPOINT ?? _endpoint ?? buildSecrets.OTEL_ENDPOINT)
+    : config.values.runtime?.app?.env?.DX_OTEL_ENDPOINT;
+  const headers =
+    _headers ??
+    Match.value(isNode()).pipe(
+      Match.when(true, () => Option.fromNullable(process.env.DX_OTEL_HEADERS ?? buildSecrets.OTEL_HEADERS)),
+      Match.when(false, () => Option.fromNullable(config.values.runtime?.app?.env?.DX_OTEL_HEADERS)),
+      Match.exhaustive,
+      Option.map((raw) => parseHeaders(raw)),
+      Option.getOrElse(() => undefined),
+    );
+
+  if (!endpoint || !headers) {
+    log.info('Missing OTEL_ENDPOINT or OTEL_HEADERS');
+    return stubExtension;
+  }
+
+  const resource = defaultResource().merge(
+    resourceFromAttributes({
+      [ATTR_SERVICE_NAME]: serviceName,
+      [ATTR_SERVICE_VERSION]: serviceVersion,
+      'deployment.environment': environment,
+    }),
+  );
+
+  const logs = logsEnabled
+    ? new OtelLogs({
+        endpoint,
+        headers,
+        resource,
+        getTags: () => Object.fromEntries(tags),
+        logLevel,
+      })
+    : undefined;
+
+  const metrics = metricsEnabled
+    ? new OtelMetrics({
+        endpoint,
+        headers,
+        resource,
+        getTags: () => Object.fromEntries(tags),
+      })
+    : undefined;
+
+  const traces = tracesEnabled
+    ? new OtelTraces({
+        endpoint,
+        headers,
+        resource,
+        getTags: () => Object.fromEntries(tags),
+      })
+    : undefined;
+
+  return {
+    initialize: () =>
+      Effect.sync(() => {
+        if (logs) {
+          log.runtimeConfig.processors.push(logs.logProcessor);
+        }
+        if (traces) {
+          traces.start();
+        }
+      }),
+    enable: Effect.fn(function* () {
+      yield* Effect.promise(() => storeObservabilityDisabled(serviceName, false));
+      yield* Ref.update(enabledRef, () => true);
+    }),
+    disable: Effect.fn(function* () {
+      yield* Effect.promise(() => storeObservabilityDisabled(serviceName, true));
+      yield* Ref.update(enabledRef, () => false);
+    }),
+    close: () =>
+      Effect.promise(async () => {
+        await logs?.close();
+        await metrics?.close();
+      }),
+    flush: () =>
+      Effect.promise(async () => {
+        await logs?.flush();
+        await metrics?.flush();
+      }),
+    setTags: (incomingTags) => {
+      for (const [key, value] of Object.entries(incomingTags)) {
+        tags.set(key, value);
+      }
+    },
+    get enabled() {
+      return Ref.get(enabledRef).pipe(Effect.runSync);
+    },
+    apis: [
+      { kind: 'logs', isAvailable: () => Effect.succeed(!!logs) } satisfies ExtensionApi,
+      metrics
+        ? ({
+            kind: 'metrics',
+            isAvailable: () => Effect.succeed(true),
+            gauge: (name, value, tags) => metrics.gauge(name, value, tags),
+            increment: (name, value, tags) => metrics.increment(name, value, tags),
+            distribution: (name, value, tags) => metrics.distribution(name, value, tags),
+          } satisfies ExtensionApi)
+        : undefined,
+      traces ? ({ kind: 'traces', isAvailable: () => Effect.succeed(true) } satisfies ExtensionApi) : undefined,
+    ].filter(isNonNullable),
+  };
+});
+
+const parseHeaders = (unparsedHeaders: string): Record<string, string> => {
+  return unparsedHeaders.split(';').reduce((acc: Record<string, string>, header) => {
+    const [key, ...rest] = header.split(':');
+    if (key && rest.length > 0) {
+      acc[key.trim().toLowerCase()] = rest.join(':').trim();
+    }
+
+    return acc;
+  }, {});
+};

package/src/extensions/otel/index.ts

@@ -0,0 +1,5 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+export * from './extension';

package/src/{otel → extensions/otel}/logs.ts

@@ -4,9 +4,8 @@
 
 import { SeverityNumber } from '@opentelemetry/api-logs';
 import { OTLPLogExporter } from '@opentelemetry/exporter-logs-otlp-http';
-import { defaultResource, resourceFromAttributes } from '@opentelemetry/resources';
 import { BatchLogRecordProcessor, LoggerProvider } from '@opentelemetry/sdk-logs';
-import { SEMRESATTRS_SERVICE_NAME, SEMRESATTRS_SERVICE_VERSION } from '@opentelemetry/semantic-conventions';
+import { ATTR_SERVICE_VERSION } from '@opentelemetry/semantic-conventions';
 
 import {
   type LogConfig,
@@ -16,44 +15,41 @@ import {
   getContextFromEntry,
   getRelativeFilename,
 } from '@dxos/log';
-import { jsonlogify } from '@dxos/util';
 
 import { type OtelOptions, setDiagLogger } from './otel';
 
+const FLATTEN_DEPTH = 1;
+
 export type OtelLogOptions = OtelOptions & {
   logLevel: LogLevel;
   /**
-   * Set `true` to capture logs sent through LoggingService from shared worker.
-   * Better to set to `false` because shared worker is initializing its own logger.
+   * Include logs forwarded from the shared worker via LoggingService.
+   *
+   * @deprecated
    */
-  includeSharedWorkerLogs: boolean;
+  includeSharedWorkerLogs?: boolean;
 };
 
 export class OtelLogs {
   private _loggerProvider: LoggerProvider;
   constructor(private readonly options: OtelLogOptions) {
     setDiagLogger(options.consoleDiagLogLevel);
-    const resource = defaultResource().merge(
-      resourceFromAttributes({
-        [SEMRESATTRS_SERVICE_NAME]: this.options.serviceName,
-        [SEMRESATTRS_SERVICE_VERSION]: this.options.serviceVersion,
-      }),
-    );
     const logExporter = new OTLPLogExporter({
       url: this.options.endpoint + '/v1/logs',
-      headers: {
-        Authorization: this.options.authorizationHeader,
-      },
+      headers: this.options.headers,
       concurrencyLimit: 10, // an optional limit on pending requests
     });
     this._loggerProvider = new LoggerProvider({
-      resource,
+      resource: this.options.resource,
       processors: [new BatchLogRecordProcessor(logExporter)],
     });
   }
 
-  public readonly logProcessor: LogProcessor = (config: LogConfig, entry: LogEntry) => {
-    const logger = this._loggerProvider.getLogger('dxos-observability', this.options.serviceVersion);
+  public readonly logProcessor: LogProcessor = (_config: LogConfig, entry: LogEntry) => {
+    const logger = this._loggerProvider.getLogger(
+      'dxos-observability',
+      this.options.resource.attributes[ATTR_SERVICE_VERSION]?.toString(),
+    );
 
     if (
       entry.level < this.options.logLevel ||
@@ -62,16 +58,17 @@ export class OtelLogs {
       return;
     }
 
-    const record = {
-      ...entry,
+    const attributes = {
+      ...this.options.getTags(),
       ...(entry.meta ? { meta: { file: getRelativeFilename(entry.meta.F), line: entry.meta.L } } : {}),
-      context: jsonlogify(getContextFromEntry(entry)),
+      ...(entry.error ? { error: entry.error.stack } : {}),
+      ...stringifyValues(getContextFromEntry(entry), 'ctx_'),
     };
 
     logger.emit({
       severityNumber: convertLevel(entry.level),
-      body: JSON.stringify(record),
-      attributes: this.options.getTags(),
+      body: entry.message,
+      attributes,
     });
   };
 
@@ -100,3 +97,38 @@ const convertLevel = (level: LogLevel): SeverityNumber => {
       return SeverityNumber.ERROR;
   }
 };
+
+const safeStringify = (value: unknown): string => {
+  try {
+    return JSON.stringify(value);
+  } catch {
+    return '[Circular]';
+  }
+};
+
+// TODO(wittjosiah): Reconcile logging utils w/ EDGE.
+const stringifyValues = (object: object | undefined, keyPrefix?: string, depth: number = 1) => {
+  if (!object) {
+    return {};
+  }
+  const result: Record<string, string> = {};
+  for (const [key, value] of Object.entries(object)) {
+    if (value === undefined) {
+      continue;
+    }
+    const newKey = keyPrefix ? `${keyPrefix}${key}` : key;
+    if (typeof value === 'object') {
+      if (!value || Array.isArray(value) || depth > FLATTEN_DEPTH) {
+        result[newKey] = safeStringify(value);
+      } else {
+        const flattened = stringifyValues(value, `${newKey}_`, depth + 1);
+        for (const [flattenedKey, flattenedValue] of Object.entries(flattened)) {
+          result[flattenedKey] = flattenedValue;
+        }
+      }
+    } else {
+      result[newKey] = String(value);
+    }
+  }
+  return result;
+};

package/src/{otel → extensions/otel}/metrics.ts

@@ -4,9 +4,7 @@
 
 import { type Meter } from '@opentelemetry/api';
 import { OTLPMetricExporter } from '@opentelemetry/exporter-metrics-otlp-http';
-import { defaultResource, resourceFromAttributes } from '@opentelemetry/resources';
 import { MeterProvider, PeriodicExportingMetricReader } from '@opentelemetry/sdk-metrics';
-import { SEMRESATTRS_SERVICE_NAME, SEMRESATTRS_SERVICE_VERSION } from '@opentelemetry/semantic-conventions';
 
 import { log } from '@dxos/log';
 import { type MetricData, TRACE_PROCESSOR } from '@dxos/tracing';
@@ -23,25 +21,17 @@ export class OtelMetrics {
     // TODO: improve error handling/logging
     //  https://github.com/open-telemetry/opentelemetry-js/issues/4823
     setDiagLogger(options.consoleDiagLogLevel);
-    const resource = defaultResource().merge(
-      resourceFromAttributes({
-        [SEMRESATTRS_SERVICE_NAME]: this.options.serviceName,
-        [SEMRESATTRS_SERVICE_VERSION]: this.options.serviceVersion,
-      }),
-    );
 
     const grafanaMetricReader = new PeriodicExportingMetricReader({
       exporter: new OTLPMetricExporter({
         url: this.options.endpoint + '/v1/metrics',
-        headers: {
-          Authorization: this.options.authorizationHeader,
-        },
+        headers: this.options.headers,
       }),
       exportIntervalMillis: EXPORT_INTERVAL,
     });
 
     this._meterProvider = new MeterProvider({
-      resource,
+      resource: this.options.resource,
       readers: [grafanaMetricReader],
     });
     this._meter = this._meterProvider.getMeter('dxos-observability');

package/src/{otel → extensions/otel}/otel.ts

@@ -3,12 +3,12 @@
 //
 
 import { DiagConsoleLogger, DiagLogLevel, diag } from '@opentelemetry/api';
+import { type Resource } from '@opentelemetry/resources';
 
 export type OtelOptions = {
   endpoint: string;
-  authorizationHeader: string;
-  serviceName: string; // For the Otel API, the name of the entity for which signals (metrics or trace) are collected.
-  serviceVersion: string; // For the Otel API, The name of the entity for which signals (metrics or trace) are collected.
+  headers: Record<string, string>;
+  resource: Resource;
   getTags: () => { [key: string]: string };
   consoleDiagLogLevel?: string;
 };

package/src/extensions/otel/traces-browser.ts

@@ -0,0 +1,110 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { type Context, type Tracer, context as otelContext, propagation, trace } from '@opentelemetry/api';
+import { getWebAutoInstrumentations } from '@opentelemetry/auto-instrumentations-web';
+import { W3CTraceContextPropagator } from '@opentelemetry/core';
+import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
+import { registerInstrumentations } from '@opentelemetry/instrumentation';
+import {
+  AlwaysOnSampler,
+  BatchSpanProcessor,
+  ParentBasedSampler,
+  type ReadableSpan,
+  type SpanProcessor,
+  TraceIdRatioBasedSampler,
+} from '@opentelemetry/sdk-trace-base';
+import { WebTracerProvider } from '@opentelemetry/sdk-trace-web';
+import { ATTR_SERVICE_VERSION } from '@opentelemetry/semantic-conventions';
+
+import { log } from '@dxos/log';
+import { type StartSpanOptions, TRACE_PROCESSOR } from '@dxos/tracing';
+
+import { type OtelOptions } from './otel';
+
+/**
+ * Injects dynamic tags (e.g. userId) as attributes on every span.
+ */
+class TagInjectorSpanProcessor implements SpanProcessor {
+  constructor(private readonly _getTags: () => Record<string, string>) {}
+
+  onStart(span: { setAttribute: (key: string, value: string) => void }): void {
+    const tags = this._getTags();
+    for (const [key, value] of Object.entries(tags)) {
+      span.setAttribute(key, value);
+    }
+  }
+
+  onEnd(_span: ReadableSpan): void {}
+
+  async shutdown(): Promise<void> {}
+
+  async forceFlush(): Promise<void> {}
+}
+
+export class OtelTraces {
+  private _tracer: Tracer;
+
+  constructor(private readonly options: OtelOptions) {
+    propagation.setGlobalPropagator(new W3CTraceContextPropagator());
+
+    const forceTraceAll = typeof localStorage !== 'undefined' && localStorage.getItem('dxos.debug.traceAll') === 'true';
+
+    const tracerProvider = new WebTracerProvider({
+      resource: this.options.resource,
+      sampler: new ParentBasedSampler({
+        root: forceTraceAll ? new AlwaysOnSampler() : new TraceIdRatioBasedSampler(0.3),
+      }),
+      spanProcessors: [
+        new TagInjectorSpanProcessor(this.options.getTags),
+        new BatchSpanProcessor(
+          new OTLPTraceExporter({
+            url: this.options.endpoint + '/v1/traces',
+            headers: this.options.headers,
+            concurrencyLimit: 10,
+          }),
+          { scheduledDelayMillis: 5_000 },
+        ),
+      ],
+    });
+
+    trace.setGlobalTracerProvider(tracerProvider);
+
+    this._tracer = trace.getTracer(
+      'dxos-observability',
+      this.options.resource.attributes[ATTR_SERVICE_VERSION]?.toString(),
+    );
+  }
+
+  public start(): void {
+    log('trace processor registered');
+
+    registerInstrumentations({
+      instrumentations: [
+        getWebAutoInstrumentations({
+          // Fetch is disabled in favor of explicit ctx on our call sites; if re-enabled, keep noisy
+          // third-party URLs out of traces (matches prior browser tracing setup).
+          '@opentelemetry/instrumentation-fetch': { enabled: false, ignoreUrls: [/api\.ipdata\.co/] },
+          '@opentelemetry/instrumentation-document-load': { enabled: false },
+          '@opentelemetry/instrumentation-xml-http-request': { enabled: false },
+        }),
+      ],
+    });
+
+    TRACE_PROCESSOR.remoteTracing.registerProcessor({
+      startSpan: (options: StartSpanOptions) => {
+        log('begin otel trace', { options });
+        const explicitParent = options.parentContext as Context | undefined;
+        const parentCtx = explicitParent ?? otelContext.active();
+        const span = this._tracer.startSpan(options.name, options, parentCtx);
+        const spanCtx = trace.setSpan(parentCtx, span);
+        return {
+          end: () => span.end(),
+          wrapExecution: <T>(fn: () => T): T => otelContext.with(spanCtx, fn),
+          spanContext: spanCtx,
+        };
+      },
+    });
+  }
+}