toad-eye 2.12.0 → 2.13.0

package/README.md

@@ -72,7 +72,9 @@ 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
 
@@ -181,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 (306+ tests)
+TypeScript · OpenTelemetry SDK 3.x · Hono · Docker Compose (Prometheus, Jaeger, Grafana, OTel Collector) · Vitest (306+ tests)

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/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/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/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.12.0",
+  "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)`);
-        }
-    }
-}