@aztec/telemetry-client 0.0.0-test.0 → 0.0.1-commit.21caa21

package/src/prom_otel_adapter.ts

@@ -1,8 +1,9 @@
 import { type Logger, createLogger } from '@aztec/foundation/log';
+import { Timer } from '@aztec/foundation/timer';
 
 import { Registry } from 'prom-client';
 
-import type { Meter, MetricsType, ObservableGauge, TelemetryClient } from './telemetry.js';
+import type { Histogram, Meter, MetricsType, ObservableGauge, TelemetryClient } from './telemetry.js';
 
 /**
  * Types matching the gossipsub and libp2p services
@@ -125,7 +126,7 @@ export class OtelGauge<Labels extends LabelsGeneric = NoLabels> implements IGaug
     }
 
     for (const [labelStr, value] of this.labeledValues.entries()) {
-      const labels = this.parseLabelsSafely(labelStr);
+      const labels = parseLabelsSafely(labelStr, this.logger);
       if (labels) {
         result.observe(value, labels);
       }
@@ -146,7 +147,7 @@ export class OtelGauge<Labels extends LabelsGeneric = NoLabels> implements IGaug
     }
 
     if (labelsOrValue) {
-      this.validateLabels(labelsOrValue);
+      validateLabels(labelsOrValue, this.labelNames, 'Gauge');
       const labelKey = JSON.stringify(labelsOrValue);
       const currentValue = this.labeledValues.get(labelKey) ?? 0;
       this.labeledValues.set(labelKey, currentValue + (value ?? 1));
@@ -169,7 +170,7 @@ export class OtelGauge<Labels extends LabelsGeneric = NoLabels> implements IGaug
       return;
     }
 
-    this.validateLabels(labelsOrValue);
+    validateLabels(labelsOrValue, this.labelNames, 'Gauge');
     const labelKey = JSON.stringify(labelsOrValue);
     this.labeledValues.set(labelKey, value!);
   }
@@ -180,7 +181,7 @@ export class OtelGauge<Labels extends LabelsGeneric = NoLabels> implements IGaug
    */
   dec(labels?: Labels): void {
     if (labels) {
-      this.validateLabels(labels);
+      validateLabels(labels, this.labelNames, 'Gauge');
       const labelKey = JSON.stringify(labels);
       const currentValue = this.labeledValues.get(labelKey) ?? 0;
       this.labeledValues.set(labelKey, currentValue - 1);
@@ -197,84 +198,215 @@ export class OtelGauge<Labels extends LabelsGeneric = NoLabels> implements IGaug
     this.currentValue = 0;
     this.labeledValues.clear();
   }
+}
+
+/**
+ * Implementation of a Histogram collector
+ */
+export class OtelHistogram<Labels extends LabelsGeneric = NoLabels> implements IHistogram<Labels> {
+  private histogram: Histogram;
+
+  constructor(
+    private logger: Logger,
+    meter: Meter,
+    name: string,
+    help: string,
+    buckets: number[] = [],
+    private labelNames: Array<keyof Labels> = [],
+  ) {
+    this.histogram = meter.createHistogram(name as MetricsType, {
+      description: help,
+      advice: buckets.length ? { explicitBucketBoundaries: buckets } : undefined,
+    });
+  }
 
   /**
-   * Validates that provided labels match the expected schema
-   * @param labels - Labels object to validate
-   * @throws Error if invalid labels are provided
+   * Starts a timer and returns a function that when called will record the time elapsed
+   * @param labels - Optional labels for the observation
    */
-  private validateLabels(labels: Labels): void {
-    if (this.labelNames.length === 0) {
-      throw new Error('Gauge was initialized without labels support');
+  startTimer(labels?: Labels): () => void {
+    if (labels) {
+      validateLabels(labels, this.labelNames, 'Histogram');
     }
 
-    for (const key of Object.keys(labels)) {
-      if (!this.labelNames.includes(key as keyof Labels)) {
-        throw new Error(`Invalid label key: ${key}`);
+    const timer = new Timer();
+    return () => {
+      // Use timer.s() here to get the duration in seconds since this is only currently used by gossipsub_heartbeat_duration_seconds
+      const duration = timer.s();
+      if (labels) {
+        this.observe(labels, duration);
+      } else {
+        this.observe(duration);
       }
-    }
+    };
   }
 
   /**
-   * Safely parses label string back to object
-   * @param labelStr - Stringified labels object
-   * @returns Labels object or null if parsing fails
+   * Observes a value
+   * @param value - Value to observe
+   */
+  observe(value: number): void;
+  /**
+   * Observes a value with labels
+   * @param labels - Labels object
+   * @param value - Value to observe
    */
-  private parseLabelsSafely(labelStr: string): Labels | null {
-    try {
-      return JSON.parse(labelStr) as Labels;
-    } catch {
-      this.logger.error(`Failed to parse label string: ${labelStr}`);
-      return null;
+  observe(labels: Labels, value: number): void;
+  observe(labelsOrValue: Labels | number, value?: number): void {
+    if (typeof labelsOrValue === 'number') {
+      this.histogram.record(labelsOrValue);
+    } else {
+      validateLabels(labelsOrValue, this.labelNames, 'Histogram');
+      this.histogram.record(value!, labelsOrValue);
     }
   }
+
+  reset(): void {
+    // OpenTelemetry histograms cannot be reset, but we implement the interface
+    this.logger.silent('OpenTelemetry histograms cannot be fully reset');
+  }
 }
 
 /**
- * Noop implementation of a Historgram collec
+ * Implementation of an AvgMinMax collector
  */
-class NoopOtelHistogram<Labels extends LabelsGeneric = NoLabels> implements IHistogram<Labels> {
+export class OtelAvgMinMax<Labels extends LabelsGeneric = NoLabels> implements IAvgMinMax<Labels> {
+  private gauges: {
+    avg: ObservableGauge;
+    min: ObservableGauge;
+    max: ObservableGauge;
+  };
+
+  private currentValues: number[] = [];
+  private labeledValues: Map<string, number[]> = new Map();
+
   constructor(
     private logger: Logger,
-    _meter: Meter,
-    _name: string, // MetricsType must be registered in the aztec labels registry
-    _help: string,
-    _buckets: number[] = [],
-    _labelNames: Array<keyof Labels> = [],
-  ) {}
-
-  // Overload signatures
-  observe(_value: number): void;
-  observe(_labels: Labels, _value: number): void;
-  observe(_valueOrLabels: number | Labels, _value?: number): void {}
-
-  startTimer(_labels?: Labels): (_labels?: Labels) => number {
-    return () => 0;
+    meter: Meter,
+    name: string,
+    help: string,
+    private labelNames: Array<keyof Labels> = [],
+  ) {
+    // Create three separate gauges for avg, min, and max
+    this.gauges = {
+      avg: meter.createObservableGauge(`${name}_avg` as MetricsType, {
+        description: `${help} (average)`,
+      }),
+      min: meter.createObservableGauge(`${name}_min` as MetricsType, {
+        description: `${help} (minimum)`,
+      }),
+      max: meter.createObservableGauge(`${name}_max` as MetricsType, {
+        description: `${help} (maximum)`,
+      }),
+    };
+
+    // Register callbacks for each gauge
+    this.gauges.avg.addCallback(this.observeAvg.bind(this));
+    this.gauges.min.addCallback(this.observeMin.bind(this));
+    this.gauges.max.addCallback(this.observeMax.bind(this));
   }
 
+  /**
+   * Sets the values for calculating avg, min, max
+   * @param values - Array of values
+   */
+  set(values: number[]): void;
+  /**
+   * Sets the values for calculating avg, min, max with labels
+   * @param labels - Labels object
+   * @param values - Array of values
+   */
+  set(labels: Labels, values: number[]): void;
+  set(labelsOrValues: number[] | Labels, values?: number[]): void {
+    if (Array.isArray(labelsOrValues)) {
+      this.currentValues = labelsOrValues;
+      return;
+    } else {
+      validateLabels(labelsOrValues, this.labelNames, 'AvgMinMax');
+      const labelKey = JSON.stringify(labelsOrValues);
+      this.labeledValues.set(labelKey, values || []);
+    }
+  }
+
+  /**
+   * Resets all stored values
+   */
   reset(): void {
-    // OpenTelemetry histograms cannot be reset, but we implement the interface
-    this.logger.warn('OpenTelemetry histograms cannot be reset');
+    this.currentValues = [];
+    this.labeledValues.clear();
+  }
+
+  /**
+   * General function to observe an aggregation
+   * @param result - Observer result
+   * @param aggregateFn - Function that calculates the aggregation
+   */
+  private observeAggregation(result: any, aggregateFn: (arr: number[]) => number): void {
+    // Observe unlabeled values
+    if (this.currentValues.length > 0) {
+      result.observe(aggregateFn(this.currentValues));
+    }
+
+    // Observe labeled values
+    for (const [labelStr, values] of this.labeledValues.entries()) {
+      if (values.length > 0) {
+        const labels = parseLabelsSafely(labelStr, this.logger);
+        if (labels) {
+          result.observe(aggregateFn(values), labels);
+        }
+      }
+    }
+  }
+
+  private observeAvg(result: any): void {
+    this.observeAggregation(result, arr => arr.reduce((sum, val) => sum + val, 0) / arr.length);
+  }
+
+  private observeMin(result: any): void {
+    this.observeAggregation(result, arr => Math.min.apply(null, arr));
+  }
+
+  private observeMax(result: any): void {
+    this.observeAggregation(result, arr => Math.max.apply(null, arr));
   }
 }
 
 /**
- * Noop implementation of an AvgMinMax collector
+ * Validates that provided labels match the expected schema
+ * @param labels - Labels object to validate
+ * @param labelNames - Array of allowed label names
+ * @param metricType - Type of metric for error message ('Gauge', 'Histogram', 'AvgMinMax')
+ * @throws Error if invalid labels are provided
  */
-class NoopOtelAvgMinMax<Labels extends LabelsGeneric = NoLabels> implements IAvgMinMax<Labels> {
-  constructor(
-    private _logger: Logger,
-    _meter: Meter,
-    _name: string, // MetricsType must be registered in the aztec labels registry
-    _help: string,
-    _labelNames: Array<keyof Labels> = [],
-  ) {}
-
-  set(_values: number[]): void;
-  set(_labels: Labels, _values: number[]): void;
-  set(_valueOrLabels: number[] | Labels, _values?: number[]): void {}
-
-  reset(): void {}
+function validateLabels<Labels extends LabelsGeneric>(
+  labels: Labels,
+  labelNames: Array<keyof Labels>,
+  metricType: string,
+): void {
+  if (labelNames.length === 0) {
+    throw new Error(`${metricType} was initialized without labels support`);
+  }
+
+  for (const key of Object.keys(labels)) {
+    if (!labelNames.includes(key as keyof Labels)) {
+      throw new Error(`Invalid label key: ${key}`);
+    }
+  }
+}
+
+/**
+ * Safely parses label string back to object
+ * @param labelStr - Stringified labels object
+ * @param logger - Logger instance for error reporting
+ * @returns Labels object or null if parsing fails
+ */
+function parseLabelsSafely<Labels extends LabelsGeneric>(labelStr: string, logger: Logger): Labels | null {
+  try {
+    return JSON.parse(labelStr) as Labels;
+  } catch {
+    logger.error(`Failed to parse label string: ${labelStr}`);
+    return null;
+  }
 }
 
 /**
@@ -304,7 +436,7 @@ export class OtelMetricsAdapter extends Registry implements MetricsRegister {
   }
 
   histogram<Labels extends LabelsGeneric = NoLabels>(configuration: HistogramConfig<Labels>): IHistogram<Labels> {
-    return new NoopOtelHistogram<Labels>(
+    return new OtelHistogram<Labels>(
       this.logger,
       this.meter,
       configuration.name as MetricsType,
@@ -315,7 +447,7 @@ export class OtelMetricsAdapter extends Registry implements MetricsRegister {
   }
 
   avgMinMax<Labels extends LabelsGeneric = NoLabels>(configuration: AvgMinMaxConfig<Labels>): IAvgMinMax<Labels> {
-    return new NoopOtelAvgMinMax<Labels>(
+    return new OtelAvgMinMax<Labels>(
       this.logger,
       this.meter,
       configuration.name as MetricsType,

package/src/start.ts

@@ -7,24 +7,24 @@ import type { TelemetryClient } from './telemetry.js';
 
 export * from './config.js';
 
-let initialised = false;
+let initialized = false;
 let telemetry: TelemetryClient = new NoopTelemetryClient();
 
 export function initTelemetryClient(config: TelemetryClientConfig): TelemetryClient {
   const log = createLogger('telemetry:client');
-  if (initialised) {
+  if (initialized) {
     log.warn('Telemetry client has already been initialized once');
     return telemetry;
   }
 
-  if (config.metricsCollectorUrl) {
+  if (config.metricsCollectorUrl || config.publicMetricsCollectorUrl) {
     log.info(`Using OpenTelemetry client with custom collector`);
     telemetry = OpenTelemetryClient.createAndStart(config, log);
   } else {
     log.info('Using NoopTelemetryClient');
   }
 
-  initialised = true;
+  initialized = true;
   return telemetry;
 }
 

package/src/telemetry.ts

@@ -24,21 +24,49 @@ export { type Span, SpanStatusCode, ValueType } from '@opentelemetry/api';
 
 type ValuesOf<T> = T extends Record<string, infer U> ? U : never;
 
+type AttributeNames = ValuesOf<typeof Attributes>;
+
+/**
+ * This is a set of attributes that could lead to high cardinality in the metrics.
+ * If you find yourself wanting to capture this data in a metric consider if it makes sense to capture
+ * as the metric value instead of an attribute or consider logging instead.
+ *
+ * Think twice before removing an attribute from this list.
+ */
+type BannedMetricAttributeNames = (typeof Attributes)[
+  | 'BLOCK_NUMBER'
+  | 'BLOCK_ARCHIVE'
+  | 'SLOT_NUMBER'
+  | 'BLOCK_PARENT'
+  | 'BLOCK_CANDIDATE_TXS_COUNT'
+  | 'BLOCK_TXS_COUNT'
+  | 'BLOCK_SIZE'
+  | 'EPOCH_SIZE'
+  | 'EPOCH_NUMBER'
+  | 'TX_HASH'
+  | 'PROVING_JOB_ID'
+  | 'P2P_ID'
+  | 'P2P_REQ_RESP_BATCH_REQUESTS_COUNT'
+  | 'TARGET_ADDRESS'
+  | 'MANA_USED'
+  | 'TOTAL_INSTRUCTIONS'];
+
 /** Global registry of attributes */
-type AttributesType = Partial<Record<ValuesOf<typeof Attributes>, AttributeValue>>;
-export type { AttributesType };
+export type AttributesType = Partial<Record<AttributeNames, AttributeValue>>;
+
+/** Subset of attributes allowed to be added to metrics */
+export type MetricAttributesType = Partial<Record<Exclude<AttributeNames, BannedMetricAttributeNames>, AttributeValue>>;
 
 /** Global registry of metrics */
-type MetricsType = (typeof Metrics)[keyof typeof Metrics];
-export type { MetricsType };
+export type MetricsType = (typeof Metrics)[keyof typeof Metrics];
 
-export type Gauge = OtelGauge<AttributesType>;
-export type Histogram = OtelHistogram<AttributesType>;
-export type UpDownCounter = OtelUpDownCounter<AttributesType>;
-export type ObservableGauge = OtelObservableGauge<AttributesType>;
-export type ObservableUpDownCounter = OtelObservableUpDownCounter<AttributesType>;
-export type ObservableResult = OtelObservableResult<AttributesType>;
-export type BatchObservableResult = OtelBatchObservableResult<AttributesType>;
+export type Gauge = OtelGauge<MetricAttributesType>;
+export type Histogram = OtelHistogram<MetricAttributesType>;
+export type UpDownCounter = OtelUpDownCounter<MetricAttributesType>;
+export type ObservableGauge = OtelObservableGauge<MetricAttributesType>;
+export type ObservableUpDownCounter = OtelObservableUpDownCounter<MetricAttributesType>;
+export type ObservableResult = OtelObservableResult<MetricAttributesType>;
+export type BatchObservableResult = OtelBatchObservableResult<MetricAttributesType>;
 
 export type { Tracer };
 
@@ -122,6 +150,16 @@ export interface TelemetryClient {
    * Flushes the telemetry client.
    */
   flush(): Promise<void>;
+
+  /**
+   * Updates what telemetry is exported to the public collector
+   */
+  setExportedPublicTelemetry(prefixes: string[]): void;
+
+  /**
+   * Updates the roles that would share telemetry (if enabled)
+   */
+  setPublicTelemetryCollectFrom(roles: string[]): void;
 }
 
 /** Objects that adhere to this interface can use @trackSpan */
@@ -165,7 +203,7 @@ export function trackSpan<T extends Traceable, F extends (...args: any[]) => any
       // run originalMethod wrapped in an active span
       // "active" means the span will be alive for the duration of the function execution
       // and if any other spans are started during the execution of originalMethod, they will be children of this span
-      // behind the scenes this uses AsyncLocalStorage https://nodejs.org/dist/latest-v18.x/docs/api/async_context.html
+      // behind the scenes this uses AsyncLocalStorage https://nodejs.org/dist/latest-v22.x/docs/api/async_context.html
       return this.tracer.startActiveSpan(name, async (span: Span) => {
         span.setAttributes(currentAttrs ?? {});
 

package/src/vendor/otel-pino-stream.ts

@@ -23,9 +23,6 @@ import { Writable } from 'stream';
 import { registerOtelLoggerProvider } from '../otel_logger_provider.js';
 import { getOtelResource } from '../otel_resource.js';
 
-/* eslint-disable @typescript-eslint/ban-types */
-/* eslint-disable camelcase */
-
 // This block is a copy (modulo code style and TypeScript types) of the Pino
 // code that defines log level value and names. This file is part of
 // *instrumenting* Pino, so we want to avoid a dependency on the library.
@@ -173,7 +170,7 @@ export class OTelPinoStream extends Writable {
         return;
       }
 
-      // Parse, and handle edge cases similar to how `pino-abtract-transport` does:
+      // Parse, and handle edge cases similar to how `pino-abstract-transport` does:
       // https://github.com/pinojs/pino-abstract-transport/blob/v1.2.0/index.js#L28-L45
       // - Emitting an 'unknown' event on parse error mimicks pino-abstract-transport.
       let recObj;

package/src/wrappers/fetch.ts

@@ -15,38 +15,31 @@ import { ATTR_JSONRPC_METHOD, ATTR_JSONRPC_REQUEST_ID } from '../vendor/attribut
  * @returns A fetch function.
  */
 export function makeTracedFetch(retries: number[], defaultNoRetry: boolean, fetch = defaultFetch, log?: Logger) {
-  return (
-    host: string,
-    rpcMethod: string,
-    body: any,
-    useApiEndpoints: boolean,
-    extraHeaders: Record<string, string> = {},
-    noRetry?: boolean,
-  ) => {
+  return (host: string, body: unknown, extraHeaders: Record<string, string> = {}, noRetry?: boolean) => {
     const telemetry = getTelemetryClient();
-    return telemetry
-      .getTracer('fetch')
-      .startActiveSpan(`JsonRpcClient.${rpcMethod}`, { kind: SpanKind.CLIENT }, async span => {
-        try {
-          if (body && typeof body.id === 'number') {
-            span.setAttribute(ATTR_JSONRPC_REQUEST_ID, body.id);
-          }
-          span.setAttribute(ATTR_JSONRPC_METHOD, rpcMethod);
-          const headers = { ...extraHeaders };
-          propagation.inject(context.active(), headers);
-          return await retry(
-            () => fetch(host, rpcMethod, body, useApiEndpoints, headers, noRetry ?? defaultNoRetry),
-            `JsonRpcClient request ${rpcMethod} to ${host}`,
-            makeBackoff(retries),
-            log,
-            false,
-          );
-        } catch (err: any) {
-          span.setStatus({ code: SpanStatusCode.ERROR, message: err?.message ?? String(err) });
-          throw err;
-        } finally {
-          span.end();
+    return telemetry.getTracer('fetch').startActiveSpan(`JsonRpcClient`, { kind: SpanKind.CLIENT }, async span => {
+      try {
+        if (body && typeof body === 'object' && 'id' in body && typeof body.id === 'number') {
+          span.setAttribute(ATTR_JSONRPC_REQUEST_ID, body.id);
         }
-      });
+        if (body && typeof body === 'object' && 'method' in body && typeof body.method === 'string') {
+          span.setAttribute(ATTR_JSONRPC_METHOD, body.method);
+        }
+        const headers = { ...extraHeaders };
+        propagation.inject(context.active(), headers);
+        return await retry(
+          () => fetch(host, body, headers, noRetry ?? defaultNoRetry),
+          `JsonRpcClient request to ${host}`,
+          makeBackoff(retries),
+          log,
+          false,
+        );
+      } catch (err: any) {
+        span.setStatus({ code: SpanStatusCode.ERROR, message: err?.message ?? String(err) });
+        throw err;
+      } finally {
+        span.end();
+      }
+    });
   };
 }

package/src/wrappers/json_rpc_server.ts

@@ -6,7 +6,7 @@ import { getOtelJsonRpcPropagationMiddleware } from '../otel_propagation.js';
 export function createTracedJsonRpcServer<T extends object = any>(
   handler: T,
   schema: ApiSchemaFor<T>,
-  options: Partial<SafeJsonRpcServerOptions> = {},
+  options: SafeJsonRpcServerOptions = {},
 ) {
   return createSafeJsonRpcServer(handler, schema, {
     ...options,

package/src/wrappers/l2_block_stream.ts

@@ -10,7 +10,7 @@ import { type Traceable, type Tracer, trackSpan } from '@aztec/telemetry-client'
 /** Extends an L2BlockStream with a tracer to create a new trace per iteration. */
 export class TraceableL2BlockStream extends L2BlockStream implements Traceable {
   constructor(
-    l2BlockSource: Pick<L2BlockSource, 'getBlocks' | 'getBlockHeader' | 'getL2Tips'>,
+    l2BlockSource: Pick<L2BlockSource, 'getPublishedBlocks' | 'getBlockHeader' | 'getL2Tips'>,
     localData: L2BlockStreamLocalDataProvider,
     handler: L2BlockStreamEventHandler,
     public readonly tracer: Tracer,

package/dest/event_loop_monitor.d.ts

@@ -1,18 +0,0 @@
-import { type Meter } from './telemetry.js';
-/**
- * Detector for custom Aztec attributes
- */
-export declare class EventLoopMonitor {
-    private meter;
-    private eventLoopDelayGauges;
-    private eventLoopUilization;
-    private eventLoopTime;
-    private started;
-    private lastELU;
-    private eventLoopDelay;
-    constructor(meter: Meter);
-    start(): void;
-    stop(): void;
-    private measure;
-}
-//# sourceMappingURL=event_loop_monitor.d.ts.map

package/dest/event_loop_monitor.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"event_loop_monitor.d.ts","sourceRoot":"","sources":["../src/event_loop_monitor.ts"],"names":[],"mappings":"AAIA,OAAO,EAEL,KAAK,KAAK,EAIX,MAAM,gBAAgB,CAAC;AAExB;;GAEG;AACH,qBAAa,gBAAgB;IAmBf,OAAO,CAAC,KAAK;IAlBzB,OAAO,CAAC,oBAAoB,CAQ1B;IAEF,OAAO,CAAC,mBAAmB,CAAkB;IAC7C,OAAO,CAAC,aAAa,CAAgB;IAErC,OAAO,CAAC,OAAO,CAAS;IAExB,OAAO,CAAC,OAAO,CAAmC;IAClD,OAAO,CAAC,cAAc,CAAoB;gBAEtB,KAAK,EAAE,KAAK;IAgChC,KAAK,IAAI,IAAI;IAab,IAAI,IAAI,IAAI;IAaZ,OAAO,CAAC,OAAO,CAyBb;CACH"}