@dxos/observability 0.8.4-main.a4bbb77 → 0.8.4-main.abd8ff62ef

package/package.json

@@ -1,50 +1,29 @@
 {
   "name": "@dxos/observability",
-  "version": "0.8.4-main.a4bbb77",
+  "version": "0.8.4-main.abd8ff62ef",
   "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,40 +43,40 @@
     "@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.a4bbb77",
-    "@dxos/client": "0.8.4-main.a4bbb77",
-    "@dxos/client-protocol": "0.8.4-main.a4bbb77",
-    "@dxos/client-services": "0.8.4-main.a4bbb77",
-    "@dxos/context": "0.8.4-main.a4bbb77",
-    "@dxos/config": "0.8.4-main.a4bbb77",
-    "@dxos/invariant": "0.8.4-main.a4bbb77",
-    "@dxos/debug": "0.8.4-main.a4bbb77",
-    "@dxos/log": "0.8.4-main.a4bbb77",
-    "@dxos/network-manager": "0.8.4-main.a4bbb77",
-    "@dxos/node-std": "0.8.4-main.a4bbb77",
-    "@dxos/protocols": "0.8.4-main.a4bbb77",
-    "@dxos/tracing": "0.8.4-main.a4bbb77",
-    "@dxos/util": "0.8.4-main.a4bbb77"
+    "zone.js": "^0.15.0",
+    "@dxos/async": "0.8.4-main.abd8ff62ef",
+    "@dxos/client": "0.8.4-main.abd8ff62ef",
+    "@dxos/client-protocol": "0.8.4-main.abd8ff62ef",
+    "@dxos/client-services": "0.8.4-main.abd8ff62ef",
+    "@dxos/config": "0.8.4-main.abd8ff62ef",
+    "@dxos/context": "0.8.4-main.abd8ff62ef",
+    "@dxos/debug": "0.8.4-main.abd8ff62ef",
+    "@dxos/invariant": "0.8.4-main.abd8ff62ef",
+    "@dxos/log-store-idb": "0.8.4-main.abd8ff62ef",
+    "@dxos/log": "0.8.4-main.abd8ff62ef",
+    "@dxos/node-std": "0.8.4-main.abd8ff62ef",
+    "@dxos/network-manager": "0.8.4-main.abd8ff62ef",
+    "@dxos/protocols": "0.8.4-main.abd8ff62ef",
+    "@dxos/tracing": "0.8.4-main.abd8ff62ef",
+    "@dxos/util": "0.8.4-main.abd8ff62ef"
   },
   "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"
+    "@dxos/effect": "0.8.4-main.abd8ff62ef",
+    "@dxos/messaging": "0.8.4-main.abd8ff62ef"
+  },
+  "peerDependencies": {
+    "@effect/platform": "0.94.4",
+    "effect": "3.20.0"
   },
   "publishConfig": {
     "access": "public"
-  },
-  "scripts": {
-    "api-keys": "./scripts/inject_api_keys.mjs"
   }
 }

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": "/api/otel",
+  "OTEL_HEADERS": null
 }

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,258 @@
+//
+// 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, resolveTelemetryTag } 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 disabled = cachedDisabled || isObservabilityDisabledSync(serviceName);
+  const enabledRef = yield* Ref.make(!disabled);
+  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;
+  }
+
+  // Matches edge's `ctx.tag` span attribute (stamped by the edge log middleware
+  // when it reads the `X-DXOS-Client-Tag` header, see
+  // /edge/packages/services/edge/src/log-middleware.ts).
+  //
+  // Stamped in TWO places:
+  //   1. Resource attribute — so logs and metrics emitted from this extension
+  //      also carry it, and for zero per-span cost.
+  //   2. Span attribute via `tags` — because edge puts `ctx.tag` in the span-
+  //      attribute context (not resource), and SigNoz indexes the two contexts
+  //      separately. Stamping it on span attributes here keeps a single
+  //      `ctx.tag = <value>` filter matching spans from both tiers in SigNoz
+  //      without requiring qualified `attribute.ctx.tag`/`resource.ctx.tag` syntax.
+  const clientTag = resolveTelemetryTag(config);
+  if (clientTag) {
+    tags.set('ctx.tag', clientTag);
+  }
+
+  const resource = defaultResource().merge(
+    resourceFromAttributes({
+      [ATTR_SERVICE_NAME]: serviceName,
+      [ATTR_SERVICE_VERSION]: serviceVersion,
+      'session.id': crypto.randomUUID(),
+      'deployment.environment': environment,
+      'dxos.process.type': detectProcessType(),
+      ...(clientTag ? { 'ctx.tag': clientTag } : {}),
+    }),
+  );
+
+  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;
+
+  const extension: Extension = {
+    initialize: () =>
+      Effect.sync(() => {
+        if (disabled) {
+          return;
+        }
+
+        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 () => {
+        // Run logs/metrics close concurrently and swallow their failures so the
+        // tracer provider shutdown below ALWAYS runs. Without this, a rejection
+        // from logs or metrics would drop the tracer provider's BatchSpanProcessor
+        // queue on process exit, manifesting as "Missing Span" in SigNoz for any
+        // already-exported children.
+        const results = await Promise.allSettled([logs?.close(), metrics?.close()]);
+        for (const result of results) {
+          if (result.status === 'rejected') {
+            log.catch(result.reason);
+          }
+        }
+        // Critical: shut down the tracer provider so BatchSpanProcessor drains its
+        // queue. Otherwise spans enqueued in the last 5s (close/teardown spans)
+        // are dropped on process exit.
+        await traces?.close();
+      }),
+    flush: () =>
+      Effect.promise(async () => {
+        const results = await Promise.allSettled([logs?.flush(), metrics?.flush()]);
+        for (const result of results) {
+          if (result.status === 'rejected') {
+            log.catch(result.reason);
+          }
+        }
+        await traces?.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),
+  };
+
+  return extension;
+});
+
+/**
+ * Synchronous best-effort check for observability opt-out.
+ * Prevents telemetry from being emitted before the async storage check completes.
+ */
+const isObservabilityDisabledSync = (serviceName: string): boolean => {
+  if (isNode()) {
+    return process.env.DX_DISABLE_OBSERVABILITY === 'true';
+  }
+  try {
+    if (typeof localStorage !== 'undefined') {
+      return localStorage.getItem(`${serviceName}/observability-disabled`) === 'true';
+    }
+  } catch {
+    // localStorage not available (e.g., in workers).
+  }
+  return false;
+};
+
+/** Best-effort detection of the JavaScript execution context type. */
+const detectProcessType = (): string => {
+  if (isNode()) {
+    return 'node';
+  }
+  if (typeof window !== 'undefined') {
+    return 'browser';
+  }
+  if (typeof (globalThis as any).ServiceWorkerGlobalScope !== 'undefined') {
+    return 'service-worker';
+  }
+  if (typeof (globalThis as any).SharedWorkerGlobalScope !== 'undefined') {
+    return 'shared-worker';
+  }
+  return 'dedicated-worker';
+};
+
+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/extensions/otel/logs.ts

@@ -0,0 +1,137 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { SeverityNumber } from '@opentelemetry/api-logs';
+import { OTLPLogExporter } from '@opentelemetry/exporter-logs-otlp-http';
+import { BatchLogRecordProcessor, LoggerProvider } from '@opentelemetry/sdk-logs';
+import { ATTR_SERVICE_VERSION } from '@opentelemetry/semantic-conventions';
+
+import {
+  type LogConfig,
+  type LogEntry,
+  LogLevel,
+  type LogProcessor,
+  getContextFromEntry,
+  getRelativeFilename,
+} from '@dxos/log';
+
+import { type OtelOptions, setDiagLogger } from './otel';
+
+const FLATTEN_DEPTH = 1;
+
+export type OtelLogOptions = OtelOptions & {
+  logLevel: LogLevel;
+  /**
+   * Include logs forwarded from the shared worker via LoggingService.
+   *
+   * @deprecated
+   */
+  includeSharedWorkerLogs?: boolean;
+};
+
+export class OtelLogs {
+  private _loggerProvider: LoggerProvider;
+  constructor(private readonly options: OtelLogOptions) {
+    setDiagLogger(options.consoleDiagLogLevel);
+    const logExporter = new OTLPLogExporter({
+      url: this.options.endpoint + '/v1/logs',
+      headers: this.options.headers,
+      concurrencyLimit: 10, // an optional limit on pending requests
+    });
+    this._loggerProvider = new LoggerProvider({
+      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.resource.attributes[ATTR_SERVICE_VERSION]?.toString(),
+    );
+
+    if (
+      entry.level < this.options.logLevel ||
+      (!this.options.includeSharedWorkerLogs && entry.meta?.S?.remoteSessionId)
+    ) {
+      return;
+    }
+
+    const attributes = {
+      ...this.options.getTags(),
+      ...(entry.meta ? { meta: { file: getRelativeFilename(entry.meta.F), line: entry.meta.L } } : {}),
+      ...(entry.error ? { error: entry.error.stack } : {}),
+      ...stringifyValues(getContextFromEntry(entry), 'ctx_'),
+    };
+
+    logger.emit({
+      severityNumber: convertLevel(entry.level),
+      body: entry.message,
+      attributes,
+    });
+  };
+
+  flush(): Promise<void> {
+    return this._loggerProvider.forceFlush();
+  }
+
+  close(): Promise<void> {
+    return this._loggerProvider.shutdown();
+  }
+}
+
+/** Maps {@link LogLevel} to OpenTelemetry {@link SeverityNumber}. */
+const convertLevel = (level: LogLevel): SeverityNumber => {
+  switch (level) {
+    case LogLevel.TRACE:
+      return SeverityNumber.TRACE;
+    case LogLevel.DEBUG:
+      return SeverityNumber.DEBUG;
+    case LogLevel.VERBOSE:
+      return SeverityNumber.INFO;
+    case LogLevel.INFO:
+      return SeverityNumber.INFO;
+    case LogLevel.WARN:
+      return SeverityNumber.WARN;
+    case LogLevel.ERROR:
+      return SeverityNumber.ERROR;
+    default:
+      return SeverityNumber.UNSPECIFIED;
+  }
+};
+
+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/span-processors.ts

@@ -0,0 +1,45 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type Context } from '@opentelemetry/api';
+import { type ReadableSpan, type Span, type SpanProcessor } from '@opentelemetry/sdk-trace-base';
+
+import { log } from '@dxos/log';
+
+/**
+ * Injects dynamic tags as attributes on every span.
+ *
+ * This is an `onStart`-only processor; `onEnd`/`shutdown`/`forceFlush` are no-ops
+ * because this processor never holds pending work (delegates export to downstream
+ * processors like BatchSpanProcessor).
+ *
+ * Use for tags that are not known at provider construction (e.g. identity
+ * resolved asynchronously after login). For values known at startup, prefer
+ * putting them on the `Resource` — see `extension.ts`.
+ *
+ * Failures in the tag provider are swallowed so they can never break span
+ * recording (the processor is best-effort and runs on the startSpan hot path).
+ */
+export class TagInjectorSpanProcessor implements SpanProcessor {
+  constructor(private readonly _getTags: () => Record<string, string>) {}
+
+  onStart(span: Span, _parentContext: Context): void {
+    let tags: Record<string, string>;
+    try {
+      tags = this._getTags();
+    } catch (err) {
+      log.catch(err);
+      return;
+    }
+    for (const [key, value] of Object.entries(tags)) {
+      span.setAttribute(key, value);
+    }
+  }
+
+  onEnd(_span: ReadableSpan): void {}
+
+  async shutdown(): Promise<void> {}
+
+  async forceFlush(): Promise<void> {}
+}