@aztec/telemetry-client 0.0.0-test.0

package/src/prom_otel_adapter.ts

@@ -0,0 +1,326 @@
+import { type Logger, createLogger } from '@aztec/foundation/log';
+
+import { Registry } from 'prom-client';
+
+import type { Meter, MetricsType, ObservableGauge, TelemetryClient } from './telemetry.js';
+
+/**
+ * Types matching the gossipsub and libp2p services
+ */
+type TopicStr = string;
+export type TopicLabel = string;
+export type TopicStrToLabel = Map<TopicStr, TopicLabel>;
+
+export enum MessageSource {
+  forward = 'forward',
+  publish = 'publish',
+}
+
+type NoLabels = Record<string, never>;
+type LabelsGeneric = Record<string, string | number>;
+type LabelKeys<Labels extends LabelsGeneric> = Extract<keyof Labels, string>;
+interface CollectFn<Labels extends LabelsGeneric> {
+  (metric: IGauge<Labels>): void;
+}
+
+interface IGauge<Labels extends LabelsGeneric = NoLabels> {
+  inc: NoLabels extends Labels ? (value?: number) => void : (labels: Labels, value?: number) => void;
+  set: NoLabels extends Labels ? (value: number) => void : (labels: Labels, value: number) => void;
+
+  collect?(): void;
+  addCollect(collectFn: CollectFn<Labels>): void;
+}
+
+interface IHistogram<Labels extends LabelsGeneric = NoLabels> {
+  startTimer(): () => void;
+
+  observe: NoLabels extends Labels ? (value: number) => void : (labels: Labels, value: number) => void;
+
+  reset(): void;
+}
+
+interface IAvgMinMax<Labels extends LabelsGeneric = NoLabels> {
+  set: NoLabels extends Labels ? (values: number[]) => void : (labels: Labels, values: number[]) => void;
+}
+
+export type GaugeConfig<Labels extends LabelsGeneric> = {
+  name: string;
+  help: string;
+} & (NoLabels extends Labels
+  ? { labelNames?: never }
+  : { labelNames: [LabelKeys<Labels>, ...Array<LabelKeys<Labels>>] });
+
+export type HistogramConfig<Labels extends LabelsGeneric> = GaugeConfig<Labels> & {
+  buckets?: number[];
+};
+
+export type AvgMinMaxConfig<Labels extends LabelsGeneric> = GaugeConfig<Labels>;
+
+export interface MetricsRegister {
+  gauge<Labels extends LabelsGeneric = NoLabels>(config: GaugeConfig<Labels>): IGauge<Labels>;
+  histogram<Labels extends LabelsGeneric = NoLabels>(config: HistogramConfig<Labels>): IHistogram<Labels>;
+  avgMinMax<Labels extends LabelsGeneric = NoLabels>(config: AvgMinMaxConfig<Labels>): IAvgMinMax<Labels>;
+}
+
+/**Otel MetricsType Adapters
+ *
+ * Some dependencies we use export metrics directly in a Prometheus format
+ * This adapter is used to convert those metrics to a format that we can use with OpenTelemetry
+ *
+ * Affected services include:
+ * - chainsafe/gossipsub
+ * - libp2p
+ */
+
+export class OtelGauge<Labels extends LabelsGeneric = NoLabels> implements IGauge<Labels> {
+  private gauge: ObservableGauge;
+  private currentValue: number = 0;
+  private labeledValues: Map<string, number> = new Map();
+  private collectFns: CollectFn<Labels>[] = [];
+
+  private _collect: () => void = () => {};
+  get collect(): () => void {
+    return this._collect;
+  }
+  set collect(fn: () => void) {
+    this._collect = fn;
+  }
+
+  constructor(
+    private logger: Logger,
+    meter: Meter,
+    name: string,
+    help: string,
+    private labelNames: Array<keyof Labels> = [],
+  ) {
+    this.gauge = meter.createObservableGauge(name as MetricsType, {
+      description: help,
+    });
+
+    // Only observe in the callback when collect() is called
+    this.gauge.addCallback(this.handleObservation.bind(this));
+  }
+
+  /**
+   * Add a collect callback
+   * @param collectFn - Callback function
+   */
+  addCollect(collectFn: CollectFn<Labels>): void {
+    this.collectFns.push(collectFn);
+  }
+
+  handleObservation(result: any): void {
+    // Execute the main collect function if assigned
+    this._collect();
+
+    // Execute all the collect functions
+    for (const fn of this.collectFns) {
+      fn(this);
+    }
+
+    // Report the current values
+    if (this.labelNames.length === 0) {
+      result.observe(this.currentValue);
+      return;
+    }
+
+    for (const [labelStr, value] of this.labeledValues.entries()) {
+      const labels = this.parseLabelsSafely(labelStr);
+      if (labels) {
+        result.observe(value, labels);
+      }
+    }
+  }
+
+  /**
+   * Increments the gauge value
+   * @param labelsOrValue - Labels object or numeric value
+   * @param value - Value to increment by (defaults to 1)
+   */
+  inc(value?: number): void;
+  inc(labels: Labels, value?: number): void;
+  inc(labelsOrValue?: Labels | number, value?: number): void {
+    if (typeof labelsOrValue === 'number') {
+      this.currentValue += labelsOrValue;
+      return;
+    }
+
+    if (labelsOrValue) {
+      this.validateLabels(labelsOrValue);
+      const labelKey = JSON.stringify(labelsOrValue);
+      const currentValue = this.labeledValues.get(labelKey) ?? 0;
+      this.labeledValues.set(labelKey, currentValue + (value ?? 1));
+      return;
+    }
+
+    this.currentValue += value ?? 1;
+  }
+
+  /**
+   * Sets the gauge value
+   * @param labelsOrValue - Labels object or numeric value
+   * @param value - Value to set
+   */
+  set(value: number): void;
+  set(labels: Labels, value: number): void;
+  set(labelsOrValue: Labels | number, value?: number): void {
+    if (typeof labelsOrValue === 'number') {
+      this.currentValue = labelsOrValue;
+      return;
+    }
+
+    this.validateLabels(labelsOrValue);
+    const labelKey = JSON.stringify(labelsOrValue);
+    this.labeledValues.set(labelKey, value!);
+  }
+
+  /**
+   * Decrements the gauge value
+   * @param labels - Optional labels object
+   */
+  dec(labels?: Labels): void {
+    if (labels) {
+      this.validateLabels(labels);
+      const labelKey = JSON.stringify(labels);
+      const currentValue = this.labeledValues.get(labelKey) ?? 0;
+      this.labeledValues.set(labelKey, currentValue - 1);
+      return;
+    }
+
+    this.currentValue -= 1;
+  }
+
+  /**
+   * Resets the gauge to initial state
+   */
+  reset(): void {
+    this.currentValue = 0;
+    this.labeledValues.clear();
+  }
+
+  /**
+   * Validates that provided labels match the expected schema
+   * @param labels - Labels object to validate
+   * @throws Error if invalid labels are provided
+   */
+  private validateLabels(labels: Labels): void {
+    if (this.labelNames.length === 0) {
+      throw new Error('Gauge was initialized without labels support');
+    }
+
+    for (const key of Object.keys(labels)) {
+      if (!this.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
+   * @returns Labels object or null if parsing fails
+   */
+  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;
+    }
+  }
+}
+
+/**
+ * Noop implementation of a Historgram collec
+ */
+class NoopOtelHistogram<Labels extends LabelsGeneric = NoLabels> implements IHistogram<Labels> {
+  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;
+  }
+
+  reset(): void {
+    // OpenTelemetry histograms cannot be reset, but we implement the interface
+    this.logger.warn('OpenTelemetry histograms cannot be reset');
+  }
+}
+
+/**
+ * Noop implementation of an AvgMinMax collector
+ */
+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 {}
+}
+
+/**
+ * Otel metrics Adapter
+ *
+ * Maps the PromClient based MetricsRegister from gossipsub and discv5 services to the Otel MetricsRegister
+ */
+export class OtelMetricsAdapter extends Registry implements MetricsRegister {
+  private readonly meter: Meter;
+
+  constructor(
+    telemetryClient: TelemetryClient,
+    private logger: Logger = createLogger('telemetry:otel-metrics-adapter'),
+  ) {
+    super();
+    this.meter = telemetryClient.getMeter('metrics-adapter');
+  }
+
+  gauge<Labels extends LabelsGeneric = NoLabels>(configuration: GaugeConfig<Labels>): IGauge<Labels> {
+    return new OtelGauge<Labels>(
+      this.logger,
+      this.meter,
+      configuration.name as MetricsType,
+      configuration.help,
+      configuration.labelNames,
+    );
+  }
+
+  histogram<Labels extends LabelsGeneric = NoLabels>(configuration: HistogramConfig<Labels>): IHistogram<Labels> {
+    return new NoopOtelHistogram<Labels>(
+      this.logger,
+      this.meter,
+      configuration.name as MetricsType,
+      configuration.help,
+      configuration.buckets,
+      configuration.labelNames,
+    );
+  }
+
+  avgMinMax<Labels extends LabelsGeneric = NoLabels>(configuration: AvgMinMaxConfig<Labels>): IAvgMinMax<Labels> {
+    return new NoopOtelAvgMinMax<Labels>(
+      this.logger,
+      this.meter,
+      configuration.name as MetricsType,
+      configuration.help,
+      configuration.labelNames,
+    );
+  }
+}

package/src/start.ts

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

package/src/telemetry.ts

@@ -0,0 +1,267 @@
+import {
+  type AttributeValue,
+  type BatchObservableCallback,
+  type MetricOptions,
+  type Observable,
+  type BatchObservableResult as OtelBatchObservableResult,
+  type Gauge as OtelGauge,
+  type Histogram as OtelHistogram,
+  type ObservableGauge as OtelObservableGauge,
+  type ObservableResult as OtelObservableResult,
+  type ObservableUpDownCounter as OtelObservableUpDownCounter,
+  type UpDownCounter as OtelUpDownCounter,
+  type Span,
+  SpanStatusCode,
+  type Tracer,
+} from '@opentelemetry/api';
+import { isPromise } from 'node:util/types';
+
+import type * as Attributes from './attributes.js';
+import type * as Metrics from './metrics.js';
+import { getTelemetryClient } from './start.js';
+
+export { type Span, SpanStatusCode, ValueType } from '@opentelemetry/api';
+
+type ValuesOf<T> = T extends Record<string, infer U> ? U : never;
+
+/** Global registry of attributes */
+type AttributesType = Partial<Record<ValuesOf<typeof Attributes>, AttributeValue>>;
+export type { AttributesType };
+
+/** Global registry of metrics */
+type MetricsType = (typeof Metrics)[keyof typeof Metrics];
+export type { MetricsType };
+
+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 { Tracer };
+
+// INTERNAL NOTE: this interface is the same as opentelemetry's Meter, but with proper types
+/**
+ * A meter that provides instruments for recording metrics.
+ */
+export interface Meter {
+  /**
+   * Creates a new gauge instrument. A gauge is a metric that represents a single numerical value that can arbitrarily go up and down.
+   * @param name - The name of the gauge
+   * @param options - The options for the gauge
+   */
+  createGauge(name: MetricsType, options?: MetricOptions): Gauge;
+
+  /**
+   * Creates a new gauge instrument. A gauge is a metric that represents a single numerical value that can arbitrarily go up and down.
+   * @param name - The name of the gauge
+   * @param options - The options for the gauge
+   */
+  createObservableGauge(name: MetricsType, options?: MetricOptions): ObservableGauge;
+
+  addBatchObservableCallback(
+    callback: BatchObservableCallback<AttributesType>,
+    observables: Observable<AttributesType>[],
+  ): void;
+
+  removeBatchObservableCallback(
+    callback: BatchObservableCallback<AttributesType>,
+    observables: Observable<AttributesType>[],
+  ): void;
+
+  /**
+   * Creates a new histogram instrument. A histogram is a metric that samples observations (usually things like request durations or response sizes) and counts them in configurable buckets.
+   * @param name - The name of the histogram
+   * @param options - The options for the histogram
+   */
+  createHistogram(name: MetricsType, options?: MetricOptions): Histogram;
+
+  /**
+   * Creates a new counter instrument. A counter can go up or down with a delta from the previous value.
+   * @param name - The name of the counter
+   * @param options - The options for the counter
+   */
+  createUpDownCounter(name: MetricsType, options?: MetricOptions): UpDownCounter;
+
+  /**
+   * Creates a new gauge instrument. A gauge is a metric that represents a single numerical value that can arbitrarily go up and down.
+   * @param name - The name of the gauge
+   * @param options - The options for the gauge
+   */
+  createObservableUpDownCounter(name: MetricsType, options?: MetricOptions): ObservableUpDownCounter;
+}
+
+/**
+ * A telemetry client that provides meters for recording metrics.
+ */
+export interface TelemetryClient {
+  /**
+   * Whether the client is enabled and reporting metrics.
+   **/
+  isEnabled(): boolean;
+  /**
+   * Creates a new meter
+   * @param name - The name of the meter.
+   */
+  getMeter(name: string): Meter;
+
+  /**
+   * Creates a new tracer
+   * @param name - The name of the tracer.
+   */
+  getTracer(name: string): Tracer;
+
+  /**
+   * Stops the telemetry client.
+   */
+  stop(): Promise<void>;
+
+  /**
+   * Flushes the telemetry client.
+   */
+  flush(): Promise<void>;
+}
+
+/** Objects that adhere to this interface can use @trackSpan */
+export interface Traceable {
+  tracer: Tracer;
+}
+
+type SpanDecorator<T extends Traceable, F extends (...args: any[]) => any> = (
+  originalMethod: F,
+  context: ClassMethodDecoratorContext<T>,
+) => F;
+
+/**
+ * Starts a new span whenever the decorated method is called.
+ * @param spanName - The name of the span to create. Can be a string or a function that returns a string.
+ * @param attributes - Initial attributes to set on the span. If a function is provided, it will be called with the arguments of the method.
+ * @param extraAttributes - Extra attributes to set on the span after the method is called. Will be called with the return value of the method. Note: if the function throws then this will not be called.
+ * @returns A decorator that wraps the method in a span.
+ *
+ * @privateRemarks
+ * This code looks complex but it's not that difficult:
+ * - decorators are functions that _replace_ a method with a different implementation
+ * - normal decorators can't take function arguments, but if we write a function that returns a decorator, we can pass arguments to that function
+ *
+ * The trackSpan function takes a span's name and some attributes and builds a decorator that wraps a method in a span with the given name and props
+ * The decorator can currently only be applied to methods on classes that have a `tracer` property. The compiler will enforce this.
+ */
+export function trackSpan<T extends Traceable, F extends (...args: any[]) => any>(
+  spanName: string | ((this: T, ...args: Parameters<F>) => string),
+  attributes?: AttributesType | ((this: T, ...args: Parameters<F>) => Promise<AttributesType> | AttributesType),
+  extraAttributes?: (this: T, returnValue: Awaited<ReturnType<F>>) => AttributesType,
+): SpanDecorator<T, F> {
+  // the return value of trackSpan is a decorator
+  return (originalMethod: F, _context: ClassMethodDecoratorContext<T>) => {
+    // the return value of the decorator replaces the original method
+    // in this wrapper method we start a span, call the original method, and then end the span
+    return async function replacementMethod(this: T, ...args: Parameters<F>): Promise<Awaited<ReturnType<F>>> {
+      const name = typeof spanName === 'function' ? spanName.call(this, ...args) : spanName;
+      const currentAttrs = typeof attributes === 'function' ? await attributes.call(this, ...args) : attributes;
+
+      // 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
+      return this.tracer.startActiveSpan(name, async (span: Span) => {
+        span.setAttributes(currentAttrs ?? {});
+
+        try {
+          const res = await originalMethod.call(this, ...args);
+          const extraAttrs = extraAttributes?.call(this, res);
+          span.setAttributes(extraAttrs ?? {});
+          return res;
+        } catch (err) {
+          span.setStatus({
+            code: SpanStatusCode.ERROR,
+            message: String(err),
+          });
+          throw err;
+        } finally {
+          span.end();
+        }
+      });
+    } as F;
+  };
+}
+
+/**
+ * Runs an event callback in a span. The span is started immediately and completes once the callback finishes running.
+ * The span will have two events added: 'callbackStart' and 'callbackEnd' to mark the start and end of the callback.
+ *
+ * @param tracer - The tracer instance to use
+ * @param spanName - The name of the span to create
+ * @param attributes - Initial attributes to set on the span
+ * @param callback - The callback to wrap in a span
+ *
+ * @returns - A new function that wraps the callback in a span
+ */
+export function wrapCallbackInSpan<F extends (...args: any[]) => any>(
+  tracer: Tracer,
+  spanName: string,
+  attributes: AttributesType,
+  callback: F,
+): F {
+  const span = tracer.startSpan(spanName, { attributes });
+  return (async (...args: Parameters<F>) => {
+    try {
+      span.addEvent('callbackStart');
+      const res = await callback(...args);
+      return res;
+    } catch (err) {
+      span.setStatus({
+        code: SpanStatusCode.ERROR,
+        message: String(err),
+      });
+      throw err;
+    } finally {
+      span.addEvent('callbackEnd');
+      span.end();
+    }
+  }) as F;
+}
+
+export function runInSpan<A extends any[], R>(
+  tracer: Tracer | string,
+  spanName: string,
+  callback: (span: Span, ...args: A) => R,
+): (...args: A) => R {
+  return (...args: A): R => {
+    const actualTracer = typeof tracer === 'string' ? getTelemetryClient().getTracer(tracer) : tracer;
+    return actualTracer.startActiveSpan(spanName, (span: Span): R => {
+      let deferSpanEnd = false;
+      try {
+        const res = callback(span, ...args);
+        if (isPromise(res)) {
+          deferSpanEnd = true;
+          return res
+            .catch(err => {
+              span.setStatus({
+                code: SpanStatusCode.ERROR,
+                message: String(err),
+              });
+              throw err;
+            })
+            .finally(() => {
+              span.end();
+            }) as R;
+        } else {
+          return res;
+        }
+      } catch (err) {
+        span.setStatus({
+          code: SpanStatusCode.ERROR,
+          message: String(err),
+        });
+        throw err;
+      } finally {
+        if (!deferSpanEnd) {
+          span.end();
+        }
+      }
+    });
+  };
+}

package/src/vendor/attributes.ts

@@ -0,0 +1,5 @@
+// See https://opentelemetry.io/docs/specs/semconv/rpc/json-rpc/
+export const ATTR_JSONRPC_METHOD = 'rpc.method';
+export const ATTR_JSONRPC_REQUEST_ID = 'rpc.jsonrpc.request_id';
+export const ATTR_JSONRPC_ERROR_CODE = 'rpc.jsonrpc.error_code';
+export const ATTR_JSONRPC_ERROR_MSG = 'rpc.jsonrpc.error_message';