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

package/src/otel/traces-browser.ts

@@ -1,59 +0,0 @@
-//
-// Copyright 2024 DXOS.org
-//
-
-import { trace, type Tracer } from '@opentelemetry/api';
-import { getWebAutoInstrumentations } from '@opentelemetry/auto-instrumentations-web';
-import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
-import { registerInstrumentations } from '@opentelemetry/instrumentation';
-import { Resource } from '@opentelemetry/resources';
-import { ConsoleSpanExporter, SimpleSpanProcessor, BatchSpanProcessor } from '@opentelemetry/sdk-trace-base';
-import { WebTracerProvider } from '@opentelemetry/sdk-trace-web';
-import { SEMRESATTRS_SERVICE_NAME, SEMRESATTRS_SERVICE_VERSION } from '@opentelemetry/semantic-conventions';
-
-import { log } from '@dxos/log';
-import { TRACE_PROCESSOR, type StartSpanOptions } from '@dxos/tracing';
-
-import { type OtelOptions } from './otel';
-
-export class OtelTraces {
-  private _tracer: Tracer;
-  constructor(private readonly options: OtelOptions) {
-    const resource = Resource.default().merge(
-      new Resource({
-        [SEMRESATTRS_SERVICE_NAME]: this.options.serviceName,
-        [SEMRESATTRS_SERVICE_VERSION]: this.options.serviceVersion,
-      }),
-    );
-
-    const tracerProvider = new WebTracerProvider({ resource });
-    tracerProvider.addSpanProcessor(new SimpleSpanProcessor(new ConsoleSpanExporter()));
-    tracerProvider.addSpanProcessor(
-      new BatchSpanProcessor(
-        new OTLPTraceExporter({
-          url: this.options.endpoint + '/v1/traces',
-          headers: {
-            Authorization: this.options.authorizationHeader,
-          },
-          concurrencyLimit: 10, // an optional limit on pending requests
-        }),
-      ),
-    );
-    // TODO(nf): ContextManager? Propogator?
-    tracerProvider.register({});
-    this._tracer = trace.getTracer('dxos-observability', this.options.serviceVersion);
-  }
-
-  public start(): void {
-    registerInstrumentations({
-      instrumentations: [getWebAutoInstrumentations()],
-    });
-    log('trace processor registered');
-    TRACE_PROCESSOR.remoteTracing.registerProcessor({
-      startSpan: (options: StartSpanOptions) => {
-        log('begin otel trace', { options });
-        return this._tracer.startSpan(options.name, options);
-      },
-    });
-  }
-}

package/src/otel/traces.ts

@@ -1,57 +0,0 @@
-//
-// Copyright 2024 DXOS.org
-//
-
-import { trace, type Tracer } from '@opentelemetry/api';
-import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
-import { Resource } from '@opentelemetry/resources';
-import {
-  BasicTracerProvider,
-  BatchSpanProcessor,
-  ConsoleSpanExporter,
-  SimpleSpanProcessor,
-} from '@opentelemetry/sdk-trace-base';
-import { SEMRESATTRS_SERVICE_NAME, SEMRESATTRS_SERVICE_VERSION } from '@opentelemetry/semantic-conventions';
-import { log } from 'debug';
-
-import { TRACE_PROCESSOR, type StartSpanOptions } from '@dxos/tracing';
-
-import { type OtelOptions } from './otel';
-
-export class OtelTraces {
-  private _tracer: Tracer;
-  constructor(private readonly options: OtelOptions) {
-    const resource = Resource.default().merge(
-      new Resource({
-        [SEMRESATTRS_SERVICE_NAME]: this.options.serviceName,
-        [SEMRESATTRS_SERVICE_VERSION]: this.options.serviceVersion,
-      }),
-    );
-
-    const tracerProvider = new BasicTracerProvider({ resource });
-    tracerProvider.addSpanProcessor(new SimpleSpanProcessor(new ConsoleSpanExporter()));
-    tracerProvider.addSpanProcessor(
-      new BatchSpanProcessor(
-        new OTLPTraceExporter({
-          url: this.options.endpoint + '/v1/traces',
-          headers: {
-            Authorization: this.options.authorizationHeader,
-          },
-          concurrencyLimit: 10, // an optional limit on pending requests
-        }),
-      ),
-    );
-    tracerProvider.register();
-    this._tracer = trace.getTracer('dxos-observability', this.options.serviceVersion);
-  }
-
-  public start(): void {
-    log('trace processor registered');
-    TRACE_PROCESSOR.remoteTracing.registerProcessor({
-      startSpan: (options: StartSpanOptions) => {
-        log('begin otel trace', { options });
-        return this._tracer.startSpan(options.name, options);
-      },
-    });
-  }
-}

package/src/segment/base.ts

@@ -1,69 +0,0 @@
-//
-// Copyright 2025 DXOS.org
-//
-
-import { type TrackParams, type PageParams, type IdentifyParams } from '@segment/analytics-node';
-
-import { log } from '@dxos/log';
-
-import {
-  type IdentityOptions,
-  type PageOptions,
-  type SegmentIdentityOptions,
-  type Tags,
-  TelemetryEvent,
-  type TrackOptions,
-} from './types';
-
-/**
- * NOTE: Segment provides a default ID if we don't provide one.
- */
-const getIdentityOptions = ({ did, installationId }: IdentityOptions): SegmentIdentityOptions => {
-  if (!did && !installationId) {
-    log.warn('No telemetry identifier provided.');
-  }
-
-  return {
-    userId: did,
-    anonymousId: installationId,
-  } as SegmentIdentityOptions;
-};
-
-/**
- * Base class for Node and BrowserSegment telemetry.
- */
-export abstract class AbstractSegmentTelemetry {
-  constructor(private readonly _getTags: () => Tags) {}
-
-  abstract identify(options: IdentifyParams): void;
-
-  abstract page(options: PageOptions): void;
-
-  abstract track(options: TrackOptions): void;
-
-  protected createPageProps(options: PageOptions): PageParams {
-    const { properties, ...rest } = options;
-    return {
-      ...getIdentityOptions(options),
-      ...rest,
-      properties: {
-        common: this._getTags(),
-        custom: properties,
-      },
-    };
-  }
-
-  protected createTrackProps(options: TrackOptions): TrackParams {
-    const { event, action, properties, ...rest } = options;
-    return {
-      ...getIdentityOptions(options),
-      ...rest,
-      event: event ?? TelemetryEvent.ACTION,
-      properties: {
-        action,
-        common: this._getTags(),
-        custom: properties,
-      },
-    };
-  }
-}

package/src/segment/browser.ts

@@ -1,68 +0,0 @@
-//
-// Copyright 2022 DXOS.org
-//
-
-import { type IdentifyParams } from '@segment/analytics-node';
-import snippet from '@segment/snippet';
-
-import { log } from '@dxos/log';
-
-import { AbstractSegmentTelemetry } from './base';
-import type { TrackOptions, SegmentTelemetryOptions, PageOptions } from './types';
-import { captureException } from '../sentry';
-
-/**
- * Browser telemetry.
- */
-// https://segment.com/docs/connections/sources/catalog/libraries/website/javascript/#basic-tracking-methods
-export class SegmentTelemetry extends AbstractSegmentTelemetry {
-  constructor({ apiKey, batchSize, getTags }: SegmentTelemetryOptions) {
-    super(getTags);
-    try {
-      const contents = snippet.min({ apiKey, page: false });
-      const script = document.createElement('script');
-      script.innerHTML = contents;
-      document.body.append(script);
-    } catch (err) {
-      log.catch('failed to initialize telemetry', err);
-    }
-  }
-
-  identify(options: IdentifyParams): void {
-    try {
-      (window as any).analytics?.identify(options.userId, options.traits);
-    } catch (err) {
-      log.catch('failed to identify', err);
-    }
-  }
-
-  page(options: PageOptions): void {
-    try {
-      const props = this.createPageProps(options);
-      (window as any).analytics?.page(props.category, props.name, props.properties);
-    } catch (err) {
-      log.catch('failed to track page', err);
-    }
-  }
-
-  track(options: TrackOptions): void {
-    try {
-      const props = this.createTrackProps(options);
-      (window as any).analytics?.track(props.event, props.properties);
-    } catch (err) {
-      log.catch('failed to track event', err);
-    }
-  }
-
-  async flush(): Promise<void> {
-    try {
-      await (window as any).analytics?.flush((err: any) => {
-        captureException(err);
-      });
-    } catch (err) {
-      log.catch('failed to flush telemetry', err);
-    }
-  }
-
-  async close(): Promise<void> {}
-}

package/src/segment/node.ts

@@ -1,94 +0,0 @@
-//
-// Copyright 2022 DXOS.org
-//
-
-import { Analytics, type IdentifyParams } from '@segment/analytics-node';
-
-import { invariant } from '@dxos/invariant';
-import { log } from '@dxos/log';
-
-import { AbstractSegmentTelemetry } from './base';
-import type { SegmentTelemetryOptions, PageOptions, TrackOptions } from './types';
-import { captureException } from '../sentry';
-
-/**
- * Node telemetry.
- */
-export class SegmentTelemetry extends AbstractSegmentTelemetry {
-  private _analytics?: Analytics;
-
-  constructor({ apiKey, batchSize, getTags }: SegmentTelemetryOptions) {
-    super(getTags);
-    try {
-      invariant(apiKey, 'Missing API key.');
-      this._analytics = new Analytics({
-        writeKey: apiKey,
-        flushAt: batchSize,
-      });
-    } catch (err) {
-      log.catch('Failed to initialize telemetry', err);
-    }
-  }
-
-  identify(options: IdentifyParams): void {
-    if (!this._analytics) {
-      log('Analytics not initialized', { action: 'identify' });
-      return;
-    }
-
-    try {
-      this._analytics.identify(options);
-    } catch (err) {
-      log.catch('Failed to identify', err);
-    }
-  }
-
-  page(options: PageOptions): void {
-    if (!this._analytics) {
-      log('Analytics not initialized', { action: 'page' });
-      return;
-    }
-
-    try {
-      this._analytics.page(this.createPageProps(options));
-    } catch (err) {
-      log.catch('Failed to track page', err);
-    }
-  }
-
-  track(options: TrackOptions): void {
-    if (!this._analytics) {
-      log('Analytics not initialized', { action: 'track' });
-      return;
-    }
-
-    log.info('sending event to telemetry', { options });
-    try {
-      this._analytics.track(this.createTrackProps(options));
-    } catch (err) {
-      log.catch('Failed to track action', err);
-    }
-  }
-
-  async flush(): Promise<void> {
-    if (!this._analytics) {
-      log('Analytics not initialized', { action: 'flush' });
-      return;
-    }
-
-    try {
-      await this._analytics.flush();
-    } catch (err) {
-      // are these errors worth capturing?
-      captureException(err);
-    }
-  }
-
-  async close(): Promise<void> {
-    if (!this._analytics) {
-      return;
-    }
-
-    await this._analytics.closeAndFlush();
-  }
-}

package/src/segment/types.ts

@@ -1,57 +0,0 @@
-//
-// Copyright 2022 DXOS.org
-//
-
-export type Tags = Record<string, string>;
-
-export type SegmentTelemetryOptions = {
-  apiKey?: string;
-  batchSize?: number;
-  enable?: boolean;
-  getTags: () => Tags;
-};
-
-// Copied from @segment/analytics-node.
-export type SegmentIdentityOptions =
-  | { userId: string; anonymousId?: string }
-  | { userId?: string; anonymousId: string };
-
-// TODO(burdon): Should require one or the other.
-export type IdentityOptions = { did?: string; installationId?: string };
-
-export type CommonOptions = IdentityOptions & {
-  timestamp?: Date;
-  properties?: Record<string, unknown>;
-};
-
-/**
- * Page views.
- * https://segment.com/docs/connections/sources/catalog/libraries/server/node/#page
- */
-export type PageOptions = CommonOptions & {
-  category?: string;
-  name?: string;
-};
-
-/**
- * Track actions.
- * https://segment.com/docs/connections/sources/catalog/libraries/server/node/#track
- */
-export type TrackOptions = CommonOptions & {
-  event?: TelemetryEvent;
-  action: string;
-};
-
-/**
- * Each event will be mapped to a different Postgres table via segment.
- */
-export enum TelemetryEvent {
-  /**
-   * Use actions.
-   */
-  ACTION = 'action',
-  /**
-   * High-volume technical metrics.
-   */
-  METRICS = 'metrics',
-}

package/src/sentry/browser.ts

@@ -1,133 +0,0 @@
-//
-// Copyright 2022 DXOS.org
-//
-
-import {
-  init as naturalInit,
-  setTag,
-  addBreadcrumb as naturalAddBreadcrumb,
-  captureException as naturalCaptureException,
-  captureMessage as naturalCaptureMessage,
-  sendFeedback as naturalSendFeedback,
-  withScope as naturalWithScope,
-  breadcrumbsIntegration,
-  browserTracingIntegration,
-  feedbackIntegration,
-  httpClientIntegration,
-  replayIntegration,
-  metrics,
-  startInactiveSpan,
-} from '@sentry/browser';
-
-import { log } from '@dxos/log';
-import { TRACE_PROCESSOR } from '@dxos/tracing';
-
-import { type InitOptions } from './types';
-
-// Polyfill export.
-export { setTag, setTags, setUser } from '@sentry/browser';
-
-/**
- * To use this SDK, call the init function as early as possible when loading the web page.
- * To set context information or send manual events, use the provided methods.
- *
- * @param options {InitOptions}
- */
-export const init = (options: InitOptions) => {
-  try {
-    log('sentry init', options);
-    naturalInit({
-      enabled: options.enable ?? true,
-      dsn: options.destination,
-      release: options.release,
-      environment: options.environment,
-      integrations: [
-        breadcrumbsIntegration({ console: false, fetch: false }),
-        httpClientIntegration({
-          failedRequestStatusCodes: [
-            // 401 errors are omitted as they happen as a part of the EDGE authentication flow.
-            [400, 400],
-            [402, 599],
-          ],
-        }),
-        feedbackIntegration({ autoInject: false }),
-        ...(options.tracing ? [browserTracingIntegration()] : []),
-        ...(options.replay ? [replayIntegration({ blockAllMedia: true, maskAllText: true })] : []),
-      ],
-      replaysSessionSampleRate: options.replaySampleRate,
-      replaysOnErrorSampleRate: options.replaySampleRateOnError,
-      tracesSampleRate: options.sampleRate,
-      transport: options.transport,
-      beforeSend: (event) => {
-        options.onError?.(event);
-        return event;
-      },
-    });
-
-    if (options.tracing) {
-      TRACE_PROCESSOR.remoteMetrics.registerProcessor(metrics);
-      TRACE_PROCESSOR.remoteTracing.registerProcessor({
-        startSpan: startInactiveSpan,
-      });
-    }
-
-    Object.entries(options.properties ?? {}).forEach(([key, value]) => {
-      setTag(key, value);
-    });
-  } catch (err) {
-    log.catch('Failed to initialize sentry', err);
-  }
-};
-
-/**
- * Records a new breadcrumb which will be attached to future events.
- *
- * Breadcrumbs will be added to subsequent events to provide more context on user's actions prior to an error or crash.
- *
- * https://docs.sentry.io/platforms/javascript/enriching-events/breadcrumbs/
- *
- * @param breadcrumb — The breadcrumb to record.
- */
-export const addBreadcrumb: typeof naturalAddBreadcrumb = (breadcrumb) => {
-  try {
-    naturalAddBreadcrumb(breadcrumb);
-    log('add breadcrumb', breadcrumb);
-  } catch (err) {
-    log.catch('Failed to add breadcrumb', err);
-  }
-};
-
-/**
- * Captures an exception event and sends it to Sentry.
- *
- * @param exception — An exception-like object.
- * @param captureContext — Additional scope data to apply to exception event.
- * @returns — The generated eventId.
- */
-export const captureException: typeof naturalCaptureException = (exception, captureContext) => {
-  try {
-    const eventId = naturalCaptureException(exception, captureContext);
-    log('capture exception', { exception, eventId, ...captureContext });
-    return eventId;
-  } catch (err) {
-    log.catch('Failed to capture exception', err);
-    return 'unknown';
-  }
-};
-
-export const captureMessage: typeof naturalCaptureMessage = (exception, captureContext) => {
-  try {
-    const eventId = naturalCaptureMessage(exception, captureContext);
-    log('capture message', { exception, eventId, captureContext });
-    return eventId;
-  } catch (err) {
-    log.catch('Failed to capture message', err);
-    return 'unknown';
-  }
-};
-
-export const captureUserFeedback = (message: string) => {
-  return naturalSendFeedback({ message }, { includeReplay: true });
-};
-
-export const withScope = naturalWithScope;

package/src/sentry/node.node.test.ts

@@ -1,39 +0,0 @@
-//
-// Copyright 2022 DXOS.org
-//
-
-import type { Stacktrace } from '@sentry/types';
-import { beforeAll, beforeEach, describe, expect, test } from 'vitest';
-
-import * as Sentry from './node';
-import { sentryTestkit } from '../testing';
-
-const { testkit, sentryTransport } = sentryTestkit();
-
-// TODO(burdon): https://example.com?
-const MOCK_DESTINATION = 'https://acacaeaccacacacabcaacdacdacadaca@sentry.io/000001';
-
-describe('Node error reporting', () => {
-  beforeAll(() => {
-    Sentry.init({
-      destination: MOCK_DESTINATION,
-      release: 'test',
-      transport: sentryTransport,
-      scrubFilenames: true,
-    });
-  });
-
-  beforeEach(() => {
-    testkit.reset();
-  });
-
-  test('should scrub stacktraces', async () => {
-    const err = new Error('error to look for');
-    Sentry.captureException(err);
-    await expect.poll(() => testkit.reports()).toHaveLength(1);
-    const report = testkit.findReport(err);
-    (report?.error?.stacktrace as Stacktrace).frames?.forEach((frame) => {
-      expect(frame.filename?.includes('/')).to.be.false;
-    });
-  });
-});

package/src/sentry/node.ts

@@ -1,126 +0,0 @@
-//
-// Copyright 2022 DXOS.org
-//
-
-import {
-  type Event,
-  init as naturalInit,
-  setTag,
-  addBreadcrumb as naturalAddBreadcrumb,
-  captureException as naturalCaptureException,
-  captureMessage as naturalCaptureMessage,
-  withScope as naturalWithScope,
-  metrics,
-  startInactiveSpan,
-} from '@sentry/node';
-
-import { log } from '@dxos/log';
-import { TRACE_PROCESSOR } from '@dxos/tracing';
-
-import { type InitOptions } from './types';
-
-// Polyfill export.
-export { setTag, setTags, setUser } from '@sentry/node';
-
-/**
- * To use this SDK, call the init function as early as possible in the main entry module.
- * To set context information or send manual events, use the provided methods.
- *
- * @param options {InitOptions}
- */
-export const init = (options: InitOptions) => {
-  try {
-    naturalInit({
-      enabled: options.enable ?? true,
-      dsn: options.destination,
-      serverName: options.installationId,
-      release: options.release,
-      environment: options.environment ?? process.env.DX_ENVIRONMENT,
-      integrations: [],
-      tracesSampleRate: options.sampleRate,
-      transport: options.transport,
-      beforeSend: (event) => {
-        options.scrubFilenames && scrub(event);
-        options.onError?.(event);
-
-        return event;
-      },
-    });
-
-    if (options.tracing) {
-      TRACE_PROCESSOR.remoteMetrics.registerProcessor(metrics);
-      TRACE_PROCESSOR.remoteTracing.registerProcessor({
-        startSpan: startInactiveSpan,
-      });
-    }
-
-    Object.entries(options.properties ?? {}).forEach(([key, value]) => {
-      setTag(key, value);
-    });
-  } catch (err) {
-    log.catch('Failed to initialize sentry', err);
-  }
-};
-
-const scrub = (event: Event) => {
-  event.exception?.values?.forEach((value) => {
-    value.stacktrace?.frames?.forEach((frame) => {
-      const filename = frame.filename?.split('/');
-      frame.filename = filename && filename[filename.length - 1];
-    });
-  });
-};
-
-/**
- * Records a new breadcrumb which will be attached to future events.
- *
- * Breadcrumbs will be added to subsequent events to provide more context on user's actions prior to an error or crash.
- *
- * https://docs.sentry.io/platforms/javascript/enriching-events/breadcrumbs/
- *
- * @param breadcrumb — The breadcrumb to record.
- */
-export const addBreadcrumb: typeof naturalAddBreadcrumb = (breadcrumb) => {
-  try {
-    naturalAddBreadcrumb(breadcrumb);
-    log('add breadcrumb', breadcrumb);
-  } catch (err) {
-    log.catch('Failed to add breadcrumb', err);
-  }
-};
-
-/**
- * Captures an exception event and sends it to Sentry.
- *
- * @param exception — An exception-like object.
- * @param captureContext — Additional scope data to apply to exception event.
- * @returns — The generated eventId.
- */
-export const captureException: typeof naturalCaptureException = (exception, captureContext) => {
-  try {
-    const eventId = naturalCaptureException(exception, captureContext);
-    log('capture exception', { exception, eventId, ...captureContext });
-    return eventId;
-  } catch (err) {
-    log.catch('Failed to capture exception', err);
-    return 'unknown';
-  }
-};
-
-export const captureMessage: typeof naturalCaptureMessage = (exception, captureContext) => {
-  try {
-    const eventId = naturalCaptureMessage(exception, captureContext);
-    log('capture message', { exception, eventId, captureContext });
-    return eventId;
-  } catch (err) {
-    log.catch('Failed to capture message', err);
-    return 'unknown';
-  }
-};
-
-export const captureUserFeedback = (message: string): Promise<void> => {
-  const feedback = `User feedback: ${message}`;
-  throw new Error(`Capture user feedback not implemented in node. Use @sentry/browser. Message: ${feedback}`);
-};
-
-export const withScope = naturalWithScope;