@dxos/observability 0.6.13 → 0.6.14-main.2b6a0f3

package/dist/lib/node-esm/chunk-D7JZEGRD.mjs

@@ -0,0 +1,609 @@
+import { createRequire } from 'node:module';const require = createRequire(import.meta.url);
+
+// packages/sdk/observability/src/observability.ts
+import { Event, scheduleTaskInterval } from "@dxos/async";
+import { PublicKey } from "@dxos/client";
+import { Context } from "@dxos/context";
+import { invariant } from "@dxos/invariant";
+import { log } from "@dxos/log";
+import { ConnectionState } from "@dxos/network-manager";
+import { DeviceKind, Platform } from "@dxos/protocols/proto/dxos/client/services";
+import { isNode } from "@dxos/util";
+
+// packages/sdk/observability/src/cli-observability-secrets.json
+var cli_observability_secrets_default = {
+  SENTRY_DESTINATION: "https://2647916221e643869965e78469479aa4@o4504012000067584.ingest.sentry.io/4504012027265029",
+  TELEMETRY_API_KEY: "B00QG6PtJJrJ0VVFe0H5a6bcUUShKyZM",
+  IPDATA_API_KEY: "73dfdecdf979c18f07d50cf841bbdd9e589f237256326ac8cca23786",
+  OTEL_ENDPOINT: null,
+  OTEL_AUTHORIZATION: null
+};
+
+// packages/sdk/observability/src/helpers/common.ts
+var getTelemetryIdentifier = (client) => {
+  if (!client?.initialized) {
+    return void 0;
+  }
+  const identity = client.halo.identity.get();
+  if (identity) {
+    return identity.identityKey.truncate();
+  }
+  return void 0;
+};
+
+// packages/sdk/observability/src/helpers/map-spaces.ts
+var mapSpaces = (spaces, options = {
+  verbose: false,
+  truncateKeys: false
+}) => {
+  return spaces.map((space) => {
+    const { open, ready } = space.internal.data.metrics ?? {};
+    const startup = open && ready && ready.getTime() - open.getTime();
+    const pipeline = space.internal.data.pipeline;
+    const startDataMutations = pipeline?.currentEpoch?.subject.assertion.timeframe.totalMessages() ?? 0;
+    const epoch = pipeline?.currentEpoch?.subject.assertion.number;
+    const currentDataMutations = pipeline?.currentDataTimeframe?.totalMessages() ?? 0;
+    const totalDataMutations = pipeline?.targetDataTimeframe?.totalMessages() ?? 0;
+    return {
+      // TODO(nf): truncate keys for DD?
+      key: space.key.truncate(),
+      open: space.isOpen,
+      members: space.members.get().length,
+      objects: space.db.coreDatabase.getAllObjectIds().length,
+      startup,
+      epoch,
+      // appliedEpoch,
+      startDataMutations,
+      currentDataMutations,
+      totalDataMutations,
+      // TODO(burdon): Negative?
+      progress: (Math.min(Math.abs((currentDataMutations - startDataMutations) / (totalDataMutations - startDataMutations)), 1) * 100).toFixed(0)
+    };
+  });
+};
+
+// packages/sdk/observability/src/observability.ts
+var __dxlog_file = "/home/runner/work/dxos/dxos/packages/sdk/observability/src/observability.ts";
+var SPACE_METRICS_MIN_INTERVAL = 1e3 * 60;
+var SPACE_TELEMETRY_MIN_INTERVAL = 1e3 * 60 * 60;
+var NETWORK_METRICS_MIN_INTERVAL = 1e3 * 60 * 5;
+var Observability = class {
+  // TODO(nf): make platform a required extension?
+  constructor({ namespace, environment, release, config, secrets, group, mode, telemetry, errorLog }) {
+    // TODO(nf): accept upstream context?
+    this._ctx = new Context(void 0, {
+      F: __dxlog_file,
+      L: 87
+    });
+    this._tags = /* @__PURE__ */ new Map();
+    this.addIPDataTelemetryTags = (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");
+    };
+    this._namespace = namespace;
+    this._mode = mode;
+    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);
+    this.setTag("mode", this._mode);
+    this.setTag("session", PublicKey.random().toHex());
+  }
+  get mode() {
+    return this._mode;
+  }
+  get group() {
+    return this._group;
+  }
+  get enabled() {
+    return this._mode !== "disabled";
+  }
+  _loadSecrets(config, secrets) {
+    if (isNode()) {
+      const mergedSecrets = {
+        ...cli_observability_secrets_default,
+        ...secrets
+      };
+      process.env.DX_ENVIRONMENT && (mergedSecrets.DX_ENVIRONMENT = process.env.DX_ENVIRONMENT);
+      process.env.DX_RELEASE && (mergedSecrets.DX_RELEASE = process.env.DX_RELEASE);
+      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);
+      process.env.DX_OTEL_ENDPOINT && (mergedSecrets.OTEL_ENDPOINT = process.env.DX_OTEL_ENDPOINT);
+      process.env.DX_OTEL_AUTHORIZATION && (mergedSecrets.OTEL_AUTHORIZATION = process.env.DX_OTEL_AUTHORIZATION);
+      return mergedSecrets;
+    } else {
+      log("config", {
+        rtc: this._secrets,
+        config
+      }, {
+        F: __dxlog_file,
+        L: 151,
+        S: this,
+        C: (f, a) => f(...a)
+      });
+      return {
+        DX_ENVIRONMENT: config?.get("runtime.app.env.DX_ENVIRONMENT"),
+        DX_RELEASE: config?.get("runtime.app.env.DX_RELEASE"),
+        SENTRY_DESTINATION: config?.get("runtime.app.env.DX_SENTRY_DESTINATION"),
+        TELEMETRY_API_KEY: config?.get("runtime.app.env.DX_TELEMETRY_API_KEY"),
+        IPDATA_API_KEY: config?.get("runtime.app.env.DX_IPDATA_API_KEY"),
+        OTEL_ENDPOINT: config?.get("runtime.app.env.DX_OTEL_ENDPOINT"),
+        OTEL_AUTHORIZATION: config?.get("runtime.app.env.DX_OTEL_AUTHORIZATION"),
+        ...secrets
+      };
+    }
+  }
+  async initialize() {
+    await this._initMetrics();
+    await this._initTelemetry();
+    await this._initErrorLogs();
+    await this._initTraces();
+  }
+  async close() {
+    const closes = [];
+    this._telemetry && closes.push(this._telemetry.close());
+    this._otelMetrics && closes.push(this._otelMetrics.close());
+    this._otelLogs && closes.push(this._otelLogs.close());
+    await Promise.all(closes);
+    await this._ctx.dispose();
+  }
+  setMode(mode) {
+    this._mode = mode;
+  }
+  //
+  // Tags
+  //
+  setTag(key, value, scope) {
+    if (this.enabled && (scope === void 0 || scope === "all" || scope === "errors")) {
+      this._setTag?.(key, value);
+    }
+    if (!scope) {
+      scope = "all";
+    }
+    this._tags.set(key, {
+      value,
+      scope
+    });
+  }
+  getTag(key) {
+    return this._tags.get(key);
+  }
+  // TODO(wittjosiah): Improve privacy of telemetry identifiers. See `getTelemetryIdentifier`.
+  async setIdentityTags(clientServices) {
+    if (clientServices.IdentityService) {
+      clientServices.IdentityService.queryIdentity().subscribe((idqr) => {
+        if (!idqr?.identity?.identityKey) {
+          log("empty response from identity service", {
+            idqr
+          }, {
+            F: __dxlog_file,
+            L: 219,
+            S: this,
+            C: (f, a) => f(...a)
+          });
+          return;
+        }
+        this.setTag("identityKey", idqr.identity.identityKey.truncate());
+      });
+    }
+    if (clientServices.DevicesService) {
+      clientServices.DevicesService.queryDevices().subscribe((dqr) => {
+        if (!dqr || !dqr.devices || dqr.devices.length === 0) {
+          log("empty response from device service", {
+            device: dqr
+          }, {
+            F: __dxlog_file,
+            L: 229,
+            S: this,
+            C: (f, a) => f(...a)
+          });
+          return;
+        }
+        invariant(dqr, "empty response from device service", {
+          F: __dxlog_file,
+          L: 232,
+          S: this,
+          A: [
+            "dqr",
+            "'empty response from device service'"
+          ]
+        });
+        const thisDevice = dqr.devices.find((device) => device.kind === DeviceKind.CURRENT);
+        if (!thisDevice) {
+          log("no current device", {
+            device: dqr
+          }, {
+            F: __dxlog_file,
+            L: 236,
+            S: this,
+            C: (f, a) => f(...a)
+          });
+          return;
+        }
+        this.setTag("deviceKey", thisDevice.deviceKey.truncate());
+        if (thisDevice.profile?.label) {
+          this.setTag("deviceProfile", thisDevice.profile.label);
+        }
+      });
+    }
+  }
+  //
+  // Metrics
+  //
+  async _initMetrics() {
+    if (this.enabled && this._secrets.OTEL_ENDPOINT && this._secrets.OTEL_AUTHORIZATION) {
+      const { OtelMetrics } = await import("./otel-YI7HAFOG.mjs");
+      this._otelMetrics = new OtelMetrics({
+        endpoint: this._secrets.OTEL_ENDPOINT,
+        authorizationHeader: this._secrets.OTEL_AUTHORIZATION,
+        serviceName: this._namespace,
+        serviceVersion: this.getTag("release")?.value ?? "0.0.0",
+        getTags: () => Object.fromEntries(Array.from(this._tags).filter(([key, value]) => {
+          return value.scope === "all" || value.scope === "metrics";
+        }).map(([key, value]) => [
+          key,
+          value.value
+        ]))
+      });
+      log("otel metrics enabled", void 0, {
+        F: __dxlog_file,
+        L: 268,
+        S: this,
+        C: (f, a) => f(...a)
+      });
+    } else {
+      log("otel metrics disabled", void 0, {
+        F: __dxlog_file,
+        L: 270,
+        S: this,
+        C: (f, a) => f(...a)
+      });
+    }
+  }
+  /**
+  * Gauge metric.
+  *
+  * The default implementation uses OpenTelemetry
+  */
+  gauge(name, value, extraTags) {
+    this._otelMetrics?.gauge(name, value, extraTags);
+  }
+  // TODO(nf): Refactor into ObservabilityExtensions.
+  startNetworkMetrics(clientServices) {
+    if (!clientServices.NetworkService) {
+      return;
+    }
+    const updateSignalMetrics = new Event().debounce(NETWORK_METRICS_MIN_INTERVAL);
+    updateSignalMetrics.on(this._ctx, async () => {
+      log("send signal metrics", void 0, {
+        F: __dxlog_file,
+        L: 292,
+        S: this,
+        C: (f, a) => f(...a)
+      });
+      (this._lastNetworkStatus?.signaling).forEach(({ server, state }) => {
+        this.gauge("dxos.client.network.signal.connectionState", state, {
+          server
+        });
+      });
+      let swarmCount = 0;
+      const connectionStates = /* @__PURE__ */ new Map();
+      for (const state in ConnectionState) {
+        connectionStates.set(state, 0);
+      }
+      let totalReadBufferSize = 0;
+      let totalWriteBufferSize = 0;
+      let totalChannelBufferSize = 0;
+      this._lastNetworkStatus?.connectionInfo?.forEach((connectionInfo) => {
+        swarmCount++;
+        for (const conn of connectionInfo.connections ?? []) {
+          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;
+          }
+        }
+        this.gauge("dxos.client.network.swarm.count", swarmCount);
+        for (const state in ConnectionState) {
+          this.gauge("dxos.client.network.connection.count", connectionStates.get(state) ?? 0, {
+            state
+          });
+        }
+        this.gauge("dxos.client.network.totalReadBufferSize", totalReadBufferSize);
+        this.gauge("dxos.client.network.totalWriteBufferSize", totalWriteBufferSize);
+        this.gauge("dxos.client.network.totalChannelBufferSize", totalChannelBufferSize);
+      });
+    });
+    clientServices.NetworkService.queryStatus().subscribe((networkStatus) => {
+      this._lastNetworkStatus = networkStatus;
+      updateSignalMetrics.emit();
+    });
+    scheduleTaskInterval(this._ctx, async () => updateSignalMetrics.emit(), NETWORK_METRICS_MIN_INTERVAL);
+  }
+  startSpacesMetrics(client, namespace) {
+    const spaces = client.spaces.get();
+    const subscriptions = /* @__PURE__ */ new Map();
+    this._ctx.onDispose(() => subscriptions.forEach((subscription) => subscription.unsubscribe()));
+    const updateSpaceMetrics = new Event().debounce(SPACE_METRICS_MIN_INTERVAL);
+    updateSpaceMetrics.on(this._ctx, async () => {
+      log("send space metrics", void 0, {
+        F: __dxlog_file,
+        L: 346,
+        S: this,
+        C: (f, a) => f(...a)
+      });
+      for (const data of mapSpaces(spaces, {
+        truncateKeys: true
+      })) {
+        this.gauge("dxos.client.space.members", data.members, {
+          key: data.key
+        });
+        this.gauge("dxos.client.space.objects", data.objects, {
+          key: data.key
+        });
+        this.gauge("dxos.client.space.epoch", data.epoch, {
+          key: data.key
+        });
+        this.gauge("dxos.client.space.currentDataMutations", data.currentDataMutations, {
+          key: data.key
+        });
+      }
+    });
+    const updateSpaceTelemetry = new Event().debounce(SPACE_TELEMETRY_MIN_INTERVAL);
+    updateSpaceTelemetry.on(this._ctx, async () => {
+      log("send space telemetry", void 0, {
+        F: __dxlog_file,
+        L: 357,
+        S: this,
+        C: (f, a) => f(...a)
+      });
+      for (const data of mapSpaces(spaces, {
+        truncateKeys: true
+      })) {
+        this.event({
+          identityId: getTelemetryIdentifier(client),
+          name: `${namespace}.space.update`,
+          properties: data
+        });
+      }
+    });
+    const subscribeToSpaceUpdate = (space) => space.pipeline.subscribe({
+      next: () => {
+        updateSpaceMetrics.emit();
+        updateSpaceTelemetry.emit();
+      }
+    });
+    spaces.forEach((space) => {
+      subscriptions.set(space.key.toHex(), subscribeToSpaceUpdate(space));
+    });
+    client.spaces.subscribe({
+      next: async (spaces2) => {
+        spaces2.filter((space) => !subscriptions.has(space.key.toHex())).forEach((space) => {
+          subscriptions.set(space.key.toHex(), subscribeToSpaceUpdate(space));
+        });
+      }
+    });
+    scheduleTaskInterval(this._ctx, async () => updateSpaceMetrics.emit(), NETWORK_METRICS_MIN_INTERVAL);
+  }
+  async startRuntimeMetrics(client, frequency = NETWORK_METRICS_MIN_INTERVAL) {
+    const platform = await client.services.services.SystemService?.getPlatform();
+    invariant(platform, "platform is required", {
+      F: __dxlog_file,
+      L: 394,
+      S: this,
+      A: [
+        "platform",
+        "'platform is required'"
+      ]
+    });
+    this.setTag("platform_type", Platform.PLATFORM_TYPE[platform.type].toLowerCase());
+    if (this._mode === "full") {
+      if (platform.platform) {
+        this.setTag("platform", platform.platform);
+      }
+      if (platform.arch) {
+        this.setTag("arch", platform.arch);
+      }
+      if (platform.runtime) {
+        this.setTag("runtime", platform.runtime);
+      }
+    }
+    scheduleTaskInterval(this._ctx, async () => {
+      if (client.services.constructor.name === "WorkerClientServices") {
+        const memory = window.performance.memory;
+        if (memory) {
+          this.gauge("dxos.client.runtime.heapTotal", memory.totalJSHeapSize);
+          this.gauge("dxos.client.runtime.heapUsed", memory.usedJSHeapSize);
+          this.gauge("dxos.client.runtime.heapSizeLimit", memory.jsHeapSizeLimit);
+        }
+      }
+      client.services.services.SystemService?.getPlatform().then((platform2) => {
+        if (platform2.memory) {
+          this.gauge("dxos.client.services.runtime.rss", platform2.memory.rss);
+          this.gauge("dxos.client.services.runtime.heapTotal", platform2.memory.heapTotal);
+          this.gauge("dxos.client.services.runtime.heapUsed", platform2.memory.heapUsed);
+        }
+      }).catch((error) => log("platform error", {
+        error
+      }, {
+        F: __dxlog_file,
+        L: 429,
+        S: this,
+        C: (f, a) => f(...a)
+      }));
+    }, frequency);
+  }
+  //
+  // Telemetry
+  //
+  async _initTelemetry() {
+    if (this._secrets.TELEMETRY_API_KEY && this._mode !== "disabled") {
+      const { SegmentTelemetry } = await import("./segment/index.mjs");
+      this._telemetry = new SegmentTelemetry({
+        apiKey: this._secrets.TELEMETRY_API_KEY,
+        batchSize: this._telemetryBatchSize,
+        getTags: () => Object.fromEntries(Array.from(this._tags).filter(([key, value]) => {
+          return value.scope === "all" || value.scope === "telemetry";
+        }).map(([key, value]) => [
+          key,
+          value.value
+        ]))
+      });
+    } else {
+      log("segment disabled", void 0, {
+        F: __dxlog_file,
+        L: 455,
+        S: this,
+        C: (f, a) => f(...a)
+      });
+    }
+  }
+  /**
+  * A telemetry event.
+  *
+  * The default implementation uses Segment.
+  */
+  event(options) {
+    this._telemetry?.event(options);
+  }
+  /**
+  * A telemetry page view.
+  *
+  * The default implementation uses Segment.
+  */
+  page(options) {
+    this._telemetry?.page(options);
+  }
+  //
+  // Error Logs
+  //
+  async _initErrorLogs() {
+    if (this._secrets.SENTRY_DESTINATION && this._mode !== "disabled") {
+      const { captureException, captureUserFeedback, init, setTag } = await import("./sentry/index.mjs");
+      const { SentryLogProcessor } = await import("./sentry-log-processor-JYJH3AMG.mjs");
+      this._captureException = captureException;
+      this._captureUserFeedback = captureUserFeedback;
+      this._setTag = setTag;
+      log.info("Initializing Sentry", {
+        dest: this._secrets.SENTRY_DESTINATION,
+        options: this._errorReportingOptions
+      }, {
+        F: __dxlog_file,
+        L: 491,
+        S: this,
+        C: (f, a) => f(...a)
+      });
+      this._sentryLogProcessor = new SentryLogProcessor();
+      init({
+        ...this._errorReportingOptions,
+        destination: this._secrets.SENTRY_DESTINATION,
+        scrubFilenames: this._mode !== "full",
+        onError: (event) => this._sentryLogProcessor.addLogBreadcrumbsTo(event)
+      });
+      this._tags.forEach((v, k) => {
+        if (v.scope === "all" || v.scope === "errors") {
+          setTag(k, v.value);
+        }
+      });
+    } else {
+      log("sentry disabled", void 0, {
+        F: __dxlog_file,
+        L: 511,
+        S: this,
+        C: (f, a) => f(...a)
+      });
+    }
+    if (this._secrets.OTEL_ENDPOINT && this._secrets.OTEL_AUTHORIZATION && this._mode !== "disabled") {
+      const { OtelLogs } = await import("./otel-YI7HAFOG.mjs");
+      this._otelLogs = new OtelLogs({
+        endpoint: this._secrets.OTEL_ENDPOINT,
+        authorizationHeader: this._secrets.OTEL_AUTHORIZATION,
+        serviceName: this._namespace,
+        serviceVersion: this.getTag("release")?.value ?? "0.0.0",
+        getTags: () => Object.fromEntries(Array.from(this._tags).filter(([key, value]) => {
+          return value.scope === "all" || value.scope === "errors";
+        }).map(([key, value]) => [
+          key,
+          value.value
+        ]))
+      });
+      log("otel logs enabled", {
+        namespace: this._namespace
+      }, {
+        F: __dxlog_file,
+        L: 530,
+        S: this,
+        C: (f, a) => f(...a)
+      });
+    } else {
+      log("otel logs disabled", void 0, {
+        F: __dxlog_file,
+        L: 532,
+        S: this,
+        C: (f, a) => f(...a)
+      });
+    }
+  }
+  startErrorLogs() {
+    this._sentryLogProcessor && log.runtimeConfig.processors.push(this._sentryLogProcessor.logProcessor);
+    this._otelLogs && log.runtimeConfig.processors.push(this._otelLogs.logProcessor);
+  }
+  startTraces() {
+    this._otelTraces && this._otelTraces.start();
+  }
+  // TODO(nf): refactor init based on providers and their capabilities
+  async _initTraces() {
+    if (this._secrets.OTEL_ENDPOINT && this._secrets.OTEL_AUTHORIZATION && this._mode !== "disabled") {
+      const { OtelTraces } = await import("./otel-YI7HAFOG.mjs");
+      this._otelTraces = new OtelTraces({
+        endpoint: this._secrets.OTEL_ENDPOINT,
+        authorizationHeader: this._secrets.OTEL_AUTHORIZATION,
+        serviceName: this._namespace,
+        serviceVersion: this.getTag("release")?.value ?? "0.0.0",
+        getTags: () => Object.fromEntries(Array.from(this._tags).filter(([key, value]) => {
+          return value.scope === "all" || value.scope === "metrics";
+        }).map(([key, value]) => [
+          key,
+          value.value
+        ]))
+      });
+    }
+  }
+  /**
+  * Manually capture an exception.
+  *
+  * The default implementation uses Sentry.
+  */
+  captureException(err) {
+    if (this.enabled) {
+      this._captureException?.(err);
+    }
+  }
+  /**
+  * Manually capture user feedback.
+  *
+  * The default implementation uses Sentry.
+  */
+  captureUserFeedback(name, email, message) {
+    void this._captureUserFeedback?.(name, email, message);
+  }
+};
+
+export {
+  Observability,
+  getTelemetryIdentifier,
+  mapSpaces
+};
+//# sourceMappingURL=chunk-D7JZEGRD.mjs.map