toad-eye 2.11.2 → 2.12.0

package/README.md

@@ -74,6 +74,18 @@ Open [localhost:3100](http://localhost:3100) (Grafana, admin/admin). 11 dashboar
 
 <!-- TODO: add Grafana dashboard screenshot here -->
 
+## 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
 
 **Instrumentation:** auto-instrument OpenAI, Anthropic, Gemini, Vercel AI SDK, and MCP servers — regular and streaming calls, with full cost tracking.
@@ -169,4 +181,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 2.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/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/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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toad-eye",
-  "version": "2.11.2",
+  "version": "2.12.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",