@aztec-labs/telemetry-client 6.0.0-nightly.20260829

package/src/config.ts

@@ -0,0 +1,135 @@
+import {
+  type ConfigMappingsType,
+  booleanConfigHelper,
+  getConfigFromMappings,
+  numberConfigHelper,
+} from '@aztec-labs/foundation/config';
+
+export interface TelemetryClientConfig {
+  metricsCollectorUrl?: URL;
+  publicMetricsCollectorUrl?: URL;
+  publicIncludeMetrics: string[];
+  publicMetricsOptOut: boolean;
+  publicMetricsCollectFrom: string[];
+  tracesCollectorUrl?: URL;
+  logsCollectorUrl?: URL;
+  otelCollectIntervalMs: number;
+  otelExportTimeoutMs: number;
+  otelExcludeMetrics: string[];
+  otelIncludeMetrics: string[];
+  otelMinTraceDurationMs: number;
+  otelBspMaxQueueSize: number;
+  otelBspMaxExportBatchSize: number;
+  otelBspScheduleDelayMs: number;
+}
+
+export const telemetryClientConfigMappings: ConfigMappingsType<TelemetryClientConfig> = {
+  metricsCollectorUrl: {
+    env: 'OTEL_EXPORTER_OTLP_METRICS_ENDPOINT',
+    description: 'The URL of the telemetry collector for metrics',
+    parseEnv: (val: string) => new URL(val),
+  },
+  tracesCollectorUrl: {
+    env: 'OTEL_EXPORTER_OTLP_TRACES_ENDPOINT',
+    description: 'The URL of the telemetry collector for traces',
+    parseEnv: (val: string) => new URL(val),
+  },
+  logsCollectorUrl: {
+    env: 'OTEL_EXPORTER_OTLP_LOGS_ENDPOINT',
+    description: 'The URL of the telemetry collector for logs',
+    parseEnv: (val: string) => new URL(val),
+  },
+  otelCollectIntervalMs: {
+    env: 'OTEL_COLLECT_INTERVAL_MS',
+    description: 'The interval at which to collect metrics',
+    ...numberConfigHelper(60000),
+  },
+  otelExportTimeoutMs: {
+    env: 'OTEL_EXPORT_TIMEOUT_MS',
+    description: 'The timeout for exporting metrics',
+    ...numberConfigHelper(30000),
+  },
+  otelExcludeMetrics: {
+    env: 'OTEL_EXCLUDE_METRICS',
+    description: 'A list of metric prefixes to exclude from export',
+    parseEnv: (val: string) =>
+      val
+        ? val
+            .split(',')
+            .map(s => s.trim())
+            .filter(s => s.length > 0)
+        : [],
+    defaultValue: [],
+  },
+  otelMinTraceDurationMs: {
+    env: 'OTEL_MIN_TRACE_DURATION_MS',
+    description: 'The minimum successful trace duration to export in milliseconds. Set to 0 to export all traces.',
+    ...numberConfigHelper(10),
+  },
+  otelBspMaxQueueSize: {
+    env: 'OTEL_BSP_MAX_QUEUE_SIZE',
+    description: 'The maximum number of completed spans to queue before export.',
+    ...numberConfigHelper(65536),
+  },
+  otelBspMaxExportBatchSize: {
+    env: 'OTEL_BSP_MAX_EXPORT_BATCH_SIZE',
+    description: 'The maximum number of spans to send to the collector in a single export.',
+    ...numberConfigHelper(4096),
+  },
+  otelBspScheduleDelayMs: {
+    env: 'OTEL_BSP_SCHEDULE_DELAY',
+    description: 'How long to wait before exporting a partially filled batch of spans, in milliseconds.',
+    ...numberConfigHelper(5000),
+  },
+  otelIncludeMetrics: {
+    env: 'OTEL_INCLUDE_METRICS',
+    description: 'A list of metric prefixes to include in export (ignored if OTEL_EXCLUDE_METRICS is set)',
+    parseEnv: (val: string) =>
+      val
+        ? val
+            .split(',')
+            .map(s => s.trim())
+            .filter(s => s.length > 0)
+        : [],
+    defaultValue: [],
+  },
+
+  publicMetricsCollectorUrl: {
+    env: 'PUBLIC_OTEL_EXPORTER_OTLP_METRICS_ENDPOINT',
+    description: 'A URL to publish a subset of metrics for public consumption',
+    parseEnv: (val: string) => new URL(val),
+  },
+  publicMetricsCollectFrom: {
+    env: 'PUBLIC_OTEL_COLLECT_FROM',
+    description: 'The role types to collect metrics from',
+    parseEnv: (val: string) =>
+      val
+        ? val
+            .split(',')
+            .map(s => s.trim())
+            .filter(s => s.length > 0)
+        : [],
+    defaultValue: [],
+  },
+  publicIncludeMetrics: {
+    env: 'PUBLIC_OTEL_INCLUDE_METRICS',
+    description: 'A list of metric prefixes to publicly export',
+    parseEnv: (val: string) =>
+      val
+        ? val
+            .split(',')
+            .map(s => s.trim())
+            .filter(s => s.length > 0)
+        : [],
+    defaultValue: [],
+  },
+  publicMetricsOptOut: {
+    env: 'PUBLIC_OTEL_OPT_OUT',
+    description: 'Whether to opt out of sharing optional telemetry',
+    ...booleanConfigHelper(true),
+  },
+};
+
+export function getConfigEnvVars(): TelemetryClientConfig {
+  return getConfigFromMappings<TelemetryClientConfig>(telemetryClientConfigMappings);
+}

package/src/index.ts

@@ -0,0 +1,11 @@
+export * from './telemetry.js';
+export * as Metrics from './metrics.js';
+export * as Attributes from './attributes.js';
+export * from './with_tracer.js';
+export * from './prom_otel_adapter.js';
+export * from './lmdb_metrics.js';
+export * from './l1_metrics.js';
+export * from './wrappers/index.js';
+export * from './start.js';
+export * from './otel_propagation.js';
+export * from './json_rpc_server_metrics.js';

package/src/json_rpc_server_metrics.ts

@@ -0,0 +1,150 @@
+import { Timer } from '@aztec-labs/foundation/timer';
+import type Koa from 'koa';
+
+import * as Attributes from './attributes.js';
+import * as Metrics from './metrics.js';
+import { getTelemetryClient } from './start.js';
+import type { Histogram, MetricAttributesType, TelemetryClient, UpDownCounter } from './telemetry.js';
+import { ATTR_JSONRPC_METHOD, ATTR_JSONRPC_SERVICE } from './vendor/attributes.js';
+
+const BATCH_SIZE_BUCKETS = [1, 2, 5, 10, 20, 50, 100, 200, 500, 1000];
+
+/** Fixed reasons for rejecting an RPC request before dispatching it to a registered handler. */
+export type JsonRpcRejectionReason =
+  | 'unauthorized'
+  | 'parse_error'
+  | 'invalid_request'
+  | 'method_not_found'
+  | 'bad_request'
+  | 'internal_error';
+
+/** Records bounded-cardinality metrics for registered JSON-RPC calls, rejected requests, and batches. */
+export class JsonRpcServerMetrics {
+  private readonly requestCount: UpDownCounter;
+  private readonly requestDuration: Histogram;
+  private readonly requestValidationDuration: Histogram;
+  private readonly rejectedRequestCount: UpDownCounter;
+  private readonly batchCount: UpDownCounter;
+  private readonly batchDuration: Histogram;
+  private readonly batchSize: Histogram;
+
+  constructor(telemetry: TelemetryClient) {
+    const meter = telemetry.getMeter('JsonRpcServer');
+    this.requestCount = meter.createUpDownCounter(Metrics.JSON_RPC_SERVER_REQUEST_COUNT);
+    this.requestDuration = meter.createHistogram(Metrics.JSON_RPC_SERVER_REQUEST_DURATION);
+    this.requestValidationDuration = meter.createHistogram(Metrics.JSON_RPC_SERVER_REQUEST_VALIDATION_DURATION);
+    this.rejectedRequestCount = meter.createUpDownCounter(Metrics.JSON_RPC_SERVER_REJECTED_REQUEST_COUNT);
+    this.batchCount = meter.createUpDownCounter(Metrics.JSON_RPC_SERVER_BATCH_COUNT);
+    this.batchDuration = meter.createHistogram(Metrics.JSON_RPC_SERVER_BATCH_DURATION);
+    this.batchSize = meter.createHistogram(Metrics.JSON_RPC_SERVER_BATCH_SIZE, {
+      advice: { explicitBucketBoundaries: BATCH_SIZE_BUCKETS },
+    });
+  }
+
+  /** Records the outcome and handler duration of a registered RPC method. */
+  public recordRequest(fullMethod: string, durationMs: number, ok: boolean): void {
+    const [service, method] = splitJsonRpcMethod(fullMethod);
+    const attributes: MetricAttributesType = {
+      ...(service === undefined ? {} : { [ATTR_JSONRPC_SERVICE]: service }),
+      [ATTR_JSONRPC_METHOD]: method,
+      [Attributes.OK]: ok,
+    };
+    this.requestCount.add(1, attributes);
+    this.requestDuration.record(durationMs, attributes);
+  }
+
+  /** Records a pre-dispatch rejection using a fixed reason. */
+  public recordRejectedRequest(reason: JsonRpcRejectionReason): void {
+    this.rejectedRequestCount.add(1, { [Attributes.JSON_RPC_REJECTION_REASON]: reason });
+  }
+
+  /** Records the duration and outcome of validating a registered RPC method's parameters. */
+  public recordRequestValidation(fullMethod: string, durationMs: number, ok: boolean): void {
+    const [service, method] = splitJsonRpcMethod(fullMethod);
+    this.requestValidationDuration.record(durationMs, {
+      ...(service === undefined ? {} : { [ATTR_JSONRPC_SERVICE]: service }),
+      [ATTR_JSONRPC_METHOD]: method,
+      [Attributes.OK]: ok,
+    });
+  }
+
+  /** Records the outcome, processing duration, and number of calls in a batch envelope. */
+  public recordBatch(size: number, durationMs: number, ok: boolean): void {
+    const attributes = { [Attributes.OK]: ok };
+    this.batchCount.add(1, attributes);
+    this.batchDuration.record(durationMs, attributes);
+    this.batchSize.record(size, attributes);
+  }
+}
+
+let metricsOwner: TelemetryClient | undefined;
+let metrics: JsonRpcServerMetrics | undefined;
+
+export function getJsonRpcServerMetrics(): JsonRpcServerMetrics {
+  const telemetry = getTelemetryClient();
+  if (metricsOwner !== telemetry) {
+    metricsOwner = telemetry;
+    metrics = new JsonRpcServerMetrics(telemetry);
+  }
+  return metrics!;
+}
+
+export function getOtelJsonRpcServerMetricsMiddleware(
+  metricsProvider: () => Pick<JsonRpcServerMetrics, 'recordBatch' | 'recordRejectedRequest'> = getJsonRpcServerMetrics,
+): (ctx: Koa.Context, next: () => Promise<void>) => Promise<void> {
+  return async function otelJsonRpcServerMetrics(ctx, next) {
+    const timer = new Timer();
+    await next();
+
+    const requestBody = (ctx.request as { body?: unknown }).body;
+    if (Array.isArray(requestBody)) {
+      metricsProvider().recordBatch(requestBody.length, timer.ms(), Array.isArray(ctx.body));
+    }
+
+    for (const reason of getRejectionReasons(ctx.status, ctx.body)) {
+      metricsProvider().recordRejectedRequest(reason);
+    }
+  };
+}
+
+export function splitJsonRpcMethod(fullMethod: string): [service: string | undefined, method: string] {
+  const separator = fullMethod.indexOf('_');
+  return separator === -1 ? [undefined, fullMethod] : [fullMethod.slice(0, separator), fullMethod.slice(separator + 1)];
+}
+
+function getRejectionReasons(status: number, response: unknown): JsonRpcRejectionReason[] {
+  if (status === 401) {
+    return ['unauthorized'];
+  }
+
+  const responses = Array.isArray(response) ? response : [response];
+  return responses.flatMap(item => {
+    const code = getErrorCode(item);
+    if (code === -32700) {
+      return ['parse_error'];
+    }
+    if (code === -32601) {
+      return ['method_not_found'];
+    }
+    if (code === -32600) {
+      return ['invalid_request'];
+    }
+    if (code === -32603) {
+      return ['internal_error'];
+    }
+    if (code === -32000) {
+      return ['bad_request'];
+    }
+    return [];
+  });
+}
+
+function getErrorCode(response: unknown): number | undefined {
+  if (!response || typeof response !== 'object' || !('error' in response)) {
+    return undefined;
+  }
+  const error = response.error;
+  return error && typeof error === 'object' && 'code' in error && typeof error.code === 'number'
+    ? error.code
+    : undefined;
+}

package/src/l1_metrics.ts

@@ -0,0 +1,64 @@
+import type { EthAddress } from '@aztec-labs/foundation/eth-address';
+import { type Chain, type FallbackTransport, type Hex, type HttpTransport, type PublicClient, formatEther } from 'viem';
+
+import { L1_SENDER } from './attributes.js';
+import { L1_BALANCE_ETH, L1_BLOB_BASE_FEE_WEI, L1_BLOCK_HEIGHT, L1_GAS_PRICE_WEI } from './metrics.js';
+import type { BatchObservableResult, Meter, ObservableGauge } from './telemetry.js';
+
+export class L1Metrics {
+  private l1BlockHeight: ObservableGauge;
+  private l1BalanceEth: ObservableGauge;
+  private gasPriceWei: ObservableGauge;
+  private blobBaseFeeWei: ObservableGauge;
+  private addresses: Hex[];
+
+  constructor(
+    private meter: Meter,
+    private client: PublicClient<FallbackTransport<HttpTransport[]>, Chain>,
+    addresses: EthAddress[],
+  ) {
+    this.l1BlockHeight = meter.createObservableGauge(L1_BLOCK_HEIGHT);
+    this.l1BalanceEth = meter.createObservableGauge(L1_BALANCE_ETH);
+    this.gasPriceWei = meter.createObservableGauge(L1_GAS_PRICE_WEI);
+    this.blobBaseFeeWei = meter.createObservableGauge(L1_BLOB_BASE_FEE_WEI);
+
+    this.addresses = addresses.map(addr => addr.toString());
+  }
+
+  start() {
+    this.meter.addBatchObservableCallback(this.observe, [this.l1BalanceEth, this.l1BlockHeight]);
+  }
+
+  stop() {
+    this.meter.removeBatchObservableCallback(this.observe, [this.l1BalanceEth, this.l1BlockHeight]);
+  }
+
+  private observe = async (observer: BatchObservableResult) => {
+    const blockNumber = await this.client.getBlockNumber();
+    const ethBalances = await Promise.all(
+      this.addresses.map(address =>
+        this.client.getBalance({
+          address,
+          blockNumber,
+        }),
+      ),
+    );
+
+    const gasPrice = await this.client.getGasPrice();
+    const blobFee = await this.client.getBlobBaseFee();
+
+    observer.observe(this.l1BlockHeight, Number(blockNumber));
+    observer.observe(this.gasPriceWei, Number(gasPrice));
+    observer.observe(this.blobBaseFeeWei, Number(blobFee));
+
+    for (let i = 0; i < ethBalances.length; i++) {
+      const wei = ethBalances[i];
+      const address = this.addresses[i];
+      const eth = parseFloat(formatEther(wei, 'wei'));
+
+      observer.observe(this.l1BalanceEth, eth, {
+        [L1_SENDER]: address,
+      });
+    }
+  };
+}

package/src/lmdb_metrics.ts

@@ -0,0 +1,45 @@
+import * as Metrics from './metrics.js';
+import type { AttributesType, BatchObservableResult, Meter, ObservableGauge } from './telemetry.js';
+
+export type LmdbStatsCallback = () => Promise<{
+  mappingSize: number;
+  physicalFileSize: number;
+  numItems: number;
+  actualSize: number;
+}>;
+
+export class LmdbMetrics {
+  private dbMapSize: ObservableGauge;
+  private dbPhysicalFileSize: ObservableGauge;
+  private dbUsedSize: ObservableGauge;
+  private dbNumItems: ObservableGauge;
+
+  constructor(
+    meter: Meter,
+    private attributes?: AttributesType,
+    private getStats?: LmdbStatsCallback,
+  ) {
+    this.dbMapSize = meter.createObservableGauge(Metrics.DB_MAP_SIZE);
+    this.dbPhysicalFileSize = meter.createObservableGauge(Metrics.DB_PHYSICAL_FILE_SIZE);
+    this.dbUsedSize = meter.createObservableGauge(Metrics.DB_USED_SIZE);
+    this.dbNumItems = meter.createObservableGauge(Metrics.DB_NUM_ITEMS);
+
+    meter.addBatchObservableCallback(this.recordDBMetrics, [
+      this.dbMapSize,
+      this.dbPhysicalFileSize,
+      this.dbUsedSize,
+      this.dbNumItems,
+    ]);
+  }
+
+  private recordDBMetrics = async (observable: BatchObservableResult) => {
+    if (!this.getStats) {
+      return;
+    }
+    const metrics = await this.getStats();
+    observable.observe(this.dbMapSize, metrics.mappingSize, this.attributes);
+    observable.observe(this.dbPhysicalFileSize, metrics.physicalFileSize, this.attributes);
+    observable.observe(this.dbNumItems, metrics.numItems, this.attributes);
+    observable.observe(this.dbUsedSize, metrics.actualSize, this.attributes);
+  };
+}

package/src/metric-utils.ts

@@ -0,0 +1,75 @@
+import type { AttributeValue, MetricOptions } from '@opentelemetry/api';
+
+import type { MetricDefinition } from './metrics.js';
+import type { AllowedAttributeNames, Meter, MetricAttributesType, UpDownCounter } from './telemetry.js';
+
+/** Extracts OpenTelemetry MetricOptions from a MetricDefinition */
+export function toMetricOptions(def: MetricDefinition): MetricOptions {
+  return {
+    description: def.description,
+    unit: def.unit,
+    valueType: def.valueType,
+  };
+}
+
+/** A mapping of attribute keys to their possible values */
+export type AttributeValuesMap = Partial<Record<AllowedAttributeNames, AttributeValue[]>>;
+
+/**
+ * Expands an attribute values map into all combinations of attribute objects.
+ * Example: { status: ['ok', 'fail'], type: ['a', 'b'] } =>
+ *   [{ status: 'ok', type: 'a' }, { status: 'ok', type: 'b' }, { status: 'fail', type: 'a' }, { status: 'fail', type: 'b' }]
+ */
+export function expandAttributeCombinations(attrMap: AttributeValuesMap): MetricAttributesType[] {
+  const keys = Object.keys(attrMap) as AllowedAttributeNames[];
+  if (keys.length === 0) {
+    return [{}];
+  }
+
+  const result: MetricAttributesType[] = [];
+
+  function generate(index: number, current: MetricAttributesType) {
+    if (index === keys.length) {
+      result.push({ ...current });
+      return;
+    }
+    const key = keys[index];
+    for (const value of attrMap[key]!) {
+      current[key] = value;
+      generate(index + 1, current);
+    }
+  }
+
+  generate(0, {});
+  return result;
+}
+
+/**
+ * Creates an UpDownCounter and initializes it to 0.
+ * @param meter - The meter to create the counter on
+ * @param metric - The metric definition
+ * @param attributes - Optional attributes for initialization. Can be:
+ *   - AttributeValuesMap: mapping of attribute keys to arrays of possible values (generates cartesian product)
+ *   - MetricAttributesType[]: explicit array of attribute objects
+ *   - undefined: initializes without attributes
+ */
+export function createUpDownCounterWithDefault(
+  meter: Meter,
+  metric: MetricDefinition,
+  attributes: AttributeValuesMap | MetricAttributesType[] | undefined = undefined,
+): UpDownCounter {
+  const counter = meter.createUpDownCounter(metric);
+  if (attributes === undefined) {
+    counter.add(0);
+  } else if (Array.isArray(attributes)) {
+    for (const attrs of attributes) {
+      counter.add(0, attrs);
+    }
+  } else {
+    const combinations = expandAttributeCombinations(attributes);
+    for (const attrs of combinations) {
+      counter.add(0, attrs);
+    }
+  }
+  return counter;
+}