@dxos/observability 0.8.3 → 0.8.4-main.05e74ebcff

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

package/src/index.ts

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

package/src/observability-extension.ts

@@ -0,0 +1,94 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import type * as Effect from 'effect/Effect';
+
+export * from './extensions';
+
+/**
+ * Kind of observability extension.
+ *
+ * - errors: Error tracking (e.g., PostHog)
+ * - events: Product usage event tracking (e.g., PostHog)
+ * - feedback: User feedback submission (e.g., PostHog)
+ * - logs: Structured logging (e.g., OTEL)
+ * - metrics: Metric data (e.g., OTEL)
+ * - traces: Distributed tracing (e.g., OTEL)
+ */
+export type Kind = 'errors' | 'events' | 'feedback' | 'logs' | 'metrics' | 'traces';
+
+/**
+ * Base for every extension API variant. All kinds implement availability the same way.
+ */
+export type ExtensionApiBase<K extends Kind = Kind> = {
+  kind: K;
+  isAvailable(): Effect.Effect<boolean>;
+};
+
+/**
+ * Metrics extension API (kind-specific methods only).
+ */
+export type Metrics = {
+  gauge(name: string, value: number, tags?: Attributes): void;
+  increment(name: string, value?: number, tags?: Attributes): void;
+  distribution(name: string, value: number, tags?: Attributes): void;
+};
+
+/**
+ * Errors extension API (kind-specific methods only).
+ */
+export type Errors = {
+  captureException(error: Error, attributes?: Attributes): void;
+};
+
+/**
+ * Events extension API (kind-specific methods only).
+ */
+export type Events = {
+  captureEvent(event: string, attributes?: Attributes): void;
+};
+
+/**
+ * Feedback extension API (kind-specific methods only).
+ */
+export type Feedback = {
+  captureUserFeedback(form: FeedbackForm): Promise<string | undefined>;
+};
+
+export type ExtensionApi =
+  | (ExtensionApiBase<'errors'> & Errors)
+  | (ExtensionApiBase<'events'> & Events)
+  | (ExtensionApiBase<'feedback'> & Feedback)
+  // TODO(wittjosiah): Direct logs api?
+  | ExtensionApiBase<'logs'>
+  | (ExtensionApiBase<'metrics'> & Metrics)
+  // TODO(wittjosiah): Direct traces api?
+  | ExtensionApiBase<'traces'>;
+
+/**
+ * Feedback form to be captured by the feedback extension.
+ */
+// TODO(wittjosiah): Support more form fields (e.g., PostHog custom surveys).
+export type FeedbackForm = { message: string; includeLogs?: boolean };
+
+/**
+ * Attributes to be attached to observability events.
+ */
+export type Attributes = Record<string, string | number | boolean | undefined>;
+
+/**
+ * Implementation of an observability extension API.
+ */
+export type Extension = {
+  initialize?(): Effect.Effect<void, Error>;
+  close?(): Effect.Effect<void>;
+  enable?(): Effect.Effect<void>;
+  disable?(): Effect.Effect<void>;
+  flush?(): Effect.Effect<void>;
+  identify?(distinctId: string, attributes?: Attributes, setOnceAttributes?: Attributes): void;
+  alias?(distinctId: string, previousId?: string): void;
+  setTags?(tags: Record<string, string>): void;
+  enabled: boolean;
+  apis: ExtensionApi[];
+};