@aztec/telemetry-client 0.0.1-commit.b655e406 → 0.0.1-commit.b8a057fa

package/src/prom_otel_adapter.ts

@@ -1,9 +1,10 @@
-import { type Logger, createLogger } from '@aztec/foundation/log';
+import { type Logger, type LoggerBindings, createLogger } from '@aztec/foundation/log';
 import { Timer } from '@aztec/foundation/timer';
 
 import { Registry } from 'prom-client';
 
-import type { Histogram, Meter, MetricsType, ObservableGauge, TelemetryClient } from './telemetry.js';
+import type { MetricDefinition } from './metrics.js';
+import type { Histogram, Meter, ObservableGauge, TelemetryClient } from './telemetry.js';
 
 /**
  * Types matching the gossipsub and libp2p services
@@ -94,9 +95,8 @@ export class OtelGauge<Labels extends LabelsGeneric = NoLabels> implements IGaug
     help: string,
     private labelNames: Array<keyof Labels> = [],
   ) {
-    this.gauge = meter.createObservableGauge(name as MetricsType, {
-      description: help,
-    });
+    const metricDef: MetricDefinition = { name, description: help };
+    this.gauge = meter.createObservableGauge(metricDef);
 
     // Only observe in the callback when collect() is called
     this.gauge.addCallback(this.handleObservation.bind(this));
@@ -214,8 +214,8 @@ export class OtelHistogram<Labels extends LabelsGeneric = NoLabels> implements I
     buckets: number[] = [],
     private labelNames: Array<keyof Labels> = [],
   ) {
-    this.histogram = meter.createHistogram(name as MetricsType, {
-      description: help,
+    const metricDef: MetricDefinition = { name, description: help };
+    this.histogram = meter.createHistogram(metricDef, {
       advice: buckets.length ? { explicitBucketBoundaries: buckets } : undefined,
     });
   }
@@ -289,15 +289,9 @@ export class OtelAvgMinMax<Labels extends LabelsGeneric = NoLabels> implements I
   ) {
     // 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)`,
-      }),
+      avg: meter.createObservableGauge({ name: `${name}_avg`, description: `${help} (average)` }),
+      min: meter.createObservableGauge({ name: `${name}_min`, description: `${help} (minimum)` }),
+      max: meter.createObservableGauge({ name: `${name}_max`, description: `${help} (maximum)` }),
     };
 
     // Register callbacks for each gauge
@@ -416,12 +410,11 @@ function parseLabelsSafely<Labels extends LabelsGeneric>(labelStr: string, logge
  */
 export class OtelMetricsAdapter extends Registry implements MetricsRegister {
   private readonly meter: Meter;
+  private logger: Logger;
 
-  constructor(
-    telemetryClient: TelemetryClient,
-    private logger: Logger = createLogger('telemetry:otel-metrics-adapter'),
-  ) {
+  constructor(telemetryClient: TelemetryClient, bindings?: LoggerBindings) {
     super();
+    this.logger = createLogger('telemetry:otel-metrics-adapter', bindings);
     this.meter = telemetryClient.getMeter('metrics-adapter');
   }
 
@@ -429,7 +422,7 @@ export class OtelMetricsAdapter extends Registry implements MetricsRegister {
     return new OtelGauge<Labels>(
       this.logger,
       this.meter,
-      configuration.name as MetricsType,
+      configuration.name,
       configuration.help,
       configuration.labelNames,
     );
@@ -439,7 +432,7 @@ export class OtelMetricsAdapter extends Registry implements MetricsRegister {
     return new OtelHistogram<Labels>(
       this.logger,
       this.meter,
-      configuration.name as MetricsType,
+      configuration.name,
       configuration.help,
       configuration.buckets,
       configuration.labelNames,
@@ -450,7 +443,7 @@ export class OtelMetricsAdapter extends Registry implements MetricsRegister {
     return new OtelAvgMinMax<Labels>(
       this.logger,
       this.meter,
-      configuration.name as MetricsType,
+      configuration.name,
       configuration.help,
       configuration.labelNames,
     );

package/src/start.ts

@@ -1,8 +1,7 @@
-import { createLogger } from '@aztec/foundation/log';
+import { type LoggerBindings, 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';
@@ -10,15 +9,25 @@ export * from './config.js';
 let initialized = false;
 let telemetry: TelemetryClient = new NoopTelemetryClient();
 
-export function initTelemetryClient(config: TelemetryClientConfig): TelemetryClient {
-  const log = createLogger('telemetry:client');
+export async function initTelemetryClient(
+  config: TelemetryClientConfig,
+  bindings?: LoggerBindings,
+): Promise<TelemetryClient> {
+  const log = createLogger('telemetry:client', bindings);
   if (initialized) {
     log.warn('Telemetry client has already been initialized once');
     return telemetry;
   }
 
-  if (config.metricsCollectorUrl || config.publicMetricsCollectorUrl) {
+  if (
+    config.metricsCollectorUrl ||
+    config.publicMetricsCollectorUrl ||
+    config.tracesCollectorUrl ||
+    config.logsCollectorUrl
+  ) {
     log.info(`Using OpenTelemetry client with custom collector`);
+    // Lazy load OpenTelemetry to avoid loading heavy deps at startup
+    const { OpenTelemetryClient } = await import('./otel.js');
     telemetry = OpenTelemetryClient.createAndStart(config, log);
   } else {
     log.info('Using NoopTelemetryClient');

package/src/telemetry.ts

@@ -1,6 +1,7 @@
 import {
   type AttributeValue,
   type BatchObservableCallback,
+  type Context,
   type MetricOptions,
   type Observable,
   type BatchObservableResult as OtelBatchObservableResult,
@@ -14,13 +15,14 @@ import {
   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 type { MetricDefinition } from './metrics.js';
 import { getTelemetryClient } from './start.js';
 
-export { type Span, SpanStatusCode, ValueType } from '@opentelemetry/api';
+export { toMetricOptions, createUpDownCounterWithDefault } from './metric-utils.js';
+
+export { type Span, SpanStatusCode, ValueType, type Context } from '@opentelemetry/api';
 
 type ValuesOf<T> = T extends Record<string, infer U> ? U : never;
 
@@ -46,7 +48,6 @@ type BannedMetricAttributeNames = (typeof Attributes)[
   | 'TX_HASH'
   | 'PROVING_JOB_ID'
   | 'P2P_ID'
-  | 'P2P_REQ_RESP_BATCH_REQUESTS_COUNT'
   | 'TARGET_ADDRESS'
   | 'MANA_USED'
   | 'TOTAL_INSTRUCTIONS'];
@@ -54,11 +55,13 @@ type BannedMetricAttributeNames = (typeof Attributes)[
 /** Global registry of attributes */
 export type AttributesType = Partial<Record<AttributeNames, AttributeValue>>;
 
+export type AllowedAttributeNames = Exclude<AttributeNames, BannedMetricAttributeNames>;
+
 /** Subset of attributes allowed to be added to metrics */
-export type MetricAttributesType = Partial<Record<Exclude<AttributeNames, BannedMetricAttributeNames>, AttributeValue>>;
+export type MetricAttributesType = Partial<Record<AllowedAttributeNames, AttributeValue>>;
 
-/** Global registry of metrics */
-export type MetricsType = (typeof Metrics)[keyof typeof Metrics];
+/** Re-export MetricDefinition for convenience */
+export type { MetricDefinition } from './metrics.js';
 
 export type Gauge = OtelGauge<MetricAttributesType>;
 export type Histogram = OtelHistogram<MetricAttributesType>;
@@ -77,17 +80,15 @@ export type { Tracer };
 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
+   * @param metric - The metric definition
    */
-  createGauge(name: MetricsType, options?: MetricOptions): Gauge;
+  createGauge(metric: MetricDefinition): 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
+   * Creates a new observable gauge instrument. A gauge is a metric that represents a single numerical value that can arbitrarily go up and down.
+   * @param metric - The metric definition
    */
-  createObservableGauge(name: MetricsType, options?: MetricOptions): ObservableGauge;
+  createObservableGauge(metric: MetricDefinition): ObservableGauge;
 
   addBatchObservableCallback(
     callback: BatchObservableCallback<AttributesType>,
@@ -101,24 +102,22 @@ export interface Meter {
 
   /**
    * 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
+   * @param metric - The metric definition
+   * @param extraOptions - Optional extra options (e.g., advice for bucket boundaries)
    */
-  createHistogram(name: MetricsType, options?: MetricOptions): Histogram;
+  createHistogram(metric: MetricDefinition, extraOptions?: Partial<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
+   * @param metric - The metric definition
    */
-  createUpDownCounter(name: MetricsType, options?: MetricOptions): UpDownCounter;
+  createUpDownCounter(metric: MetricDefinition): 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
+   * Creates a new observable up/down counter instrument.
+   * @param metric - The metric definition
    */
-  createObservableUpDownCounter(name: MetricsType, options?: MetricOptions): ObservableUpDownCounter;
+  createObservableUpDownCounter(metric: MetricDefinition): ObservableUpDownCounter;
 }
 
 /**
@@ -160,6 +159,17 @@ export interface TelemetryClient {
    * Updates the roles that would share telemetry (if enabled)
    */
   setPublicTelemetryCollectFrom(roles: string[]): void;
+
+  /**
+   * Get current trace context as an opaque string for propagation.
+   * Returns the W3C traceparent header value if a trace is active, undefined otherwise.
+   */
+  getTraceContext(): string | undefined;
+
+  /**
+   * Recreates a context propagated by a remote system
+   */
+  extractPropagatedContext(traceContext: string): Context | undefined;
 }
 
 /** Objects that adhere to this interface can use @trackSpan */
@@ -204,24 +214,36 @@ export function trackSpan<T extends Traceable, F extends (...args: any[]) => any
       // "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-v22.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();
-        }
-      });
+      return this.tracer.startActiveSpan(
+        name,
+        {
+          attributes: currentAttrs,
+        },
+        async (span: Span) => {
+          try {
+            const res = await originalMethod.call(this, ...args);
+            const extraAttrs = extraAttributes?.call(this, res);
+            span.setAttributes(extraAttrs ?? {});
+            span.setStatus({
+              code: SpanStatusCode.OK,
+            });
+            return res;
+          } catch (err) {
+            span.setStatus({
+              code: SpanStatusCode.ERROR,
+              message: String(err),
+            });
+
+            if (typeof err === 'string' || (err && err instanceof Error)) {
+              span.recordException(err);
+            }
+
+            throw err;
+          } finally {
+            span.end();
+          }
+        },
+      );
     } as F;
   };
 }
@@ -265,41 +287,57 @@ export function wrapCallbackInSpan<F extends (...args: any[]) => any>(
 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 => {
+  callback: (span: Span, ...args: A) => Promise<R>,
+): (...args: A) => Promise<R> {
+  return (...args: A): Promise<R> => {
     const actualTracer = typeof tracer === 'string' ? getTelemetryClient().getTracer(tracer) : tracer;
-    return actualTracer.startActiveSpan(spanName, (span: Span): R => {
-      let deferSpanEnd = false;
+    return actualTracer.startActiveSpan(spanName, async (span: Span): Promise<R> => {
       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;
-        }
+        const res = await callback(span, ...args);
+        span.setStatus({
+          code: SpanStatusCode.OK,
+        });
+
+        return res;
       } catch (err) {
         span.setStatus({
           code: SpanStatusCode.ERROR,
           message: String(err),
         });
+        if (typeof err === 'string' || (err && err instanceof Error)) {
+          span.recordException(err);
+        }
         throw err;
       } finally {
-        if (!deferSpanEnd) {
-          span.end();
-        }
+        span.end();
       }
     });
   };
 }
+
+/**
+ * Execute a callback within a span immediately (for one-off traced calls).
+ * Unlike runInSpan which returns a reusable function, this executes right away.
+ */
+export function execInSpan<R>(
+  tracer: Tracer | string,
+  spanName: string,
+  callback: (span: Span) => Promise<R>,
+): Promise<R> {
+  const actualTracer = typeof tracer === 'string' ? getTelemetryClient().getTracer(tracer) : tracer;
+  return actualTracer.startActiveSpan(spanName, async (span: Span): Promise<R> => {
+    try {
+      const res = await callback(span);
+      span.setStatus({ code: SpanStatusCode.OK });
+      return res;
+    } catch (err) {
+      span.setStatus({ code: SpanStatusCode.ERROR, message: String(err) });
+      if (typeof err === 'string' || (err && err instanceof Error)) {
+        span.recordException(err);
+      }
+      throw err;
+    } finally {
+      span.end();
+    }
+  });
+}

package/src/wrappers/fetch.ts

@@ -9,12 +9,17 @@ import { ATTR_JSONRPC_METHOD, ATTR_JSONRPC_REQUEST_ID } from '../vendor/attribut
 
 /**
  * Makes a fetch function that retries based on the given attempts and propagates trace information.
- * @param retries - Sequence of intervals (in seconds) to retry.
+ * @param retries - Sequence of intervals (in seconds) to retry, or a factory function returning an iterator for custom/indefinite backoff.
  * @param noRetry - Whether to stop retries on server errors.
  * @param log - Optional logger for logging attempts.
  * @returns A fetch function.
  */
-export function makeTracedFetch(retries: number[], defaultNoRetry: boolean, fetch = defaultFetch, log?: Logger) {
+export function makeTracedFetch(
+  retries: number[] | (() => Generator<number>),
+  defaultNoRetry: boolean,
+  fetch = defaultFetch,
+  log?: Logger,
+) {
   return (host: string, body: unknown, extraHeaders: Record<string, string> = {}, noRetry?: boolean) => {
     const telemetry = getTelemetryClient();
     return telemetry.getTracer('fetch').startActiveSpan(`JsonRpcClient`, { kind: SpanKind.CLIENT }, async span => {
@@ -27,10 +32,11 @@ export function makeTracedFetch(retries: number[], defaultNoRetry: boolean, fetc
         }
         const headers = { ...extraHeaders };
         propagation.inject(context.active(), headers);
+        const backoff = typeof retries === 'function' ? retries() : makeBackoff(retries);
         return await retry(
           () => fetch(host, body, headers, noRetry ?? defaultNoRetry),
           `JsonRpcClient request to ${host}`,
-          makeBackoff(retries),
+          backoff,
           log,
           false,
         );

package/src/wrappers/index.ts

@@ -1,3 +1,2 @@
-export * from './l2_block_stream.js';
 export * from './fetch.js';
 export * from './json_rpc_server.js';

package/dest/wrappers/l2_block_stream.d.ts

@@ -1,15 +0,0 @@
-import { type L2BlockSource, L2BlockStream, type L2BlockStreamEventHandler, type L2BlockStreamLocalDataProvider } from '@aztec/stdlib/block';
-import { type Traceable, type Tracer } from '@aztec/telemetry-client';
-/** Extends an L2BlockStream with a tracer to create a new trace per iteration. */
-export declare class TraceableL2BlockStream extends L2BlockStream implements Traceable {
-    readonly tracer: Tracer;
-    private readonly name;
-    constructor(l2BlockSource: Pick<L2BlockSource, 'getPublishedBlocks' | 'getBlockHeader' | 'getL2Tips'>, localData: L2BlockStreamLocalDataProvider, handler: L2BlockStreamEventHandler, tracer: Tracer, name?: string, log?: import("@aztec/foundation/log").Logger, opts?: {
-        proven?: boolean;
-        pollIntervalMS?: number;
-        batchSize?: number;
-        startingBlock?: number;
-    });
-    work(): Promise<void>;
-}
-//# sourceMappingURL=l2_block_stream.d.ts.map

package/dest/wrappers/l2_block_stream.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"l2_block_stream.d.ts","sourceRoot":"","sources":["../../src/wrappers/l2_block_stream.ts"],"names":[],"mappings":"AACA,OAAO,EACL,KAAK,aAAa,EAClB,aAAa,EACb,KAAK,yBAAyB,EAC9B,KAAK,8BAA8B,EACpC,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,KAAK,SAAS,EAAE,KAAK,MAAM,EAAa,MAAM,yBAAyB,CAAC;AAEjF,kFAAkF;AAClF,qBAAa,sBAAuB,SAAQ,aAAc,YAAW,SAAS;aAK1D,MAAM,EAAE,MAAM;IAC9B,OAAO,CAAC,QAAQ,CAAC,IAAI;gBAJrB,aAAa,EAAE,IAAI,CAAC,aAAa,EAAE,oBAAoB,GAAG,gBAAgB,GAAG,WAAW,CAAC,EACzF,SAAS,EAAE,8BAA8B,EACzC,OAAO,EAAE,yBAAyB,EAClB,MAAM,EAAE,MAAM,EACb,IAAI,GAAE,MAAwB,EAC/C,GAAG,yCAAqC,EACxC,IAAI,GAAE;QACJ,MAAM,CAAC,EAAE,OAAO,CAAC;QACjB,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,aAAa,CAAC,EAAE,MAAM,CAAC;KACnB;IAUC,IAAI;CAGd"}

package/dest/wrappers/l2_block_stream.js

@@ -1,26 +0,0 @@
-function _ts_decorate(decorators, target, key, desc) {
-    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
-    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
-    else for(var i = decorators.length - 1; i >= 0; i--)if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
-    return c > 3 && r && Object.defineProperty(target, key, r), r;
-}
-import { createLogger } from '@aztec/foundation/log';
-import { L2BlockStream } from '@aztec/stdlib/block';
-import { trackSpan } from '@aztec/telemetry-client';
-/** Extends an L2BlockStream with a tracer to create a new trace per iteration. */ export class TraceableL2BlockStream extends L2BlockStream {
-    tracer;
-    name;
-    constructor(l2BlockSource, localData, handler, tracer, name = 'L2BlockStream', log = createLogger('types:block_stream'), opts = {}){
-        super(l2BlockSource, localData, handler, log, opts), this.tracer = tracer, this.name = name;
-    }
-    // We need to use a non-arrow function to be able to access `this`
-    // See https://www.typescriptlang.org/docs/handbook/2/functions.html#declaring-this-in-a-function
-    work() {
-        return super.work();
-    }
-}
-_ts_decorate([
-    trackSpan(function() {
-        return `${this.name}.work`;
-    })
-], TraceableL2BlockStream.prototype, "work", null);

package/src/wrappers/l2_block_stream.ts

@@ -1,37 +0,0 @@
-import { createLogger } from '@aztec/foundation/log';
-import {
-  type L2BlockSource,
-  L2BlockStream,
-  type L2BlockStreamEventHandler,
-  type L2BlockStreamLocalDataProvider,
-} from '@aztec/stdlib/block';
-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, 'getPublishedBlocks' | 'getBlockHeader' | 'getL2Tips'>,
-    localData: L2BlockStreamLocalDataProvider,
-    handler: L2BlockStreamEventHandler,
-    public readonly tracer: Tracer,
-    private readonly name: string = 'L2BlockStream',
-    log = createLogger('types:block_stream'),
-    opts: {
-      proven?: boolean;
-      pollIntervalMS?: number;
-      batchSize?: number;
-      startingBlock?: number;
-    } = {},
-  ) {
-    super(l2BlockSource, localData, handler, log, opts);
-  }
-
-  // We need to use a non-arrow function to be able to access `this`
-  // See https://www.typescriptlang.org/docs/handbook/2/functions.html#declaring-this-in-a-function
-  @trackSpan(function () {
-    return `${this!.name}.work`;
-  })
-  override work() {
-    return super.work();
-  }
-}