@strands-agents/sdk 0.4.0 → 0.6.0

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

@@ -0,0 +1,219 @@
+/**
+ * OpenTelemetry integration.
+ *
+ * This module provides tracing capabilities using OpenTelemetry,
+ * enabling trace data to be sent to OTLP endpoints.
+ *
+ * Uses a fully stateful approach via OpenTelemetry's context propagation.
+ * Parent-child relationships are established automatically through
+ * context.active(). Use context.with() to set a span as active before
+ * creating child spans.
+ *
+ * @example
+ * ```typescript
+ * const tracer = new Tracer()
+ * const parentSpan = tracer.startAgentSpan({ ... })
+ *
+ * // Run code with parentSpan as active context
+ * await context.with(trace.setSpan(context.active(), parentSpan), async () => {
+ *   // Child spans automatically parent to parentSpan
+ *   const childSpan = tracer.startModelInvokeSpan({ messages })
+ *   // ...
+ *   tracer.endModelInvokeSpan(childSpan)
+ * })
+ *
+ * tracer.endAgentSpan(parentSpan)
+ * ```
+ */
+import type { Span, AttributeValue } from '@opentelemetry/api';
+import type { EndAgentSpanOptions, EndModelSpanOptions, EndToolCallSpanOptions, EndAgentLoopSpanOptions, StartAgentSpanOptions, StartModelInvokeSpanOptions, StartToolCallSpanOptions, StartAgentLoopSpanOptions } from './types.js';
+/**
+ * Tracer manages OpenTelemetry spans for agent operations.
+ *
+ * Uses a fully stateful approach via OpenTelemetry's context propagation.
+ * Parent-child relationships are established automatically through context.active().
+ *
+ * To create nested spans, use context.with() to set the parent span as active:
+ * ```typescript
+ * const parent = tracer.startAgentSpan({ ... })
+ * context.with(trace.setSpan(context.active(), parent), () => {
+ *   const child = tracer.startModelInvokeSpan({ messages }) // auto-parents to parent
+ * })
+ * ```
+ */
+export declare class Tracer {
+    /**
+     * OpenTelemetry tracer instance obtained from the global API.
+     */
+    private readonly _tracer;
+    /**
+     * Whether to use latest experimental semantic conventions.
+     *
+     * Enabled via `OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental`.
+     * Changes attribute names (e.g., `gen_ai.system` → `gen_ai.provider.name`) and
+     * event formats (single `gen_ai.client.inference.operation.details` event vs
+     * separate per-message events). Enable when your observability backend supports
+     * newer GenAI conventions.
+     *
+     * @see https://opentelemetry.io/docs/specs/semconv/gen-ai/
+     */
+    private readonly _useLatestConventions;
+    /**
+     * Whether to include full tool JSON schemas in span attributes.
+     *
+     * Enabled via `OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_tool_definitions`.
+     * Useful for debugging tool configuration issues. Disabled by default to
+     * reduce span payload size and observability costs.
+     *
+     * Can be combined with other options:
+     * `OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental,gen_ai_tool_definitions`
+     */
+    private readonly _includeToolDefinitions;
+    /**
+     * Custom attributes to include on all spans created by this tracer.
+     */
+    private readonly _traceAttributes;
+    /** Root span for the current agent invocation. */
+    private _agentSpan;
+    /** Span for the current agent loop cycle, used to parent model and tool spans. */
+    private _loopSpan;
+    /**
+     * Initialize the tracer with OpenTelemetry configuration.
+     * Reads OTEL_SEMCONV_STABILITY_OPT_IN to determine convention version.
+     * Gets tracer from the global API to ensure ground truth - works correctly
+     * whether the user or Strands initialized the tracer provider.
+     *
+     * @param traceAttributes - Optional custom attributes to include on all spans
+     */
+    constructor(traceAttributes?: Record<string, AttributeValue>);
+    /**
+     * Start an agent invocation span.
+     * Returns the span which should be ended with endAgentSpan.
+     * Parents to the current active span from context.active().
+     *
+     * @param options - Options for starting the agent span
+     */
+    startAgentSpan(options: StartAgentSpanOptions): Span | null;
+    /**
+     * End an agent invocation span.
+     *
+     * @param span - The span to end, or null if span creation failed
+     * @param options - Options for ending the span including response, error, and usage data
+     */
+    endAgentSpan(span: Span | null, options?: EndAgentSpanOptions): void;
+    /**
+     * Start a model invocation span.
+     * Parents to the current active span from context.active().
+     *
+     * @param options - Options for starting the model invocation span
+     */
+    startModelInvokeSpan(options: StartModelInvokeSpanOptions): Span | null;
+    /**
+     * End a model invocation span.
+     *
+     * @param span - The span to end, or null if span creation failed
+     * @param options - Options for ending the span including usage, metrics, error, and output
+     */
+    endModelInvokeSpan(span: Span | null, options?: EndModelSpanOptions): void;
+    /**
+     * Start a tool call span.
+     * Parents to the current active span from context.active().
+     *
+     * @param options - Options for starting the tool call span
+     */
+    startToolCallSpan(options: StartToolCallSpanOptions): Span | null;
+    /**
+     * End a tool call span.
+     *
+     * @param span - The span to end, or null if span creation failed
+     * @param options - Options for ending the tool call span
+     */
+    endToolCallSpan(span: Span | null, options?: EndToolCallSpanOptions): void;
+    /**
+     * Runs a callback with the given span set as the active OpenTelemetry context.
+     * Downstream code (e.g., MCP clients) can read the span from context.active()
+     * for distributed trace propagation. No-ops if span is null.
+     *
+     * @param span - The span to set as active, or null if span creation failed
+     * @param fn - The callback to run within the span's context
+     * @returns The return value of the callback
+     */
+    withSpanContext<T>(span: Span | null, fn: () => T): T;
+    /**
+     * Start an agent loop cycle span.
+     * Parents to the current active span from context.active().
+     *
+     * @param options - Options for starting the agent loop span
+     */
+    startAgentLoopSpan(options: StartAgentLoopSpanOptions): Span | null;
+    /**
+     * End an agent loop cycle span.
+     *
+     * @param span - The span to end, or null if span creation failed
+     * @param options - Options for ending the agent loop span
+     */
+    endAgentLoopSpan(span: Span | null, options?: EndAgentLoopSpanOptions): void;
+    /**
+     * Create a span parented to the current active context.
+     */
+    private _startSpan;
+    /**
+     * End a span with the given attributes and optional error.
+     */
+    private _endSpan;
+    /**
+     * Add an event to a span.
+     */
+    private _addEvent;
+    /**
+     * Get common attributes based on semantic convention version.
+     * The attribute name changed between OTEL semconv versions:
+     * - Stable: 'gen_ai.system'
+     * - Latest experimental: 'gen_ai.provider.name'
+     */
+    private _getCommonAttributes;
+    /**
+     * Add message events to a span.
+     * Uses different event formats based on semantic convention version:
+     * - Latest: Single 'gen_ai.client.inference.operation.details' event with all messages
+     * - Stable: Separate events per message (gen_ai.user.message, gen_ai.assistant.message, etc.)
+     */
+    private _addEventMessages;
+    /**
+     * Get the event name for a message based on its type.
+     */
+    private _getEventNameForMessage;
+    /**
+     * Set usage attributes on an attributes object.
+     * Sets both legacy (prompt_tokens/completion_tokens) and new (input_tokens/output_tokens)
+     * attribute names for compatibility with different OTEL backends.
+     */
+    private _setUsageAttributes;
+    /**
+     * Set metrics attributes on an attributes object.
+     */
+    private _setMetricsAttributes;
+    /**
+     * Add response event to a span.
+     */
+    private _addResponseEvent;
+    /**
+     * Add output event to a span for model invocation.
+     */
+    private _addOutputEvent;
+    /**
+     * Parse the OTEL_SEMCONV_STABILITY_OPT_IN environment variable.
+     */
+    private static _parseSemconvOptIn;
+    /**
+     * Map content blocks to OTEL parts format (latest conventions).
+     * Converts SDK content block types to OTEL semantic convention format.
+     */
+    private static _mapContentBlocksToOtelParts;
+    /**
+     * Map content blocks to stable format (older conventions).
+     * Simplifies content blocks to a minimal structure for legacy OTEL backends.
+     */
+    private static _mapContentBlocksToStableFormat;
+}
+//# sourceMappingURL=tracer.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tracer.d.ts","sourceRoot":"","sources":["../../../src/telemetry/tracer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAGH,OAAO,KAAK,EAAE,IAAI,EAAqC,cAAc,EAAE,MAAM,oBAAoB,CAAA;AAEjG,OAAO,KAAK,EACV,mBAAmB,EACnB,mBAAmB,EACnB,sBAAsB,EACtB,uBAAuB,EACvB,qBAAqB,EACrB,2BAA2B,EAC3B,wBAAwB,EACxB,yBAAyB,EAG1B,MAAM,YAAY,CAAA;AAKnB;;;;;;;;;;;;;GAaG;AACH,qBAAa,MAAM;IACjB;;OAEG;IACH,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAY;IAEpC;;;;;;;;;;OAUG;IACH,OAAO,CAAC,QAAQ,CAAC,qBAAqB,CAAS;IAE/C;;;;;;;;;OASG;IACH,OAAO,CAAC,QAAQ,CAAC,uBAAuB,CAAS;IAEjD;;OAEG;IACH,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAgC;IAEjE,kDAAkD;IAClD,OAAO,CAAC,UAAU,CAAkB;IAEpC,kFAAkF;IAClF,OAAO,CAAC,SAAS,CAAkB;IAEnC;;;;;;;OAOG;gBACS,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC;IAY5D;;;;;;OAMG;IACH,cAAc,CAAC,OAAO,EAAE,qBAAqB,GAAG,IAAI,GAAG,IAAI;IAqC3D;;;;;OAKG;IACH,YAAY,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI,EAAE,OAAO,GAAE,mBAAwB,GAAG,IAAI;IAoBxE;;;;;OAKG;IACH,oBAAoB,CAAC,OAAO,EAAE,2BAA2B,GAAG,IAAI,GAAG,IAAI;IAsBvE;;;;;OAKG;IACH,kBAAkB,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI,EAAE,OAAO,GAAE,mBAAwB,GAAG,IAAI;IAoB9E;;;;;OAKG;IACH,iBAAiB,CAAC,OAAO,EAAE,wBAAwB,GAAG,IAAI,GAAG,IAAI;IA0CjE;;;;;OAKG;IACH,eAAe,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI,EAAE,OAAO,GAAE,sBAA2B,GAAG,IAAI;IAqC9E;;;;;;;;OAQG;IACH,eAAe,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,GAAG,IAAI,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC;IAKrD;;;;;OAKG;IACH,kBAAkB,CAAC,OAAO,EAAE,yBAAyB,GAAG,IAAI,GAAG,IAAI;IAmBnE;;;;;OAKG;IACH,gBAAgB,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI,EAAE,OAAO,GAAE,uBAA4B,GAAG,IAAI;IAUhF;;OAEG;IACH,OAAO,CAAC,UAAU;IA8BlB;;OAEG;IACH,OAAO,CAAC,QAAQ;IAoBhB;;OAEG;IACH,OAAO,CAAC,SAAS;IAgBjB;;;;;OAKG;IACH,OAAO,CAAC,oBAAoB;IAc5B;;;;;OAKG;IACH,OAAO,CAAC,iBAAiB;IAwBzB;;OAEG;IACH,OAAO,CAAC,uBAAuB;IAc/B;;;;OAIG;IACH,OAAO,CAAC,mBAAmB;IAe3B;;OAEG;IACH,OAAO,CAAC,qBAAqB;IAM7B;;OAEG;IACH,OAAO,CAAC,iBAAiB;IA2BzB;;OAEG;IACH,OAAO,CAAC,eAAe;IAwBvB;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,kBAAkB;IAUjC;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,4BAA4B;IAiB3C;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,+BAA+B;CAkB/C"}