@introspection-sdk/introspection-pi 0.7.0 → 0.7.2

package/dist/instrument-agent.d.ts

@@ -1,8 +1,8 @@
 /**
  * Subscribe to a pi-agent {@link Agent} to emit `execute_tool` spans for every
- * tool call the loop runs.
+ * tool call the loop runs, and (optionally) one `invoke_agent` span per run.
  */
-import { type Attributes, type Context as OtelContext, type Tracer } from "@opentelemetry/api";
+import { type Attributes, type Context as OtelContext, type Meter, type Tracer } from "@opentelemetry/api";
 import type { Agent, AgentEvent } from "@earendil-works/pi-agent-core";
 import { type AgentMeta } from "./attributes.js";
 export interface InstrumentAgentOptions {
@@ -10,9 +10,31 @@ export interface InstrumentAgentOptions {
     tracer: Tracer;
     /** Required metadata stamped onto every execute_tool span. */
     meta: AgentMeta;
+    /**
+     * Optional meter. When set, the wrapper also records
+     * `gen_ai.execute_tool.duration` per tool call and (when `runSpans` is
+     * enabled) `gen_ai.invoke_agent.duration` per run.
+     */
+    meter?: Meter;
+    /**
+     * Emit one `invoke_agent {agent.name}` span per agent run
+     * (`agent_start` → `agent_end`), carrying conversation/agent identity
+     * and the final finish reason. Usage attributes stay on the chat spans
+     * only, so aggregations that sum a whole trace don't double-count.
+     *
+     * Off by default: hosts that already create their own turn/run spans
+     * (and parent chat spans onto them via `getParentContext`) would get
+     * duplicate run spans otherwise. When enabled, wire the chat spans under
+     * the run span with
+     * `instrumentStream(fn, { getParentContext: () => handle.getRunContext() })`;
+     * tool spans parent onto the run span automatically unless
+     * `getParentContext` is provided.
+     */
+    runSpans?: boolean;
     /**
      * Returns the parent OTel context for the next tool span. If undefined or
-     * returns null, `context.active()` is used at the time the start event fires.
+     * returns null, the active run span (when `runSpans` is enabled) or
+     * `context.active()` is used at the time the start event fires.
      */
     getParentContext?: () => OtelContext | null | undefined;
     /**
@@ -26,13 +48,20 @@ export interface InstrumentAgentOptions {
     spanName?: (toolName: string) => string;
 }
 export interface AgentInstrumentation {
-    /** Stop subscribing and finalize any tool spans still open. */
+    /** Stop subscribing and finalize any spans still open. */
     stop: () => void;
+    /**
+     * OTel context of the active `invoke_agent` span, when `runSpans` is
+     * enabled and a run is in flight. Pass to `instrumentStream`'s
+     * `getParentContext` so chat spans nest under the run span.
+     */
+    getRunContext: () => OtelContext | undefined;
 }
 /**
  * Subscribe to {@link Agent.subscribe} and emit one `execute_tool ${name}`
- * span per tool call. Returns a handle whose `stop()` unsubscribes and
- * finalizes any still-open spans.
+ * span per tool call (plus one `invoke_agent` span per run when enabled).
+ * Returns a handle whose `stop()` unsubscribes and finalizes any still-open
+ * spans.
  *
  * Tool call IDs are assumed unique per agent run; concurrent tool execution
  * (`ToolExecutionMode = "parallel"`) is supported because each id keys its

package/dist/instrument-agent.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"instrument-agent.d.ts","sourceRoot":"","sources":["../src/instrument-agent.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAIL,KAAK,UAAU,EACf,KAAK,OAAO,IAAI,WAAW,EAE3B,KAAK,MAAM,EACZ,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,+BAA+B,CAAC;AAEvE,OAAO,EAGL,KAAK,SAAS,EACf,MAAM,iBAAiB,CAAC;AAEzB,MAAM,WAAW,sBAAsB;IACrC,iDAAiD;IACjD,MAAM,EAAE,MAAM,CAAC;IACf,8DAA8D;IAC9D,IAAI,EAAE,SAAS,CAAC;IAChB;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,WAAW,GAAG,IAAI,GAAG,SAAS,CAAC;IACxD;;;OAGG;IACH,eAAe,CAAC,EAAE,CAChB,KAAK,EAAE,OAAO,CAAC,UAAU,EAAE;QAAE,IAAI,EAAE,sBAAsB,CAAA;KAAE,CAAC,KACzD,UAAU,CAAC;IAChB,8CAA8C;IAC9C,QAAQ,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,MAAM,CAAC;CACzC;AAED,MAAM,WAAW,oBAAoB;IACnC,+DAA+D;IAC/D,IAAI,EAAE,MAAM,IAAI,CAAC;CAClB;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,KAAK,EACZ,IAAI,EAAE,sBAAsB,GAC3B,oBAAoB,CAkBtB"}
+{"version":3,"file":"instrument-agent.d.ts","sourceRoot":"","sources":["../src/instrument-agent.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAKL,KAAK,UAAU,EACf,KAAK,OAAO,IAAI,WAAW,EAC3B,KAAK,KAAK,EAEV,KAAK,MAAM,EACZ,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,+BAA+B,CAAC;AAMvE,OAAO,EAIL,KAAK,SAAS,EACf,MAAM,iBAAiB,CAAC;AAKzB,MAAM,WAAW,sBAAsB;IACrC,iDAAiD;IACjD,MAAM,EAAE,MAAM,CAAC;IACf,8DAA8D;IAC9D,IAAI,EAAE,SAAS,CAAC;IAChB;;;;OAIG;IACH,KAAK,CAAC,EAAE,KAAK,CAAC;IACd;;;;;;;;;;;;;OAaG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,MAAM,WAAW,GAAG,IAAI,GAAG,SAAS,CAAC;IACxD;;;OAGG;IACH,eAAe,CAAC,EAAE,CAChB,KAAK,EAAE,OAAO,CAAC,UAAU,EAAE;QAAE,IAAI,EAAE,sBAAsB,CAAA;KAAE,CAAC,KACzD,UAAU,CAAC;IAChB,8CAA8C;IAC9C,QAAQ,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,MAAM,CAAC;CACzC;AAED,MAAM,WAAW,oBAAoB;IACnC,0DAA0D;IAC1D,IAAI,EAAE,MAAM,IAAI,CAAC;IACjB;;;;OAIG;IACH,aAAa,EAAE,MAAM,WAAW,GAAG,SAAS,CAAC;CAC9C;AAeD;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,KAAK,EACZ,IAAI,EAAE,sBAAsB,GAC3B,oBAAoB,CAiCtB"}

package/dist/instrument-agent.js

@@ -1,14 +1,18 @@
 /**
  * Subscribe to a pi-agent {@link Agent} to emit `execute_tool` spans for every
- * tool call the loop runs.
+ * tool call the loop runs, and (optionally) one `invoke_agent` span per run.
  */
-import { context as otelContext, SpanKind, SpanStatusCode, } from "@opentelemetry/api";
-import { GenAiSpanName, IntrospectionAttr } from "@introspection-sdk/types";
-import { executeToolAttributes, executeToolResultAttribute, } from "./attributes.js";
+import { context as otelContext, SpanKind, SpanStatusCode, trace, } from "@opentelemetry/api";
+import { GenAi, GenAiSpanName, IntrospectionAttr, } from "@introspection-sdk/types";
+import { executeToolAttributes, executeToolResultAttribute, invokeAgentAttributes, } from "./attributes.js";
+import { semconvFinishReason } from "./convert.js";
+import { classifyErrorType } from "./error-type.js";
+import { genAiMetrics } from "./metrics.js";
 /**
  * Subscribe to {@link Agent.subscribe} and emit one `execute_tool ${name}`
- * span per tool call. Returns a handle whose `stop()` unsubscribes and
- * finalizes any still-open spans.
+ * span per tool call (plus one `invoke_agent` span per run when enabled).
+ * Returns a handle whose `stop()` unsubscribes and finalizes any still-open
+ * spans.
  *
  * Tool call IDs are assumed unique per agent run; concurrent tool execution
  * (`ToolExecutionMode = "parallel"`) is supported because each id keys its
@@ -17,39 +21,85 @@ import { executeToolAttributes, executeToolResultAttribute, } from "./attributes
 export function instrumentAgent(agent, opts) {
     const buildSpanName = opts.spanName ?? GenAiSpanName.executeTool;
     const activeSpans = new Map();
+    const metrics = opts.meter ? genAiMetrics(opts.meter) : undefined;
+    const state = { run: undefined };
     const unsubscribe = agent.subscribe((event, signal) => {
-        handleEvent(event, opts, activeSpans, buildSpanName, signal);
+        handleEvent(event, agent, opts, activeSpans, state, metrics, buildSpanName, signal);
     });
     return {
         stop: () => {
             unsubscribe();
-            for (const span of activeSpans.values()) {
-                span.setStatus({ code: SpanStatusCode.OK });
+            for (const { span } of activeSpans.values()) {
                 span.end();
             }
             activeSpans.clear();
+            if (state.run) {
+                state.run.span.end();
+                state.run = undefined;
+            }
         },
+        getRunContext: () => state.run?.context,
     };
 }
-function handleEvent(event, opts, activeSpans, buildSpanName, signal) {
+function handleEvent(event, agent, opts, activeSpans, state, metrics, buildSpanName, signal) {
     switch (event.type) {
-        case "tool_execution_start": {
+        case "agent_start": {
+            if (!opts.runSpans)
+                return;
             const parentContext = opts.getParentContext?.() ?? otelContext.active();
-            const span = opts.tracer.startSpan(buildSpanName(event.toolName), { kind: SpanKind.INTERNAL }, parentContext ?? undefined);
-            span.setAttributes(executeToolAttributes(event.toolName, event.toolCallId, event.args, opts.meta));
-            const extra = opts.extraAttributes?.(event);
-            if (extra) {
-                span.setAttributes(extra);
+            const span = opts.tracer.startSpan(GenAiSpanName.invokeAgent(opts.meta.agentName), {
+                kind: SpanKind.INTERNAL,
+                attributes: invokeAgentAttributes(opts.meta),
+            }, parentContext ?? undefined);
+            state.run = {
+                span,
+                context: trace.setSpan(parentContext ?? otelContext.active(), span),
+                startedAt: Date.now(),
+            };
+            return;
+        }
+        case "message_end": {
+            const run = state.run;
+            const message = event.message;
+            if (!run || message.role !== "assistant" || !("usage" in message)) {
+                return;
             }
-            activeSpans.set(event.toolCallId, span);
+            // Track outcome only. The run span deliberately carries NO
+            // gen_ai.usage.* attributes: platform aggregations sum usage across
+            // every span in a conversation, so aggregated usage on the run span
+            // would double-count the chat spans beneath it.
+            run.lastStopReason = message.stopReason;
+            run.errorMessage = message.errorMessage;
+            return;
+        }
+        case "agent_end": {
+            const run = state.run;
+            if (!run)
+                return;
+            state.run = undefined;
+            finishRunSpan(run, opts.meta, metrics, signal);
+            return;
+        }
+        case "tool_execution_start": {
+            const parentContext = opts.getParentContext?.() ?? state.run?.context ?? otelContext.active();
+            const description = lookupToolDescription(agent, event.toolName);
+            // Full attribute set at span creation time so samplers see
+            // gen_ai.operation.name / tool.name / tool.type.
+            const attributes = {
+                ...executeToolAttributes(event.toolName, event.toolCallId, event.args, opts.meta, description),
+                ...opts.extraAttributes?.(event),
+            };
+            const span = opts.tracer.startSpan(buildSpanName(event.toolName), { kind: SpanKind.INTERNAL, attributes }, parentContext ?? undefined);
+            activeSpans.set(event.toolCallId, { span, startedAt: Date.now() });
             return;
         }
         case "tool_execution_end": {
-            const span = activeSpans.get(event.toolCallId);
-            if (!span)
+            const active = activeSpans.get(event.toolCallId);
+            if (!active)
                 return;
             activeSpans.delete(event.toolCallId);
-            span.setAttributes(executeToolResultAttribute(event.result));
+            const { span, startedAt } = active;
+            let errorType;
             if (event.isError && signal?.aborted) {
                 // The run's AbortSignal fired: pi synthesizes "Operation aborted"
                 // error results for tool calls cut short by a requested abort. A
@@ -58,6 +108,8 @@ function handleEvent(event, opts, activeSpans, buildSpanName, signal) {
                 span.setAttribute(IntrospectionAttr.TERMINATION_REASON, "cancelled");
             }
             else if (event.isError) {
+                errorType = "tool_error";
+                span.setAttribute("error.type", errorType);
                 span.setStatus({
                     code: SpanStatusCode.ERROR,
                     message: typeof event.result === "string"
@@ -68,15 +120,70 @@ function handleEvent(event, opts, activeSpans, buildSpanName, signal) {
                 });
             }
             else {
-                span.setStatus({ code: SpanStatusCode.OK });
+                // Semconv scopes gen_ai.tool.call.result to successful executions;
+                // error text is carried on the span status instead.
+                span.setAttributes(executeToolResultAttribute(event.result));
             }
             span.end();
+            if (metrics) {
+                const attributes = {
+                    [GenAi.TOOL_NAME]: event.toolName,
+                    [GenAi.TOOL_TYPE]: "function",
+                    [GenAi.AGENT_NAME]: opts.meta.agentName,
+                };
+                if (errorType)
+                    attributes["error.type"] = errorType;
+                metrics.executeToolDuration.record((Date.now() - startedAt) / 1000, attributes);
+            }
             return;
         }
         default:
             return;
     }
 }
+function finishRunSpan(run, meta, metrics, signal) {
+    const { span } = run;
+    if (run.lastStopReason) {
+        span.setAttribute(GenAi.RESPONSE_FINISH_REASONS, [
+            semconvFinishReason(run.lastStopReason),
+        ]);
+    }
+    let errorType;
+    const aborted = run.lastStopReason === "aborted" || signal?.aborted === true;
+    if (aborted) {
+        // Mirrors the chat-span contract: a requested cancellation is an
+        // outcome, not a failure.
+        span.setAttribute(IntrospectionAttr.TERMINATION_REASON, "cancelled");
+    }
+    else if (run.lastStopReason === "error") {
+        const errorMessage = run.errorMessage ?? "Unknown error";
+        errorType = classifyErrorType(errorMessage, "model_error");
+        span.setAttribute("error.type", errorType);
+        span.recordException(new Error(errorMessage));
+        span.setStatus({ code: SpanStatusCode.ERROR, message: errorMessage });
+    }
+    span.end();
+    if (metrics) {
+        const attributes = { [GenAi.AGENT_NAME]: meta.agentName };
+        if (errorType)
+            attributes["error.type"] = errorType;
+        metrics.invokeAgentDuration.record((Date.now() - run.startedAt) / 1000, attributes);
+    }
+}
+/**
+ * Best-effort `gen_ai.tool.description` lookup from the agent's tool
+ * registry. Defensive against partial Agent implementations (tests, mocks)
+ * that don't expose `state.tools`.
+ */
+function lookupToolDescription(agent, toolName) {
+    try {
+        return agent.state?.tools?.find((tool) => tool.name === toolName)
+            ?.description;
+    }
+    catch {
+        return undefined;
+    }
+}
 function safeStringify(value) {
     try {
         return JSON.stringify(value);

package/dist/instrument-agent.js.map

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

package/dist/instrument-stream.d.ts

@@ -2,7 +2,7 @@
  * Wrap a pi-agent `StreamFn` so each invocation emits a `chat` span that
  * conforms to the OTEL GenAI semantic convention.
  */
-import { type Attributes, type Context as OtelContext, type Tracer } from "@opentelemetry/api";
+import { type Attributes, type Context as OtelContext, type Meter, type Tracer } from "@opentelemetry/api";
 import { type Api, type Context, type Model } from "@earendil-works/pi-ai";
 import type { StreamFn } from "@earendil-works/pi-agent-core";
 import { type AbortTerminationReason } from "@introspection-sdk/types";
@@ -12,6 +12,13 @@ export interface InstrumentStreamOptions {
     tracer: Tracer;
     /** Required metadata stamped onto every chat span. */
     meta: AgentMeta;
+    /**
+     * Optional meter. When set, the wrapper also records the GenAI client
+     * metrics (`gen_ai.client.token.usage`, `gen_ai.client.operation.duration`,
+     * `gen_ai.client.operation.time_to_first_chunk`,
+     * `gen_ai.client.operation.time_per_output_chunk`).
+     */
+    meter?: Meter;
     /**
      * Returns the parent OTel context for the next chat span. If undefined or
      * returns null, `context.active()` is used at call time.
@@ -22,7 +29,7 @@ export interface InstrumentStreamOptions {
      * on top of the GenAI semconv attributes for each chat span.
      */
     extraAttributes?: (model: Model<Api>, context: Context) => Attributes;
-    /** Override the default span name builder. */
+    /** Override the default span name builder (default: `chat {model.id}`). */
     spanName?: (model: Model<Api>, context: Context) => string;
     /**
      * Returns the compaction summaries known for the session, read at span
@@ -47,7 +54,8 @@ export interface InstrumentStreamOptions {
     abortTerminationReason?: () => AbortTerminationReason | null;
 }
 /**
- * Wrap a {@link StreamFn} to emit `chat ${provider}` spans.
+ * Wrap a {@link StreamFn} to emit `chat {model}` spans (CLIENT kind — the
+ * model runs in a remote process).
  *
  * Reassign `agent.streamFn` with the result:
  *

package/dist/instrument-stream.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"instrument-stream.d.ts","sourceRoot":"","sources":["../src/instrument-stream.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAKL,KAAK,UAAU,EACf,KAAK,OAAO,IAAI,WAAW,EAE3B,KAAK,MAAM,EACZ,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAKL,KAAK,GAAG,EACR,KAAK,OAAO,EACZ,KAAK,KAAK,EACX,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,+BAA+B,CAAC;AAC9D,OAAO,EAGL,KAAK,sBAAsB,EAC5B,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAGL,KAAK,SAAS,EACf,MAAM,iBAAiB,CAAC;AAEzB,MAAM,WAAW,uBAAuB;IACtC,wCAAwC;IACxC,MAAM,EAAE,MAAM,CAAC;IACf,sDAAsD;IACtD,IAAI,EAAE,SAAS,CAAC;IAChB;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,WAAW,GAAG,IAAI,GAAG,SAAS,CAAC;IACxD;;;OAGG;IACH,eAAe,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,CAAC,GAAG,CAAC,EAAE,OAAO,EAAE,OAAO,KAAK,UAAU,CAAC;IACtE,8CAA8C;IAC9C,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,CAAC,GAAG,CAAC,EAAE,OAAO,EAAE,OAAO,KAAK,MAAM,CAAC;IAC3D;;;;;;;OAOG;IACH,sBAAsB,CAAC,EAAE,MAAM,SAAS,MAAM,EAAE,CAAC;IACjD;;;;;;;;;;OAUG;IACH,sBAAsB,CAAC,EAAE,MAAM,sBAAsB,GAAG,IAAI,CAAC;CAC9D;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,QAAQ,EAClB,IAAI,EAAE,uBAAuB,GAC5B,QAAQ,CA0CV"}
+{"version":3,"file":"instrument-stream.d.ts","sourceRoot":"","sources":["../src/instrument-stream.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAKL,KAAK,UAAU,EACf,KAAK,OAAO,IAAI,WAAW,EAC3B,KAAK,KAAK,EAEV,KAAK,MAAM,EACZ,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAKL,KAAK,GAAG,EACR,KAAK,OAAO,EACZ,KAAK,KAAK,EACX,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,+BAA+B,CAAC;AAC9D,OAAO,EAIL,KAAK,sBAAsB,EAC5B,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAIL,KAAK,SAAS,EACf,MAAM,iBAAiB,CAAC;AAIzB,MAAM,WAAW,uBAAuB;IACtC,wCAAwC;IACxC,MAAM,EAAE,MAAM,CAAC;IACf,sDAAsD;IACtD,IAAI,EAAE,SAAS,CAAC;IAChB;;;;;OAKG;IACH,KAAK,CAAC,EAAE,KAAK,CAAC;IACd;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,WAAW,GAAG,IAAI,GAAG,SAAS,CAAC;IACxD;;;OAGG;IACH,eAAe,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,CAAC,GAAG,CAAC,EAAE,OAAO,EAAE,OAAO,KAAK,UAAU,CAAC;IACtE,2EAA2E;IAC3E,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,CAAC,GAAG,CAAC,EAAE,OAAO,EAAE,OAAO,KAAK,MAAM,CAAC;IAC3D;;;;;;;OAOG;IACH,sBAAsB,CAAC,EAAE,MAAM,SAAS,MAAM,EAAE,CAAC;IACjD;;;;;;;;;;OAUG;IACH,sBAAsB,CAAC,EAAE,MAAM,sBAAsB,GAAG,IAAI,CAAC;CAC9D;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,QAAQ,EAClB,IAAI,EAAE,uBAAuB,GAC5B,QAAQ,CA6CV"}

package/dist/instrument-stream.js

@@ -4,10 +4,13 @@
  */
 import { context as otelContext, SpanKind, SpanStatusCode, trace, } from "@opentelemetry/api";
 import { createAssistantMessageEventStream, } from "@earendil-works/pi-ai";
-import { GenAiSpanName, IntrospectionAttr, } from "@introspection-sdk/types";
-import { chatRequestAttributes, chatResponseAttributes, } from "./attributes.js";
+import { GenAi, GenAiSpanName, IntrospectionAttr, } from "@introspection-sdk/types";
+import { chatRequestAttributes, chatResponseAttributes, serverAttributes, } from "./attributes.js";
+import { classifyErrorType, classifyThrownErrorType } from "./error-type.js";
+import { genAiMetrics } from "./metrics.js";
 /**
- * Wrap a {@link StreamFn} to emit `chat ${provider}` spans.
+ * Wrap a {@link StreamFn} to emit `chat {model}` spans (CLIENT kind — the
+ * model runs in a remote process).
  *
  * Reassign `agent.streamFn` with the result:
  *
@@ -20,17 +23,21 @@ import { chatRequestAttributes, chatResponseAttributes, } from "./attributes.js"
  * `error` events, never thrown synchronously.
  */
 export function instrumentStream(streamFn, opts) {
-    const buildSpanName = opts.spanName ?? ((model) => GenAiSpanName.chat(model.provider));
+    const buildSpanName = opts.spanName ?? ((model) => GenAiSpanName.chat(model.id));
+    const metrics = opts.meter ? genAiMetrics(opts.meter) : undefined;
     return ((model, context, options) => {
         const parentContext = opts.getParentContext?.() ?? otelContext.active();
-        const span = opts.tracer.startSpan(buildSpanName(model, context), { kind: SpanKind.INTERNAL }, parentContext ?? undefined);
-        span.setAttributes(chatRequestAttributes(model, context, opts.meta, {
-            compactionSummaries: opts.getCompactionSummaries?.(),
-        }));
-        const extra = opts.extraAttributes?.(model, context);
-        if (extra) {
-            span.setAttributes(extra);
-        }
+        // Compute the full attribute set up front and pass it at span creation
+        // time so samplers see gen_ai.operation.name / provider / model /
+        // server.*.
+        const attributes = {
+            ...chatRequestAttributes(model, context, opts.meta, {
+                compactionSummaries: opts.getCompactionSummaries?.(),
+                streamOptions: options,
+            }),
+            ...opts.extraAttributes?.(model, context),
+        };
+        const span = opts.tracer.startSpan(buildSpanName(model, context), { kind: SpanKind.CLIENT, attributes }, parentContext ?? undefined);
         const proxy = createAssistantMessageEventStream();
         const spanContext = trace.setSpan(parentContext ?? otelContext.active(), span);
         void runUpstream({
@@ -41,20 +48,43 @@ export function instrumentStream(streamFn, opts) {
             spanContext,
             span,
             proxy,
+            metrics,
             abortTerminationReason: opts.abortTerminationReason,
         });
         return proxy;
     });
 }
-async function runUpstream({ streamFn, model, context, options, spanContext, span, proxy, abortTerminationReason, }) {
+async function runUpstream({ streamFn, model, context, options, spanContext, span, proxy, metrics, abortTerminationReason, }) {
     let finished = false;
+    const startedAt = Date.now();
+    const startedAtMonotonic = performance.now();
+    let lastChunkAt;
     try {
         const upstream = await otelContext.with(spanContext, () => streamFn(model, context, options));
         for await (const event of upstream) {
+            if (isOutputChunk(event)) {
+                const now = performance.now();
+                if (lastChunkAt === undefined) {
+                    const timeToFirstChunk = (now - startedAtMonotonic) / 1000;
+                    span.setAttribute("gen_ai.response.time_to_first_chunk", timeToFirstChunk);
+                    metrics?.timeToFirstChunk.record(timeToFirstChunk, chatMetricAttributes(model));
+                }
+                else {
+                    metrics?.timePerOutputChunk.record((now - lastChunkAt) / 1000, chatMetricAttributes(model));
+                }
+                lastChunkAt = now;
+            }
             proxy.push(event);
             if (!finished && (event.type === "done" || event.type === "error")) {
                 finished = true;
-                finishSpan(span, event, abortTerminationReason);
+                finishSpan({
+                    span,
+                    event,
+                    model,
+                    startedAt,
+                    metrics,
+                    abortTerminationReason,
+                });
             }
         }
     }
@@ -62,26 +92,40 @@ async function runUpstream({ streamFn, model, context, options, spanContext, spa
         const errorMessage = err instanceof Error ? err.message : String(err);
         const errorEvent = {
             type: "error",
-            reason: "error",
-            error: assistantErrorMessage(model, errorMessage),
+            reason: options?.signal?.aborted === true ? "aborted" : "error",
+            error: assistantErrorMessage(model, errorMessage, options?.signal?.aborted === true),
         };
-        span.recordException(err instanceof Error ? err : new Error(errorMessage));
+        if (options?.signal?.aborted !== true) {
+            recordGenAiException(span, err, classifyThrownErrorType(err));
+        }
         proxy.push(errorEvent);
         if (!finished) {
             finished = true;
-            finishSpan(span, errorEvent, abortTerminationReason);
+            finishSpan({
+                span,
+                event: errorEvent,
+                model,
+                startedAt,
+                metrics,
+                abortTerminationReason,
+            });
         }
     }
     finally {
         if (!finished) {
             // Upstream ended without a terminal event — close the span anyway so
             // we don't leak.
-            span.setStatus({ code: SpanStatusCode.OK });
             span.end();
         }
     }
 }
-function finishSpan(span, event, abortTerminationReason) {
+function isOutputChunk(event) {
+    return ((event.type === "text_delta" ||
+        event.type === "thinking_delta" ||
+        event.type === "toolcall_delta") &&
+        event.delta.length > 0);
+}
+function finishSpan({ span, event, model, startedAt, metrics, abortTerminationReason, }) {
     const message = event.type === "done" ? event.message : event.error;
     span.setAttributes(chatResponseAttributes(message));
     const aborted = (event.type === "error" && event.reason === "aborted") ||
@@ -91,6 +135,7 @@ function finishSpan(span, event, abortTerminationReason) {
         : abortTerminationReason
             ? abortTerminationReason()
             : "cancelled";
+    let errorType;
     if (terminationReason !== null) {
         // A requested cancellation is an outcome, not a failure: status stays
         // Unset (no success assertion over a truncated generation, no error),
@@ -105,15 +150,57 @@ function finishSpan(span, event, abortTerminationReason) {
         // abort (callback returned null) — fail toward a false error, never a
         // hidden one.
         const errorMessage = message.errorMessage ?? "Unknown error";
-        span.recordException(new Error(errorMessage));
+        errorType = classifyErrorType(errorMessage, "model_error");
+        recordGenAiException(span, new Error(errorMessage), errorType);
         span.setStatus({ code: SpanStatusCode.ERROR, message: errorMessage });
     }
-    else {
-        span.setStatus({ code: SpanStatusCode.OK });
+    if (metrics) {
+        recordCompletionMetrics(metrics, model, message, startedAt, errorType);
     }
     span.end();
 }
-function assistantErrorMessage(model, errorMessage) {
+function chatMetricAttributes(model) {
+    return {
+        [GenAi.OPERATION_NAME]: "chat",
+        [GenAi.PROVIDER_NAME]: model.provider,
+        [GenAi.REQUEST_MODEL]: model.id,
+        ...serverAttributes(model.baseUrl),
+    };
+}
+function recordCompletionMetrics(metrics, model, message, startedAt, errorType) {
+    const attributes = chatMetricAttributes(model);
+    if (message.model) {
+        attributes[GenAi.RESPONSE_MODEL] = message.model;
+    }
+    const durationAttributes = errorType
+        ? { ...attributes, "error.type": errorType }
+        : attributes;
+    metrics.operationDuration.record((Date.now() - startedAt) / 1000, durationAttributes);
+    const inputTokens = message.usage.input + message.usage.cacheRead + message.usage.cacheWrite;
+    if (inputTokens > 0) {
+        metrics.tokenUsage.record(inputTokens, {
+            ...attributes,
+            "gen_ai.token.type": "input",
+        });
+    }
+    if (message.usage.output > 0) {
+        metrics.tokenUsage.record(message.usage.output, {
+            ...attributes,
+            "gen_ai.token.type": "output",
+        });
+    }
+}
+function recordGenAiException(span, error, errorType) {
+    const exception = error instanceof Error ? error : new Error(String(error));
+    span.setAttribute("error.type", errorType);
+    // recordException writes the standard `exception` span event
+    // (exception.type / exception.message / exception.stacktrace). The
+    // semconv `gen_ai.client.operation.exception` signal is a *log* event —
+    // duplicating it as a second span event is not part of the convention,
+    // so only the standard exception event is recorded here.
+    span.recordException(exception);
+}
+function assistantErrorMessage(model, errorMessage, aborted = false) {
     return {
         role: "assistant",
         content: [],
@@ -128,7 +215,7 @@ function assistantErrorMessage(model, errorMessage) {
             totalTokens: 0,
             cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
         },
-        stopReason: "error",
+        stopReason: aborted ? "aborted" : "error",
         errorMessage,
         timestamp: Date.now(),
     };

package/dist/instrument-stream.js.map

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

package/dist/metrics.d.ts

@@ -0,0 +1,26 @@
+/**
+ * GenAI client metric instruments per the OTel GenAI semconv metrics doc.
+ *
+ * Instruments are created lazily per `Meter` and cached, so repeated
+ * `instrumentStream` / `instrumentAgent` calls sharing a meter reuse the
+ * same histograms. Bucket boundaries follow the spec's
+ * ExplicitBucketBoundaries advice where one is defined.
+ */
+import type { Histogram, Meter } from "@opentelemetry/api";
+export interface GenAiMetrics {
+    /** `gen_ai.client.token.usage` — record once per token type per call. */
+    tokenUsage: Histogram;
+    /** `gen_ai.client.operation.duration` — seconds per chat call. */
+    operationDuration: Histogram;
+    /** `gen_ai.client.operation.time_to_first_chunk` — streaming only. */
+    timeToFirstChunk: Histogram;
+    /** `gen_ai.client.operation.time_per_output_chunk` — per chunk after the first. */
+    timePerOutputChunk: Histogram;
+    /** `gen_ai.execute_tool.duration` — seconds per tool execution. */
+    executeToolDuration: Histogram;
+    /** `gen_ai.invoke_agent.duration` — seconds per in-process agent run. */
+    invokeAgentDuration: Histogram;
+}
+/** Get (or create) the GenAI instruments for a meter. */
+export declare function genAiMetrics(meter: Meter): GenAiMetrics;
+//# sourceMappingURL=metrics.d.ts.map

package/dist/metrics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.d.ts","sourceRoot":"","sources":["../src/metrics.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAmB3D,MAAM,WAAW,YAAY;IAC3B,yEAAyE;IACzE,UAAU,EAAE,SAAS,CAAC;IACtB,kEAAkE;IAClE,iBAAiB,EAAE,SAAS,CAAC;IAC7B,sEAAsE;IACtE,gBAAgB,EAAE,SAAS,CAAC;IAC5B,mFAAmF;IACnF,kBAAkB,EAAE,SAAS,CAAC;IAC9B,mEAAmE;IACnE,mBAAmB,EAAE,SAAS,CAAC;IAC/B,yEAAyE;IACzE,mBAAmB,EAAE,SAAS,CAAC;CAChC;AAID,yDAAyD;AACzD,wBAAgB,YAAY,CAAC,KAAK,EAAE,KAAK,GAAG,YAAY,CAmDvD"}