toad-eye 2.4.5 → 2.6.0

package/dist/instrumentations/create.js

@@ -1,8 +1,8 @@
 import { createRequire } from "node:module";
 import { trace, context, diag, SpanStatusCode, } from "@opentelemetry/api";
 import { traceLLMCall, processContent } from "../core/spans.js";
-import { calculateCost } from "../core/pricing.js";
-import { recordRequestDuration, recordRequestCost, recordTokens, recordRequest, recordError, recordTimeToFirstToken, recordResponseEmpty, recordResponseLatencyPerToken, recordBudgetExceeded, recordBudgetDowngraded, } from "../core/metrics.js";
+import { calculateCost, getModelPricing } from "../core/pricing.js";
+import { recordRequestDuration, recordRequestCost, recordTokens, recordRequest, recordError, recordTimeToFirstToken, recordResponseEmpty, recordResponseLatencyPerToken, recordContextUtilization, recordContextBlocked, recordBudgetExceeded, recordBudgetDowngraded, } from "../core/metrics.js";
 import { getConfig, getBudgetTracker } from "../core/tracer.js";
 import { ToadBudgetExceededError } from "../budget/index.js";
 import { GEN_AI_ATTRS, INSTRUMENTATION_NAME } from "../types/index.js";
@@ -31,6 +31,7 @@ function loadModule(moduleName) {
 async function* wrapAsyncIterable(stream, accumulate, onFirstChunk, onComplete, onError) {
     const acc = {
         completion: "",
+        thinkingContent: "",
         inputTokens: 0,
         outputTokens: 0,
         toolCalls: [],
@@ -93,14 +94,16 @@ original, patch, providerName) {
                 recordBudgetDowngraded(override.budget);
             }
         }
-        const span = tracer.startSpan(`chat ${effectiveModel}`);
+        const op = patch.operationName ?? "chat";
+        const span = tracer.startSpan(`${op} ${effectiveModel}`);
         const ctx = trace.setSpan(context.active(), span);
         const sessionId = config?.sessionExtractor?.() ?? config?.sessionId;
+        let ttftMs = 0;
         span.setAttributes({
             [GEN_AI_ATTRS.PROVIDER]: effectiveProvider,
             [GEN_AI_ATTRS.REQUEST_MODEL]: effectiveModel,
             [GEN_AI_ATTRS.TEMPERATURE]: req.temperature ?? 1.0,
-            [GEN_AI_ATTRS.OPERATION]: "chat",
+            [GEN_AI_ATTRS.OPERATION]: op,
             ...(sessionId !== undefined && { [GEN_AI_ATTRS.SESSION_ID]: sessionId }),
         });
         let response;
@@ -136,11 +139,22 @@ original, patch, providerName) {
             ? resp["stream"]
             : response;
         const wrapped = context.bind(ctx, wrapAsyncIterable(streamIterable, (acc, chunk) => patch.accumulateChunk(acc, chunk), () => {
-            recordTimeToFirstToken(performance.now() - start, effectiveProvider, effectiveModel);
+            const ttft = performance.now() - start;
+            ttftMs = ttft;
+            recordTimeToFirstToken(ttft, effectiveProvider, effectiveModel);
+            // Span event for per-trace TTFT debugging in Jaeger
+            span.addEvent("gen_ai.content.first_token", {
+                "gen_ai.response.time_to_first_token_ms": ttft,
+            });
+            span.setAttribute("gen_ai.response.time_to_first_token_ms", ttft);
         }, (acc) => {
             const duration = performance.now() - start;
             const cost = calculateCost(effectiveModel, acc.inputTokens, acc.outputTokens);
             const processedCompletion = processContent(acc.completion);
+            // Anthropic extended thinking — track separately from completion
+            if (acc.thinkingContent.length > 0) {
+                span.setAttribute("gen_ai.toad_eye.thinking.content_length", acc.thinkingContent.length);
+            }
             // Record tool calls from streaming chunks
             if (acc.toolCalls.length > 0) {
                 span.setAttribute(GEN_AI_ATTRS.TOOL_NAME, acc.toolCalls.map((t) => t.name).join(", "));
@@ -154,10 +168,18 @@ original, patch, providerName) {
                 [GEN_AI_ATTRS.INPUT_TOKENS]: acc.inputTokens,
                 [GEN_AI_ATTRS.OUTPUT_TOKENS]: acc.outputTokens,
                 [GEN_AI_ATTRS.COST]: cost,
-                [GEN_AI_ATTRS.STATUS]: "success",
-                [GEN_AI_ATTRS.FINISH_REASONS]: ["stop"],
+                [GEN_AI_ATTRS.STATUS]: acc.finishReason === "SAFETY" ? "error" : "success",
+                [GEN_AI_ATTRS.FINISH_REASONS]: [acc.finishReason ?? "stop"],
             });
-            span.setStatus({ code: SpanStatusCode.OK });
+            if (acc.finishReason === "SAFETY") {
+                span.setStatus({
+                    code: SpanStatusCode.ERROR,
+                    message: "Content blocked by safety filter",
+                });
+            }
+            else {
+                span.setStatus({ code: SpanStatusCode.OK });
+            }
             span.end();
             recordRequest(effectiveProvider, effectiveModel);
             recordRequestDuration(duration, effectiveProvider, effectiveModel);
@@ -170,6 +192,37 @@ original, patch, providerName) {
             if (acc.outputTokens > 0) {
                 recordResponseLatencyPerToken(duration / acc.outputTokens, effectiveProvider, effectiveModel);
             }
+            // Context window utilization — ratio of input tokens to model's max context
+            const pricing = getModelPricing(effectiveModel);
+            if (pricing?.maxContextTokens && acc.inputTokens > 0) {
+                const utilization = acc.inputTokens / pricing.maxContextTokens;
+                span.setAttribute(GEN_AI_ATTRS.CONTEXT_UTILIZATION, utilization);
+                recordContextUtilization(utilization, effectiveProvider, effectiveModel);
+                // Context guard — post-stream warning
+                const guard = config?.contextGuard;
+                if (guard) {
+                    if (guard.alertAt !== undefined && utilization >= guard.alertAt) {
+                        recordContextBlocked(effectiveModel);
+                        span.addEvent("gen_ai.context.limit_exceeded", {
+                            "gen_ai.toad_eye.context_utilization": utilization,
+                            "gen_ai.toad_eye.context.threshold": guard.alertAt,
+                        });
+                        console.warn(`toad-eye: context window ${(utilization * 100).toFixed(0)}% full for ${effectiveModel} — exceeds alertAt threshold ${(guard.alertAt * 100).toFixed(0)}%. Compress context before next call.`);
+                    }
+                    else if (guard.warnAt !== undefined &&
+                        utilization >= guard.warnAt) {
+                        console.warn(`toad-eye: context window ${(utilization * 100).toFixed(0)}% full for ${effectiveModel} (${acc.inputTokens}/${pricing.maxContextTokens} tokens)`);
+                    }
+                }
+            }
+            // Prefill/decode latency split — TTFT = prefill, rest = decode
+            if (ttftMs > 0) {
+                const decodeMs = duration - ttftMs;
+                span.setAttribute("gen_ai.toad_eye.latency.decode_ms", decodeMs);
+                if (acc.outputTokens > 0 && decodeMs > 0) {
+                    span.setAttribute("gen_ai.toad_eye.throughput.tokens_per_second", acc.outputTokens / (decodeMs / 1000));
+                }
+            }
             // Budget recording — releases the reservation made in checkBefore
             if (budget) {
                 const exceeded = budget.recordCost(cost, effectiveModel, userId, estimatedCost);
@@ -225,6 +278,7 @@ original, patch, providerName) {
             model: req.model,
             prompt: req.prompt,
             temperature: req.temperature,
+            operationName: patch.operationName,
         }, async () => {
             const response = await original.call(this, body, ...rest);
             const res = patch.extractResponse(response, req.model);
@@ -257,6 +311,11 @@ export function createInstrumentation(config) {
                 return activePatches.length > 0;
             }
             catch (err) {
+                // Clean up any patches applied before the failure
+                for (const { proto, method, original } of activePatches) {
+                    proto[method] = original;
+                }
+                activePatches.length = 0;
                 diag.warn(`toad-eye: failed to patch ${config.name}: ${err}`);
                 return false;
             }

package/dist/instrumentations/gemini.js

@@ -17,6 +17,7 @@ function extractPrompt(request) {
 const generateContent = {
     getPrototype: (sdk) => sdk?.GenerativeModel?.prototype,
     method: "generateContent",
+    operationName: "chat",
     extractRequest(body, thisArg) {
         return {
             prompt: extractPrompt(body),
@@ -42,6 +43,7 @@ const generateContent = {
 const generateContentStream = {
     getPrototype: (sdk) => sdk?.GenerativeModel?.prototype,
     method: "generateContentStream",
+    operationName: "chat",
     extractRequest(body, thisArg) {
         return {
             prompt: extractPrompt(body),
@@ -78,6 +80,11 @@ const generateContentStream = {
                 }
             }
         }
+        // Track finish reason (especially SAFETY blocks)
+        const finishReason = c?.candidates?.[0]?.finishReason;
+        if (finishReason) {
+            acc.finishReason = finishReason;
+        }
         if (c?.usageMetadata) {
             acc.inputTokens = c.usageMetadata.promptTokenCount ?? acc.inputTokens;
             acc.outputTokens =

package/dist/instrumentations/openai.js

@@ -59,6 +59,10 @@ const chatCompletions = {
                         existing.arguments += tc.function.arguments;
                 }
                 else {
+                    // Fill gaps to avoid sparse array with non-contiguous indices
+                    while (acc.toolCalls.length < tc.index) {
+                        acc.toolCalls.push({ name: "", arguments: "" });
+                    }
                     acc.toolCalls[tc.index] = {
                         name: tc.function?.name ?? "",
                         arguments: tc.function?.arguments ?? "",
@@ -76,6 +80,7 @@ const chatCompletions = {
 const embeddings = {
     getPrototype: (sdk) => sdk?.Embeddings?.prototype,
     method: "create",
+    operationName: "embeddings",
     extractRequest: (body) => {
         const b = body;
         const input = b?.input;

package/dist/instrumentations/types.d.ts

@@ -15,16 +15,24 @@ export interface AccumulatedToolCall {
 /** Accumulated stream data — only primitives, no raw SDK objects. */
 export interface StreamAccumulator {
     completion: string;
+    /** Anthropic extended thinking content (tracked separately from completion). */
+    thinkingContent: string;
     inputTokens: number;
     outputTokens: number;
     toolCalls: AccumulatedToolCall[];
+    /** Finish reason from the final chunk (e.g., "stop", "SAFETY"). */
+    finishReason?: string | undefined;
 }
+/** OTel GenAI operation types. Default is "chat". */
+export type OperationName = "chat" | "text_completion" | "embeddings" | "generate_content";
 /** Describes a single method to monkey-patch on an SDK prototype. */
 export interface PatchTarget {
     /** How to find the prototype from the loaded SDK module */
     getPrototype: (sdk: any) => any | undefined;
     /** Method name on the prototype to patch */
     method: string;
+    /** OTel operation name for span naming. Default: "chat". */
+    operationName?: OperationName | undefined;
     /** Extract LLMCallInput fields from the request arguments.
      *  thisArg is the SDK object instance — use it when the model name is not in the request body
      *  (e.g., Gemini's GenerativeModel stores it as this.model). */

package/dist/mcp/context.d.ts

@@ -0,0 +1,12 @@
+/**
+ * W3C trace context extraction from MCP _meta field.
+ *
+ * In stdio transport, there are no HTTP headers. Context is passed
+ * via the _meta field in JSON-RPC params:
+ * { "params": { "_meta": { "traceparent": "00-..." } } }
+ *
+ * For SSE/HTTP transports, standard header propagation works too,
+ * but _meta is the universal path that works everywhere.
+ */
+import { type Context } from "@opentelemetry/api";
+export declare function extractContextFromMeta(meta?: Record<string, unknown>): Context;

package/dist/mcp/context.js

@@ -0,0 +1,22 @@
+/**
+ * W3C trace context extraction from MCP _meta field.
+ *
+ * In stdio transport, there are no HTTP headers. Context is passed
+ * via the _meta field in JSON-RPC params:
+ * { "params": { "_meta": { "traceparent": "00-..." } } }
+ *
+ * For SSE/HTTP transports, standard header propagation works too,
+ * but _meta is the universal path that works everywhere.
+ */
+import { context, propagation } from "@opentelemetry/api";
+export function extractContextFromMeta(meta) {
+    if (!meta?.["traceparent"])
+        return context.active();
+    const carrier = {
+        traceparent: String(meta["traceparent"]),
+    };
+    if (meta["tracestate"]) {
+        carrier["tracestate"] = String(meta["tracestate"]);
+    }
+    return propagation.extract(context.active(), carrier);
+}

package/dist/mcp/index.d.ts

@@ -0,0 +1,3 @@
+export { toadEyeMiddleware, traceSampling } from "./middleware.js";
+export type { TraceSamplingOptions } from "./middleware.js";
+export type { ToadMcpOptions, McpSpanAttributes } from "./types.js";

package/dist/mcp/index.js

@@ -0,0 +1 @@
+export { toadEyeMiddleware, traceSampling } from "./middleware.js";

package/dist/mcp/metrics.d.ts

@@ -0,0 +1,11 @@
+/**
+ * MCP-specific OTel metrics.
+ *
+ * Separate from core metrics (core/metrics.ts) — these only exist
+ * when MCP middleware is active. Initialized on first middleware call.
+ */
+export declare function recordMcpToolCall(toolName: string, durationMs: number, status: "success" | "error"): void;
+export declare function recordMcpToolError(toolName: string, errorType: string): void;
+export declare function recordMcpResourceRead(uri: string): void;
+export declare function recordMcpSessionStart(): void;
+export declare function recordMcpSessionEnd(): void;

package/dist/mcp/metrics.js

@@ -0,0 +1,58 @@
+/**
+ * MCP-specific OTel metrics.
+ *
+ * Separate from core metrics (core/metrics.ts) — these only exist
+ * when MCP middleware is active. Initialized on first middleware call.
+ */
+import { metrics, } from "@opentelemetry/api";
+import { GEN_AI_METRICS } from "../types/metrics.js";
+const METER_NAME = "toad-eye-mcp";
+let toolDuration;
+let toolCalls;
+let toolErrors;
+let resourceReads;
+let sessionActive;
+let initialized = false;
+function ensureInit() {
+    if (initialized)
+        return;
+    initialized = true;
+    const meter = metrics.getMeter(METER_NAME);
+    toolDuration = meter.createHistogram(GEN_AI_METRICS.MCP_TOOL_DURATION, {
+        description: "MCP tool execution duration",
+        unit: "ms",
+    });
+    toolCalls = meter.createCounter(GEN_AI_METRICS.MCP_TOOL_CALLS, {
+        description: "MCP tool call count by tool name and status",
+    });
+    toolErrors = meter.createCounter(GEN_AI_METRICS.MCP_TOOL_ERRORS, {
+        description: "MCP tool errors by tool name and error type",
+    });
+    resourceReads = meter.createCounter(GEN_AI_METRICS.MCP_RESOURCE_READS, {
+        description: "MCP resource read count by URI",
+    });
+    sessionActive = meter.createUpDownCounter(GEN_AI_METRICS.MCP_SESSION_ACTIVE, {
+        description: "Number of active MCP sessions",
+    });
+}
+export function recordMcpToolCall(toolName, durationMs, status) {
+    ensureInit();
+    toolCalls.add(1, { "gen_ai.tool.name": toolName, status });
+    toolDuration.record(durationMs, { "gen_ai.tool.name": toolName });
+}
+export function recordMcpToolError(toolName, errorType) {
+    ensureInit();
+    toolErrors.add(1, { "gen_ai.tool.name": toolName, "error.type": errorType });
+}
+export function recordMcpResourceRead(uri) {
+    ensureInit();
+    resourceReads.add(1, { "gen_ai.data_source.id": uri });
+}
+export function recordMcpSessionStart() {
+    ensureInit();
+    sessionActive.add(1);
+}
+export function recordMcpSessionEnd() {
+    ensureInit();
+    sessionActive.add(-1);
+}

package/dist/mcp/middleware.d.ts

@@ -0,0 +1,48 @@
+/**
+ * MCP Server Middleware — wraps McpServer handler registration
+ * to automatically instrument tool calls, resource reads, and prompt gets.
+ *
+ * Uses Wrapper Pattern: intercepts .tool(), .resource(), .prompt() methods
+ * on the McpServer instance. Each handler is wrapped with OTel span creation.
+ *
+ * Why not monkey-patching: MCP SDK uses private class members (_requestHandlers)
+ * and strict TypeScript. Wrapping the public API is the stable path.
+ */
+import type { ToadMcpOptions } from "./types.js";
+export declare function toadEyeMiddleware(server: any, options?: ToadMcpOptions): void;
+/**
+ * Trace a sampling/createMessage call (server → client LLM request).
+ *
+ * Sampling is an outgoing request from the MCP server to the client,
+ * asking the client's LLM to generate a response. This cannot be
+ * auto-intercepted via wrapper pattern, so wrap manually.
+ *
+ * @example
+ * ```ts
+ * import { traceSampling } from "toad-eye/mcp";
+ *
+ * server.tool("summarize", { text: z.string() }, async ({ text }, ctx) => {
+ *   const response = await traceSampling(
+ *     () => ctx.mcpReq.requestSampling({
+ *       messages: [{ role: "user", content: { type: "text", text } }],
+ *       maxTokens: 500,
+ *     }),
+ *     { model: "gpt-4" }
+ *   );
+ *   return { content: [{ type: "text", text: response.content.text }] };
+ * });
+ * ```
+ */
+export declare function traceSampling<T>(fn: () => Promise<T>, options: TraceSamplingOptions): Promise<T>;
+export interface TraceSamplingOptions {
+    /** The model being requested for sampling. */
+    readonly model?: string | undefined;
+    /** Max tokens requested. */
+    readonly maxTokens?: number | undefined;
+    /** MCP server name for span attributes. */
+    readonly serverName?: string | undefined;
+    /** MCP server version for span attributes. */
+    readonly serverVersion?: string | undefined;
+    /** Parent OTel context. */
+    readonly parentContext?: import("@opentelemetry/api").Context | undefined;
+}

package/dist/mcp/middleware.js

@@ -0,0 +1,253 @@
+/**
+ * MCP Server Middleware — wraps McpServer handler registration
+ * to automatically instrument tool calls, resource reads, and prompt gets.
+ *
+ * Uses Wrapper Pattern: intercepts .tool(), .resource(), .prompt() methods
+ * on the McpServer instance. Each handler is wrapped with OTel span creation.
+ *
+ * Why not monkey-patching: MCP SDK uses private class members (_requestHandlers)
+ * and strict TypeScript. Wrapping the public API is the stable path.
+ */
+import { context, diag, DiagConsoleLogger, DiagLogLevel, } from "@opentelemetry/api";
+import { extractContextFromMeta } from "./context.js";
+import { startToolSpan, startResourceSpan, startPromptSpan, startSamplingSpan, endSpanSuccess, endSpanError, } from "./spans.js";
+import { recordMcpToolCall, recordMcpToolError, recordMcpResourceRead, recordMcpSessionStart, } from "./metrics.js";
+const DEFAULT_MAX_PAYLOAD_SIZE = 4096;
+function truncate(value, maxBytes) {
+    if (value.length <= maxBytes)
+        return value;
+    return value.slice(0, maxBytes) + "...[truncated]";
+}
+function redactObject(obj, keys) {
+    if (typeof obj !== "object" || obj === null)
+        return {};
+    const result = {};
+    for (const [k, v] of Object.entries(obj)) {
+        result[k] = keys.includes(k) ? "[REDACTED]" : v;
+    }
+    return result;
+}
+/**
+ * Instrument an MCP server with OpenTelemetry tracing.
+ *
+ * Wraps .tool(), .resource(), .prompt() registration methods so every
+ * handler execution produces an OTel span with correct GenAI semconv attributes.
+ *
+ * @example
+ * ```ts
+ * import { McpServer } from "@modelcontextprotocol/sdk/server/index.js";
+ * import { toadEyeMiddleware } from "toad-eye/mcp";
+ *
+ * const server = new McpServer({ name: "my-server", version: "1.0.0" });
+ * toadEyeMiddleware(server);
+ *
+ * server.tool("calculate", { expression: z.string() }, async ({ expression }) => {
+ *   return { content: [{ type: "text", text: String(eval(expression)) }] };
+ * });
+ * ```
+ */
+/**
+ * Redirect OTel diagnostics to stderr to avoid polluting stdout.
+ * In stdio MCP transport, stdout IS the JSON-RPC channel —
+ * any stray console.log or OTel diagnostic would crash the connection.
+ */
+function ensureStdioSafe() {
+    const stderrLogger = new DiagConsoleLogger();
+    // Override the logger to use stderr-only methods
+    const safeLogger = {
+        verbose: (...args) => stderrLogger.verbose(String(args[0])),
+        debug: (...args) => stderrLogger.debug(String(args[0])),
+        info: (...args) => stderrLogger.info(String(args[0])),
+        warn: (...args) => stderrLogger.warn(String(args[0])),
+        error: (...args) => stderrLogger.error(String(args[0])),
+    };
+    diag.setLogger(safeLogger, DiagLogLevel.WARN);
+}
+export function toadEyeMiddleware(
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+server, options = {}) {
+    ensureStdioSafe();
+    recordMcpSessionStart();
+    const serverName = server.name ?? server._name ?? "mcp-server";
+    const serverVersion = server.version ?? server._version ?? "unknown";
+    const recordInputs = options.recordInputs ?? false;
+    const recordOutputs = options.recordOutputs ?? false;
+    const redactKeys = options.redactKeys ?? [];
+    const maxPayload = options.maxPayloadSize ?? DEFAULT_MAX_PAYLOAD_SIZE;
+    const propagate = options.propagateContext ?? true;
+    const spanOpts = { serverName, serverVersion };
+    // --- Wrap .tool() ---
+    const originalTool = server.tool.bind(server);
+    server.tool = function wrappedTool(name, ...rest) {
+        // Find the handler — last function argument
+        const handlerIndex = rest.findIndex((arg) => typeof arg === "function");
+        if (handlerIndex === -1) {
+            return originalTool(name, ...rest);
+        }
+        const originalHandler = rest[handlerIndex];
+        rest[handlerIndex] = async function wrappedHandler(...handlerArgs) {
+            // Extract _meta for context propagation
+            const firstArg = handlerArgs[0];
+            const meta = propagate
+                ? firstArg?._meta
+                : undefined;
+            const parentCtx = propagate
+                ? extractContextFromMeta(meta)
+                : context.active();
+            const span = startToolSpan(name, {
+                ...spanOpts,
+                parentContext: parentCtx,
+            });
+            // Record inputs if enabled
+            if (recordInputs && firstArg) {
+                const sanitized = redactKeys.length > 0 ? redactObject(firstArg, redactKeys) : firstArg;
+                const serialized = truncate(JSON.stringify(sanitized), maxPayload);
+                span.setAttribute("gen_ai.tool.call.arguments", serialized);
+            }
+            // Custom hook
+            if (options.onToolCall) {
+                options.onToolCall(span, name, firstArg);
+            }
+            const start = performance.now();
+            try {
+                const result = await context.with(context.active(), () => originalHandler(...handlerArgs));
+                const durationMs = performance.now() - start;
+                // Record outputs if enabled
+                if (recordOutputs && result) {
+                    const serialized = truncate(JSON.stringify(result), maxPayload);
+                    span.setAttribute("gen_ai.tool.call.result", serialized);
+                }
+                endSpanSuccess(span);
+                recordMcpToolCall(name, durationMs, "success");
+                return result;
+            }
+            catch (error) {
+                const durationMs = performance.now() - start;
+                const errorType = error instanceof Error ? error.constructor.name : "UnknownError";
+                endSpanError(span, error);
+                recordMcpToolCall(name, durationMs, "error");
+                recordMcpToolError(name, errorType);
+                throw error;
+            }
+        };
+        return originalTool(name, ...rest);
+    };
+    // --- Wrap .resource() ---
+    const originalResource = server.resource?.bind(server);
+    if (originalResource) {
+        server.resource = function wrappedResource(name, ...rest) {
+            const handlerIndex = rest.findIndex((arg) => typeof arg === "function");
+            if (handlerIndex === -1) {
+                return originalResource(name, ...rest);
+            }
+            const originalHandler = rest[handlerIndex];
+            rest[handlerIndex] = async function wrappedHandler(...handlerArgs) {
+                const uri = handlerArgs[0]?.uri ?? name;
+                const parentCtx = propagate
+                    ? extractContextFromMeta(handlerArgs[0]?._meta)
+                    : context.active();
+                const span = startResourceSpan(uri, {
+                    ...spanOpts,
+                    parentContext: parentCtx,
+                });
+                if (options.onResourceRead) {
+                    options.onResourceRead(span, uri);
+                }
+                try {
+                    const result = await originalHandler(...handlerArgs);
+                    endSpanSuccess(span);
+                    recordMcpResourceRead(uri);
+                    return result;
+                }
+                catch (error) {
+                    endSpanError(span, error);
+                    throw error;
+                }
+            };
+            return originalResource(name, ...rest);
+        };
+    }
+    // --- Wrap .prompt() ---
+    const originalPrompt = server.prompt?.bind(server);
+    if (originalPrompt) {
+        server.prompt = function wrappedPrompt(name, ...rest) {
+            const handlerIndex = rest.findIndex((arg) => typeof arg === "function");
+            if (handlerIndex === -1) {
+                return originalPrompt(name, ...rest);
+            }
+            const originalHandler = rest[handlerIndex];
+            rest[handlerIndex] = async function wrappedHandler(...handlerArgs) {
+                const parentCtx = propagate
+                    ? extractContextFromMeta(handlerArgs[0]?._meta)
+                    : context.active();
+                const span = startPromptSpan(name, {
+                    ...spanOpts,
+                    parentContext: parentCtx,
+                });
+                try {
+                    const result = await originalHandler(...handlerArgs);
+                    endSpanSuccess(span);
+                    return result;
+                }
+                catch (error) {
+                    endSpanError(span, error);
+                    throw error;
+                }
+            };
+            return originalPrompt(name, ...rest);
+        };
+    }
+}
+/**
+ * Trace a sampling/createMessage call (server → client LLM request).
+ *
+ * Sampling is an outgoing request from the MCP server to the client,
+ * asking the client's LLM to generate a response. This cannot be
+ * auto-intercepted via wrapper pattern, so wrap manually.
+ *
+ * @example
+ * ```ts
+ * import { traceSampling } from "toad-eye/mcp";
+ *
+ * server.tool("summarize", { text: z.string() }, async ({ text }, ctx) => {
+ *   const response = await traceSampling(
+ *     () => ctx.mcpReq.requestSampling({
+ *       messages: [{ role: "user", content: { type: "text", text } }],
+ *       maxTokens: 500,
+ *     }),
+ *     { model: "gpt-4" }
+ *   );
+ *   return { content: [{ type: "text", text: response.content.text }] };
+ * });
+ * ```
+ */
+export async function traceSampling(fn, options) {
+    const model = options.model ?? "unknown";
+    const span = startSamplingSpan(model, {
+        serverName: options.serverName ?? "mcp-server",
+        serverVersion: options.serverVersion ?? "unknown",
+        parentContext: options.parentContext,
+    });
+    if (options.maxTokens !== undefined) {
+        span.setAttribute("gen_ai.request.max_tokens", options.maxTokens);
+    }
+    const start = performance.now();
+    try {
+        const result = await fn();
+        const durationMs = performance.now() - start;
+        // Extract token usage from response if available
+        const response = result;
+        if (response && typeof response === "object") {
+            if (response["model"]) {
+                span.setAttribute("gen_ai.response.model", String(response["model"]));
+            }
+        }
+        span.setAttribute("gen_ai.mcp.sampling.duration_ms", durationMs);
+        endSpanSuccess(span);
+        return result;
+    }
+    catch (error) {
+        endSpanError(span, error);
+        throw error;
+    }
+}

package/dist/mcp/spans.d.ts

@@ -0,0 +1,28 @@
+/**
+ * OTel span creation for MCP operations.
+ *
+ * Maps MCP methods to OTel GenAI semantic conventions:
+ * - tools/call              → execute_tool {tool_name}
+ * - resources/read          → retrieval {uri}
+ * - prompts/get             → prompt {name}
+ * - sampling/createMessage  → chat {model}
+ */
+import { type Context } from "@opentelemetry/api";
+declare const tracer: import("@opentelemetry/api").Tracer;
+export interface SpanOptions {
+    readonly serverName: string;
+    readonly serverVersion: string;
+    readonly parentContext: Context;
+}
+export declare function startToolSpan(toolName: string, options: SpanOptions): import("@opentelemetry/api").Span;
+export declare function startResourceSpan(uri: string, options: SpanOptions): import("@opentelemetry/api").Span;
+export declare function startPromptSpan(promptName: string, options: SpanOptions): import("@opentelemetry/api").Span;
+export interface SamplingSpanOptions {
+    readonly serverName: string;
+    readonly serverVersion: string;
+    readonly parentContext?: Context | undefined;
+}
+export declare function startSamplingSpan(model: string, options: SamplingSpanOptions): import("@opentelemetry/api").Span;
+export declare function endSpanSuccess(span: ReturnType<typeof tracer.startSpan>): void;
+export declare function endSpanError(span: ReturnType<typeof tracer.startSpan>, error: unknown): void;
+export {};