toad-eye 2.11.2 → 2.13.0

package/README.md

@@ -72,7 +72,21 @@ Open [localhost:3100](http://localhost:3100) (Grafana, admin/admin). 11 dashboar
 
 > **Requires:** [Docker Desktop](https://docs.docker.com/get-started/get-docker/) (or Docker Engine + Compose plugin)
 
-<!-- TODO: add Grafana dashboard screenshot here -->
+![Grafana MCP Server Dashboard](https://raw.githubusercontent.com/vola-trebla/toad-eye/main/demo/grafana-mcp-dashboard.png)
+
+![Jaeger E2E Trace](https://raw.githubusercontent.com/vola-trebla/toad-eye/main/demo/jaeger-e2e-trace.png)
+
+## Why toad-eye
+
+| Feature                      | toad-eye | Sentry MCP | Grafana Cloud (OpenLIT) |
+| ---------------------------- | -------- | ---------- | ----------------------- |
+| TypeScript-native            | ✅       | ✅         | ❌ (Python)             |
+| Self-hosted                  | ✅       | ❌         | ❌                      |
+| MCP E2E tracing              | ✅       | ❌         | ❌                      |
+| MCP-specific metrics         | ✅       | Partial    | Partial                 |
+| Privacy controls             | ✅       | ❌         | ❌                      |
+| Tool hallucination detection | ✅       | ❌         | ❌                      |
+| Budget guards                | ✅       | ❌         | ❌                      |
 
 ## What You Get
 
@@ -169,4 +183,4 @@ Full metrics and span attribute reference: [COMPATIBILITY.md](https://github.com
 
 ## Tech Stack
 
-TypeScript · OpenTelemetry SDK 2.x · Hono · Docker Compose (Prometheus, Jaeger, Grafana, OTel Collector) · Vitest (285+ tests)
+TypeScript · OpenTelemetry SDK 3.x · Hono · Docker Compose (Prometheus, Jaeger, Grafana, OTel Collector) · Vitest (306+ tests)

package/dist/alerts/grafana.js

@@ -16,7 +16,7 @@ export async function postGrafanaAnnotation(grafanaUrl, alert, apiKey) {
         body: JSON.stringify({
             time: Date.now(),
             tags: ["toad-eye", "alert", alert.name],
-            text: `🚨 ${alert.name}: ${alert.value.toFixed(4)} > ${alert.threshold}`,
+            text: `🚨 ${alert.name}: ${alert.value.toFixed(4)} (threshold: ${alert.threshold})`,
         }),
     });
     if (!res.ok) {

package/dist/cli.js

@@ -263,7 +263,9 @@ async function demo() {
         }
     };
     const run = () => {
-        tick().then(() => setTimeout(run, DEMO_TICK_INTERVAL_MS));
+        tick()
+            .catch((err) => console.error("Demo error:", err))
+            .then(() => setTimeout(run, DEMO_TICK_INTERVAL_MS));
     };
     run();
 }
@@ -342,10 +344,10 @@ function runCli() {
             status();
             break;
         case "demo":
-            demo();
+            void demo();
             break;
         case "export-trace":
-            exportTraceCommand();
+            void exportTraceCommand();
             break;
         case "help":
         case "--help":

package/dist/core/console-exporter.d.ts

@@ -9,7 +9,7 @@
  *   🐸 chat gpt-4o  [1.2s] $0.003 ✅
  *   🐸 tools/call broken  [12ms] ❌ TypeError
  */
-import type { SpanExporter, ReadableSpan } from "@opentelemetry/sdk-trace-base";
+import type { SpanExporter, ReadableSpan } from "@opentelemetry/sdk-trace";
 import { type ExportResult } from "@opentelemetry/core";
 export declare class ToadEyeConsoleExporter implements SpanExporter {
     export(spans: ReadableSpan[], resultCallback: (result: ExportResult) => void): void;

package/dist/core/lifecycle.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Shared LLM call orchestration — budget, metrics, context guard.
+ *
+ * Both traceLLMCall() (manual) and createStreamingHandler() (auto)
+ * need the same pre/post-call logic. This module provides it as
+ * composable functions to eliminate duplication.
+ *
+ * @internal Not exported from the public API.
+ */
+import type { Span } from "@opentelemetry/api";
+import type { LLMProvider } from "../types/index.js";
+import type { BudgetTracker } from "../budget/index.js";
+export interface BudgetPreCheckResult {
+    readonly effectiveProvider: LLMProvider;
+    readonly effectiveModel: string;
+    readonly estimatedCost: number;
+    readonly budget: BudgetTracker | null;
+}
+/**
+ * Run budget check before the LLM call.
+ * May downgrade provider/model if budget is in downgrade mode.
+ * Throws ToadBudgetExceededError if budget is in block mode.
+ */
+export declare function performBudgetPreCheck(provider: LLMProvider, model: string, userId: string | undefined): BudgetPreCheckResult;
+export interface SuccessMetricsInput {
+    readonly duration: number;
+    readonly provider: string;
+    readonly model: string;
+    readonly cost: number;
+    readonly inputTokens: number;
+    readonly outputTokens: number;
+    readonly completion: string;
+    readonly attrs?: Readonly<Record<string, string>> | undefined;
+}
+/**
+ * Record all success-path metrics: request, duration, cost, tokens,
+ * empty response detection, latency per token.
+ */
+export declare function recordSuccessMetrics(input: SuccessMetricsInput): void;
+/**
+ * Evaluate context window utilization and trigger warnings/blocks.
+ * Must be called BEFORE span.end().
+ */
+export declare function evaluateContextGuard(span: Span, model: string, provider: string, inputTokens: number): void;
+/**
+ * Record actual cost after the LLM call. Releases the reservation
+ * made in performBudgetPreCheck. Warns if budget exceeded.
+ */
+export declare function recordBudgetPostCheck(budget: BudgetTracker | null, cost: number, model: string, userId: string | undefined, estimatedCost: number): void;
+/**
+ * Record error-path metrics. Distinguishes budget block errors from
+ * generic errors to avoid inflating error rate.
+ */
+export declare function handleErrorMetrics(error: unknown, duration: number, provider: string, model: string, budget: BudgetTracker | null, estimatedCost: number, attrs?: Readonly<Record<string, string>>): void;

package/dist/core/lifecycle.js

@@ -0,0 +1,110 @@
+/**
+ * Shared LLM call orchestration — budget, metrics, context guard.
+ *
+ * Both traceLLMCall() (manual) and createStreamingHandler() (auto)
+ * need the same pre/post-call logic. This module provides it as
+ * composable functions to eliminate duplication.
+ *
+ * @internal Not exported from the public API.
+ */
+import { GEN_AI_ATTRS } from "../types/index.js";
+import { calculateCost, getModelPricing } from "./pricing.js";
+import { recordRequest, recordRequestDuration, recordRequestCost, recordTokens, recordResponseEmpty, recordResponseLatencyPerToken, recordContextUtilization, recordContextBlocked, recordBudgetExceeded, recordBudgetDowngraded, recordBudgetBlocked, recordError, } from "./metrics.js";
+import { getConfig, getBudgetTracker } from "./tracer.js";
+import { ToadBudgetExceededError } from "../budget/index.js";
+/**
+ * Run budget check before the LLM call.
+ * May downgrade provider/model if budget is in downgrade mode.
+ * Throws ToadBudgetExceededError if budget is in block mode.
+ */
+export function performBudgetPreCheck(provider, model, userId) {
+    const budget = getBudgetTracker();
+    const estimatedCost = budget ? calculateCost(model, 500, 200) : 0;
+    let effectiveProvider = provider;
+    let effectiveModel = model;
+    if (budget) {
+        const override = budget.checkBefore(provider, model, userId, estimatedCost);
+        if (override) {
+            effectiveProvider = override.provider;
+            effectiveModel = override.model;
+            recordBudgetDowngraded(override.budget);
+        }
+    }
+    return { effectiveProvider, effectiveModel, estimatedCost, budget };
+}
+/**
+ * Record all success-path metrics: request, duration, cost, tokens,
+ * empty response detection, latency per token.
+ */
+export function recordSuccessMetrics(input) {
+    const { duration, provider, model, cost, inputTokens, outputTokens, completion, attrs, } = input;
+    recordRequest(provider, model, attrs);
+    recordRequestDuration(duration, provider, model, attrs);
+    recordRequestCost(cost, provider, model, attrs);
+    recordTokens(inputTokens + outputTokens, provider, model, attrs);
+    if (completion.trim() === "") {
+        recordResponseEmpty(provider, model, attrs);
+    }
+    if (outputTokens > 0) {
+        recordResponseLatencyPerToken(duration / outputTokens, provider, model, attrs);
+    }
+}
+// ── Context guard ─────────────────────────────────────────────────
+/**
+ * Evaluate context window utilization and trigger warnings/blocks.
+ * Must be called BEFORE span.end().
+ */
+export function evaluateContextGuard(span, model, provider, inputTokens) {
+    const pricing = getModelPricing(model);
+    if (!pricing?.maxContextTokens || inputTokens <= 0)
+        return;
+    const utilization = inputTokens / pricing.maxContextTokens;
+    span.setAttribute(GEN_AI_ATTRS.CONTEXT_UTILIZATION, utilization);
+    recordContextUtilization(utilization, provider, model);
+    const guard = getConfig()?.contextGuard;
+    if (!guard)
+        return;
+    if (guard.alertAt !== undefined && utilization >= guard.alertAt) {
+        recordContextBlocked(model);
+        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 ${model} — 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 ${model} (${inputTokens}/${pricing.maxContextTokens} tokens)`);
+    }
+}
+// ── Budget post-check ─────────────────────────────────────────────
+/**
+ * Record actual cost after the LLM call. Releases the reservation
+ * made in performBudgetPreCheck. Warns if budget exceeded.
+ */
+export function recordBudgetPostCheck(budget, cost, model, userId, estimatedCost) {
+    if (!budget)
+        return;
+    const exceeded = budget.recordCost(cost, model, userId, estimatedCost);
+    if (exceeded) {
+        recordBudgetExceeded(exceeded.budget);
+        console.warn(`toad-eye: ${exceeded.budget} budget exceeded — limit $${exceeded.limit}, current $${exceeded.current.toFixed(2)}`);
+    }
+}
+// ── Error metrics ─────────────────────────────────────────────────
+/**
+ * Record error-path metrics. Distinguishes budget block errors from
+ * generic errors to avoid inflating error rate.
+ */
+export function handleErrorMetrics(error, duration, provider, model, budget, estimatedCost, attrs) {
+    recordRequest(provider, model, attrs);
+    recordRequestDuration(duration, provider, model, attrs);
+    if (budget) {
+        budget.releaseReservation(estimatedCost);
+    }
+    if (error instanceof ToadBudgetExceededError) {
+        recordBudgetBlocked(error.budget);
+    }
+    else {
+        recordError(provider, model, attrs);
+    }
+}

package/dist/core/span-end-processor.d.ts

@@ -4,7 +4,7 @@
  * Extracts LLM/MCP-relevant attributes from ReadableSpan into a clean
  * SpanEndData object — user never touches OTel SDK internals.
  */
-import type { SpanProcessor, ReadableSpan } from "@opentelemetry/sdk-trace-base";
+import type { SpanProcessor, ReadableSpan } from "@opentelemetry/sdk-trace";
 /** Structured span data passed to the onSpanEnd callback. */
 export interface SpanEndData {
     readonly traceId: string;

package/dist/core/spans.js

@@ -1,10 +1,10 @@
 import { createHash } from "node:crypto";
 import { trace, SpanStatusCode } from "@opentelemetry/api";
 import { GEN_AI_ATTRS, INSTRUMENTATION_NAME } from "../types/index.js";
-import { recordRequestDuration, recordRequestCost, recordTokens, recordRequest, recordError, recordBudgetExceeded, recordBudgetBlocked, recordBudgetDowngraded, recordResponseEmpty, recordResponseLatencyPerToken, recordContextUtilization, recordContextBlocked, recordThinkingRatio, } from "./metrics.js";
-import { getConfig, getBudgetTracker } from "./tracer.js";
-import { calculateCost, getModelPricing } from "./pricing.js";
-import { ToadBudgetExceededError } from "../budget/index.js";
+import { recordThinkingRatio } from "./metrics.js";
+import { getConfig } from "./tracer.js";
+import { calculateCost } from "./pricing.js";
+import { performBudgetPreCheck, recordSuccessMetrics, evaluateContextGuard, recordBudgetPostCheck, handleErrorMetrics, } from "./lifecycle.js";
 const tracer = trace.getTracer(INSTRUMENTATION_NAME);
 let saltWarningEmitted = false;
 // Track the last config ref so saltWarningEmitted resets across re-inits without circular imports
@@ -109,10 +109,6 @@ function setBaseAttributes(span, input) {
         ...attrs,
     });
 }
-function recordBaseMetrics(duration, provider, model, attrs) {
-    recordRequest(provider, model, attrs);
-    recordRequestDuration(duration, provider, model, attrs);
-}
 function setSuccessAttributes(span, input, output, resolvedCost) {
     const completion = processContent(output.completion);
     span.setAttributes({
@@ -164,25 +160,15 @@ export async function traceLLMCall(input, fn) {
     if (!getConfig()) {
         console.warn("toad-eye: traceLLMCall called before initObservability() — no telemetry will be recorded.");
     }
-    const budget = getBudgetTracker();
-    let effectiveInput = input;
-    // Estimated cost for reservation — reduces race window for concurrent requests.
-    // Uses conservative token estimates; actual cost is reconciled in recordCost.
-    const estimatedCost = budget ? calculateCost(input.model, 500, 200) : 0;
-    // Budget check BEFORE the LLM call
-    if (budget) {
-        const userId = input.attributes?.[GEN_AI_ATTRS.USER_ID];
-        const override = budget.checkBefore(input.provider, input.model, userId, estimatedCost);
-        if (override) {
-            // Downgrade mode — use modified provider/model
-            effectiveInput = {
-                ...input,
-                provider: override.provider,
-                model: override.model,
-            };
-            recordBudgetDowngraded(override.budget);
+    const userId = input.attributes?.[GEN_AI_ATTRS.USER_ID];
+    const { effectiveProvider, effectiveModel, estimatedCost, budget } = performBudgetPreCheck(input.provider, input.model, userId);
+    const effectiveInput = effectiveProvider !== input.provider || effectiveModel !== input.model
+        ? {
+            ...input,
+            provider: effectiveProvider,
+            model: effectiveModel,
         }
-    }
+        : input;
     const op = effectiveInput.operationName ?? "chat";
     return tracer.startActiveSpan(`${op} ${effectiveInput.model}`, async (span) => {
         const start = performance.now();
@@ -194,70 +180,25 @@ export async function traceLLMCall(input, fn) {
             const resolvedCost = output.cost ??
                 calculateCost(effectiveInput.model, output.inputTokens, output.outputTokens);
             setSuccessAttributes(span, effectiveInput, output, resolvedCost);
-            recordBaseMetrics(duration, effectiveInput.provider, effectiveInput.model, attrs);
-            recordRequestCost(resolvedCost, effectiveInput.provider, effectiveInput.model, attrs);
-            recordTokens(output.inputTokens + output.outputTokens, effectiveInput.provider, effectiveInput.model, attrs);
-            // Proxy quality metrics — no extra dependencies, response text analysis only
-            if (output.completion.trim() === "") {
-                recordResponseEmpty(effectiveInput.provider, effectiveInput.model, attrs);
-            }
-            if (output.outputTokens > 0) {
-                recordResponseLatencyPerToken(duration / output.outputTokens, effectiveInput.provider, effectiveInput.model, attrs);
-            }
-            // Context window utilization — ratio of input tokens to model's max context
-            const pricing = getModelPricing(effectiveInput.model);
-            if (pricing?.maxContextTokens && output.inputTokens > 0) {
-                const utilization = output.inputTokens / pricing.maxContextTokens;
-                span.setAttribute(GEN_AI_ATTRS.CONTEXT_UTILIZATION, utilization);
-                recordContextUtilization(utilization, effectiveInput.provider, effectiveInput.model);
-                // Context guard — post-call warning when approaching limit.
-                // This warns about the CURRENT call's context usage so agents
-                // can compress context before the NEXT call.
-                const guard = getConfig()?.contextGuard;
-                if (guard) {
-                    if (guard.alertAt !== undefined && utilization >= guard.alertAt) {
-                        recordContextBlocked(effectiveInput.model);
-                        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 ${effectiveInput.model} — 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 ${effectiveInput.model} (${output.inputTokens}/${pricing.maxContextTokens} tokens)`);
-                    }
-                }
-            }
-            // Budget recording AFTER the call — releases the cost reservation
-            if (budget) {
-                const userId = effectiveInput.attributes?.[GEN_AI_ATTRS.USER_ID];
-                const exceeded = budget.recordCost(resolvedCost, effectiveInput.model, userId, estimatedCost);
-                if (exceeded) {
-                    recordBudgetExceeded(exceeded.budget);
-                    console.warn(`toad-eye: ${exceeded.budget} budget exceeded — limit $${exceeded.limit}, current $${exceeded.current.toFixed(2)}`);
-                }
-            }
+            recordSuccessMetrics({
+                duration,
+                provider: effectiveInput.provider,
+                model: effectiveInput.model,
+                cost: resolvedCost,
+                inputTokens: output.inputTokens,
+                outputTokens: output.outputTokens,
+                completion: output.completion,
+                attrs,
+            });
+            evaluateContextGuard(span, effectiveInput.model, effectiveInput.provider, output.inputTokens);
+            recordBudgetPostCheck(budget, resolvedCost, effectiveInput.model, effectiveInput.attributes?.[GEN_AI_ATTRS.USER_ID], estimatedCost);
             return output;
         }
         catch (error) {
             const duration = performance.now() - start;
             const message = error instanceof Error ? error.message : String(error);
-            const attrs = resolveAttributes(effectiveInput);
             setErrorAttributes(span, message);
-            recordBaseMetrics(duration, effectiveInput.provider, effectiveInput.model, attrs);
-            // Release cost reservation on any error (no cost was incurred)
-            if (budget) {
-                budget.releaseReservation(estimatedCost);
-            }
-            if (error instanceof ToadBudgetExceededError) {
-                // Budget blocks are intentional guardrails, not errors — record
-                // only the budget-specific metric to avoid inflating error rate
-                recordBudgetBlocked(error.budget);
-            }
-            else {
-                recordError(effectiveInput.provider, effectiveInput.model, attrs);
-            }
+            handleErrorMetrics(error, duration, effectiveInput.provider, effectiveInput.model, budget, estimatedCost, resolveAttributes(effectiveInput));
             throw error;
         }
         finally {

package/dist/core/tracer.js

@@ -3,7 +3,7 @@ import { resourceFromAttributes } from "@opentelemetry/resources";
 import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
 import { OTLPMetricExporter } from "@opentelemetry/exporter-metrics-otlp-http";
 import { PeriodicExportingMetricReader } from "@opentelemetry/sdk-metrics";
-import { TraceIdRatioBasedSampler, ParentBasedSampler, BatchSpanProcessor, } from "@opentelemetry/sdk-trace-node";
+import { TraceIdRatioBasedSampler, ParentBasedSampler, BatchSpanProcessor, } from "@opentelemetry/sdk-trace";
 import { ATTR_SERVICE_NAME } from "@opentelemetry/semantic-conventions";
 import { initMetrics, resetMetrics } from "./metrics.js";
 import { resetCustomPricing } from "./pricing.js";
@@ -96,7 +96,7 @@ export function initObservability(config) {
     const needsCustomProcessors = config.instrument?.includes("ai") || config.onSpanEnd !== undefined;
     const spanProcessors = needsCustomProcessors
         ? [
-            new BatchSpanProcessor(traceExporter),
+            new BatchSpanProcessor({ exporter: traceExporter }),
             ...(config.instrument?.includes("ai")
                 ? [new ToadEyeAISpanProcessor()]
                 : []),

package/dist/instrumentations/create.js

@@ -1,9 +1,10 @@
 import { createRequire } from "node:module";
 import { trace, context, diag, SpanStatusCode, } from "@opentelemetry/api";
 import { traceLLMCall, processContent } from "../core/spans.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 { calculateCost } from "../core/pricing.js";
+import { recordTimeToFirstToken, recordError } from "../core/metrics.js";
+import { getConfig } from "../core/tracer.js";
+import { performBudgetPreCheck, recordSuccessMetrics, evaluateContextGuard, recordBudgetPostCheck, handleErrorMetrics, } from "../core/lifecycle.js";
 import { GEN_AI_ATTRS, INSTRUMENTATION_NAME } from "../types/index.js";
 const require = createRequire(import.meta.url);
 function isModuleInstalled(moduleName) {
@@ -75,35 +76,27 @@ original, patch, providerName) {
                 b["stream_options"] = { include_usage: true };
             }
         }
-        // Pass thisArg so extractRequest can access instance properties (e.g., Gemini model name)
         const req = patch.extractRequest(body, thisArg);
         const start = performance.now();
-        // Budget check BEFORE the LLM call — mirrors traceLLMCall behavior
-        const budget = getBudgetTracker();
         const config = getConfig();
         const userId = config?.attributes?.[GEN_AI_ATTRS.USER_ID];
-        const estimatedCost = budget ? calculateCost(req.model, 500, 200) : 0;
-        let effectiveProvider = providerName;
-        let effectiveModel = req.model;
-        if (budget) {
-            const override = budget.checkBefore(providerName, req.model, userId, estimatedCost);
-            if (override) {
-                effectiveProvider = override.provider;
-                effectiveModel = override.model;
-                recordBudgetDowngraded(override.budget);
-            }
-        }
+        const { effectiveProvider, effectiveModel, estimatedCost, budget } = performBudgetPreCheck(providerName, req.model, userId);
         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;
+        const processedPrompt = processContent(req.prompt);
         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]: op,
             ...(sessionId !== undefined && { [GEN_AI_ATTRS.SESSION_ID]: sessionId }),
+            ...(processedPrompt !== undefined && {
+                [GEN_AI_ATTRS.PROMPT]: processedPrompt,
+            }),
+            ...config?.attributes,
         });
         let response;
         try {
@@ -112,18 +105,20 @@ original, patch, providerName) {
         catch (err) {
             const duration = performance.now() - start;
             const message = err instanceof Error ? err.message : String(err);
-            // Release budget reservation — no cost was incurred
-            if (budget)
-                budget.releaseReservation(estimatedCost);
+            const sanitized = processContent(message);
             span.setAttributes({
+                [GEN_AI_ATTRS.INPUT_TOKENS]: 0,
+                [GEN_AI_ATTRS.OUTPUT_TOKENS]: 0,
+                [GEN_AI_ATTRS.COST]: 0,
                 [GEN_AI_ATTRS.STATUS]: "error",
-                [GEN_AI_ATTRS.ERROR]: message,
+                ...(sanitized !== undefined && { [GEN_AI_ATTRS.ERROR]: sanitized }),
+            });
+            span.setStatus({
+                code: SpanStatusCode.ERROR,
+                message: sanitized ?? message,
             });
-            span.setStatus({ code: SpanStatusCode.ERROR, message });
             span.end();
-            recordRequest(effectiveProvider, effectiveModel);
-            recordRequestDuration(duration, effectiveProvider, effectiveModel);
-            recordError(effectiveProvider, effectiveModel);
+            handleErrorMetrics(err, duration, effectiveProvider, effectiveModel, budget, estimatedCost, config?.attributes);
             throw err;
         }
         // Some SDKs (Gemini) return { stream: AsyncIterable } instead of a direct AsyncIterable
@@ -179,42 +174,23 @@ original, patch, providerName) {
             else {
                 span.setStatus({ code: SpanStatusCode.OK });
             }
-            span.end();
-            recordRequest(effectiveProvider, effectiveModel);
-            recordRequestDuration(duration, effectiveProvider, effectiveModel);
-            recordRequestCost(cost, effectiveProvider, effectiveModel);
-            recordTokens(acc.inputTokens + acc.outputTokens, effectiveProvider, effectiveModel);
-            // Quality metrics
-            if (acc.completion.trim() === "") {
-                recordResponseEmpty(effectiveProvider, effectiveModel);
-            }
-            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)`);
-                    }
-                }
+            const attrs = config?.attributes;
+            recordSuccessMetrics({
+                duration,
+                provider: effectiveProvider,
+                model: effectiveModel,
+                cost,
+                inputTokens: acc.inputTokens,
+                outputTokens: acc.outputTokens,
+                completion: acc.completion,
+                attrs,
+            });
+            // SAFETY finish reason is an error for metrics
+            if (acc.finishReason === "SAFETY") {
+                recordError(effectiveProvider, effectiveModel, attrs);
             }
-            // Prefill/decode latency split — TTFT = prefill, rest = decode
+            evaluateContextGuard(span, effectiveModel, effectiveProvider, acc.inputTokens);
+            // Prefill/decode latency split (streaming-specific)
             if (ttftMs > 0) {
                 const decodeMs = duration - ttftMs;
                 span.setAttribute("gen_ai.toad_eye.latency.decode_ms", decodeMs);
@@ -222,29 +198,26 @@ original, patch, providerName) {
                     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);
-                if (exceeded) {
-                    recordBudgetExceeded(exceeded.budget);
-                    console.warn(`toad-eye: ${exceeded.budget} budget exceeded — limit $${exceeded.limit}, current $${exceeded.current.toFixed(2)}`);
-                }
-            }
+            recordBudgetPostCheck(budget, cost, effectiveModel, userId, estimatedCost);
+            // span.end() AFTER all span writes including budget post-check
+            span.end();
         }, (err) => {
             const duration = performance.now() - start;
             const message = err instanceof Error ? err.message : String(err);
-            // Release budget reservation on stream error
-            if (budget)
-                budget.releaseReservation(estimatedCost);
+            const sanitized = processContent(message);
             span.setAttributes({
+                [GEN_AI_ATTRS.INPUT_TOKENS]: 0,
+                [GEN_AI_ATTRS.OUTPUT_TOKENS]: 0,
+                [GEN_AI_ATTRS.COST]: 0,
                 [GEN_AI_ATTRS.STATUS]: "error",
-                [GEN_AI_ATTRS.ERROR]: message,
+                ...(sanitized !== undefined && { [GEN_AI_ATTRS.ERROR]: sanitized }),
+            });
+            span.setStatus({
+                code: SpanStatusCode.ERROR,
+                message: sanitized ?? message,
             });
-            span.setStatus({ code: SpanStatusCode.ERROR, message });
             span.end();
-            recordRequest(effectiveProvider, effectiveModel);
-            recordRequestDuration(duration, effectiveProvider, effectiveModel);
-            recordError(effectiveProvider, effectiveModel);
+            handleErrorMetrics(err, duration, effectiveProvider, effectiveModel, budget, estimatedCost, config?.attributes);
         }));
         // Proxy preserves the original object shape (getters, private fields, methods)
         // while intercepting only the async iterator for instrumentation

package/dist/mcp/middleware.d.ts

@@ -9,10 +9,8 @@
  * and strict TypeScript. Wrapping the public API is the stable path.
  */
 import type { ToadMcpOptions } from "./types.js";
-export interface ToadEyeMiddlewareDispose {
-    /** Call when the MCP server is shutting down to decrement the active session counter. */
-    (): void;
-}
+/** Call when the MCP server is shutting down to decrement the active session counter. */
+export type ToadEyeMiddlewareDispose = () => void;
 export declare function toadEyeMiddleware(server: any, options?: ToadMcpOptions): ToadEyeMiddlewareDispose;
 /**
  * Trace a sampling/createMessage call (server → client LLM request).

package/dist/vercel.d.ts

@@ -20,7 +20,7 @@
  * });
  * ```
  */
-import type { SpanProcessor, ReadableSpan } from "@opentelemetry/sdk-trace-base";
+import type { SpanProcessor, ReadableSpan } from "@opentelemetry/sdk-trace";
 /**
  * OTel SpanProcessor that enriches Vercel AI SDK spans with toad-eye
  * cost attributes and records metrics.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toad-eye",
-  "version": "2.11.2",
+  "version": "2.13.0",
   "description": "Observability for MCP servers and LLM applications — traces, metrics, dashboards. One-line instrumentation for OpenAI, Anthropic, Gemini, and MCP. Self-hosted with Grafana + Prometheus + Jaeger.",
   "type": "module",
   "main": "dist/index.js",
@@ -87,23 +87,23 @@
   ],
   "license": "ISC",
   "dependencies": {
-    "@opentelemetry/api": "^1.9.0",
-    "@opentelemetry/exporter-metrics-otlp-http": "^0.213.0",
-    "@opentelemetry/exporter-trace-otlp-http": "^0.213.0",
-    "@opentelemetry/resources": "^2.6.0",
-    "@opentelemetry/sdk-metrics": "^2.6.0",
-    "@opentelemetry/sdk-node": "^0.213.0",
-    "@opentelemetry/sdk-trace-base": "^2.6.0",
-    "@opentelemetry/sdk-trace-node": "^2.6.0",
-    "@opentelemetry/semantic-conventions": "^1.40.0",
-    "yaml": "^2.7.0"
+    "@opentelemetry/api": "^1.10.0",
+    "@opentelemetry/core": "^3.1.0",
+    "@opentelemetry/exporter-metrics-otlp-http": "^0.301.0",
+    "@opentelemetry/exporter-trace-otlp-http": "^0.301.0",
+    "@opentelemetry/resources": "^3.1.0",
+    "@opentelemetry/sdk-metrics": "^3.1.0",
+    "@opentelemetry/sdk-node": "^0.301.0",
+    "@opentelemetry/sdk-trace": "^3.1.0",
+    "@opentelemetry/semantic-conventions": "^1.44.0",
+    "yaml": "^2.9.1"
   },
   "peerDependencies": {
     "@anthropic-ai/sdk": ">=0.30.0",
     "@google/generative-ai": ">=0.20.0",
+    "@modelcontextprotocol/sdk": ">=1.0.0",
     "nodemailer": ">=8.0.0",
-    "openai": ">=4.0.0",
-    "@modelcontextprotocol/sdk": ">=1.0.0"
+    "openai": ">=4.0.0"
   },
   "peerDependenciesMeta": {
     "openai": {
@@ -123,7 +123,7 @@
     }
   },
   "devDependencies": {
-    "@types/nodemailer": "^7.0.11",
-    "vitest": "^4.1.0"
+    "@types/nodemailer": "^8.0.2",
+    "vitest": "^5.1.0"
   }
 }

package/dist/context/error.d.ts

@@ -1,15 +0,0 @@
-/** Thrown when context guard blockAt threshold is exceeded. */
-export declare class ToadContextExceededError extends Error {
-    readonly utilization: number;
-    readonly threshold: number;
-    readonly model: string;
-    readonly maxContextTokens: number;
-    readonly inputTokens: number;
-    constructor(info: {
-        utilization: number;
-        threshold: number;
-        model: string;
-        maxContextTokens: number;
-        inputTokens: number;
-    });
-}

package/dist/context/error.js

@@ -1,17 +0,0 @@
-/** Thrown when context guard blockAt threshold is exceeded. */
-export class ToadContextExceededError extends Error {
-    utilization;
-    threshold;
-    model;
-    maxContextTokens;
-    inputTokens;
-    constructor(info) {
-        super(`toad-eye: context window ${(info.utilization * 100).toFixed(0)}% full (${info.inputTokens}/${info.maxContextTokens} tokens) for model ${info.model} — blocked at ${(info.threshold * 100).toFixed(0)}%`);
-        this.name = "ToadContextExceededError";
-        this.utilization = info.utilization;
-        this.threshold = info.threshold;
-        this.model = info.model;
-        this.maxContextTokens = info.maxContextTokens;
-        this.inputTokens = info.inputTokens;
-    }
-}

package/dist/context/guard.d.ts

@@ -1,8 +0,0 @@
-export declare function resetContextGuardState(): void;
-/**
- * Check context utilization before an LLM call.
- * - If utilization > blockAt → throw ToadContextExceededError
- * - If utilization > warnAt → console.warn (once per model per session)
- * - If model unknown or no guard configured → skip silently
- */
-export declare function checkContextGuard(model: string, inputTokens: number): void;

package/dist/context/guard.js

@@ -1,41 +0,0 @@
-import { getModelPricing } from "../core/pricing.js";
-import { getConfig } from "../core/tracer.js";
-import { ToadContextExceededError } from "./error.js";
-let warnedModels = new Set();
-export function resetContextGuardState() {
-    warnedModels = new Set();
-}
-/**
- * Check context utilization before an LLM call.
- * - If utilization > blockAt → throw ToadContextExceededError
- * - If utilization > warnAt → console.warn (once per model per session)
- * - If model unknown or no guard configured → skip silently
- */
-export function checkContextGuard(model, inputTokens) {
-    if (inputTokens <= 0)
-        return;
-    const config = getConfig();
-    const guard = config?.contextGuard;
-    if (!guard)
-        return;
-    const pricing = getModelPricing(model);
-    if (!pricing?.maxContextTokens)
-        return;
-    const utilization = inputTokens / pricing.maxContextTokens;
-    if (guard.blockAt !== undefined && utilization >= guard.blockAt) {
-        throw new ToadContextExceededError({
-            utilization,
-            threshold: guard.blockAt,
-            model,
-            maxContextTokens: pricing.maxContextTokens,
-            inputTokens,
-        });
-    }
-    if (guard.warnAt !== undefined && utilization >= guard.warnAt) {
-        const key = `${model}:${Math.floor(utilization * 10)}`;
-        if (!warnedModels.has(key)) {
-            warnedModels.add(key);
-            console.warn(`toad-eye: context window ${(utilization * 100).toFixed(0)}% full for ${model} (${inputTokens}/${pricing.maxContextTokens} tokens)`);
-        }
-    }
-}