@dxos/observability 0.8.4-main.84f28bd → 0.8.4-main.8baae0fced

package/src/extensions/otel/otel.ts

@@ -0,0 +1,34 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { DiagConsoleLogger, DiagLogLevel, diag } from '@opentelemetry/api';
+import { type Resource } from '@opentelemetry/resources';
+
+export type OtelOptions = {
+  endpoint: string;
+  headers: Record<string, string>;
+  resource: Resource;
+  getTags: () => { [key: string]: string };
+  consoleDiagLogLevel?: string;
+};
+
+export const setDiagLogger = (level?: string) => {
+  const logLevel = DiagLogLevel[level as keyof typeof DiagLogLevel];
+  if (logLevel) {
+    diag.setLogger(new DiagConsoleLogger(), logLevel);
+  }
+};
+
+/**
+ * Resolve a possibly-relative OTLP exporter URL to an absolute URL.
+ * The OpenTelemetry browser HTTP exporter validates user-provided URLs with `new URL(url)`,
+ * which throws on relative paths like `/api/otel/v1/logs`. In a browser context we resolve
+ * against `window.location.origin`; outside the browser we return the input unchanged.
+ */
+export const resolveOtlpUrl = (url: string): string => {
+  if (typeof window !== 'undefined' && url.startsWith('/')) {
+    return new URL(url, window.location.origin).toString();
+  }
+  return url;
+};

package/src/extensions/otel/span-processors.ts

@@ -0,0 +1,45 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type Context } from '@opentelemetry/api';
+import { type ReadableSpan, type Span, type SpanProcessor } from '@opentelemetry/sdk-trace-base';
+
+import { log } from '@dxos/log';
+
+/**
+ * Injects dynamic tags as attributes on every span.
+ *
+ * This is an `onStart`-only processor; `onEnd`/`shutdown`/`forceFlush` are no-ops
+ * because this processor never holds pending work (delegates export to downstream
+ * processors like BatchSpanProcessor).
+ *
+ * Use for tags that are not known at provider construction (e.g. identity
+ * resolved asynchronously after login). For values known at startup, prefer
+ * putting them on the `Resource` — see `extension.ts`.
+ *
+ * Failures in the tag provider are swallowed so they can never break span
+ * recording (the processor is best-effort and runs on the startSpan hot path).
+ */
+export class TagInjectorSpanProcessor implements SpanProcessor {
+  constructor(private readonly _getTags: () => Record<string, string>) {}
+
+  onStart(span: Span, _parentContext: Context): void {
+    let tags: Record<string, string>;
+    try {
+      tags = this._getTags();
+    } catch (err) {
+      log.catch(err);
+      return;
+    }
+    for (const [key, value] of Object.entries(tags)) {
+      span.setAttribute(key, value);
+    }
+  }
+
+  onEnd(_span: ReadableSpan): void {}
+
+  async shutdown(): Promise<void> {}
+
+  async forceFlush(): Promise<void> {}
+}

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, resolveOtlpUrl } 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: resolveOtlpUrl(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, resolveOtlpUrl } 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: resolveOtlpUrl(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,199 @@
+//
+// 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;
+  /**
+   * Maximum byte size passed to `logStore.export()` when uploading feedback logs.
+   * Should match the upload limit enforced by the server receiving the logs.
+   * When omitted the full store is exported without trimming.
+   */
+  feedbackLogMaxSize?: number;
+};
+
+/** 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,
+  feedbackLogMaxSize,
+}) {
+  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) => {
+          return new Promise<string | undefined>((resolve, reject) => {
+            posthog.getSurveys((surveys) => {
+              void (async () => {
+                try {
+                  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 });
+                    resolve(undefined);
+                    return;
+                  }
+
+                  let debugLogDumpKey: string | null = null;
+                  if (form.includeLogs !== false && logStore !== undefined) {
+                    const ndjson = await logStore.export({ maxSize: feedbackLogMaxSize });
+                    if (ndjson.length > 0) {
+                      debugLogDumpKey = (await uploadLogs(ndjson)) ?? 'failed';
+                    }
+                  }
+
+                  // https://posthog.com/docs/surveys/implementing-custom-surveys
+                  const question = survey.questions[0];
+                  const result = 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,
+                  });
+                  resolve(result?.uuid);
+                } catch (err) {
+                  log.error('Failed to capture user feedback', { err });
+                  reject(err);
+                }
+              })();
+            });
+          });
+        },
+        isAvailable: checkFeedbackSurveyAvailable,
+      },
+    ],
+  };
+});

package/src/extensions/posthog/index.ts

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