@dxos/observability 0.8.1-main.ba2dec9 → 0.8.1-staging.31c3ee1

package/src/helpers/node-observability.ts

@@ -114,11 +114,11 @@ export const initializeNodeObservability = async ({
   const environment = process.env.DX_ENVIRONMENT ?? 'unknown';
 
   const observability = new Observability({
+    mode,
     namespace,
     release,
     environment,
     group,
-    mode,
     errorLog: {
       sentryInitOptions: {
         environment,
@@ -136,9 +136,10 @@ export const initializeNodeObservability = async ({
   try {
     const res = await fetch(`https://api.ipdata.co/?api-key=${IPDATA_API_KEY}`);
     const ipData = await res.json();
-    ipData && observability.addIPDataTelemetryTags(ipData);
+    ipData && observability.setIPDataTelemetryTags(ipData);
   } catch (err) {
     observability?.captureException(err);
   }
+
   return observability;
 };

package/src/helpers/setup-telemetry-listeners.ts

@@ -4,8 +4,8 @@
 
 import type { Client } from '@dxos/client';
 
-import { getTelemetryIdentifier } from './common';
-import type { Observability } from '../observability';
+import { getTelemetryIdentity } from './common';
+import { type Observability } from '../observability';
 
 let lastFocusEvent = new Date();
 let totalTime = 0;
@@ -17,12 +17,11 @@ export const setupTelemetryListeners = (namespace: string, client: Client, obser
       return;
     }
 
-    setTimeout(() =>
-      observability.event({
-        did: getTelemetryIdentifier(client),
-        name: `${namespace}.window.click`,
+    setTimeout(() => {
+      observability.track({
+        ...getTelemetryIdentity(client),
+        action: 'window.click',
         properties: {
-          href: window.location.href,
           id: (event.target as HTMLElement)?.id,
           path: (event.composedPath() as HTMLElement[])
             .filter((el) => Boolean(el.tagName))
@@ -30,68 +29,67 @@ export const setupTelemetryListeners = (namespace: string, client: Client, obser
             .reverse()
             .join('>'),
         },
-      }),
-    );
+      });
+    });
   };
 
   const focusCallback = () => {
     const now = new Date();
-    setTimeout(() =>
-      observability.event({
-        did: getTelemetryIdentifier(client),
-        name: `${namespace}.window.focus`,
+    setTimeout(() => {
+      observability.track({
+        ...getTelemetryIdentity(client),
+        action: 'window.focus',
         properties: {
-          href: window.location.href,
           timeAway: now.getTime() - lastFocusEvent.getTime(),
         },
-      }),
-    );
+      });
+    });
+
     lastFocusEvent = now;
   };
 
   const blurCallback = () => {
     const now = new Date();
-    const timeSpent = now.getTime() - lastFocusEvent.getTime();
-    setTimeout(() =>
-      observability.event({
-        did: getTelemetryIdentifier(client),
-        name: `${namespace}.window.blur`,
+    const duration = now.getTime() - lastFocusEvent.getTime();
+    setTimeout(() => {
+      observability.track({
+        ...getTelemetryIdentity(client),
+        action: 'window.blur',
         properties: {
-          href: window.location.href,
-          timeSpent,
+          duration,
         },
-      }),
-    );
+      });
+    });
+
     lastFocusEvent = now;
-    totalTime = totalTime + timeSpent;
+    totalTime = totalTime + duration;
   };
 
   const unloadCallback = () => {
-    setTimeout(() =>
-      observability.event({
-        did: getTelemetryIdentifier(client),
-        name: `${namespace}.page.unload`,
+    setTimeout(() => {
+      observability.track({
+        ...getTelemetryIdentity(client),
+        action: 'page.unload',
         properties: {
-          href: window.location.href,
-          timeSpent: totalTime,
+          duration: totalTime,
         },
-      }),
-    );
+      });
+    });
   };
 
   const errorCallback = (event: ErrorEvent) => {
-    setTimeout(() =>
-      observability.event({
-        did: getTelemetryIdentifier(client),
-        name: `${namespace}.window.error`,
+    setTimeout(() => {
+      observability.track({
+        ...getTelemetryIdentity(client),
+        action: 'window.error',
         properties: {
-          href: window.location.href,
           message: event.message,
           filename: event.filename,
           stack: (event.error as Error)?.stack,
+          cause: (event.error as Error)?.cause,
         },
-      }),
-    );
+      });
+    });
   };
 
   window.addEventListener('click', clickCallback, true);

package/src/observability.ts

@@ -13,9 +13,9 @@ import { DeviceKind, type NetworkStatus, Platform } from '@dxos/protocols/proto/
 import { isNode } from '@dxos/util';
 
 import buildSecrets from './cli-observability-secrets.json';
-import { type IPData, getTelemetryIdentifier, mapSpaces } from './helpers';
+import { getTelemetryIdentity, type IPData, mapSpaces } from './helpers';
 import { type OtelLogs, type OtelMetrics, type OtelTraces } from './otel';
-import { type SegmentTelemetry, type EventOptions, type PageOptions } from './segment';
+import { type SegmentTelemetry, type TrackOptions, type PageOptions, TelemetryEvent } from './segment';
 import { type InitOptions, type captureException as SentryCaptureException } from './sentry';
 import { type SentryLogProcessor } from './sentry/sentry-log-processor';
 
@@ -35,20 +35,28 @@ export type ObservabilitySecrets = {
   OTEL_AUTHORIZATION: string | null;
 };
 
-export type Mode = 'basic' | 'full' | 'disabled';
 export type TagScope = 'errors' | 'telemetry' | 'metrics' | 'all';
 
+/** Gathering mode. */
+export type Mode = 'basic' | 'full' | 'disabled';
+
 export type ObservabilityOptions = {
-  /// The webapp (e.g. 'composer.dxos.org'), 'cli', or 'agent'.
-  namespace: string;
   mode: Mode;
-  // TODO(nf): make platform a required extension?
-  // platform: Platform;
-  release?: string;
+
+  /** Environment. */
   environment?: string;
+
+  /** Application namespace. */
+  namespace: string;
+
+  /** Application release. */
+  release?: string;
+
+  /** User group. */
+  group?: string;
+
   config?: Config;
   secrets?: Record<string, string>;
-  group?: string;
 
   telemetry?: {
     batchSize?: number;
@@ -62,8 +70,34 @@ export type ObservabilityOptions = {
 /*
  * Observability provides a common interface for error logging, metrics, and telemetry.
  * It currently provides these capabilities using Sentry, OpenTelemetry, and Segment.
+ *
+ * Segment:
+ * https://app.segment.com/dxos/sources/composer-app/debugger
+ * https://app.segment.com/dxos/sources/composer-app/settings/keys
+ *
+ * NOTE:
+ * - Segment maintains a set of admin creates Source (e.g., "composer-app").
+ * - Each source has at least one API_KEY, which is used by the client.
+ *
+ * Testing:
+ * https://app.segment.com/dxos/sources/composer-app/settings/keys
+ * - DX_TELEMETRY_API_KEY
+ * - DX_SENTRY_DESTINATION
+ *
+ * Sentry:
+ * https://sentry.io/organizations/dxos/issues
+ *
+ * OpenTelemetry:
+ * https://dxosorg.grafana.net/explore
  */
 export class Observability {
+  private _mode: Mode;
+  private readonly _namespace: string;
+  private readonly _config?: Config;
+  private readonly _group?: string;
+  private readonly _secrets: ObservabilitySecrets;
+  private readonly _tags = new Map<string, { value: string; scope: TagScope }>();
+
   // TODO(wittjosiah): Generic metrics interface.
   private _otelMetrics?: OtelMetrics;
   private _otelTraces?: OtelTraces;
@@ -75,47 +109,39 @@ export class Observability {
   private _otelLogs?: OtelLogs;
   private _errorReportingOptions?: InitOptions;
   private _captureException?: typeof SentryCaptureException;
-  private _captureUserFeedback?: (name: string, email: string, message: string) => Promise<void>;
-  private _setTag?: (key: string, value: string) => void;
+  private _captureUserFeedback?: (message: string) => Promise<void>;
+  private _lastNetworkStatus?: NetworkStatus;
 
-  private _secrets: ObservabilitySecrets;
-  private _namespace: string;
-  private _mode: Mode;
-  private _config?: Config;
-  private _group?: string;
-  // TODO(nf): accept upstream context?
   private _ctx = new Context();
-  private _tags = new Map<string, { value: string; scope: TagScope }>();
-  private _lastNetworkStatus?: NetworkStatus;
 
   // TODO(nf): make platform a required extension?
   constructor({
+    mode,
     namespace,
     environment,
     release,
     config,
-    secrets,
     group,
-    mode,
+    secrets,
     telemetry,
     errorLog,
   }: ObservabilityOptions) {
-    this._namespace = namespace;
     this._mode = mode;
+    this._namespace = namespace;
     this._config = config;
     this._group = group;
     this._secrets = this._loadSecrets(config, secrets);
+
     this._telemetryBatchSize = telemetry?.batchSize ?? 30;
     this._errorReportingOptions = errorLog?.sentryInitOptions;
 
-    if (this._group) {
-      this.setTag('group', this._group);
-    }
-    this.setTag('namespace', this._namespace);
-    environment && this.setTag('environment', environment);
-    release && this.setTag('release', release);
+    // Tags.
     this.setTag('mode', this._mode);
+    this.setTag('namespace', this._namespace);
+    this.setTag('environment', environment);
+    this.setTag('release', release);
     this.setTag('session', PublicKey.random().toHex());
+    this.setTag('group', this._group);
   }
 
   get mode() {
@@ -139,7 +165,6 @@ export class Observability {
 
       process.env.DX_ENVIRONMENT && (mergedSecrets.DX_ENVIRONMENT = process.env.DX_ENVIRONMENT);
       process.env.DX_RELEASE && (mergedSecrets.DX_RELEASE = process.env.DX_RELEASE);
-      // TODO: prefix these with DX_?
       process.env.SENTRY_DESTINATION && (mergedSecrets.SENTRY_DESTINATION = process.env.SENTRY_DESTINATION);
       process.env.TELEMETRY_API_KEY && (mergedSecrets.TELEMETRY_API_KEY = process.env.TELEMETRY_API_KEY);
       process.env.IPDATA_API_KEY && (mergedSecrets.IPDATA_API_KEY = process.env.IPDATA_API_KEY);
@@ -163,6 +188,7 @@ export class Observability {
   }
 
   async initialize() {
+    log('initializing...');
     await this._initLogs();
     await this._initMetrics();
     await this._initTelemetry();
@@ -171,6 +197,7 @@ export class Observability {
   }
 
   async close() {
+    log('closing...');
     const closes: Promise<void>[] = [];
     this._telemetry && closes.push(this._telemetry.close());
     this._otelMetrics && closes.push(this._otelMetrics.close());
@@ -178,8 +205,6 @@ export class Observability {
 
     await Promise.all(closes);
     await this._ctx.dispose();
-
-    // TODO(wittjosiah): Remove telemetry, etc. scripts.
   }
 
   setMode(mode: Mode) {
@@ -190,13 +215,23 @@ export class Observability {
   // Tags
   //
 
-  setTag(key: string, value: string, scope?: TagScope) {
+  /** Callback (e.g., to share tags with Sentry.) */
+  private _setTag?: (key: string, value: string) => void;
+
+  /**
+   * camelCase keys are converted to snake_case in Segment.
+   */
+  setTag(key: string, value: string | undefined, scope?: TagScope) {
+    if (value === undefined) {
+      return;
+    }
     if (this.enabled && (scope === undefined || scope === 'all' || scope === 'errors')) {
       this._setTag?.(key, value);
     }
     if (!scope) {
       scope = 'all';
     }
+
     this._tags.set(key, { value, scope });
   }
 
@@ -204,14 +239,6 @@ export class Observability {
     return this._tags.get(key);
   }
 
-  addIPDataTelemetryTags = (ipData: IPData) => {
-    this.setTag('city', ipData.city, 'telemetry');
-    this.setTag('region', ipData.region, 'telemetry');
-    this.setTag('country', ipData.country, 'telemetry');
-    ipData.latitude && this.setTag('latitude', ipData.latitude.toString(), 'telemetry');
-    ipData.longitude && this.setTag('longitude', ipData.longitude.toString(), 'telemetry');
-  };
-
   // TODO(wittjosiah): Improve privacy of telemetry identifiers. See `getTelemetryIdentifier`.
   async setIdentityTags(clientServices: Partial<ClientServices>) {
     if (clientServices.IdentityService) {
@@ -220,7 +247,9 @@ export class Observability {
           log('empty response from identity service', { idqr });
           return;
         }
+
         this.setTag('did', idqr.identity.did);
+        this._telemetry?.identify({ userId: idqr.identity.did });
       });
     }
 
@@ -230,13 +259,14 @@ export class Observability {
           log('empty response from device service', { device: dqr });
           return;
         }
-        invariant(dqr, 'empty response from device service');
 
+        invariant(dqr, 'empty response from device service');
         const thisDevice = dqr.devices.find((device) => device.kind === DeviceKind.CURRENT);
         if (!thisDevice) {
           log('no current device', { device: dqr });
           return;
         }
+
         this.setTag('deviceKey', thisDevice.deviceKey.truncate());
         if (thisDevice.profile?.label) {
           this.setTag('deviceProfile', thisDevice.profile.label);
@@ -245,6 +275,14 @@ export class Observability {
     }
   }
 
+  setIPDataTelemetryTags = (ipData: IPData) => {
+    this.setTag('city', ipData.city, 'telemetry');
+    this.setTag('region', ipData.region, 'telemetry');
+    this.setTag('country', ipData.country, 'telemetry');
+    ipData.latitude && this.setTag('latitude', ipData.latitude.toString(), 'telemetry');
+    ipData.longitude && this.setTag('longitude', ipData.longitude.toString(), 'telemetry');
+  };
+
   //
   // Logs
   //
@@ -342,7 +380,6 @@ export class Observability {
           connectionStates.set(conn.state, (connectionStates.get(conn.state) ?? 0) + 1);
           totalReadBufferSize += conn.readBufferSize ?? 0;
           totalWriteBufferSize += conn.writeBufferSize ?? 0;
-
           for (const stream of conn.streams ?? []) {
             totalChannelBufferSize += stream.writeBufferSize ?? 0;
           }
@@ -387,9 +424,10 @@ export class Observability {
     updateSpaceTelemetry.on(this._ctx, async () => {
       log('send space telemetry');
       for (const data of mapSpaces(spaces, { truncateKeys: true })) {
-        this.event({
-          did: getTelemetryIdentifier(client),
-          name: `${namespace}.space.update`,
+        this.track({
+          ...getTelemetryIdentity(client),
+          event: TelemetryEvent.METRICS,
+          action: 'space.update',
           properties: data,
         });
       }
@@ -424,9 +462,8 @@ export class Observability {
     const platform = await client.services.services.SystemService?.getPlatform();
     invariant(platform, 'platform is required');
 
-    this.setTag('platform_type', Platform.PLATFORM_TYPE[platform.type as number].toLowerCase());
+    this.setTag('platformType', Platform.PLATFORM_TYPE[platform.type as number].toLowerCase());
     if (this._mode === 'full') {
-      // platform[foo] does not work?
       if (platform.platform) {
         this.setTag('platform', platform.platform);
       }
@@ -488,21 +525,19 @@ export class Observability {
   }
 
   /**
-   * A telemetry event.
-   *
+   * Submit telemetry page view.
    * The default implementation uses Segment.
    */
-  event(options: EventOptions) {
-    this._telemetry?.event(options);
+  page(options: PageOptions) {
+    this._telemetry?.page(options);
   }
 
   /**
-   * A telemetry page view.
-   *
+   * Submit telemetry user action.
    * The default implementation uses Segment.
    */
-  page(options: PageOptions) {
-    this._telemetry?.page(options);
+  track(options: TrackOptions) {
+    this._telemetry?.track(options);
   }
 
   //
@@ -515,10 +550,9 @@ export class Observability {
       const { SentryLogProcessor } = await import('./sentry/sentry-log-processor');
       this._captureException = captureException;
       this._captureUserFeedback = captureUserFeedback;
-
       this._setTag = setTag;
 
-      // TODO(nf): refactor package into this one?
+      // TODO(nf): Refactor package into this one?
       log.info('Initializing Sentry', {
         dest: this._secrets.SENTRY_DESTINATION,
         options: this._errorReportingOptions,
@@ -530,9 +564,9 @@ export class Observability {
         scrubFilenames: this._mode !== 'full',
         onError: (event) => this._sentryLogProcessor!.addLogBreadcrumbsTo(event),
       });
-      // TODO(nf): set platform at instantiation? needed for node.
 
-      // TODO(nf): is this different than passing as properties in options?
+      // TODO(nf): Set platform at instantiation? needed for node.
+      // TODO(nf): Is this different than passing as properties in options?
       this._tags.forEach((v, k) => {
         if (v.scope === 'all' || v.scope === 'errors') {
           setTag(k, v.value);
@@ -551,7 +585,7 @@ export class Observability {
     this._otelTraces && this._otelTraces.start();
   }
 
-  // TODO(nf): refactor init based on providers and their capabilities
+  // TODO(nf): Refactor init based on providers and their capabilities.
   private async _initTraces() {
     if (this._secrets.OTEL_ENDPOINT && this._secrets.OTEL_AUTHORIZATION && this._mode !== 'disabled') {
       const { OtelTraces } = await import('./otel');
@@ -574,7 +608,6 @@ export class Observability {
 
   /**
    * Manually capture an exception.
-   *
    * The default implementation uses Sentry.
    */
   captureException(err: any) {
@@ -585,13 +618,17 @@ export class Observability {
 
   /**
    * Manually capture user feedback.
-   *
    * The default implementation uses Sentry.
    */
-  captureUserFeedback(name: string, email: string, message: string) {
+  captureUserFeedback(message: string) {
+    if (!this._secrets.SENTRY_DESTINATION) {
+      log.info('Feedback submitted without Sentry destination', { message });
+      return;
+    }
+
     // TODO(Zan): Should this respect telemetry mode? Sending feedback is explicitly user-initiated.
     // - Maybe if telemetry is disable we shouldn't enable replay.
     // - (Check the browser.ts implementation for reference).
-    void this._captureUserFeedback?.(name, email, message);
+    void this._captureUserFeedback?.(message);
   }
 }

package/src/segment/base.ts

@@ -0,0 +1,69 @@
+//
+// 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

@@ -2,56 +2,55 @@
 // Copyright 2022 DXOS.org
 //
 
+import { type IdentifyParams } from '@segment/analytics-node';
 import snippet from '@segment/snippet';
 
 import { log } from '@dxos/log';
 
-import type { EventOptions, SegmentTelemetryOptions, PageOptions } from './types';
+import { AbstractSegmentTelemetry } from './base';
+import type { TrackOptions, SegmentTelemetryOptions, PageOptions } from './types';
 import { captureException } from '../sentry';
 
-export class SegmentTelemetry {
-  private _getTags: () => { [key: string]: string };
-
+/**
+ * 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) {
-    this._getTags = getTags;
+    super(getTags);
     try {
-      const contents = snippet.min({
-        apiKey,
-        page: false,
-      });
-
+      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);
+      log.catch('failed to initialize telemetry', err);
     }
   }
 
-  page({ did: userId, ...options }: PageOptions = {}) {
+  identify(options: IdentifyParams) {
     try {
-      (window as any).analytics?.page({
-        context: this._getTags(),
-        ...options,
-        userId,
-      });
+      (window as any).analytics?.identify(options.userId, options.traits);
     } catch (err) {
-      log.catch('Failed to track page', err);
+      log.catch('failed to identify', err);
     }
   }
 
-  event({ did: userId, name: event, ...options }: EventOptions) {
+  page(options: PageOptions) {
     try {
-      options.properties = {
-        ...options.properties,
-        ...this._getTags(),
-      };
-      (window as any).analytics?.track({
-        ...options,
-        event,
-      });
+      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) {
+    try {
+      const props = this.createTrackProps(options);
+      (window as any).analytics?.track(props.event, props.properties);
     } catch (err) {
-      log.catch('Failed to track event', err);
+      log.catch('failed to track event', err);
     }
   }
 
@@ -61,7 +60,7 @@ export class SegmentTelemetry {
         captureException(err);
       });
     } catch (err) {
-      log.catch('Failed to flush telemetry', err);
+      log.catch('failed to flush telemetry', err);
     }
   }