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

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

@@ -0,0 +1,139 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+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 {
+  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 { TRACE_ALL_KEY, type RemoteSpan, type StartSpanOptions, TRACE_PROCESSOR } from '@dxos/tracing';
+
+import { type OtelOptions } from './otel';
+import { TagInjectorSpanProcessor } from './span-processors';
+
+export class OtelTraces {
+  private _tracer: Tracer;
+  private readonly _tracerProvider: WebTracerProvider;
+
+  constructor(private readonly options: OtelOptions) {
+    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',
+            headers: this.options.headers,
+            concurrencyLimit: 10,
+          }),
+          { scheduledDelayMillis: 5_000 },
+        ),
+      ],
+    });
+
+    trace.setGlobalTracerProvider(this._tracerProvider);
+
+    this._tracer = trace.getTracer(
+      'dxos-observability',
+      this.options.resource.attributes[ATTR_SERVICE_VERSION]?.toString(),
+    );
+  }
+
+  /**
+   * 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({
+          '@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 },
+        }),
+      ],
+    });
+
+    const tracer = this._tracer;
+
+    TRACE_PROCESSOR.tracingBackend = {
+      startSpan: (options: StartSpanOptions): RemoteSpan => {
+        log('begin otel trace', { 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,
+        };
+      },
+    };
+  }
+}

package/src/extensions/otel/traces.ts

@@ -0,0 +1,113 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import {
+  ROOT_CONTEXT,
+  SpanStatusCode,
+  type Tracer,
+  context as otelContext,
+  propagation,
+  trace,
+} from '@opentelemetry/api';
+import { W3CTraceContextPropagator } from '@opentelemetry/core';
+import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
+import { BasicTracerProvider, BatchSpanProcessor } from '@opentelemetry/sdk-trace-base';
+import { ATTR_SERVICE_VERSION } from '@opentelemetry/semantic-conventions';
+
+import { log } from '@dxos/log';
+import { type RemoteSpan, type StartSpanOptions, TRACE_PROCESSOR } from '@dxos/tracing';
+
+import { type OtelOptions } from './otel';
+import { TagInjectorSpanProcessor } from './span-processors';
+
+export class OtelTraces {
+  private _tracer: Tracer;
+  private readonly _tracerProvider: BasicTracerProvider;
+
+  constructor(private readonly options: OtelOptions) {
+    propagation.setGlobalPropagator(new W3CTraceContextPropagator());
+
+    this._tracerProvider = new BasicTracerProvider({
+      resource: this.options.resource,
+      spanProcessors: [
+        new TagInjectorSpanProcessor(this.options.getTags),
+        new BatchSpanProcessor(
+          new OTLPTraceExporter({
+            url: this.options.endpoint + '/v1/traces',
+            headers: this.options.headers,
+            concurrencyLimit: 10,
+          }),
+        ),
+      ],
+    });
+
+    trace.setGlobalTracerProvider(this._tracerProvider);
+    this._tracer = trace.getTracer(
+      'dxos-observability',
+      this.options.resource.attributes[ATTR_SERVICE_VERSION]?.toString(),
+    );
+  }
+
+  /**
+   * Forcibly flush the BatchSpanProcessor. Call before process exit 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 `BasicTracerProvider.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');
+
+    const tracer = this._tracer;
+
+    TRACE_PROCESSOR.tracingBackend = {
+      startSpan: (options: StartSpanOptions): RemoteSpan => {
+        log('begin otel trace', { 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,
+        };
+      },
+    };
+  }
+}

package/src/extensions/posthog/extension.ts

@@ -0,0 +1,181 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+import { type PostHogConfig } from 'posthog-js';
+
+import { type Config } from '@dxos/config';
+import { log } from '@dxos/log';
+import { type IdbLogStore } from '@dxos/log-store-idb';
+
+import { type Extension } from '../../observability-extension';
+import { stubExtension } from '../stub';
+
+export type ExtensionsOptions = {
+  config: Config;
+  /** Release identifier, e.g. `composer@0.8.3`. */
+  release?: string;
+  /** Deployment environment, e.g. `production` or `staging`. */
+  environment?: string;
+  posthog?: Partial<PostHogConfig>;
+  /**
+   * Shared persistent log store for debug log dumps.
+   * The owning app is expected to register `logStore.processor` with `log` itself —
+   * this extension only consumes the buffered logs (via `export()`).
+   */
+  logStore?: IdbLogStore;
+};
+
+/** Upload serialized logs to the feedback-logs endpoint. Returns the R2 key on success. */
+const uploadLogs = async (body: string): Promise<string | undefined> => {
+  try {
+    const response = await fetch('/api/feedback-logs', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/x-ndjson' },
+      body,
+    });
+    if (!response.ok) {
+      log.warn('feedback log upload failed', { status: response.status });
+      return undefined;
+    }
+    const { key } = await response.json();
+    return key;
+  } catch (err) {
+    log.warn('feedback log upload error', { error: err });
+    return undefined;
+  }
+};
+
+/** Create a PostHog-backed observability extension for events, errors, and feedback. */
+export const extensions: (options: ExtensionsOptions) => Effect.Effect<Extension> = Effect.fn(function* ({
+  config,
+  release,
+  environment,
+  posthog: posthogConfig,
+  logStore,
+}) {
+  if (typeof window === 'undefined') {
+    log('PostHog is being stubbed because it is running in a worker.');
+    return stubExtension;
+  }
+
+  const feedbackSurveyId = config.get('runtime.app.env.DX_POSTHOG_FEEDBACK_SURVEY_ID');
+  const apiKey = config.get('runtime.app.env.DX_POSTHOG_API_KEY');
+  const api_host = config.get('runtime.app.env.DX_POSTHOG_API_HOST');
+  if (!apiKey || !api_host) {
+    log.info('Missing POSTHOG_API_KEY or POSTHOG_API_HOST');
+    return stubExtension;
+  }
+
+  const { default: posthog } = yield* Effect.promise(() => import('posthog-js'));
+  const { logProcessor } = yield* Effect.promise(() => import('./log-processor'));
+  let feedbackSurveyAvailable: boolean | null = null;
+  let unregisterPosthogProcessors: (() => void) | undefined;
+
+  const checkFeedbackSurveyAvailable = (): Effect.Effect<boolean> =>
+    feedbackSurveyId
+      ? Effect.promise(() => {
+          if (feedbackSurveyAvailable !== null) {
+            return Promise.resolve(feedbackSurveyAvailable);
+          }
+          return new Promise<boolean>((resolve) => {
+            posthog.getSurveys((surveys) => {
+              const found = surveys.some((s) => s.id === feedbackSurveyId);
+              feedbackSurveyAvailable = found;
+              resolve(found);
+            });
+          });
+        })
+      : Effect.succeed(false);
+
+  return {
+    initialize: () =>
+      Effect.sync(() => {
+        // https://posthog.com/docs/libraries/js/config
+        posthog.init(apiKey, {
+          api_host,
+          mask_all_text: true,
+          capture_exceptions: true,
+          ...posthogConfig,
+        });
+        if (release || environment) {
+          posthog.register({
+            ...(release ? { release } : {}),
+            ...(environment ? { environment } : {}),
+          });
+        }
+        unregisterPosthogProcessors?.();
+        const removePosthogLog = log.addProcessor(logProcessor);
+        unregisterPosthogProcessors = () => {
+          removePosthogLog();
+        };
+      }),
+    close: () =>
+      Effect.sync(() => {
+        unregisterPosthogProcessors?.();
+        unregisterPosthogProcessors = undefined;
+      }),
+    enable: () => Effect.sync(() => posthog.opt_in_capturing()),
+    disable: () => Effect.sync(() => posthog.opt_out_capturing()),
+    identify: (distinctId, attributes, setOnceAttributes) => {
+      posthog.identify(distinctId, attributes, setOnceAttributes);
+    },
+    alias: (distinctId, previousId) => {
+      posthog.alias(distinctId, previousId);
+    },
+    setTags: (tags) => {
+      posthog.register_for_session(tags);
+    },
+    get enabled(): boolean {
+      return posthog.is_capturing();
+    },
+    apis: [
+      {
+        kind: 'events',
+        isAvailable: () => Effect.succeed(true),
+        captureEvent: (event, attributes) => {
+          posthog.capture(event, attributes);
+        },
+      },
+      {
+        kind: 'errors',
+        isAvailable: () => Effect.succeed(true),
+        captureException: (error, attributes) => {
+          posthog.captureException(error, attributes);
+        },
+      },
+      {
+        kind: 'feedback',
+        // TODO(wittjosiah): Support custom surveys.
+        captureUserFeedback: (form) => {
+          posthog.getSurveys(async (surveys) => {
+            const survey = surveys.find((survey) => survey.id === feedbackSurveyId);
+            if (!survey || survey.questions.length === 0) {
+              log.error('Missing feedback survey or survey has no questions', { feedbackSurveyId });
+              return;
+            }
+
+            let debugLogDumpKey: string | null = null;
+            if (form.includeLogs !== false && logStore !== undefined) {
+              const ndjson = await logStore.export();
+              if (ndjson.length > 0) {
+                debugLogDumpKey = (await uploadLogs(ndjson)) ?? 'failed';
+              }
+            }
+
+            // https://posthog.com/docs/surveys/implementing-custom-surveys
+            const question = survey.questions[0];
+            posthog.capture('survey sent', {
+              $survey_id: survey.id,
+              $survey_questions: [{ id: question.id, question: question.question }],
+              [`$survey_response_${question.id}`]: form.message,
+              debug_log_dump_key: debugLogDumpKey,
+            });
+          });
+        },
+        isAvailable: checkFeedbackSurveyAvailable,
+      },
+    ],
+  };
+});

package/src/extensions/posthog/index.ts

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

package/src/extensions/posthog/log-processor.test.ts

@@ -0,0 +1,186 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { beforeEach, describe, expect, test, vi } from 'vitest';
+
+import { InvariantViolation } from '@dxos/invariant';
+import { type LogConfig, LogEntry, type LogEntryInit, LogLevel } from '@dxos/log';
+
+// Replace the posthog-js module with a stub so log-processor's top-level import resolves to our mock.
+// Dynamic imports are used so that both the mock and log-processor are loaded after vi.mock is hoisted.
+vi.mock('posthog-js', () => ({
+  default: {
+    captureException: vi.fn(),
+  },
+}));
+const { default: posthog } = await import('posthog-js');
+const { logProcessor } = await import('./log-processor');
+
+const baseConfig: LogConfig = {
+  options: {},
+  captureFilters: [{ level: LogLevel.WARN }],
+  processors: [],
+};
+
+const createEntry = (overrides: Partial<LogEntryInit> = {}): LogEntry =>
+  new LogEntry({
+    level: LogLevel.ERROR,
+    message: 'test error',
+    ...overrides,
+  });
+
+describe('logProcessor', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  test('skips entries that do not pass capture filters', () => {
+    const entry = createEntry({ level: LogLevel.DEBUG });
+    logProcessor(baseConfig, entry);
+    expect(posthog.captureException).not.toHaveBeenCalled();
+  });
+
+  test('skips entries from remote sessions', () => {
+    const entry = createEntry({
+      error: new Error('test'),
+      meta: { F: 'test.ts', L: 1, S: { remoteSessionId: 'remote-123' } },
+    });
+    logProcessor(baseConfig, entry);
+    expect(posthog.captureException).not.toHaveBeenCalled();
+  });
+
+  test('skips entries without errors', () => {
+    const entry = createEntry({ error: undefined, context: {} });
+    logProcessor(baseConfig, entry);
+    expect(posthog.captureException).not.toHaveBeenCalled();
+  });
+
+  test('captures error from entry.error', () => {
+    const error = new Error('direct error');
+    const entry = createEntry({
+      error,
+      meta: { F: 'packages/sdk/observability/src/test.ts', L: 42, S: undefined },
+    });
+    logProcessor(baseConfig, entry);
+    expect(posthog.captureException).toHaveBeenCalledWith(
+      error,
+      expect.objectContaining({
+        transaction: 'packages/sdk/observability/src/test.ts:42',
+      }),
+    );
+  });
+
+  test('captures error from context when level is ERROR but no entry.error', () => {
+    const contextError = new Error('context error');
+    const entry = createEntry({
+      level: LogLevel.ERROR,
+      error: undefined,
+      context: { someKey: contextError },
+      meta: { F: 'test.ts', L: 10, S: undefined },
+    });
+    logProcessor(baseConfig, entry);
+    expect(posthog.captureException).toHaveBeenCalledWith(contextError, expect.any(Object));
+  });
+
+  test('sets transaction from file:line metadata', () => {
+    const entry = createEntry({
+      error: new Error('err'),
+      meta: { F: '/home/user/project/packages/sdk/observability/src/index.ts', L: 99, S: undefined },
+    });
+    logProcessor(baseConfig, entry);
+    expect(posthog.captureException).toHaveBeenCalledWith(
+      expect.any(Error),
+      expect.objectContaining({
+        transaction: 'packages/sdk/observability/src/index.ts:99',
+      }),
+    );
+  });
+
+  test('sets service_host_issue/session for worker entries', () => {
+    const entry = createEntry({
+      error: new Error('worker err'),
+      meta: { F: 'test.ts', L: 1, S: { hostSessionId: 'host-abc' } },
+    });
+    logProcessor(baseConfig, entry);
+    expect(posthog.captureException).toHaveBeenCalledWith(
+      expect.any(Error),
+      expect.objectContaining({
+        service_host_issue: true,
+        service_host_session: 'host-abc',
+      }),
+    );
+  });
+
+  test('sets uptime_seconds from metadata', () => {
+    const entry = createEntry({
+      error: new Error('err'),
+      meta: { F: 'test.ts', L: 1, S: { uptimeSeconds: 123 } },
+    });
+    logProcessor(baseConfig, entry);
+    expect(posthog.captureException).toHaveBeenCalledWith(
+      expect.any(Error),
+      expect.objectContaining({
+        uptime_seconds: 123,
+      }),
+    );
+  });
+
+  test('sets invariant_violation flag for InvariantViolation errors', () => {
+    const error = new InvariantViolation('broken invariant');
+    const entry = createEntry({
+      error,
+      meta: { F: 'test.ts', L: 1, S: undefined },
+    });
+    logProcessor(baseConfig, entry);
+    expect(posthog.captureException).toHaveBeenCalledWith(
+      error,
+      expect.objectContaining({
+        invariant_violation: true,
+      }),
+    );
+  });
+
+  test('does not set invariant_violation for normal errors', () => {
+    const error = new Error('normal error');
+    const entry = createEntry({
+      error,
+      meta: { F: 'test.ts', L: 1, S: undefined },
+    });
+    logProcessor(baseConfig, entry);
+    const callArgs = vi.mocked(posthog.captureException).mock.calls[0];
+    expect(callArgs[1]).not.toHaveProperty('invariant_violation');
+  });
+});
+
+describe('getRelativeFilename', () => {
+  // We test this indirectly through the transaction property set by logProcessor.
+
+  test('extracts relative path from absolute path containing packages/', () => {
+    const entry = createEntry({
+      error: new Error('err'),
+      meta: { F: '/home/user/code/packages/sdk/observability/src/file.ts', L: 5, S: undefined },
+    });
+    logProcessor(baseConfig, entry);
+    expect(posthog.captureException).toHaveBeenCalledWith(
+      expect.any(Error),
+      expect.objectContaining({
+        transaction: 'packages/sdk/observability/src/file.ts:5',
+      }),
+    );
+  });
+
+  test('returns original filename if no match', () => {
+    const entry = createEntry({
+      error: new Error('err'),
+      meta: { F: 'no-packages-here.ts', L: 1, S: undefined },
+    });
+    logProcessor(baseConfig, entry);
+    expect(posthog.captureException).toHaveBeenCalledWith(
+      expect.any(Error),
+      expect.objectContaining({
+        transaction: 'no-packages-here.ts:1',
+      }),
+    );
+  });
+});

package/src/extensions/posthog/log-processor.ts

@@ -0,0 +1,43 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import posthog from 'posthog-js';
+
+import { InvariantViolation } from '@dxos/invariant';
+import { type LogConfig, type LogEntry, LogLevel, type LogProcessor, shouldLog } from '@dxos/log';
+
+export const logProcessor: LogProcessor = (config: LogConfig, entry: LogEntry) => {
+  // Don't forward logs from remote sessions.
+  if (!shouldLog(entry, config.captureFilters) || entry.meta?.S?.remoteSessionId) {
+    return;
+  }
+
+  let capturedError = entry.error;
+  if (capturedError == null && entry.level === LogLevel.ERROR) {
+    capturedError = Object.values(entry.context ?? {}).find((v): v is Error => v instanceof Error);
+  }
+
+  if (!capturedError) {
+    return;
+  }
+
+  const additionalProperties: Record<string, string | boolean | number> = {};
+  const { filename, line } = entry.computedMeta;
+  if (filename !== undefined && line !== undefined) {
+    additionalProperties.transaction = `${filename}:${line}`;
+  }
+  if (entry.meta?.S?.hostSessionId) {
+    additionalProperties.service_host_issue = true;
+    additionalProperties.service_host_session = entry.meta.S.hostSessionId;
+  }
+  if (entry.meta?.S?.uptimeSeconds != null) {
+    additionalProperties.uptime_seconds = entry.meta.S.uptimeSeconds;
+  }
+
+  if (capturedError instanceof InvariantViolation) {
+    additionalProperties.invariant_violation = true;
+  }
+
+  posthog.captureException(capturedError, additionalProperties);
+};

package/src/extensions/stub.ts

@@ -0,0 +1,19 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { type Extension } from '../observability-extension';
+
+export const stubExtension: Extension = {
+  initialize: () => Effect.succeed(undefined),
+  enable: () => Effect.succeed(undefined),
+  disable: () => Effect.succeed(undefined),
+  flush: () => Effect.succeed(undefined),
+  setTags: () => undefined,
+  get enabled() {
+    return true;
+  },
+  apis: [],
+};