@dxos/observability 0.8.3 → 0.8.4-main.1068cf700f

package/src/extensions/posthog/extension.ts

@@ -0,0 +1,172 @@
+//
+// 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 { LogBuffer } from '../../log-buffer';
+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>;
+};
+
+/** 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,
+}) {
+  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'));
+  const logBuffer = new LogBuffer();
+  let feedbackSurveyAvailable: boolean | null = null;
+
+  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 } : {}),
+          });
+        }
+        log.runtimeConfig.processors.push(logProcessor);
+        log.runtimeConfig.processors.push(logBuffer.logProcessor);
+      }),
+    close: () =>
+      Effect.sync(() => {
+        for (const processor of [logProcessor, logBuffer.logProcessor]) {
+          const index = log.runtimeConfig.processors.indexOf(processor);
+          if (index !== -1) {
+            log.runtimeConfig.processors.splice(index, 1);
+          }
+        }
+      }),
+    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 | undefined;
+            if (form.includeLogs !== false && logBuffer.size > 0) {
+              debugLogDumpKey = await uploadLogs(logBuffer.serialize());
+            }
+
+            // 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,
+              ...(debugLogDumpKey ? { 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,185 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { beforeEach, describe, expect, test, vi } from 'vitest';
+
+import { InvariantViolation } from '@dxos/invariant';
+import { type LogConfig, type LogEntry, 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<LogEntry> = {}): 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,54 @@
+//
+// 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> = {};
+  if (entry.meta) {
+    additionalProperties.transaction = `${getRelativeFilename(entry.meta.F)}:${entry.meta.L}`;
+    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);
+};
+
+const getRelativeFilename = (filename: string) => {
+  // TODO(burdon): Hack uses "packages" as an anchor (pre-parse NX?)
+  // Including `packages/` part of the path so that excluded paths (e.g. from dist) are clickable in vscode.
+  const match = filename.match(/.+\/(packages\/.+\/.+)/);
+  if (match) {
+    const [, filePath] = match;
+    return filePath;
+  }
+
+  return filename;
+};

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: [],
+};

package/src/index.ts

@@ -1,6 +1,8 @@
 //
-// Copyright 2023 DXOS.org
+// Copyright 2025 DXOS.org
 //
 
-export * from './helpers';
-export * from './observability';
+export * from './log-buffer';
+export * as Observability from './observability';
+export * as ObservabilityExtension from './observability-extension';
+export * as ObservabilityProvider from './providers';

package/src/log-buffer.test.ts

@@ -0,0 +1,134 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { describe, test } from 'vitest';
+
+import { type LogConfig, type LogEntry, LogLevel } from '@dxos/log';
+
+import { LogBuffer } from './log-buffer';
+
+const baseConfig: LogConfig = {
+  options: {},
+  filters: [{ level: LogLevel.DEBUG }],
+  processors: [],
+};
+
+const createEntry = (overrides: Partial<LogEntry> = {}): LogEntry => ({
+  level: LogLevel.INFO,
+  message: 'test message',
+  ...overrides,
+});
+
+describe('LogBuffer', () => {
+  test('pushes and serializes log entries', ({ expect }) => {
+    const buffer = new LogBuffer(10);
+    buffer.logProcessor(baseConfig, createEntry({ message: 'hello' }));
+    buffer.logProcessor(baseConfig, createEntry({ message: 'world' }));
+
+    expect(buffer.size).toBe(2);
+    const lines = buffer.serialize().split('\n');
+    expect(lines).toHaveLength(2);
+
+    const first = JSON.parse(lines[0]);
+    expect(first.m).toBe('hello');
+    expect(first.l).toBe('I');
+    expect(first.t).toBeDefined();
+
+    const second = JSON.parse(lines[1]);
+    expect(second.m).toBe('world');
+  });
+
+  test('evicts oldest entries when buffer is full', ({ expect }) => {
+    const buffer = new LogBuffer(3);
+    buffer.logProcessor(baseConfig, createEntry({ message: 'a' }));
+    buffer.logProcessor(baseConfig, createEntry({ message: 'b' }));
+    buffer.logProcessor(baseConfig, createEntry({ message: 'c' }));
+    buffer.logProcessor(baseConfig, createEntry({ message: 'd' }));
+
+    expect(buffer.size).toBe(3);
+    const lines = buffer.serialize().split('\n');
+    const messages = lines.map((l) => JSON.parse(l).m);
+    expect(messages).toEqual(['b', 'c', 'd']);
+  });
+
+  test('skips TRACE-level logs', ({ expect }) => {
+    const buffer = new LogBuffer(10);
+    buffer.logProcessor(baseConfig, createEntry({ level: LogLevel.TRACE, message: 'trace' }));
+    expect(buffer.size).toBe(0);
+  });
+
+  test('captures DEBUG-level and above', ({ expect }) => {
+    const buffer = new LogBuffer(10);
+    buffer.logProcessor(baseConfig, createEntry({ level: LogLevel.DEBUG, message: 'debug' }));
+    buffer.logProcessor(baseConfig, createEntry({ level: LogLevel.WARN, message: 'warn' }));
+    buffer.logProcessor(baseConfig, createEntry({ level: LogLevel.ERROR, message: 'error' }));
+
+    expect(buffer.size).toBe(3);
+    const lines = buffer.serialize().split('\n');
+    expect(JSON.parse(lines[0]).l).toBe('D');
+    expect(JSON.parse(lines[1]).l).toBe('W');
+    expect(JSON.parse(lines[2]).l).toBe('E');
+  });
+
+  test('captures file and line metadata', ({ expect }) => {
+    const buffer = new LogBuffer(10);
+    buffer.logProcessor(
+      baseConfig,
+      createEntry({
+        meta: { F: '/home/user/project/packages/sdk/test.ts', L: 42, S: undefined },
+      }),
+    );
+
+    const lines = buffer.serialize().split('\n');
+    const record = JSON.parse(lines[0]);
+    expect(record.f).toBe('packages/sdk/test.ts');
+    expect(record.n).toBe(42);
+  });
+
+  test('captures error stack', ({ expect }) => {
+    const buffer = new LogBuffer(10);
+    const error = new Error('boom');
+    buffer.logProcessor(baseConfig, createEntry({ error }));
+
+    const lines = buffer.serialize().split('\n');
+    const record = JSON.parse(lines[0]);
+    expect(record.e).toContain('boom');
+  });
+
+  test('truncates context to 500 chars', ({ expect }) => {
+    const buffer = new LogBuffer(10);
+    const longValue = 'x'.repeat(1000);
+    buffer.logProcessor(baseConfig, createEntry({ context: { data: longValue } }));
+
+    const lines = buffer.serialize().split('\n');
+    const record = JSON.parse(lines[0]);
+    expect(record.c).toBeDefined();
+    expect(record.c!.length).toBe(500);
+  });
+
+  test('skips Error context objects', ({ expect }) => {
+    const buffer = new LogBuffer(10);
+    buffer.logProcessor(baseConfig, createEntry({ context: new Error('ctx error') }));
+
+    const lines = buffer.serialize().split('\n');
+    const record = JSON.parse(lines[0]);
+    expect(record.c).toBeUndefined();
+  });
+
+  test('handles non-serializable context gracefully', ({ expect }) => {
+    const buffer = new LogBuffer(10);
+    const circular: Record<string, any> = {};
+    circular.self = circular;
+    buffer.logProcessor(baseConfig, createEntry({ context: circular }));
+
+    const lines = buffer.serialize().split('\n');
+    const record = JSON.parse(lines[0]);
+    expect(record.c).toBeUndefined();
+  });
+
+  test('serialize returns empty string for empty buffer', ({ expect }) => {
+    const buffer = new LogBuffer(10);
+    expect(buffer.serialize()).toBe('');
+  });
+});

package/src/log-buffer.ts

@@ -0,0 +1,101 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type LogConfig, type LogEntry, LogLevel, type LogProcessor, shortLevelName } from '@dxos/log';
+import { CircularBuffer } from '@dxos/util';
+
+const DEFAULT_BUFFER_SIZE = 2_000;
+const MAX_CONTEXT_LENGTH = 500;
+
+/**
+ * Compact log record with short property names for small serialized size.
+ */
+export type LogRecord = {
+  /** ISO timestamp. */
+  t: string;
+  /** Level letter (D, V, I, W, E). */
+  l: string;
+  /** Message. */
+  m: string;
+  /** File path. */
+  f?: string;
+  /** Line number. */
+  n?: number;
+  /** Error stack. */
+  e?: string;
+  /** Context JSON. */
+  c?: string;
+};
+
+/**
+ * Captures recent log entries in a circular buffer for debug log dump on feedback submission.
+ */
+export class LogBuffer {
+  private readonly _buffer: CircularBuffer<LogRecord>;
+
+  constructor(size = DEFAULT_BUFFER_SIZE) {
+    this._buffer = new CircularBuffer<LogRecord>(size);
+  }
+
+  /** Log processor that can be registered with `log.runtimeConfig.processors`. */
+  readonly logProcessor: LogProcessor = (_config: LogConfig, entry: LogEntry) => {
+    if (entry.level <= LogLevel.TRACE) {
+      return;
+    }
+
+    const record: LogRecord = {
+      t: new Date().toISOString(),
+      l: shortLevelName[entry.level] ?? '?',
+      m: entry.message ?? '',
+    };
+
+    if (entry.meta) {
+      record.f = getRelativeFilename(entry.meta.F);
+      record.n = entry.meta.L;
+    }
+
+    if (entry.error) {
+      record.e = entry.error.stack ?? entry.error.message;
+    }
+
+    if (entry.context != null) {
+      try {
+        const ctx = typeof entry.context === 'function' ? entry.context() : entry.context;
+        if (ctx != null && !(ctx instanceof Error)) {
+          let json = JSON.stringify(ctx);
+          if (json.length > MAX_CONTEXT_LENGTH) {
+            json = json.slice(0, MAX_CONTEXT_LENGTH);
+          }
+          record.c = json;
+        }
+      } catch {
+        // Skip context that throws or is non-serializable.
+      }
+    }
+
+    this._buffer.push(record);
+  };
+
+  /** Number of entries currently in the buffer. */
+  get size(): number {
+    return this._buffer.elementCount;
+  }
+
+  /** Serialize buffer contents as NDJSON (newline-delimited JSON). */
+  serialize(): string {
+    const lines: string[] = [];
+    for (const record of this._buffer) {
+      lines.push(JSON.stringify(record));
+    }
+    return lines.join('\n');
+  }
+}
+
+const getRelativeFilename = (filename: string): string => {
+  const match = filename.match(/.+\/(packages\/.+\/.+)/);
+  if (match) {
+    return match[1];
+  }
+  return filename;
+};