@strands-agents/sdk 0.5.0 → 0.7.0

package/dist/src/telemetry/config.js

@@ -1,46 +1,104 @@
 /**
  * OpenTelemetry configuration and setup utilities for Strands agents.
  *
- * This module provides centralized configuration and initialization functionality
- * for OpenTelemetry components and other telemetry infrastructure shared across Strands applications.
+ * Provides {@link setupTracer} for distributed tracing and {@link setupMeter}
+ * for OTEL metrics export. Both use the global OTel API so any provider
+ * registered here (or by the user) is automatically picked up by the Agent.
+ *
+ * This module is only loaded when the user explicitly imports and calls
+ * {@link setupTracer} or {@link setupMeter}. The core agent loop
+ * (tracer.ts, meter.ts) does not depend on this module.
+ *
+ * Uses NodeTracerProvider when available for async context propagation
+ * across MCP server boundaries. Falls back to BasicTracerProvider in
+ * environments without async_hooks support.
  */
+import { metrics as otelMetrics, trace } from '@opentelemetry/api';
 import { Resource, envDetectorSync } from '@opentelemetry/resources';
-import { NodeTracerProvider, ConsoleSpanExporter } from '@opentelemetry/sdk-trace-node';
-import { SimpleSpanProcessor, BatchSpanProcessor } from '@opentelemetry/sdk-trace-base';
+import { BasicTracerProvider, ConsoleSpanExporter, SimpleSpanProcessor, BatchSpanProcessor, } from '@opentelemetry/sdk-trace-base';
+import { MeterProvider, PeriodicExportingMetricReader, ConsoleMetricExporter } from '@opentelemetry/sdk-metrics';
 import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
+import { OTLPMetricExporter } from '@opentelemetry/exporter-metrics-otlp-http';
 import { logger } from '../logging/index.js';
-const DEFAULT_SERVICE_NAME = 'strands-agents';
+import { getServiceName } from './utils.js';
+let DefaultTracerProvider = BasicTracerProvider;
+if (typeof globalThis.process?.getBuiltinModule === 'function') {
+    try {
+        const nodeModule = globalThis.process.getBuiltinModule('node:module');
+        if (nodeModule) {
+            const req = nodeModule.createRequire(import.meta.url);
+            DefaultTracerProvider = req('@opentelemetry/sdk-trace-node').NodeTracerProvider;
+        }
+    }
+    catch {
+        logger.info('sdk-trace-node not available; using BasicTracerProvider without async context propagation');
+    }
+}
 const DEFAULT_SERVICE_NAMESPACE = 'strands';
 const DEFAULT_DEPLOYMENT_ENVIRONMENT = 'development';
 /**
- * Get the service name, respecting the OTEL_SERVICE_NAME environment variable.
+ * Get an OpenTelemetry Tracer instance.
+ *
+ * Wraps the OTel trace API to provide a consistent tracer scoped to the
+ * configured service name.
+ *
+ * @returns An OTel Tracer instance from the global tracer provider
+ *
+ * @example
+ * ```typescript
+ * import { setupTracer, getTracer } from '@strands-agents/sdk/telemetry'
+ *
+ * // Set up telemetry first (or register your own NodeTracerProvider)
+ * setupTracer({ exporters: { otlp: true } })
+ *
+ * // Get a tracer and create custom spans
+ * const tracer = getTracer()
+ * const span = tracer.startSpan('my-custom-operation')
+ * span.setAttribute('custom.key', 'value')
  *
- * @returns The service name from OTEL_SERVICE_NAME or the default 'strands-agents'
+ * // ........
+ *
+ * span.end()
+ * ```
+ */
+export function getTracer() {
+    return trace.getTracer(getServiceName());
+}
+/**
+ * Get an OpenTelemetry Meter instance.
+ *
+ * Wraps the OTel metrics API to provide a consistent meter scoped to the
+ * configured service name. Returns a no-op meter until a MeterProvider is
+ * registered (either via {@link setupMeter} or by the user directly).
+ *
+ * @returns An OTel Meter instance from the global meter provider
+ *
+ * @example
+ * ```typescript
+ * import { setupMeter, getMeter } from '@strands-agents/sdk/telemetry'
+ *
+ * setupMeter({ exporters: { otlp: true } })
+ *
+ * const meter = getMeter()
+ * const counter = meter.createCounter('my.custom.counter')
+ * counter.add(1)
+ * ```
  */
-export function getServiceName() {
-    return globalThis?.process?.env?.OTEL_SERVICE_NAME || DEFAULT_SERVICE_NAME;
+export function getMeter() {
+    return otelMetrics.getMeter(getServiceName());
 }
 let _provider = null;
 /**
  * Set up the tracer provider with the given configuration.
  *
  * @param config - Tracer configuration options
- * @returns The configured NodeTracerProvider
+ * @returns The configured tracer provider
  *
  * @example
  * ```typescript
- * import { telemetry } from '@strands-agents/sdk'
- *
- * // Simple setup with defaults
- * const provider = telemetry.setupTracer({
- *   exporters: { otlp: true }
- * })
- *
- * // Custom provider
- * telemetry.setupTracer({
- *   provider: new NodeTracerProvider({ resource: myResource }),
- *   exporters: { otlp: true, console: true }
- * })
+ * import { telemetry } from '\@strands-agents/sdk'
+ *
+ * telemetry.setupTracer({ exporters: { otlp: true } })
  * ```
  */
 export function setupTracer(config = {}) {
@@ -48,45 +106,97 @@ export function setupTracer(config = {}) {
         logger.warn('tracer provider already initialized, returning existing provider');
         return _provider;
     }
-    // Use provided provider or create default
-    _provider = config.provider ?? new NodeTracerProvider({ resource: getOtelResource() });
-    // Add exporters if requested
+    _provider = config.provider ?? new DefaultTracerProvider({ resource: getOtelResource() });
+    // Exporters are additive — if a custom provider already has processors, these append to them.
     if (config.exporters?.otlp)
-        addOtlpExporter(_provider);
+        addOtlpTraceExporter(_provider);
     if (config.exporters?.console)
-        addConsoleExporter(_provider);
-    // register() sets up global tracer provider, context manager, and propagators
+        addConsoleTraceExporter(_provider);
     _provider.register();
-    // Flush pending spans on exit for short-lived scripts using BatchSpanProcessor
-    process.once('beforeExit', () => {
-        if (_provider) {
-            _provider.forceFlush().catch((err) => {
-                logger.warn(`error=<${err}> | failed to flush tracer provider on exit`);
-            });
-        }
-    });
+    if (typeof globalThis.process?.once === 'function') {
+        globalThis.process.once('beforeExit', () => {
+            if (_provider) {
+                _provider.forceFlush().catch((err) => {
+                    logger.warn(`error=<${err}> | failed to flush tracer provider on exit`);
+                });
+            }
+        });
+    }
     return _provider;
 }
-function addOtlpExporter(provider) {
+let _meterProvider = null;
+/**
+ * Set up the OTEL meter provider with the given configuration.
+ *
+ * @param config - Meter configuration options
+ * @returns The configured meter provider
+ *
+ * @example
+ * ```typescript
+ * import { telemetry } from '\@strands-agents/sdk'
+ *
+ * telemetry.setupMeter({ exporters: { otlp: true } })
+ * ```
+ */
+export function setupMeter(config = {}) {
+    if (_meterProvider) {
+        logger.warn('meter provider already initialized, returning existing provider');
+        return _meterProvider;
+    }
+    _meterProvider = config.provider ?? new MeterProvider({ resource: getOtelResource() });
+    // Exporters are additive — if a custom provider already has readers, these append to them.
+    if (config.exporters?.otlp)
+        addOtlpMetricReader(_meterProvider);
+    if (config.exporters?.console)
+        addConsoleMetricReader(_meterProvider);
+    otelMetrics.setGlobalMeterProvider(_meterProvider);
+    if (typeof globalThis.process?.once === 'function') {
+        globalThis.process.once('beforeExit', () => {
+            if (_meterProvider) {
+                _meterProvider.forceFlush().catch((err) => {
+                    logger.warn(`error=<${err}> | failed to flush meter provider on exit`);
+                });
+            }
+        });
+    }
+    return _meterProvider;
+}
+function addOtlpTraceExporter(provider) {
     try {
         provider.addSpanProcessor(new BatchSpanProcessor(new OTLPTraceExporter()));
     }
     catch (error) {
-        logger.warn(`error=<${error}> | failed to configure otlp exporter`);
+        logger.warn(`error=<${error}> | failed to configure otlp trace exporter`);
     }
 }
-function addConsoleExporter(provider) {
+function addConsoleTraceExporter(provider) {
     try {
         provider.addSpanProcessor(new SimpleSpanProcessor(new ConsoleSpanExporter()));
     }
     catch (error) {
-        logger.warn(`error=<${error}> | failed to configure console exporter`);
+        logger.warn(`error=<${error}> | failed to configure console trace exporter`);
+    }
+}
+function addOtlpMetricReader(provider) {
+    try {
+        provider.addMetricReader(new PeriodicExportingMetricReader({ exporter: new OTLPMetricExporter() }));
+    }
+    catch (error) {
+        logger.warn(`error=<${error}> | failed to configure otlp metric exporter`);
+    }
+}
+function addConsoleMetricReader(provider) {
+    try {
+        provider.addMetricReader(new PeriodicExportingMetricReader({ exporter: new ConsoleMetricExporter() }));
+    }
+    catch (error) {
+        logger.warn(`error=<${error}> | failed to configure console metric exporter`);
     }
 }
 function getOtelResource() {
     const serviceName = getServiceName();
-    const serviceNamespace = process.env.OTEL_SERVICE_NAMESPACE || DEFAULT_SERVICE_NAMESPACE;
-    const deploymentEnvironment = process.env.OTEL_DEPLOYMENT_ENVIRONMENT || DEFAULT_DEPLOYMENT_ENVIRONMENT;
+    const serviceNamespace = globalThis.process?.env?.OTEL_SERVICE_NAMESPACE || DEFAULT_SERVICE_NAMESPACE;
+    const deploymentEnvironment = globalThis.process?.env?.OTEL_DEPLOYMENT_ENVIRONMENT || DEFAULT_DEPLOYMENT_ENVIRONMENT;
     const defaultResource = new Resource({
         'service.name': serviceName,
         'service.namespace': serviceNamespace,
@@ -94,7 +204,6 @@ function getOtelResource() {
         'telemetry.sdk.name': 'opentelemetry',
         'telemetry.sdk.language': 'typescript',
     });
-    // Merge with OTEL_RESOURCE_ATTRIBUTES env var (env attrs take precedence)
     const envResource = envDetectorSync.detect();
     return defaultResource.merge(envResource);
 }

package/dist/src/telemetry/config.js.map

@@ -1 +1 @@
-{"version":3,"file":"config.js","sourceRoot":"","sources":["../../../src/telemetry/config.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../../src/telemetry/config.ts"],"names":[],"mappings":"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"}

package/dist/src/telemetry/index.d.ts

@@ -2,17 +2,20 @@
  * OpenTelemetry telemetry support for Strands Agents SDK.
  *
  * This module provides `setupTracer()` to configure a NodeTracerProvider
- * with OTLP or console exporters. The Agent class handles tracing internally
- * once telemetry is configured.
+ * with OTLP or console exporters, and `setupMeter()` to configure a
+ * MeterProvider for OTEL metrics export. The Agent class handles tracing
+ * and metrics internally once telemetry is configured.
  *
  * @example Basic setup with OTLP exporter
  * ```typescript
- * import { telemetry, Agent } from '@strands-agents/sdk'
+ * import { Agent } from '@strands-agents/sdk'
+ * import { setupTracer, setupMeter } from '@strands-agents/sdk/telemetry'
  *
  * // Configure telemetry with OTLP exporter
- * telemetry.setupTracer({ exporters: { otlp: true } })
+ * setupTracer({ exporters: { otlp: true } })
+ * setupMeter({ exporters: { otlp: true } })
  *
- * // Agent automatically traces invocations
+ * // Agent automatically traces invocations and emits metrics
  * const agent = new Agent()
  * ```
  *
@@ -29,6 +32,6 @@
  * const agent = new Agent()
  * ```
  */
-export { setupTracer } from './config.js';
-export type { TracerConfig } from './config.js';
+export { setupTracer, getTracer, setupMeter, getMeter } from './config.js';
+export type { TracerConfig, MeterConfig } from './config.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/src/telemetry/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/telemetry/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AACzC,YAAY,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/telemetry/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAA;AAC1E,YAAY,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA"}

package/dist/src/telemetry/index.js

@@ -2,17 +2,20 @@
  * OpenTelemetry telemetry support for Strands Agents SDK.
  *
  * This module provides `setupTracer()` to configure a NodeTracerProvider
- * with OTLP or console exporters. The Agent class handles tracing internally
- * once telemetry is configured.
+ * with OTLP or console exporters, and `setupMeter()` to configure a
+ * MeterProvider for OTEL metrics export. The Agent class handles tracing
+ * and metrics internally once telemetry is configured.
  *
  * @example Basic setup with OTLP exporter
  * ```typescript
- * import { telemetry, Agent } from '@strands-agents/sdk'
+ * import { Agent } from '@strands-agents/sdk'
+ * import { setupTracer, setupMeter } from '@strands-agents/sdk/telemetry'
  *
  * // Configure telemetry with OTLP exporter
- * telemetry.setupTracer({ exporters: { otlp: true } })
+ * setupTracer({ exporters: { otlp: true } })
+ * setupMeter({ exporters: { otlp: true } })
  *
- * // Agent automatically traces invocations
+ * // Agent automatically traces invocations and emits metrics
  * const agent = new Agent()
  * ```
  *
@@ -29,5 +32,5 @@
  * const agent = new Agent()
  * ```
  */
-export { setupTracer } from './config.js';
+export { setupTracer, getTracer, setupMeter, getMeter } from './config.js';
 //# sourceMappingURL=index.js.map

package/dist/src/telemetry/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/telemetry/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/telemetry/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAA"}

package/dist/src/telemetry/meter.d.ts

@@ -0,0 +1,296 @@
+/**
+ * Agent loop metrics tracking.
+ *
+ * The {@link Meter} accumulates local metrics during agent invocation and
+ * provides them as a read-only {@link AgentMetrics} snapshot via the
+ * {@link Meter.metrics} getter for inclusion in {@link AgentResult}.
+ *
+ * When an OTEL MeterProvider is registered (via {@link setupMeter} or
+ * directly), the Meter also emits counters and histograms through the
+ * global OTEL metrics API, enabling export to OTLP backends.
+ */
+import type { Usage, Metrics, ModelMetadataEventData } from '../models/streaming.js';
+import type { ToolUse } from '../tools/types.js';
+import type { JSONSerializable } from '../types/json.js';
+/**
+ * Per-tool execution metrics.
+ */
+export interface ToolMetricsData {
+    /**
+     * Total number of calls to this tool.
+     */
+    callCount: number;
+    /**
+     * Number of successful calls.
+     */
+    successCount: number;
+    /**
+     * Number of failed calls.
+     */
+    errorCount: number;
+    /**
+     * Total execution time in milliseconds.
+     */
+    totalTime: number;
+}
+/**
+ * Per-cycle usage tracking.
+ */
+export interface AgentLoopMetricsData {
+    /**
+     * Unique identifier for this cycle.
+     */
+    cycleId: string;
+    /**
+     * Duration of this cycle in milliseconds.
+     */
+    duration: number;
+    /**
+     * Token usage for this cycle.
+     */
+    usage: Usage;
+}
+/**
+ * Per-invocation metrics tracking.
+ */
+export interface InvocationMetricsData {
+    /**
+     * Cycle metrics for this invocation.
+     */
+    cycles: AgentLoopMetricsData[];
+    /**
+     * Accumulated token usage for this invocation.
+     */
+    usage: Usage;
+}
+/**
+ * JSON-serializable representation of AgentMetrics.
+ */
+export interface AgentMetricsData {
+    /**
+     * Number of agent loop cycles executed.
+     */
+    cycleCount: number;
+    /**
+     * Accumulated token usage across all model invocations.
+     */
+    accumulatedUsage: Usage;
+    /**
+     * Accumulated performance metrics across all model invocations.
+     */
+    accumulatedMetrics: Metrics;
+    /**
+     * Per-invocation metrics.
+     */
+    agentInvocations: InvocationMetricsData[];
+    /**
+     * Per-tool execution metrics keyed by tool name.
+     */
+    toolMetrics: Record<string, ToolMetricsData>;
+}
+/**
+ * Options for recording tool usage.
+ */
+interface ToolUsageOptions {
+    /**
+     * The tool that was used.
+     */
+    tool: ToolUse;
+    /**
+     * Execution duration in milliseconds.
+     */
+    duration: number;
+    /**
+     * Whether the tool call succeeded.
+     */
+    success: boolean;
+}
+/**
+ * Read-only snapshot of aggregated agent metrics.
+ *
+ * Returned by {@link Meter.metrics} and stored on {@link AgentResult}.
+ * Provides access to cycle counts, tool usage, token consumption,
+ * and per-invocation breakdowns. Supports serialization via {@link toJSON}.
+ *
+ * @example
+ * ```typescript
+ * const result = await agent.invoke('Hello')
+ * console.log(result.metrics?.cycleCount)
+ * console.log(result.metrics?.totalDuration)
+ * console.log(result.metrics?.accumulatedData)
+ * console.log(result.metrics?.toolMetrics)
+ * console.log(JSON.stringify(result.metrics))
+ * ```
+ */
+export declare class AgentMetrics implements JSONSerializable<AgentMetricsData> {
+    /**
+     * Number of agent loop cycles executed.
+     */
+    readonly cycleCount: number;
+    /**
+     * Accumulated token usage across all model invocations.
+     */
+    readonly accumulatedUsage: Usage;
+    /**
+     * Accumulated performance metrics across all model invocations.
+     */
+    readonly accumulatedMetrics: Metrics;
+    /**
+     * Per-invocation metrics.
+     */
+    readonly agentInvocations: InvocationMetricsData[];
+    /**
+     * Per-tool execution metrics keyed by tool name.
+     */
+    readonly toolMetrics: Record<string, ToolMetricsData>;
+    constructor(data?: Partial<AgentMetricsData>);
+    /**
+     * The most recent agent invocation, or undefined if none exist.
+     */
+    get latestAgentInvocation(): InvocationMetricsData | undefined;
+    /**
+     * Accumulated usage and performance metrics across all model invocations.
+     */
+    get accumulatedData(): {
+        usage: Usage;
+        metrics: Metrics;
+    };
+    /**
+     * Total duration of all cycles in milliseconds.
+     */
+    get totalDuration(): number;
+    /**
+     * Average cycle duration in milliseconds, or 0 if no cycles exist.
+     */
+    get averageCycleTime(): number;
+    /**
+     * Per-tool execution statistics with computed averages and rates.
+     */
+    get toolUsage(): Record<string, ToolMetricsData & {
+        averageTime: number;
+        successRate: number;
+    }>;
+    /**
+     * Returns a JSON-serializable representation of all collected metrics.
+     * Called automatically by JSON.stringify().
+     *
+     * @returns A plain object suitable for round-trip serialization
+     */
+    toJSON(): AgentMetricsData;
+}
+/**
+ * Accumulates local metrics during agent invocation.
+ *
+ * Tracks cycle counts, token usage, tool execution stats, and model latency.
+ * Use the {@link metrics} getter to obtain a read-only {@link AgentMetrics}
+ * snapshot for inclusion in {@link AgentResult}.
+ *
+ * When an OTEL MeterProvider is registered, the same data is also emitted
+ * as OTEL counters and histograms via the global metrics API. If no
+ * provider is registered the OTEL meter is a no-op and adds no overhead.
+ */
+export declare class Meter {
+    /**
+     * Number of agent loop cycles executed.
+     */
+    private _cycleCount;
+    /**
+     * Accumulated token usage across all model invocations.
+     */
+    private readonly _accumulatedUsage;
+    /**
+     * Accumulated performance metrics across all model invocations.
+     */
+    private readonly _accumulatedMetrics;
+    /**
+     * Per-invocation metrics.
+     */
+    private readonly _agentInvocations;
+    /**
+     * Per-tool execution metrics keyed by tool name.
+     */
+    private readonly _toolMetrics;
+    private readonly _otelMeter;
+    private readonly _otelCycleCounter;
+    private readonly _otelInvocationCounter;
+    private readonly _otelCycleDuration;
+    private readonly _otelToolCallCounter;
+    private readonly _otelToolErrorCounter;
+    private readonly _otelToolDuration;
+    private readonly _otelInputTokens;
+    private readonly _otelOutputTokens;
+    private readonly _otelModelLatency;
+    private readonly _otelTimeToFirstToken;
+    constructor();
+    /**
+     * Begin tracking a new agent invocation.
+     * Creates a new InvocationMetricsData entry for per-invocation metrics.
+     */
+    startNewInvocation(): void;
+    /**
+     * Start a new agent loop cycle.
+     *
+     * @returns The cycle id and start time
+     */
+    startCycle(): {
+        cycleId: string;
+        startTime: number;
+    };
+    /**
+     * End the current agent loop cycle and record its duration.
+     *
+     * @param startTime - The timestamp when the cycle started (milliseconds since epoch)
+     */
+    endCycle(startTime: number): void;
+    /**
+     * Record metrics for a completed tool invocation.
+     *
+     * @param options - Tool usage recording options
+     */
+    endToolCall(options: ToolUsageOptions): void;
+    /**
+     * Update loop-level metrics from a model response.
+     *
+     * Call this after each model invocation within a cycle to
+     * accumulate usage and latency.
+     *
+     * @param metadata - The metadata event from a model invocation, or undefined if unavailable
+     */
+    updateCycle(metadata?: ModelMetadataEventData): void;
+    /**
+     * Read-only snapshot of the accumulated metrics.
+     * Returns an AgentMetrics instance suitable for inclusion in AgentResult.
+     */
+    get metrics(): AgentMetrics;
+    /**
+     * The most recent agent invocation, or undefined if none exist.
+     */
+    private get _latestAgentInvocation();
+    /**
+     * Update accumulated usage and metrics from a model metadata event.
+     *
+     * @param metadata - The metadata event from a model invocation
+     */
+    private _updateFromMetadata;
+    /**
+     * Update the accumulated token usage with new usage data.
+     *
+     * @param usage - The usage data to accumulate
+     */
+    private _updateUsage;
+    /**
+     * Creates an empty Usage object with all counters set to zero.
+     *
+     * @returns A Usage object with zeroed counters
+     */
+    private static _createEmptyUsage;
+    /**
+     * Accumulates token usage from a source into a target Usage object.
+     *
+     * @param target - The Usage object to accumulate into (mutated in place)
+     * @param source - The Usage object to accumulate from
+     */
+    private static _accumulateUsage;
+}
+export {};
+//# sourceMappingURL=meter.d.ts.map

package/dist/src/telemetry/meter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"meter.d.ts","sourceRoot":"","sources":["../../../src/telemetry/meter.ts"],"names":[],"mappings":"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"}