@dxos/observability 0.8.4-main.bc674ce → 0.8.4-main.bcb3aa67d6

package/src/extensions/posthog/extension.ts

@@ -0,0 +1,174 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+import { type PostHogConfig } from 'posthog-js';
+
+import { type Config } from '@dxos/config';
+import { LogBuffer, log } from '@dxos/log';
+
+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 log buffer for debug log dumps. Creates a local one if not provided. */
+  logBuffer?: LogBuffer;
+};
+
+/** 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,
+  logBuffer: externalLogBuffer,
+}) {
+  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 = externalLogBuffer ?? 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 | null = null;
+            if (form.includeLogs !== false && logBuffer.size > 0) {
+              debugLogDumpKey = (await uploadLogs(logBuffer.serialize())) ?? '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,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,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): void;
+};
+
+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[];
+};