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

package/src/telemetry.ts

@@ -0,0 +1,348 @@
+import {
+  type AttributeValue,
+  type BatchObservableCallback,
+  type Context,
+  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 type * as Attributes from './attributes.js';
+import type { MetricDefinition } from './metrics.js';
+import { getTelemetryClient } from './start.js';
+import type * as VendorAttributes from './vendor/attributes.js';
+
+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;
+
+type AttributeNames = ValuesOf<typeof Attributes>;
+
+type AllowedVendorMetricAttributeNames = (typeof VendorAttributes)['ATTR_JSONRPC_METHOD' | 'ATTR_JSONRPC_SERVICE'];
+
+/**
+ * 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'
+  | 'TARGET_ADDRESS'
+  | 'MANA_USED'
+  | 'TOTAL_INSTRUCTIONS'];
+
+/** Global registry of attributes */
+export type AttributesType = Partial<Record<AttributeNames, AttributeValue>>;
+
+export type AllowedAttributeNames =
+  | Exclude<AttributeNames, BannedMetricAttributeNames>
+  | AllowedVendorMetricAttributeNames;
+
+/** Subset of attributes allowed to be added to metrics */
+export type MetricAttributesType = Partial<Record<AllowedAttributeNames, AttributeValue>>;
+
+/** Re-export MetricDefinition for convenience */
+export type { MetricDefinition } from './metrics.js';
+
+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 };
+
+// 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 metric - The metric definition
+   */
+  createGauge(metric: MetricDefinition): 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(metric: MetricDefinition): 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 metric - The metric definition
+   * @param extraOptions - Optional extra options (e.g., advice for bucket boundaries)
+   */
+  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 metric - The metric definition
+   */
+  createUpDownCounter(metric: MetricDefinition): UpDownCounter;
+
+  /**
+   * Creates a new observable up/down counter instrument.
+   * @param metric - The metric definition
+   */
+  createObservableUpDownCounter(metric: MetricDefinition): 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>;
+
+  /**
+   * 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;
+
+  /**
+   * 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 */
+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-v22.x/docs/api/async_context.html
+      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;
+  };
+}
+
+/**
+ * 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) => Promise<R>,
+): (...args: A) => Promise<R> {
+  return (...args: A): 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, ...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 {
+        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/vendor/attributes.ts

@@ -0,0 +1,6 @@
+// See https://opentelemetry.io/docs/specs/semconv/rpc/json-rpc/
+export const ATTR_JSONRPC_METHOD = 'rpc.method';
+export const ATTR_JSONRPC_SERVICE = 'rpc.service';
+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';

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

@@ -0,0 +1,279 @@
+/*
+ * Adapted from open-telemetry/opentelemetry-js-contrib
+ * All changes are prefixed with [aztec] to make them easy to identify
+ *
+ * Copyright The OpenTelemetry Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { type Logger, SeverityNumber, logs } from '@opentelemetry/api-logs';
+import { millisToHrTime } from '@opentelemetry/core';
+import { Writable } from 'stream';
+
+import { registerOtelLoggerProvider } from '../otel_logger_provider.js';
+import { getOtelResource } from '../otel_resource.js';
+
+// 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.
+const DEFAULT_LEVELS = {
+  trace: 10,
+  debug: 20,
+  info: 30,
+  warn: 40,
+  error: 50,
+  fatal: 60,
+};
+
+const OTEL_SEV_NUM_FROM_PINO_LEVEL: { [level: number]: SeverityNumber } = {
+  [DEFAULT_LEVELS.trace]: SeverityNumber.TRACE,
+  [DEFAULT_LEVELS.debug]: SeverityNumber.DEBUG,
+  [DEFAULT_LEVELS.info]: SeverityNumber.INFO,
+  [DEFAULT_LEVELS.warn]: SeverityNumber.WARN,
+  [DEFAULT_LEVELS.error]: SeverityNumber.ERROR,
+  [DEFAULT_LEVELS.fatal]: SeverityNumber.FATAL,
+};
+
+const EXTRA_SEV_NUMS = [
+  SeverityNumber.TRACE2,
+  SeverityNumber.TRACE3,
+  SeverityNumber.TRACE4,
+  SeverityNumber.DEBUG2,
+  SeverityNumber.DEBUG3,
+  SeverityNumber.DEBUG4,
+  SeverityNumber.INFO2,
+  SeverityNumber.INFO3,
+  SeverityNumber.INFO4,
+  SeverityNumber.WARN2,
+  SeverityNumber.WARN3,
+  SeverityNumber.WARN4,
+  SeverityNumber.ERROR2,
+  SeverityNumber.ERROR3,
+  SeverityNumber.ERROR4,
+  SeverityNumber.FATAL2,
+  SeverityNumber.FATAL3,
+  SeverityNumber.FATAL4,
+];
+
+function severityNumberFromPinoLevel(lvl: number) {
+  // Fast common case: one of the known levels
+  const sev = OTEL_SEV_NUM_FROM_PINO_LEVEL[lvl];
+  if (sev !== undefined) {
+    return sev;
+  }
+
+  // Otherwise, scale the Pino level range -- 10 (trace) to 70 (fatal+10)
+  // -- onto the extra OTel severity numbers (TRACE2, TRACE3, ..., FATAL4).
+  // Values below trace (10) map to SeverityNumber.TRACE2, which may be
+  // considered a bit weird, but it means the unnumbered levels are always
+  // just for exactly matching values.
+  const relativeLevelWeight = (lvl - 10) / (70 - 10);
+  const otelSevIdx = Math.floor(relativeLevelWeight * EXTRA_SEV_NUMS.length);
+  const cappedOTelIdx = Math.min(EXTRA_SEV_NUMS.length - 1, Math.max(0, otelSevIdx));
+  const otelSevValue = EXTRA_SEV_NUMS[cappedOTelIdx];
+  return otelSevValue;
+}
+
+// [aztec] Custom function to map Aztec logging levels to OpenTelemetry severity numbers
+function severityNumberFromAztecPinoLevel(lvl: number) {
+  return (
+    OTEL_SEV_NUM_FROM_PINO_LEVEL[lvl] ??
+    /* verbose */ (lvl === 25 ? SeverityNumber.DEBUG3 : undefined) ??
+    severityNumberFromPinoLevel(lvl)
+  );
+}
+
+/**
+ * Return a function that knows how to convert the "time" field value on a
+ * Pino log record to an OTel LogRecord timestamp value.
+ *
+ * How to convert the serialized "time" on a Pino log record
+ * depends on the Logger's `Symbol(pino.time)` prop, configurable
+ * via https://getpino.io/#/docs/api?id=timestamp-boolean-function
+ *
+ * For example:
+ *    const logger = pino({timestamp: pino.stdTimeFunctions.isoTime})
+ * results in log record entries of the form:
+ *    ,"time":"2024-05-17T22:03:25.969Z"
+ * `otelTimestampFromTime` will be given the value of the "time" field:
+ *   "2024-05-17T22:03:25.969Z"
+ * which should be parsed to a number of milliseconds since the epoch.
+ */
+export function getTimeConverter(pinoLogger: any, pinoMod: any) {
+  const stdTimeFns = pinoMod.stdTimeFunctions;
+  const loggerTimeFn = pinoLogger[pinoMod.symbols.timeSym];
+  if (loggerTimeFn === stdTimeFns.epochTime) {
+    return (time: number) => time;
+  } else if (loggerTimeFn === stdTimeFns.unixTime) {
+    return (time: number) => time * 1e3;
+  } else if (loggerTimeFn === stdTimeFns.isoTime) {
+    return (time: string) => new Date(time).getTime();
+  } else if (loggerTimeFn === stdTimeFns.nullTime) {
+    return () => Date.now();
+  } else {
+    // The logger has a custom time function. Don't guess.
+    return () => NaN;
+  }
+}
+
+interface OTelPinoStreamOptions {
+  messageKey?: string;
+  levels: any; // Pino.LevelMapping
+  otelTimestampFromTime?: (time: any) => number;
+}
+
+/**
+ * A Pino stream for sending records to the OpenTelemetry Logs API.
+ *
+ * - This stream emits an 'unknown' event on an unprocessable pino record.
+ *   The event arguments are: `logLine: string`, `err: string | Error`.
+ */
+export class OTelPinoStream extends Writable {
+  private _otelLogger: Logger;
+  private _messageKey: string;
+  private _levels;
+  private _otelTimestampFromTime;
+
+  constructor(options: OTelPinoStreamOptions) {
+    super();
+
+    // Note: A PINO_CONFIG event was added to pino (2024-04-04) to send config
+    // to transports. Eventually OTelPinoStream might be able to use this
+    // for auto-configuration in newer pino versions. The event currently does
+    // not include the `timeSym` value that is needed here, however.
+    this._messageKey = options.messageKey ?? 'msg';
+    this._levels = options.levels;
+
+    // [aztec] The following will break if we set up a custom time function in our logger
+    this._otelTimestampFromTime = options.otelTimestampFromTime ?? ((time: number) => time);
+
+    // Cannot use `instrumentation.logger` until have delegating LoggerProvider:
+    // https://github.com/open-telemetry/opentelemetry-js/issues/4399
+    // [aztec] Use the name of this package
+    this._otelLogger = logs.getLogger('@aztec-labs/telemetry-client/otel-pino-stream', '0.1.0');
+  }
+
+  override _write(s: string, _encoding: string, callback: Function) {
+    try {
+      /* istanbul ignore if */
+      if (!s) {
+        return;
+      }
+
+      // 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;
+      try {
+        recObj = JSON.parse(s);
+      } catch (parseErr) {
+        // Invalid JSON suggests a bug in Pino, or a logger configuration bug
+        // (a bogus `options.timestamp` or serializer).
+        this.emit('unknown', s.toString(), parseErr);
+        callback();
+        return;
+      }
+      /* istanbul ignore if */
+      if (recObj === null) {
+        this.emit('unknown', s.toString(), 'Null value ignored');
+        callback();
+        return;
+      }
+      /* istanbul ignore if */
+      if (typeof recObj !== 'object') {
+        recObj = {
+          data: recObj,
+        };
+      }
+
+      const {
+        time,
+        [this._messageKey]: body,
+        level, // eslint-disable-line @typescript-eslint/no-unused-vars
+
+        // The typical Pino `hostname` and `pid` fields are removed because they
+        // are redundant with the OpenTelemetry `host.name` and `process.pid`
+        // Resource attributes, respectively. This code cannot change the
+        // LoggerProvider's `resource`, so getting the OpenTelemetry equivalents
+        // depends on the user using the OpenTelemetry HostDetector and
+        // ProcessDetector.
+        // https://getpino.io/#/docs/api?id=opt-base
+        hostname, // eslint-disable-line @typescript-eslint/no-unused-vars
+        pid, // eslint-disable-line @typescript-eslint/no-unused-vars
+
+        // The `trace_id` et al fields that may have been added by the
+        // "log correlation" feature are stripped, because they are redundant.
+        // trace_id, // eslint-disable-line @typescript-eslint/no-unused-vars
+        // span_id, // eslint-disable-line @typescript-eslint/no-unused-vars
+        // trace_flags, // eslint-disable-line @typescript-eslint/no-unused-vars
+
+        // [aztec] They are not redundant, we depend on them for correlation.
+        // The instrumentation package seems to be adding these fields via a custom hook.
+        // We push them from the logger module in foundation, so we don't want to clear them here.
+
+        ...attributes
+      } = recObj;
+
+      let timestamp = this._otelTimestampFromTime(time);
+      if (isNaN(timestamp)) {
+        attributes['time'] = time; // save the unexpected "time" field to attributes
+        timestamp = Date.now();
+      }
+
+      // This avoids a possible subtle bug when a Pino logger uses
+      // `time: pino.stdTimeFunctions.unixTime` and logs in the first half-second
+      // since process start. The rounding involved results in:
+      //    timestamp < performance.timeOrigin
+      // If that is passed to Logger.emit() it will be misinterpreted by
+      // `timeInputToHrTime` as a `performance.now()` value.
+      const timestampHrTime = millisToHrTime(timestamp);
+
+      // Prefer using `stream.lastLevel`, because `recObj.level` can be customized
+      // to anything via `formatters.level`
+      // (https://getpino.io/#/docs/api?id=formatters-object).
+      // const lastLevel = (this as any).lastLevel;
+
+      // [aztec] We do not prefer stream.lastLevel since it's undefined here, as we are running
+      // on a worker thread, so we use recObj.level because we know that we won't customize it.
+      const lastLevel = recObj.level;
+
+      const otelRec = {
+        timestamp: timestampHrTime,
+        observedTimestamp: timestampHrTime,
+        severityNumber: severityNumberFromAztecPinoLevel(lastLevel),
+        severityText: this._levels.labels[lastLevel],
+        body,
+        attributes,
+      };
+
+      this._otelLogger.emit(otelRec);
+    } catch (err) {
+      // [aztec] Log errors to stderr
+      // eslint-disable-next-line no-console
+      console.error(`Error in OTelPinoStream: ${err}`);
+    }
+    callback();
+  }
+}
+
+// [aztec] Default export that loads the resource information and creates a new otel pino stream.
+// Invoked by pino when creating a transport in a worker thread out of this stream.
+// Note that the original open-telemetry/opentelemetry-js-contrib was set up to run on the main
+// nodejs loop, as opposed to in a worker as pino recommends.
+export default function (options: OTelPinoStreamOptions): OTelPinoStream {
+  const url = process.env.OTEL_EXPORTER_OTLP_LOGS_ENDPOINT;
+  const resource = getOtelResource();
+  // We re-register here because this runs on a worker thread
+  registerOtelLoggerProvider(resource, url ? new URL(url) : undefined);
+  return new OTelPinoStream(options);
+}

package/src/with_tracer.ts

@@ -0,0 +1,35 @@
+import type { TelemetryClient, Tracer } from './telemetry.js';
+
+/**
+ * A minimal class that enables recording metrics with a telemetry client.
+ * This base class enables tracing
+ *
+ * In other words:
+ * Enables the ability to call `@trackSpan` on methods.
+ *
+ * Example:
+ *
+ * ```
+ * import {Attributes, type TelemetryClient, WithTracer, trackSpan } from '@aztec-labs/telemetry-client';
+ *
+ * class MyClass extends WithTracer {
+ *   // Constructor is required to be passed the TelemetryClient implementation.
+ *   constructor(client: TelemetryClient) {
+ *     super(client, 'MyClass');
+ *   }
+ *
+ *   @trackSpan('MyClass.myMethod', (arg: string) => ({
+ *     [Attributes.ARG]: arg,
+ *   }))
+ *   public myMethod(arg: string) {
+ *     // ...
+ *   }
+ * }
+ * ```
+ */
+export class WithTracer {
+  public readonly tracer: Tracer;
+  constructor(client: TelemetryClient, name: string) {
+    this.tracer = client.getTracer(name);
+  }
+}