@dxos/observability 0.8.4-main.fffef41 → 0.9.0

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

@@ -0,0 +1,53 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import posthog from 'posthog-js';
+
+import { InvariantViolation } from '@dxos/invariant';
+import { type LogConfig, type LogEntry, LogLevel, type LogProcessor, getContextFromEntry, 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;
+  }
+
+  // Forward primitive context values so callers can attach queryable attributes (e.g. fatal_dialog: true).
+  const context = getContextFromEntry(entry);
+  if (context) {
+    for (const [key, value] of Object.entries(context)) {
+      if (typeof value === 'string' || typeof value === 'boolean' || typeof value === 'number') {
+        additionalProperties[key] = value;
+      }
+    }
+  }
+
+  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[];
+};