@dxos/observability 0.8.4-main.ef1bc66f44 → 0.8.4-main.f466a3d56e

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dxos/observability",
-  "version": "0.8.4-main.ef1bc66f44",
+  "version": "0.8.4-main.f466a3d56e",
   "description": "Provides a common interface for app and platform observability",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
@@ -8,7 +8,7 @@
     "type": "git",
     "url": "https://github.com/dxos/dxos"
   },
-  "license": "MIT",
+  "license": "FSL-1.1-Apache-2.0",
   "author": "DXOS.org",
   "sideEffects": false,
   "type": "module",
@@ -29,48 +29,52 @@
     "src"
   ],
   "dependencies": {
-    "@opentelemetry/api": "^1.9.0",
-    "@opentelemetry/api-logs": "^0.203.0",
-    "@opentelemetry/auto-instrumentations-web": "^0.51.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",
-    "@opentelemetry/instrumentation": "^0.203.0",
-    "@opentelemetry/resources": "^2.1.0",
-    "@opentelemetry/sdk-logs": "^0.203.0",
-    "@opentelemetry/sdk-metrics": "^2.1.0",
-    "@opentelemetry/sdk-trace-base": "^2.1.0",
-    "@opentelemetry/sdk-trace-web": "^2.1.0",
-    "@opentelemetry/semantic-conventions": "^1.37.0",
+    "@opentelemetry/api": "^1.9.1",
+    "@opentelemetry/api-logs": "^0.218.0",
+    "@opentelemetry/auto-instrumentations-web": "^0.63.0",
+    "@opentelemetry/core": "^2.7.1",
+    "@opentelemetry/exporter-logs-otlp-http": "^0.218.0",
+    "@opentelemetry/exporter-metrics-otlp-http": "^0.218.0",
+    "@opentelemetry/exporter-trace-otlp-http": "^0.218.0",
+    "@opentelemetry/instrumentation": "^0.218.0",
+    "@opentelemetry/resources": "^2.7.1",
+    "@opentelemetry/sdk-logs": "^0.218.0",
+    "@opentelemetry/sdk-metrics": "^2.7.1",
+    "@opentelemetry/sdk-trace-base": "^2.7.1",
+    "@opentelemetry/sdk-trace-web": "^2.7.1",
+    "@opentelemetry/semantic-conventions": "^1.41.1",
     "debug": "^4.3.4",
     "js-yaml": "4.1.1",
     "localforage": "^1.10.0",
-    "posthog-js": "^1.347.2",
+    "posthog-js": "^1.353.0",
     "uuid": "^9.0.0",
-    "@dxos/async": "0.8.4-main.ef1bc66f44",
-    "@dxos/client": "0.8.4-main.ef1bc66f44",
-    "@dxos/client-protocol": "0.8.4-main.ef1bc66f44",
-    "@dxos/config": "0.8.4-main.ef1bc66f44",
-    "@dxos/context": "0.8.4-main.ef1bc66f44",
-    "@dxos/client-services": "0.8.4-main.ef1bc66f44",
-    "@dxos/debug": "0.8.4-main.ef1bc66f44",
-    "@dxos/invariant": "0.8.4-main.ef1bc66f44",
-    "@dxos/log": "0.8.4-main.ef1bc66f44",
-    "@dxos/network-manager": "0.8.4-main.ef1bc66f44",
-    "@dxos/protocols": "0.8.4-main.ef1bc66f44",
-    "@dxos/node-std": "0.8.4-main.ef1bc66f44",
-    "@dxos/tracing": "0.8.4-main.ef1bc66f44",
-    "@dxos/util": "0.8.4-main.ef1bc66f44"
+    "zone.js": "^0.15.0",
+    "@dxos/async": "0.8.4-main.f466a3d56e",
+    "@dxos/client-services": "0.8.4-main.f466a3d56e",
+    "@dxos/client": "0.8.4-main.f466a3d56e",
+    "@dxos/invariant": "0.8.4-main.f466a3d56e",
+    "@dxos/client-protocol": "0.8.4-main.f466a3d56e",
+    "@dxos/config": "0.8.4-main.f466a3d56e",
+    "@dxos/debug": "0.8.4-main.f466a3d56e",
+    "@dxos/log": "0.8.4-main.f466a3d56e",
+    "@dxos/node-std": "0.8.4-main.f466a3d56e",
+    "@dxos/log-store-idb": "0.8.4-main.f466a3d56e",
+    "@dxos/network-manager": "0.8.4-main.f466a3d56e",
+    "@dxos/tracing": "0.8.4-main.f466a3d56e",
+    "@dxos/util": "0.8.4-main.f466a3d56e",
+    "@dxos/protocols": "0.8.4-main.f466a3d56e",
+    "@dxos/context": "0.8.4-main.f466a3d56e"
   },
   "devDependencies": {
     "@effect/platform": "0.94.4",
     "@types/debug": "^4.1.10",
     "@types/js-yaml": "^4.0.5",
-    "zone.js": "^0.15.0"
+    "@dxos/effect": "0.8.4-main.f466a3d56e",
+    "@dxos/messaging": "0.8.4-main.f466a3d56e"
   },
   "peerDependencies": {
     "@effect/platform": "0.94.4",
-    "effect": "3.19.16"
+    "effect": "3.20.0"
   },
   "publishConfig": {
     "access": "public"

package/src/cli-observability-secrets.json

@@ -1,6 +1,6 @@
 {
   "POSTHOG_API_KEY": null,
   "IPDATA_API_KEY": "73dfdecdf979c18f07d50cf841bbdd9e589f237256326ac8cca23786",
-  "OTEL_ENDPOINT": "https://ingest.eu.signoz.cloud:443",
-  "OTEL_HEADERS": "signoz-ingestion-key: 5300e0c9-a5e8-4a10-9c61-f473e539c0b7"
+  "OTEL_ENDPOINT": "/api/otel",
+  "OTEL_HEADERS": null
 }

package/src/extensions/otel/extension.ts

@@ -9,7 +9,7 @@ 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 { type Config, resolveTelemetryTag } from '@dxos/config';
 import { LogLevel, log } from '@dxos/log';
 import { isNode, isNonNullable } from '@dxos/util';
 
@@ -57,12 +57,17 @@ export const extensions: (options: ExtensionsOptions) => Effect.Effect<Extension
   const { OtelTraces } = yield* Effect.promise(() => import('./traces'));
 
   const cachedDisabled = yield* Effect.promise(() => isObservabilityDisabled(serviceName));
-  const enabledRef = yield* Ref.make(!cachedDisabled);
+  const disabled = cachedDisabled || isObservabilityDisabledSync(serviceName);
+  const enabledRef = yield* Ref.make(!disabled);
   const tags = new Map<string, string>();
 
-  const endpoint = isNode()
+  const rawEndpoint = isNode()
     ? (process.env.DX_OTEL_ENDPOINT ?? _endpoint ?? buildSecrets.OTEL_ENDPOINT)
-    : config.values.runtime?.app?.env?.DX_OTEL_ENDPOINT;
+    : (config.values.runtime?.app?.env?.DX_OTEL_ENDPOINT ?? _endpoint);
+  // The OTLP exporter (>= 0.203) validates URLs and rejects relative paths.
+  // In the browser/worker, resolve relative endpoints against the current origin
+  // so callers can keep using paths like `/api/otel` for proxied deployments.
+  const endpoint = !isNode() && rawEndpoint?.startsWith('/') ? resolveRelativeEndpoint(rawEndpoint) : rawEndpoint;
   const headers =
     _headers ??
     Match.value(isNode()).pipe(
@@ -73,23 +78,49 @@ export const extensions: (options: ExtensionsOptions) => Effect.Effect<Extension
       Option.getOrElse(() => undefined),
     );
 
-  if (!endpoint || !headers) {
-    log.info('Missing OTEL_ENDPOINT or OTEL_HEADERS');
+  if (!endpoint) {
+    log.info('Missing OTEL_ENDPOINT');
     return stubExtension;
   }
+  // Headers are optional when using a proxy that injects auth server-side.
+  const resolvedHeaders = headers ?? {};
+  // OTLP HTTP exporters require an absolute URL. Resolve relative paths using the current origin.
+  // globalThis.location is defined in all browser contexts (main thread, dedicated/service workers).
+  const resolvedEndpoint =
+    !isNode() && endpoint.startsWith('/') ? `${globalThis.location.origin}${endpoint}` : endpoint;
+
+  // 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,
+        endpoint: resolvedEndpoint,
+        headers: resolvedHeaders,
         resource,
         getTags: () => Object.fromEntries(tags),
         logLevel,
@@ -98,8 +129,8 @@ export const extensions: (options: ExtensionsOptions) => Effect.Effect<Extension
 
   const metrics = metricsEnabled
     ? new OtelMetrics({
-        endpoint,
-        headers,
+        endpoint: resolvedEndpoint,
+        headers: resolvedHeaders,
         resource,
         getTags: () => Object.fromEntries(tags),
       })
@@ -107,16 +138,20 @@ export const extensions: (options: ExtensionsOptions) => Effect.Effect<Extension
 
   const traces = tracesEnabled
     ? new OtelTraces({
-        endpoint,
-        headers,
+        endpoint: resolvedEndpoint,
+        headers: resolvedHeaders,
         resource,
         getTags: () => Object.fromEntries(tags),
       })
     : undefined;
 
-  return {
+  const extension: Extension = {
     initialize: () =>
       Effect.sync(() => {
+        if (disabled) {
+          return;
+        }
+
         if (logs) {
           log.runtimeConfig.processors.push(logs.logProcessor);
         }
@@ -134,13 +169,31 @@ export const extensions: (options: ExtensionsOptions) => Effect.Effect<Extension
     }),
     close: () =>
       Effect.promise(async () => {
-        await logs?.close();
-        await metrics?.close();
+        // 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 () => {
-        await logs?.flush();
-        await metrics?.flush();
+        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)) {
@@ -164,8 +217,56 @@ export const extensions: (options: ExtensionsOptions) => Effect.Effect<Extension
       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';
+};
+
+/**
+ * Resolves a relative OTLP endpoint path against the current global origin.
+ * Workers expose the same `globalThis.location` as the page that spawned them;
+ * if neither is available we fall back to the original path and let the OTLP
+ * exporter surface the configuration error.
+ */
+const resolveRelativeEndpoint = (path: string): string => {
+  const origin = (globalThis as { location?: { origin?: string } }).location?.origin;
+  return origin ? `${origin}${path}` : path;
+};
+
 const parseHeaders = (unparsedHeaders: string): Record<string, string> => {
   return unparsedHeaders.split(';').reduce((acc: Record<string, string>, header) => {
     const [key, ...rest] = header.split(':');

package/src/extensions/otel/logs.ts

@@ -16,7 +16,7 @@ import {
   getRelativeFilename,
 } from '@dxos/log';
 
-import { type OtelOptions, setDiagLogger } from './otel';
+import { type OtelOptions, resolveOtlpUrl, setDiagLogger } from './otel';
 
 const FLATTEN_DEPTH = 1;
 
@@ -35,7 +35,7 @@ export class OtelLogs {
   constructor(private readonly options: OtelLogOptions) {
     setDiagLogger(options.consoleDiagLogLevel);
     const logExporter = new OTLPLogExporter({
-      url: this.options.endpoint + '/v1/logs',
+      url: resolveOtlpUrl(this.options.endpoint + '/v1/logs'),
       headers: this.options.headers,
       concurrencyLimit: 10, // an optional limit on pending requests
     });
@@ -81,8 +81,11 @@ export class OtelLogs {
   }
 }
 
+/** 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:
@@ -94,7 +97,7 @@ const convertLevel = (level: LogLevel): SeverityNumber => {
     case LogLevel.ERROR:
       return SeverityNumber.ERROR;
     default:
-      return SeverityNumber.ERROR;
+      return SeverityNumber.UNSPECIFIED;
   }
 };
 

package/src/extensions/otel/metrics.ts

@@ -9,7 +9,7 @@ import { MeterProvider, PeriodicExportingMetricReader } from '@opentelemetry/sdk
 import { log } from '@dxos/log';
 import { type MetricData, TRACE_PROCESSOR } from '@dxos/tracing';
 
-import { type OtelOptions, setDiagLogger } from './otel';
+import { type OtelOptions, resolveOtlpUrl, setDiagLogger } from './otel';
 
 const EXPORT_INTERVAL = 60 * 1000;
 
@@ -24,7 +24,7 @@ export class OtelMetrics {
 
     const grafanaMetricReader = new PeriodicExportingMetricReader({
       exporter: new OTLPMetricExporter({
-        url: this.options.endpoint + '/v1/metrics',
+        url: resolveOtlpUrl(this.options.endpoint + '/v1/metrics'),
         headers: this.options.headers,
       }),
       exportIntervalMillis: EXPORT_INTERVAL,

package/src/extensions/otel/otel.ts

@@ -19,3 +19,16 @@ export const setDiagLogger = (level?: string) => {
     diag.setLogger(new DiagConsoleLogger(), logLevel);
   }
 };
+
+/**
+ * Resolve a possibly-relative OTLP exporter URL to an absolute URL.
+ * The OpenTelemetry browser HTTP exporter validates user-provided URLs with `new URL(url)`,
+ * which throws on relative paths like `/api/otel/v1/logs`. In a browser context we resolve
+ * against `window.location.origin`; outside the browser we return the input unchanged.
+ */
+export const resolveOtlpUrl = (url: string): string => {
+  if (typeof window !== 'undefined' && url.startsWith('/')) {
+    return new URL(url, window.location.origin).toString();
+  }
+  return url;
+};

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> {}
+}

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

@@ -2,37 +2,61 @@
 // Copyright 2024 DXOS.org
 //
 
-import { type Tracer, trace } from '@opentelemetry/api';
+import {
+  ROOT_CONTEXT,
+  SpanStatusCode,
+  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 { BatchSpanProcessor } from '@opentelemetry/sdk-trace-base';
+import {
+  AlwaysOnSampler,
+  BatchSpanProcessor,
+  ParentBasedSampler,
+  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 { TRACE_ALL_KEY, type RemoteSpan, type StartSpanOptions, TRACE_PROCESSOR } from '@dxos/tracing';
 
-import { type OtelOptions } from './otel';
+import { type OtelOptions, resolveOtlpUrl } from './otel';
+import { TagInjectorSpanProcessor } from './span-processors';
 
 export class OtelTraces {
   private _tracer: Tracer;
+  private readonly _tracerProvider: WebTracerProvider;
 
   constructor(private readonly options: OtelOptions) {
-    const tracerProvider = new WebTracerProvider({
+    propagation.setGlobalPropagator(new W3CTraceContextPropagator());
+
+    const forceTraceAll = typeof localStorage !== 'undefined' && localStorage.getItem(TRACE_ALL_KEY) === 'true';
+
+    this._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',
+            url: resolveOtlpUrl(this.options.endpoint + '/v1/traces'),
             headers: this.options.headers,
-            concurrencyLimit: 10, // an optional limit on pending requests
+            concurrencyLimit: 10,
           }),
+          { scheduledDelayMillis: 5_000 },
         ),
       ],
     });
 
-    trace.setGlobalTracerProvider(tracerProvider);
+    trace.setGlobalTracerProvider(this._tracerProvider);
 
     this._tracer = trace.getTracer(
       'dxos-observability',
@@ -40,18 +64,76 @@ export class OtelTraces {
     );
   }
 
+  /**
+   * Forcibly flush the BatchSpanProcessor. Call before process exit / page unload
+   * to avoid losing queued spans (which manifests as "Missing Span" in SigNoz —
+   * their already-exported children reference a parent that never made it to OTLP).
+   */
+  public async flush(): Promise<void> {
+    await this._tracerProvider.forceFlush();
+  }
+
+  /**
+   * Flush + shut down the tracer provider via `WebTracerProvider.shutdown()`,
+   * which forces a final export then terminates all span processors.
+   *
+   * Terminal and effectively one-shot: safe to call after `flush()`, but
+   * `flush()` MUST NOT be called after `close()` — shutdown stops further
+   * exporting, so subsequent `close()`/`flush()` calls resolve without
+   * emitting new spans.
+   */
+  public async close(): Promise<void> {
+    await this._tracerProvider.shutdown();
+  }
+
   public start(): void {
     log('trace processor registered');
 
     registerInstrumentations({
-      instrumentations: [getWebAutoInstrumentations()],
+      instrumentations: [
+        getWebAutoInstrumentations({
+          '@opentelemetry/instrumentation-fetch': { enabled: false, ignoreUrls: [/api\.ipdata\.co/] },
+          '@opentelemetry/instrumentation-document-load': { enabled: false },
+          '@opentelemetry/instrumentation-xml-http-request': { enabled: false },
+          '@opentelemetry/instrumentation-user-interaction': { enabled: false },
+        }),
+      ],
     });
 
-    TRACE_PROCESSOR.remoteTracing.registerProcessor({
-      startSpan: (options: StartSpanOptions) => {
+    const tracer = this._tracer;
+
+    TRACE_PROCESSOR.tracingBackend = {
+      startSpan: (options: StartSpanOptions): RemoteSpan => {
         log('begin otel trace', { options });
-        return this._tracer.startSpan(options.name, options);
+        const parentCtx = options.parentContext
+          ? propagation.extract(ROOT_CONTEXT, {
+              traceparent: options.parentContext.traceparent,
+              tracestate: options.parentContext.tracestate ?? '',
+            })
+          : otelContext.active();
+
+        const span = tracer.startSpan(options.name, options, parentCtx);
+
+        const sc = span.spanContext();
+        const spanContext =
+          sc && sc.traceId && sc.spanId
+            ? {
+                traceparent: `00-${sc.traceId}-${sc.spanId}-${(sc.traceFlags ?? 0).toString(16).padStart(2, '0')}`,
+                tracestate: sc.traceState?.serialize(),
+              }
+            : undefined;
+
+        return {
+          end: (endTime?: number) => span.end(endTime),
+          setError: (err: unknown) => {
+            if (err instanceof Error) {
+              span.recordException(err);
+            }
+            span.setStatus({ code: SpanStatusCode.ERROR, message: err instanceof Error ? err.message : String(err) });
+          },
+          spanContext,
+        };
       },
-    });
+    };
   }
 }