@aztec/telemetry-client 0.75.0-commit.c03ba01a2a4122e43e90d5133ba017e54b90e9d2

package/dest/otel.js

@@ -0,0 +1,237 @@
+import { addLogDataHandler } from '@aztec/foundation/log';
+import { MetricExporter as GoogleCloudMetricExporter } from '@google-cloud/opentelemetry-cloud-monitoring-exporter';
+import { TraceExporter as GoogleCloudTraceExporter } from '@google-cloud/opentelemetry-cloud-trace-exporter';
+import { DiagConsoleLogger, DiagLogLevel, context, diag, isSpanContextValid, trace } from '@opentelemetry/api';
+import { OTLPMetricExporter } from '@opentelemetry/exporter-metrics-otlp-http';
+import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
+import { HostMetrics } from '@opentelemetry/host-metrics';
+import { ExplicitBucketHistogramAggregation, InstrumentType, MeterProvider, PeriodicExportingMetricReader, View } from '@opentelemetry/sdk-metrics';
+import { BatchSpanProcessor, NodeTracerProvider } from '@opentelemetry/sdk-trace-node';
+import { ATTR_SERVICE_NAME, ATTR_SERVICE_VERSION } from '@opentelemetry/semantic-conventions';
+import { EventLoopMonitor } from './event_loop_monitor.js';
+import { linearBuckets } from './histogram_utils.js';
+import { OtelFilterMetricExporter } from './otel_filter_metric_exporter.js';
+import { registerOtelLoggerProvider } from './otel_logger_provider.js';
+import { getOtelResource } from './otel_resource.js';
+export class OpenTelemetryClient {
+    resource;
+    meterProvider;
+    traceProvider;
+    loggerProvider;
+    log;
+    hostMetrics;
+    eventLoopMonitor;
+    targetInfo;
+    meters;
+    tracers;
+    constructor(resource, meterProvider, traceProvider, loggerProvider, log){
+        this.resource = resource;
+        this.meterProvider = meterProvider;
+        this.traceProvider = traceProvider;
+        this.loggerProvider = loggerProvider;
+        this.log = log;
+        this.meters = new Map();
+        this.tracers = new Map();
+    }
+    getMeter(name) {
+        let meter = this.meters.get(name);
+        if (!meter) {
+            meter = this.meterProvider.getMeter(name, this.resource.attributes[ATTR_SERVICE_VERSION]);
+            this.meters.set(name, meter);
+        }
+        return meter;
+    }
+    getTracer(name) {
+        let tracer = this.tracers.get(name);
+        if (!tracer) {
+            tracer = this.traceProvider.getTracer(name, this.resource.attributes[ATTR_SERVICE_VERSION]);
+            this.tracers.set(name, tracer);
+        }
+        return tracer;
+    }
+    start() {
+        this.log.info('Starting OpenTelemetry client');
+        diag.setLogger(new DiagConsoleLogger(), DiagLogLevel.INFO);
+        // Add a callback to the logger to set context data from current trace
+        // Adapted from open-telemetry/opentelemetry-js-contrib PinoInstrumentation._getMixinFunction
+        addLogDataHandler((data)=>{
+            const spanContext = trace.getSpan(context.active())?.spanContext();
+            return spanContext && isSpanContextValid(spanContext) ? {
+                ...data,
+                ['trace_id']: spanContext.traceId,
+                ['span_id']: spanContext.spanId,
+                ['trace_flags']: `0${spanContext.traceFlags.toString(16)}`
+            } : data;
+        });
+        this.hostMetrics = new HostMetrics({
+            name: this.resource.attributes[ATTR_SERVICE_NAME],
+            meterProvider: this.meterProvider
+        });
+        this.eventLoopMonitor = new EventLoopMonitor(this.meterProvider.getMeter(this.resource.attributes[ATTR_SERVICE_NAME]));
+        // See these two links for more information on providing target information:
+        // https://opentelemetry.io/docs/specs/otel/compatibility/prometheus_and_openmetrics/#resource-attributes
+        // https://github.com/OpenObservability/OpenMetrics/blob/main/specification/OpenMetrics.md#supporting-target-metadata-in-both-push-based-and-pull-based-systems
+        this.targetInfo = this.meterProvider.getMeter('target').createGauge('target_info', {
+            description: 'Target metadata'
+        });
+        this.targetInfo.record(1, this.resource.attributes);
+        this.hostMetrics.start();
+        this.eventLoopMonitor.start();
+    }
+    isEnabled() {
+        return true;
+    }
+    async flush() {
+        await Promise.all([
+            this.meterProvider.forceFlush(),
+            this.loggerProvider?.forceFlush(),
+            this.traceProvider instanceof NodeTracerProvider ? this.traceProvider.forceFlush() : Promise.resolve()
+        ]);
+    }
+    async stop() {
+        this.eventLoopMonitor?.stop();
+        const flushAndShutdown = async (provider)=>{
+            if (!provider) {
+                return;
+            }
+            await provider.forceFlush();
+            await provider.shutdown();
+        };
+        await Promise.all([
+            flushAndShutdown(this.meterProvider),
+            flushAndShutdown(this.loggerProvider),
+            this.traceProvider instanceof NodeTracerProvider ? flushAndShutdown(this.traceProvider) : Promise.resolve()
+        ]);
+    }
+    static createMeterProvider(resource, options) {
+        return new MeterProvider({
+            resource,
+            readers: options.exporter ? [
+                new PeriodicExportingMetricReader(options)
+            ] : [],
+            views: [
+                // Every histogram matching the selector (type + unit) gets these custom buckets assigned
+                new View({
+                    instrumentType: InstrumentType.HISTOGRAM,
+                    instrumentUnit: 'ms',
+                    aggregation: new ExplicitBucketHistogramAggregation(// 181 buckets between 5ms and 1hr
+                    [
+                        ...linearBuckets(5, 100, 20),
+                        ...linearBuckets(100, 1_000, 20).slice(1),
+                        ...linearBuckets(1_000, 10_000, 20).slice(1),
+                        ...linearBuckets(10_000, 60_000, 20).slice(1),
+                        ...linearBuckets(60_000, 300_000, 20).slice(1),
+                        ...linearBuckets(300_000, 600_000, 20).slice(1),
+                        ...linearBuckets(600_000, 1_200_000, 20).slice(1),
+                        ...linearBuckets(1_200_000, 1_800_000, 20).slice(1),
+                        ...linearBuckets(1_800_000, 3_600_000, 20).slice(1)
+                    ], true)
+                }),
+                new View({
+                    instrumentType: InstrumentType.HISTOGRAM,
+                    instrumentUnit: 'us',
+                    aggregation: new ExplicitBucketHistogramAggregation([
+                        ...linearBuckets(5, 100, 20),
+                        ...linearBuckets(100, 1_000, 20).slice(1),
+                        ...linearBuckets(1_000, 10_000, 90).slice(1),
+                        ...linearBuckets(10_000, 100_000, 20).slice(1),
+                        ...linearBuckets(100_000, 1_000_000, 20).slice(1),
+                        ...linearBuckets(1_000_000, 60_000_000, 20).slice(1)
+                    ], true)
+                }),
+                new View({
+                    instrumentType: InstrumentType.HISTOGRAM,
+                    instrumentUnit: 'By',
+                    aggregation: new ExplicitBucketHistogramAggregation(// 143 buckets between 32 bytes and 2MB
+                    [
+                        ...linearBuckets(2 ** 5, 2 ** 10, 31),
+                        ...linearBuckets(2 ** 10, 2 ** 15, 31).slice(1),
+                        ...linearBuckets(2 ** 15, 2 ** 18, 32).slice(1),
+                        ...linearBuckets(2 ** 18, 2 ** 20, 32).slice(1),
+                        ...linearBuckets(2 ** 20, 2 ** 21, 16).slice(1)
+                    ], true)
+                }),
+                new View({
+                    instrumentType: InstrumentType.HISTOGRAM,
+                    instrumentUnit: 'gas/s',
+                    aggregation: new ExplicitBucketHistogramAggregation([
+                        ...linearBuckets(100_000, 10_000_000, 100),
+                        ...linearBuckets(10_000_000, 100_000_000, 100).slice(1)
+                    ], true)
+                }),
+                new View({
+                    instrumentType: InstrumentType.HISTOGRAM,
+                    instrumentUnit: 'mana/s',
+                    aggregation: new ExplicitBucketHistogramAggregation([
+                        ...linearBuckets(100_000, 10_000_000, 100),
+                        ...linearBuckets(10_000_000, 100_000_000, 100).slice(1)
+                    ], true)
+                }),
+                new View({
+                    instrumentType: InstrumentType.HISTOGRAM,
+                    instrumentUnit: 'gas/block',
+                    aggregation: new ExplicitBucketHistogramAggregation([
+                        ...linearBuckets(100_000, 10_000_000, 100),
+                        ...linearBuckets(10_000_000, 50_000_000, 50).slice(1)
+                    ], true)
+                }),
+                new View({
+                    instrumentType: InstrumentType.HISTOGRAM,
+                    instrumentUnit: 'gas/tx',
+                    aggregation: new ExplicitBucketHistogramAggregation([
+                        ...linearBuckets(50_000, 1_000_000, 20),
+                        ...linearBuckets(1_000_000, 10_000_000, 100).slice(1)
+                    ], true)
+                })
+            ]
+        });
+    }
+    static getGcloudClientFactory(config) {
+        return (resource, log)=>{
+            const tracerProvider = new NodeTracerProvider({
+                resource,
+                spanProcessors: [
+                    new BatchSpanProcessor(new GoogleCloudTraceExporter({
+                        resourceFilter: /.*/
+                    }))
+                ]
+            });
+            tracerProvider.register();
+            const meterProvider = OpenTelemetryClient.createMeterProvider(resource, {
+                exporter: new OtelFilterMetricExporter(new GoogleCloudMetricExporter(), config.otelExcludeMetrics ?? []),
+                exportTimeoutMillis: config.otelExportTimeoutMs,
+                exportIntervalMillis: config.otelCollectIntervalMs
+            });
+            return new OpenTelemetryClient(resource, meterProvider, tracerProvider, undefined, log);
+        };
+    }
+    static getCustomClientFactory(config) {
+        return (resource, log)=>{
+            const tracerProvider = new NodeTracerProvider({
+                resource,
+                spanProcessors: config.tracesCollectorUrl ? [
+                    new BatchSpanProcessor(new OTLPTraceExporter({
+                        url: config.tracesCollectorUrl.href
+                    }))
+                ] : []
+            });
+            tracerProvider.register();
+            const meterProvider = OpenTelemetryClient.createMeterProvider(resource, {
+                exporter: config.metricsCollectorUrl ? new OtelFilterMetricExporter(new OTLPMetricExporter({
+                    url: config.metricsCollectorUrl.href
+                }), config.otelExcludeMetrics ?? []) : undefined,
+                exportTimeoutMillis: config.otelExportTimeoutMs,
+                exportIntervalMillis: config.otelCollectIntervalMs
+            });
+            const loggerProvider = registerOtelLoggerProvider(resource, config.logsCollectorUrl);
+            return new OpenTelemetryClient(resource, meterProvider, tracerProvider, loggerProvider, log);
+        };
+    }
+    static createAndStart(config, log) {
+        const resource = getOtelResource();
+        const factory = config.useGcloudObservability ? OpenTelemetryClient.getGcloudClientFactory(config) : OpenTelemetryClient.getCustomClientFactory(config);
+        const service = factory(resource, log);
+        service.start();
+        return service;
+    }
+}

package/dest/otel_filter_metric_exporter.js

@@ -0,0 +1,33 @@
+export class OtelFilterMetricExporter {
+    exporter;
+    excludeMetricPrefixes;
+    constructor(exporter, excludeMetricPrefixes){
+        this.exporter = exporter;
+        this.excludeMetricPrefixes = excludeMetricPrefixes;
+        if (exporter.selectAggregation) {
+            this.selectAggregation = exporter.selectAggregation.bind(exporter);
+        }
+        if (exporter.selectAggregationTemporality) {
+            this.selectAggregationTemporality = exporter.selectAggregationTemporality.bind(exporter);
+        }
+    }
+    export(metrics, resultCallback) {
+        const filteredMetrics = {
+            resource: metrics.resource,
+            scopeMetrics: metrics.scopeMetrics.map(({ scope, metrics })=>({
+                    scope,
+                    metrics: this.filterMetrics(metrics)
+                })).filter(({ metrics })=>metrics.length > 0)
+        };
+        this.exporter.export(filteredMetrics, resultCallback);
+    }
+    filterMetrics(metrics) {
+        return metrics.filter((metric)=>!this.excludeMetricPrefixes.some((prefix)=>metric.descriptor.name.startsWith(prefix)));
+    }
+    forceFlush() {
+        return this.exporter.forceFlush();
+    }
+    shutdown() {
+        return this.exporter.shutdown();
+    }
+}

package/dest/otel_logger_provider.js

@@ -0,0 +1,25 @@
+import { logs as otelLogs } from '@opentelemetry/api-logs';
+import { OTLPLogExporter } from '@opentelemetry/exporter-logs-otlp-http';
+import { CompressionAlgorithm } from '@opentelemetry/otlp-exporter-base';
+import { BatchLogRecordProcessor, LoggerProvider } from '@opentelemetry/sdk-logs';
+export function registerOtelLoggerProvider(resource, otelLogsUrl) {
+    const loggerProvider = new LoggerProvider({
+        resource
+    });
+    if (!otelLogsUrl) {
+        // If no URL provided, return it disconnected.
+        return loggerProvider;
+    }
+    const logExporter = new OTLPLogExporter({
+        compression: CompressionAlgorithm.GZIP,
+        url: otelLogsUrl.href
+    });
+    // Add a processor to the logger provider
+    loggerProvider.addLogRecordProcessor(new BatchLogRecordProcessor(logExporter, {
+        /** The maximum batch size of every export. It must be smaller or equal to
+       * maxQueueSize. */ maxExportBatchSize: 1024,
+        /** The maximum queue size. After the size is reached log records are dropped. */ maxQueueSize: 4096
+    }));
+    otelLogs.setGlobalLoggerProvider(loggerProvider);
+    return loggerProvider;
+}

package/dest/otel_propagation.js

@@ -0,0 +1,44 @@
+import { ROOT_CONTEXT, SpanKind, SpanStatusCode, propagation } from '@opentelemetry/api';
+import { getTelemetryClient } from './start.js';
+import { ATTR_JSONRPC_ERROR_CODE, ATTR_JSONRPC_ERROR_MSG, ATTR_JSONRPC_METHOD, ATTR_JSONRPC_REQUEST_ID } from './vendor/attributes.js';
+export function getOtelJsonRpcPropagationMiddleware(scope = 'JsonRpcServer') {
+    return function otelJsonRpcPropagation(ctx, next) {
+        const tracer = getTelemetryClient().getTracer(scope);
+        const context = propagation.extract(ROOT_CONTEXT, ctx.request.headers);
+        const method = ctx.request.body?.method;
+        return tracer.startActiveSpan(`JsonRpcServer.${method ?? 'unknown'}`, {
+            kind: SpanKind.SERVER
+        }, context, async (span)=>{
+            if (ctx.id) {
+                span.setAttribute(ATTR_JSONRPC_REQUEST_ID, ctx.id);
+            }
+            if (method) {
+                span.setAttribute(ATTR_JSONRPC_METHOD, method);
+            }
+            try {
+                await next();
+                const err = ctx.body.error?.message;
+                const code = ctx.body.error?.code;
+                if (err) {
+                    span.setStatus({
+                        code: SpanStatusCode.ERROR,
+                        message: err
+                    });
+                    span.setAttribute(ATTR_JSONRPC_ERROR_CODE, code);
+                    span.setAttribute(ATTR_JSONRPC_ERROR_MSG, err);
+                } else {
+                    span.setStatus({
+                        code: SpanStatusCode.OK
+                    });
+                }
+            } catch (err) {
+                span.setStatus({
+                    code: SpanStatusCode.ERROR,
+                    message: String(err)
+                });
+            } finally{
+                span.end();
+            }
+        });
+    };
+}

package/dest/otel_resource.js

@@ -0,0 +1,16 @@
+import { GcpDetectorSync } from '@google-cloud/opentelemetry-resource-util';
+import { detectResourcesSync, envDetectorSync, osDetectorSync, processDetectorSync, serviceInstanceIdDetectorSync } from '@opentelemetry/resources';
+import { aztecDetector } from './aztec_resource_detector.js';
+export function getOtelResource() {
+    const resource = detectResourcesSync({
+        detectors: [
+            osDetectorSync,
+            envDetectorSync,
+            processDetectorSync,
+            serviceInstanceIdDetectorSync,
+            aztecDetector,
+            new GcpDetectorSync()
+        ]
+    });
+    return resource;
+}

package/dest/prom_otel_adapter.js

@@ -0,0 +1,183 @@
+import { createLogger } from '@aztec/foundation/log';
+import { Registry } from 'prom-client';
+export var MessageSource = /*#__PURE__*/ function(MessageSource) {
+    MessageSource["forward"] = "forward";
+    MessageSource["publish"] = "publish";
+    return MessageSource;
+}({});
+/**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 {
+    logger;
+    labelNames;
+    gauge;
+    currentValue;
+    labeledValues;
+    collectFns;
+    _collect;
+    get collect() {
+        return this._collect;
+    }
+    set collect(fn) {
+        this._collect = fn;
+    }
+    constructor(logger, meter, name, help, labelNames = []){
+        this.logger = logger;
+        this.labelNames = labelNames;
+        this.currentValue = 0;
+        this.labeledValues = new Map();
+        this.collectFns = [];
+        this._collect = ()=>{};
+        this.gauge = meter.createObservableGauge(name, {
+            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) {
+        this.collectFns.push(collectFn);
+    }
+    handleObservation(result) {
+        // 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);
+            }
+        }
+    }
+    inc(labelsOrValue, value) {
+        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;
+    }
+    set(labelsOrValue, value) {
+        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) {
+        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() {
+        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
+   */ validateLabels(labels) {
+        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)) {
+                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
+   */ parseLabelsSafely(labelStr) {
+        try {
+            return JSON.parse(labelStr);
+        } catch  {
+            this.logger.error(`Failed to parse label string: ${labelStr}`);
+            return null;
+        }
+    }
+}
+/**
+ * Noop implementation of a Historgram collec
+ */ class NoopOtelHistogram {
+    logger;
+    constructor(logger, _meter, _name, _help, _buckets = [], _labelNames = []){
+        this.logger = logger;
+    }
+    observe(_valueOrLabels, _value) {}
+    startTimer(_labels) {
+        return ()=>0;
+    }
+    reset() {
+        // 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 {
+    _logger;
+    constructor(_logger, _meter, _name, _help, _labelNames = []){
+        this._logger = _logger;
+    }
+    set(_valueOrLabels, _values) {}
+    reset() {}
+}
+/**
+ * Otel metrics Adapter
+ *
+ * Maps the PromClient based MetricsRegister from gossipsub and discv5 services to the Otel MetricsRegister
+ */ export class OtelMetricsAdapter extends Registry {
+    logger;
+    meter;
+    constructor(telemetryClient, logger = createLogger('telemetry:otel-metrics-adapter')){
+        super(), this.logger = logger;
+        this.meter = telemetryClient.getMeter('metrics-adapter');
+    }
+    gauge(configuration) {
+        return new OtelGauge(this.logger, this.meter, configuration.name, configuration.help, configuration.labelNames);
+    }
+    histogram(configuration) {
+        return new NoopOtelHistogram(this.logger, this.meter, configuration.name, configuration.help, configuration.buckets, configuration.labelNames);
+    }
+    avgMinMax(configuration) {
+        return new NoopOtelAvgMinMax(this.logger, this.meter, configuration.name, configuration.help, configuration.labelNames);
+    }
+}

package/dest/start.js

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

package/dest/telemetry.js

@@ -0,0 +1,116 @@
+import { SpanStatusCode } from '@opentelemetry/api';
+import { isPromise } from 'node:util/types';
+import { getTelemetryClient } from './start.js';
+export { SpanStatusCode, ValueType } from '@opentelemetry/api';
+/**
+ * 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(spanName, attributes, extraAttributes) {
+    // the return value of trackSpan is a decorator
+    return (originalMethod, _context)=>{
+        // 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(...args) {
+            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.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();
+                }
+            });
+        };
+    };
+}
+/**
+ * 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(tracer, spanName, attributes, callback) {
+    const span = tracer.startSpan(spanName, {
+        attributes
+    });
+    return async (...args)=>{
+        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();
+        }
+    };
+}
+export function runInSpan(tracer, spanName, callback) {
+    return (...args)=>{
+        const actualTracer = typeof tracer === 'string' ? getTelemetryClient().getTracer(tracer) : tracer;
+        return actualTracer.startActiveSpan(spanName, (span)=>{
+            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();
+                    });
+                } else {
+                    return res;
+                }
+            } catch (err) {
+                span.setStatus({
+                    code: SpanStatusCode.ERROR,
+                    message: String(err)
+                });
+                throw err;
+            } finally{
+                if (!deferSpanEnd) {
+                    span.end();
+                }
+            }
+        });
+    };
+}