@aztec/telemetry-client 0.0.1-commit.fcb71a6 → 0.0.1-commit.fffb133c

package/src/nodejs_metrics_monitor.ts

@@ -3,17 +3,9 @@ import { type EventLoopUtilization, type IntervalHistogram, monitorEventLoopDela
 
 import * as Attributes from './attributes.js';
 import * as Metrics from './metrics.js';
-import {
-  type BatchObservableResult,
-  type Meter,
-  type ObservableGauge,
-  type UpDownCounter,
-  ValueType,
-} from './telemetry.js';
-
-/**
- * Detector for custom Aztec attributes
- */
+import type { BatchObservableResult, Meter, ObservableGauge, UpDownCounter } from './telemetry.js';
+
+/** Monitors Node.js runtime metrics */
 export class NodejsMetricsMonitor {
   private eventLoopDelayGauges: {
     min: ObservableGauge;
@@ -38,53 +30,25 @@ export class NodejsMetricsMonitor {
   private eventLoopDelay: IntervalHistogram;
 
   constructor(private meter: Meter) {
-    const nsObsGauge = (name: (typeof Metrics)[keyof typeof Metrics], description: string) =>
-      meter.createObservableGauge(name, {
-        unit: 'ns',
-        valueType: ValueType.INT,
-        description,
-      });
-
     this.eventLoopDelayGauges = {
-      min: nsObsGauge(Metrics.NODEJS_EVENT_LOOP_DELAY_MIN, 'Minimum delay of the event loop'),
-      mean: nsObsGauge(Metrics.NODEJS_EVENT_LOOP_DELAY_MEAN, 'Mean delay of the event loop'),
-      max: nsObsGauge(Metrics.NODEJS_EVENT_LOOP_DELAY_MAX, 'Max delay of the event loop'),
-      stddev: nsObsGauge(Metrics.NODEJS_EVENT_LOOP_DELAY_STDDEV, 'Stddev delay of the event loop'),
-      p50: nsObsGauge(Metrics.NODEJS_EVENT_LOOP_DELAY_P50, 'P50 delay of the event loop'),
-      p90: nsObsGauge(Metrics.NODEJS_EVENT_LOOP_DELAY_P90, 'P90 delay of the event loop'),
-      p99: nsObsGauge(Metrics.NODEJS_EVENT_LOOP_DELAY_P99, 'P99 delay of the event loop'),
+      min: meter.createObservableGauge(Metrics.NODEJS_EVENT_LOOP_DELAY_MIN),
+      mean: meter.createObservableGauge(Metrics.NODEJS_EVENT_LOOP_DELAY_MEAN),
+      max: meter.createObservableGauge(Metrics.NODEJS_EVENT_LOOP_DELAY_MAX),
+      stddev: meter.createObservableGauge(Metrics.NODEJS_EVENT_LOOP_DELAY_STDDEV),
+      p50: meter.createObservableGauge(Metrics.NODEJS_EVENT_LOOP_DELAY_P50),
+      p90: meter.createObservableGauge(Metrics.NODEJS_EVENT_LOOP_DELAY_P90),
+      p99: meter.createObservableGauge(Metrics.NODEJS_EVENT_LOOP_DELAY_P99),
     };
 
-    this.eventLoopUilization = meter.createObservableGauge(Metrics.NODEJS_EVENT_LOOP_UTILIZATION, {
-      valueType: ValueType.DOUBLE,
-      description: 'How busy is the event loop',
-    });
-
-    this.eventLoopTime = meter.createUpDownCounter(Metrics.NODEJS_EVENT_LOOP_TIME, {
-      unit: 'ms',
-      valueType: ValueType.INT,
-      description: 'How much time the event loop has spent in a given state',
-    });
-
+    this.eventLoopUilization = meter.createObservableGauge(Metrics.NODEJS_EVENT_LOOP_UTILIZATION);
+    this.eventLoopTime = meter.createUpDownCounter(Metrics.NODEJS_EVENT_LOOP_TIME);
     this.eventLoopDelay = monitorEventLoopDelay();
 
     this.memoryGauges = {
-      heapUsed: meter.createObservableGauge(Metrics.NODEJS_MEMORY_HEAP_USAGE, {
-        unit: 'By',
-        description: 'Memory used by the V8 heap',
-      }),
-      heapTotal: meter.createObservableGauge(Metrics.NODEJS_MEMORY_HEAP_TOTAL, {
-        unit: 'By',
-        description: 'The max size the V8 heap can grow to',
-      }),
-      arrayBuffers: meter.createObservableGauge(Metrics.NODEJS_MEMORY_BUFFER_USAGE, {
-        unit: 'By',
-        description: 'Memory allocated for buffers (includes native memory used)',
-      }),
-      external: meter.createObservableGauge(Metrics.NODEJS_MEMORY_NATIVE_USAGE, {
-        unit: 'By',
-        description: 'Memory allocated for native C++ objects',
-      }),
+      heapUsed: meter.createObservableGauge(Metrics.NODEJS_MEMORY_HEAP_USAGE),
+      heapTotal: meter.createObservableGauge(Metrics.NODEJS_MEMORY_HEAP_TOTAL),
+      arrayBuffers: meter.createObservableGauge(Metrics.NODEJS_MEMORY_BUFFER_USAGE),
+      external: meter.createObservableGauge(Metrics.NODEJS_MEMORY_NATIVE_USAGE),
     };
   }
 

package/src/noop.ts

@@ -1,13 +1,63 @@
-import { type Meter, type Span, type SpanContext, type Tracer, createNoopMeter } from '@opentelemetry/api';
+import { type Context, type Span, type SpanContext, type Tracer, createNoopMeter } from '@opentelemetry/api';
 
-import type { TelemetryClient } from './telemetry.js';
+import type { MetricDefinition } from './metrics.js';
+import type {
+  Gauge,
+  Histogram,
+  Meter,
+  ObservableGauge,
+  ObservableUpDownCounter,
+  TelemetryClient,
+  UpDownCounter,
+} from './telemetry.js';
+
+/** A no-op meter that implements our custom Meter interface */
+class NoopMeter implements Meter {
+  private otelMeter = createNoopMeter();
+
+  createGauge(_metric: MetricDefinition): Gauge {
+    return this.otelMeter.createGauge('');
+  }
+
+  createObservableGauge(_metric: MetricDefinition): ObservableGauge {
+    return this.otelMeter.createObservableGauge('');
+  }
+
+  createHistogram(_metric: MetricDefinition, _extraOptions?: Parameters<Meter['createHistogram']>[1]): Histogram {
+    return this.otelMeter.createHistogram('');
+  }
+
+  createUpDownCounter(_metric: MetricDefinition): UpDownCounter {
+    return this.otelMeter.createUpDownCounter('');
+  }
+
+  createObservableUpDownCounter(_metric: MetricDefinition): ObservableUpDownCounter {
+    return this.otelMeter.createObservableUpDownCounter('');
+  }
+
+  addBatchObservableCallback(
+    callback: Parameters<Meter['addBatchObservableCallback']>[0],
+    observables: Parameters<Meter['addBatchObservableCallback']>[1],
+  ): void {
+    this.otelMeter.addBatchObservableCallback(callback, observables);
+  }
+
+  removeBatchObservableCallback(
+    callback: Parameters<Meter['removeBatchObservableCallback']>[0],
+    observables: Parameters<Meter['removeBatchObservableCallback']>[1],
+  ): void {
+    this.otelMeter.removeBatchObservableCallback(callback, observables);
+  }
+}
 
 export class NoopTelemetryClient implements TelemetryClient {
+  private meter = new NoopMeter();
+
   setExportedPublicTelemetry(_prefixes: string[]): void {}
   setPublicTelemetryCollectFrom(_roles: string[]): void {}
 
   getMeter(): Meter {
-    return createNoopMeter();
+    return this.meter;
   }
 
   getTracer(): Tracer {
@@ -25,6 +75,14 @@ export class NoopTelemetryClient implements TelemetryClient {
   isEnabled() {
     return false;
   }
+
+  getTraceContext(): string | undefined {
+    return undefined;
+  }
+
+  extractPropagatedContext(_traceContext: string): Context | undefined {
+    return undefined;
+  }
 }
 
 // @opentelemetry/api internally uses NoopTracer and NoopSpan but they're not exported

package/src/otel.ts

@@ -1,16 +1,20 @@
 import { type LogData, type Logger, addLogDataHandler } from '@aztec/foundation/log';
 
 import {
+  type Context,
   DiagConsoleLogger,
   DiagLogLevel,
-  type Meter,
+  type Meter as OtelMeter,
+  ROOT_CONTEXT,
   type Tracer,
   type TracerProvider,
   context,
   diag,
   isSpanContextValid,
+  propagation,
   trace,
 } from '@opentelemetry/api';
+import { W3CTraceContextPropagator } from '@opentelemetry/core';
 import { OTLPMetricExporter } from '@opentelemetry/exporter-metrics-otlp-http';
 import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
 import { HostMetrics } from '@opentelemetry/host-metrics';
@@ -28,18 +32,67 @@ import { BatchSpanProcessor, NodeTracerProvider } from '@opentelemetry/sdk-trace
 import { ATTR_SERVICE_NAME, ATTR_SERVICE_VERSION } from '@opentelemetry/semantic-conventions';
 
 import type { TelemetryClientConfig } from './config.js';
+import { toMetricOptions } from './metric-utils.js';
+import type { MetricDefinition } from './metrics.js';
 import { NodejsMetricsMonitor } from './nodejs_metrics_monitor.js';
 import { OtelFilterMetricExporter, PublicOtelFilterMetricExporter } from './otel_filter_metric_exporter.js';
 import { registerOtelLoggerProvider } from './otel_logger_provider.js';
 import { getOtelResource } from './otel_resource.js';
-import type { TelemetryClient } from './telemetry.js';
+import type {
+  Gauge,
+  Histogram,
+  Meter,
+  ObservableGauge,
+  ObservableUpDownCounter,
+  TelemetryClient,
+  UpDownCounter,
+} from './telemetry.js';
+
+/** Wraps an OpenTelemetry Meter to implement our custom Meter interface */
+class WrappedMeter implements Meter {
+  constructor(private otelMeter: OtelMeter) {}
+
+  createGauge(metric: MetricDefinition): Gauge {
+    return this.otelMeter.createGauge(metric.name, toMetricOptions(metric));
+  }
+
+  createObservableGauge(metric: MetricDefinition): ObservableGauge {
+    return this.otelMeter.createObservableGauge(metric.name, toMetricOptions(metric));
+  }
+
+  createHistogram(metric: MetricDefinition, extraOptions?: Parameters<Meter['createHistogram']>[1]): Histogram {
+    return this.otelMeter.createHistogram(metric.name, { ...toMetricOptions(metric), ...extraOptions });
+  }
+
+  createUpDownCounter(metric: MetricDefinition): UpDownCounter {
+    return this.otelMeter.createUpDownCounter(metric.name, toMetricOptions(metric));
+  }
+
+  createObservableUpDownCounter(metric: MetricDefinition): ObservableUpDownCounter {
+    return this.otelMeter.createObservableUpDownCounter(metric.name, toMetricOptions(metric));
+  }
+
+  addBatchObservableCallback(
+    callback: Parameters<Meter['addBatchObservableCallback']>[0],
+    observables: Parameters<Meter['addBatchObservableCallback']>[1],
+  ): void {
+    this.otelMeter.addBatchObservableCallback(callback, observables);
+  }
+
+  removeBatchObservableCallback(
+    callback: Parameters<Meter['removeBatchObservableCallback']>[0],
+    observables: Parameters<Meter['removeBatchObservableCallback']>[1],
+  ): void {
+    this.otelMeter.removeBatchObservableCallback(callback, observables);
+  }
+}
 
 export type OpenTelemetryClientFactory = (resource: IResource, log: Logger) => OpenTelemetryClient;
 
 export class OpenTelemetryClient implements TelemetryClient {
   hostMetrics: HostMetrics | undefined;
   nodejsMetricsMonitor: NodejsMetricsMonitor | undefined;
-  private meters: Map<string, Meter> = new Map<string, Meter>();
+  private meters: Map<string, WrappedMeter> = new Map<string, WrappedMeter>();
   private tracers: Map<string, Tracer> = new Map<string, Tracer>();
 
   protected constructor(
@@ -62,7 +115,8 @@ export class OpenTelemetryClient implements TelemetryClient {
   getMeter(name: string): Meter {
     let meter = this.meters.get(name);
     if (!meter) {
-      meter = this.meterProvider.getMeter(name, this.resource.attributes[ATTR_SERVICE_VERSION] as string);
+      const otelMeter = this.meterProvider.getMeter(name, this.resource.attributes[ATTR_SERVICE_VERSION] as string);
+      meter = new WrappedMeter(otelMeter);
       this.meters.set(name, meter);
     }
     return meter;
@@ -100,9 +154,10 @@ export class OpenTelemetryClient implements TelemetryClient {
       meterProvider: this.meterProvider,
     });
 
-    this.nodejsMetricsMonitor = new NodejsMetricsMonitor(
+    const nodejsMeter = new WrappedMeter(
       this.meterProvider.getMeter(this.resource.attributes[ATTR_SERVICE_NAME] as string),
     );
+    this.nodejsMetricsMonitor = new NodejsMetricsMonitor(nodejsMeter);
 
     this.hostMetrics.start();
     this.nodejsMetricsMonitor.start();
@@ -138,6 +193,19 @@ export class OpenTelemetryClient implements TelemetryClient {
     ]);
   }
 
+  public getTraceContext(): string | undefined {
+    const carrier: Record<string, string> = {};
+    propagation.inject(context.active(), carrier);
+    return carrier['traceparent'];
+  }
+
+  public extractPropagatedContext(traceContext: string): Context {
+    const extractedContext = propagation.extract(ROOT_CONTEXT, {
+      traceparent: traceContext,
+    });
+    return extractedContext;
+  }
+
   public static createMeterProvider(
     resource: IResource,
     exporters: Array<PeriodicExportingMetricReaderOptions>,
@@ -279,7 +347,9 @@ export class OpenTelemetryClient implements TelemetryClient {
           : [],
       });
 
-      tracerProvider.register();
+      tracerProvider.register({
+        propagator: new W3CTraceContextPropagator(),
+      });
 
       const exporters: PeriodicExportingMetricReaderOptions[] = [];
       if (config.metricsCollectorUrl) {

package/src/prom_otel_adapter.ts

@@ -3,7 +3,8 @@ 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
@@ -429,7 +423,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 +433,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 +444,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/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 } 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;
 
@@ -57,8 +59,8 @@ 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 */
-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 +79,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 +101,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 +158,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 +213,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 +286,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/l2_block_stream.ts

@@ -11,7 +11,10 @@ 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'>,
+    l2BlockSource: Pick<
+      L2BlockSource,
+      'getBlocks' | 'getBlockHeader' | 'getL2Tips' | 'getCheckpoints' | 'getCheckpointedBlocks'
+    >,
     localData: L2BlockStreamLocalDataProvider,
     handler: L2BlockStreamEventHandler,
     public readonly tracer: Tracer,