toad-eye 2.2.0 → 2.4.0

package/dist/cli.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { execSync, spawn } from "node:child_process";
+import { execFileSync, spawn } from "node:child_process";
 import { cpSync, existsSync, mkdirSync, writeFileSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -12,10 +12,19 @@ const DEMO_TICK_INTERVAL_MS = 2000;
 const DEMO_TOKEN_INPUT_RANGE = [50, 500];
 const DEMO_TOKEN_OUTPUT_RANGE = [20, 300];
 const SERVICES = [
-    { name: "Grafana", url: "http://localhost:3100", login: "admin / admin" },
-    { name: "Jaeger UI", url: "http://localhost:16686" },
-    { name: "Prometheus", url: "http://localhost:9090" },
-    { name: "OTel Collector", url: "http://localhost:4318" },
+    {
+        name: "Grafana",
+        service: "grafana",
+        url: "http://localhost:3100",
+        login: "admin / admin",
+    },
+    { name: "Jaeger UI", service: "jaeger", url: "http://localhost:16686" },
+    { name: "Prometheus", service: "prometheus", url: "http://localhost:9090" },
+    {
+        name: "OTel Collector",
+        service: "collector",
+        url: "http://localhost:4318",
+    },
 ];
 function getTemplatesDir() {
     const thisFile = fileURLToPath(import.meta.url);
@@ -35,8 +44,9 @@ function requireInfra(message = `Run \`npx toad-eye init\` first.`) {
 }
 function init() {
     const dest = join(process.cwd(), INFRA_DIR);
-    if (existsSync(dest)) {
-        console.log(`\u2705 ${INFRA_DIR}/ already exists, skipping.`);
+    const force = process.argv.includes("--force");
+    if (existsSync(dest) && !force) {
+        console.log(`✅ ${INFRA_DIR}/ already exists, skipping. Use --force to overwrite.`);
         return;
     }
     const templatesDir = getTemplatesDir();
@@ -44,39 +54,59 @@ function init() {
         console.error(`\u274c Templates not found at ${templatesDir}. Reinstall toad-eye.`);
         process.exit(1);
     }
+    const existed = existsSync(dest);
     mkdirSync(dest, { recursive: true });
     cpSync(templatesDir, dest, { recursive: true });
-    console.log(`\u2705 Created ${INFRA_DIR}/ with observability stack config.`);
+    const action = force && existed ? "Updated" : "Created";
+    console.log(`✅ ${action} ${INFRA_DIR}/ with observability stack config.`);
     console.log();
     console.log("Next steps:");
     console.log("  npx toad-eye up      Start the stack");
     console.log("  npx toad-eye status  Check running services");
 }
+function requireDocker() {
+    try {
+        execFileSync("docker", ["--version"], { stdio: "ignore" });
+    }
+    catch {
+        console.error("❌ Docker not found. Install Docker Desktop: https://docs.docker.com/get-started/get-docker/");
+        process.exit(1);
+    }
+}
 function up() {
+    requireDocker();
     const composeFile = requireInfra();
-    console.log("\u{1f438} Starting observability stack...");
-    execSync(`docker compose -f ${composeFile} up -d`, { stdio: "inherit" });
+    console.log("🐸 Starting observability stack...");
+    console.log("   (first run downloads ~500MB of Docker images — this may take a few minutes)\n");
+    execFileSync("docker", ["compose", "-f", composeFile, "up", "-d"], {
+        stdio: "inherit",
+    });
     console.log();
     status();
+    console.log("   Run 'npx toad-eye demo' to send test data and verify the stack works.");
 }
 function down() {
     const composeFile = requireInfra("Nothing to stop.");
     console.log("\u{1f44b} Stopping observability stack...");
-    execSync(`docker compose -f ${composeFile} down`, { stdio: "inherit" });
+    execFileSync("docker", ["compose", "-f", composeFile, "down"], {
+        stdio: "inherit",
+    });
     console.log("\u2705 Stack stopped.");
 }
+/** Find the docker container matching a service by exact service name. Exported for testing. */
+export function findContainerByService(containers, serviceKey) {
+    return containers.find((c) => c.Service === serviceKey);
+}
 function status() {
     const composeFile = requireInfra();
     try {
-        const output = execSync(`docker compose -f ${composeFile} ps --format json`, {
-            encoding: "utf-8",
-        });
+        const output = execFileSync("docker", ["compose", "-f", composeFile, "ps", "--format", "json"], { encoding: "utf-8" });
         const lines = output.trim().split("\n").filter(Boolean);
         const containers = lines.map((line) => JSON.parse(line));
         console.log("\u{1f438} toad-eye stack:");
         console.log();
         for (const svc of SERVICES) {
-            const container = containers.find((c) => svc.name.toLowerCase().includes(c.Service.toLowerCase()));
+            const container = findContainerByService(containers, svc.service);
             const state = container?.State === "running" ? "\u{1f7e2}" : "\u{1f534}";
             const loginInfo = "login" in svc ? ` (${svc.login})` : "";
             console.log(`  ${state} ${svc.name.padEnd(16)} ${svc.url}${loginInfo}`);
@@ -121,12 +151,25 @@ async function simulateLLMCall(provider, model, prompt) {
 }
 async function demo() {
     requireInfra();
+    // Warn early if OTel Collector is unreachable — data would be silently lost otherwise
+    try {
+        await fetch("http://localhost:4318/v1/traces", {
+            method: "POST",
+            body: "[]",
+            signal: AbortSignal.timeout(2000),
+        });
+    }
+    catch {
+        console.warn("⚠️  OTel Collector not reachable at localhost:4318 — data will not be recorded.\n   Run 'npx toad-eye up' first, then retry.\n");
+    }
     initObservability({
         serviceName: "toad-eye-demo",
         endpoint: "http://localhost:4318",
     });
-    console.log("\u{1f438}\u{1f441}\u{fe0f} toad-eye demo — sending mock LLM traffic");
+    console.log("🐸👁️ toad-eye demo — sending mock LLM traffic");
     console.log("    Press Ctrl+C to stop\n");
+    console.log("✅ Stack verified! Add this to your app:\n");
+    console.log("   import { initObservability } from 'toad-eye';\n   initObservability({ serviceName: 'my-app', instrument: ['openai'] });\n");
     process.on("SIGINT", async () => {
         console.log("\n\u{1f44b} Shutting down...");
         await shutdown();
@@ -186,47 +229,56 @@ async function exportTraceCommand() {
     }
 }
 function help() {
+    const cmd = (name) => name.padEnd(15);
     console.log(`
-\u{1f438} toad-eye CLI — observability stack for LLM services
+🐸 toad-eye CLI — observability stack for LLM services
 
 Commands:
-  init     Copy observability configs into your project
-  up       Start the stack (OTel Collector + Prometheus + Jaeger + Grafana)
-  down     Stop the stack
-  status   Show running services and URLs
-  demo           Send mock LLM traffic to see data in Grafana
-  export-trace   Export a Jaeger trace to toad-eval YAML
-  help           Show this message
+  ${cmd("init")}Copy observability configs into your project
+  ${cmd("init --force")}Overwrite existing configs with latest templates
+  ${cmd("up")}Start the stack (OTel Collector + Prometheus + Jaeger + Grafana)
+  ${cmd("down")}Stop the stack
+  ${cmd("status")}Show running services and URLs
+  ${cmd("demo")}Send mock LLM traffic to see data in Grafana
+  ${cmd("export-trace")}Export a Jaeger trace to toad-eval YAML
+  ${cmd("help")}Show this message
 `);
 }
-const command = process.argv[2];
-switch (command) {
-    case "init":
-        init();
-        break;
-    case "up":
-        up();
-        break;
-    case "down":
-        down();
-        break;
-    case "status":
-        status();
-        break;
-    case "demo":
-        demo();
-        break;
-    case "export-trace":
-        exportTraceCommand();
-        break;
-    case "help":
-    case "--help":
-    case "-h":
-    case undefined:
-        help();
-        break;
-    default:
-        console.error(`Unknown command: ${command}`);
-        help();
-        process.exit(1);
+function runCli() {
+    const command = process.argv[2];
+    switch (command) {
+        case "init":
+            init();
+            break;
+        case "up":
+            up();
+            break;
+        case "down":
+            down();
+            break;
+        case "status":
+            status();
+            break;
+        case "demo":
+            demo();
+            break;
+        case "export-trace":
+            exportTraceCommand();
+            break;
+        case "help":
+        case "--help":
+        case "-h":
+        case undefined:
+            help();
+            break;
+        default:
+            console.error(`Unknown command: ${command}`);
+            help();
+            process.exit(1);
+    }
+}
+// Only auto-execute when run as CLI entry point, not when imported (e.g., in tests)
+if (process.argv[1] !== undefined &&
+    fileURLToPath(import.meta.url) === resolve(process.argv[1])) {
+    runCli();
 }

package/dist/core/metrics.d.ts

@@ -1,4 +1,6 @@
 export declare function initMetrics(): void;
+/** Reset metrics state so the next initMetrics() creates fresh instruments. Called from shutdown(). */
+export declare function resetMetrics(): void;
 export declare function recordRequestDuration(ms: number, provider: string, model: string, attrs?: Record<string, string>): void;
 export declare function recordRequestCost(usd: number, provider: string, model: string, attrs?: Record<string, string>): void;
 export declare function recordTokens(count: number, provider: string, model: string, attrs?: Record<string, string>): void;
@@ -13,3 +15,5 @@ export declare function recordTimeToFirstToken(ms: number, provider: string, mod
 export declare function recordBudgetExceeded(budgetType: string): void;
 export declare function recordBudgetBlocked(budgetType: string): void;
 export declare function recordBudgetDowngraded(budgetType: string): void;
+export declare function recordResponseEmpty(provider: string, model: string, attrs?: Record<string, string>): void;
+export declare function recordResponseLatencyPerToken(msPerToken: number, provider: string, model: string, attrs?: Record<string, string>): void;

package/dist/core/metrics.js

@@ -14,6 +14,8 @@ let timeToFirstToken;
 let budgetExceeded;
 let budgetBlocked;
 let budgetDowngraded;
+let responseEmpty;
+let responseLatencyPerToken;
 let initialized = false;
 export function initMetrics() {
     if (initialized)
@@ -64,8 +66,19 @@ export function initMetrics() {
     budgetDowngraded = meter.createCounter(GEN_AI_METRICS.BUDGET_DOWNGRADED, {
         description: "Number of LLM calls downgraded due to budget limits",
     });
+    responseEmpty = meter.createCounter(GEN_AI_METRICS.RESPONSE_EMPTY, {
+        description: "Number of LLM responses with empty or whitespace-only completion",
+    });
+    responseLatencyPerToken = meter.createHistogram(GEN_AI_METRICS.RESPONSE_LATENCY_PER_TOKEN, {
+        description: "Generation latency normalized per output token (ms/token). Higher values indicate slower generation speed.",
+        unit: "ms",
+    });
     initialized = true;
 }
+/** Reset metrics state so the next initMetrics() creates fresh instruments. Called from shutdown(). */
+export function resetMetrics() {
+    initialized = false;
+}
 /** Build metric labels: provider + model + optional FinOps attributes. */
 function baseLabels(provider, model, attrs) {
     return {
@@ -94,7 +107,7 @@ export function recordAgentSteps(stepCount) {
 }
 export function recordAgentToolUsage(toolName) {
     agentToolUsage.add(1, {
-        [GEN_AI_ATTRS.AGENT_TOOL_NAME]: toolName,
+        [GEN_AI_ATTRS.TOOL_NAME]: toolName,
     });
 }
 export function recordGuardEvaluation(ruleName) {
@@ -128,3 +141,9 @@ export function recordBudgetBlocked(budgetType) {
 export function recordBudgetDowngraded(budgetType) {
     budgetDowngraded.add(1, { budget_type: budgetType });
 }
+export function recordResponseEmpty(provider, model, attrs) {
+    responseEmpty.add(1, baseLabels(provider, model, attrs));
+}
+export function recordResponseLatencyPerToken(msPerToken, provider, model, attrs) {
+    responseLatencyPerToken.record(msPerToken, baseLabels(provider, model, attrs));
+}

package/dist/core/pricing.d.ts

@@ -12,6 +12,8 @@ export interface ModelPricing {
  * Useful for enterprise contracts or custom/fine-tuned models.
  */
 export declare function setCustomPricing(pricing: Record<string, ModelPricing>): void;
+/** Reset custom pricing to empty. Called from shutdown() to avoid stale state across re-inits. */
+export declare function resetCustomPricing(): void;
 /**
  * Get pricing for a model. Custom pricing takes precedence.
  * Returns undefined if model is not in any pricing table.

package/dist/core/pricing.js

@@ -31,6 +31,10 @@ let customPricing = {};
 export function setCustomPricing(pricing) {
     customPricing = { ...pricing };
 }
+/** Reset custom pricing to empty. Called from shutdown() to avoid stale state across re-inits. */
+export function resetCustomPricing() {
+    customPricing = {};
+}
 /**
  * Get pricing for a model. Custom pricing takes precedence.
  * Returns undefined if model is not in any pricing table.

package/dist/core/spans.d.ts

@@ -1,7 +1,7 @@
-import type { LLMSpanAttributes } from "../types/index.js";
+import type { LLMProvider } from "../types/index.js";
 /** Input for traceLLMCall — what the user knows before calling the LLM */
 export interface LLMCallInput {
-    readonly provider: LLMSpanAttributes["provider"];
+    readonly provider: LLMProvider;
     readonly model: string;
     readonly prompt: string;
     readonly temperature?: number | undefined;
@@ -13,6 +13,8 @@ export interface LLMCallOutput {
     readonly completion: string;
     readonly inputTokens: number;
     readonly outputTokens: number;
-    readonly cost: number;
+    /** Cost in USD. If omitted, auto-calculated from model pricing table. */
+    readonly cost?: number | undefined;
 }
+export declare function processContent(text: string): string | undefined;
 export declare function traceLLMCall(input: LLMCallInput, fn: () => Promise<LLMCallOutput>): Promise<LLMCallOutput>;

package/dist/core/spans.js

@@ -1,32 +1,73 @@
 import { createHash } from "node:crypto";
-import { trace, diag, SpanStatusCode } from "@opentelemetry/api";
+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, } from "./metrics.js";
+import { recordRequestDuration, recordRequestCost, recordTokens, recordRequest, recordError, recordBudgetExceeded, recordBudgetBlocked, recordBudgetDowngraded, recordResponseEmpty, recordResponseLatencyPerToken, } from "./metrics.js";
 import { getConfig, getBudgetTracker } from "./tracer.js";
-import { GEN_AI_ATTRS as ATTRS } from "../types/index.js";
+import { calculateCost } from "./pricing.js";
+import { ToadBudgetExceededError } from "../budget/index.js";
 const tracer = trace.getTracer(INSTRUMENTATION_NAME);
 let saltWarningEmitted = false;
+// Track the last config ref so saltWarningEmitted resets across re-inits without circular imports
+let lastConfigRef = null;
 function sha256(text) {
     const config = getConfig();
     const salt = config?.salt ?? "";
+    // Auto-reset saltWarningEmitted when SDK is re-initialized (config ref changes)
+    if (config !== lastConfigRef) {
+        lastConfigRef = config;
+        saltWarningEmitted = false;
+    }
     if (config?.hashContent && !config.salt && !saltWarningEmitted) {
-        diag.warn("toad-eye: hashContent is enabled without salt — short strings may be reversible. Set salt in config for stronger privacy.");
+        console.warn("toad-eye: hashContent is enabled without salt — short strings may be reversible. Set salt in config for stronger privacy.");
         saltWarningEmitted = true;
     }
     return createHash("sha256")
         .update(salt + text)
         .digest("hex");
 }
-function processContent(text) {
+// Built-in PII patterns — enabled via redactDefaults: true
+// Note: no `g` flag here — a fresh RegExp is created per call to avoid lastIndex state issues
+const DEFAULT_REDACT_PATTERNS = [
+    /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}\b/, // email
+    /\b\d{3}-\d{2}-\d{4}\b/, // SSN (US)
+    /\b\d{4}[\s-]?\d{4}[\s-]?\d{4}[\s-]?\d{4}\b/, // credit card
+    /\b\+?\d{1,3}[\s.-]?\(?\d{2,4}\)?[\s.-]?\d{3,4}[\s.-]?\d{3,4}\b/, // phone
+];
+function applyRedaction(text, pattern) {
+    let count = 0;
+    const regex = new RegExp(pattern.source, "g");
+    const result = text.replace(regex, () => {
+        count++;
+        return "[REDACTED]";
+    });
+    return [result, count];
+}
+export function processContent(text) {
     const config = getConfig();
     if (config?.recordContent === false)
         return undefined;
     let processed = text;
+    let totalRedacted = 0;
+    // Apply default PII patterns if enabled
+    if (config?.redactDefaults) {
+        for (const pattern of DEFAULT_REDACT_PATTERNS) {
+            const [result, count] = applyRedaction(processed, pattern);
+            processed = result;
+            totalRedacted += count;
+        }
+    }
+    // Apply custom patterns
     if (config?.redactPatterns?.length) {
         for (const pattern of config.redactPatterns) {
-            processed = processed.replace(pattern, "[REDACTED]");
+            const [result, count] = applyRedaction(processed, pattern);
+            processed = result;
+            totalRedacted += count;
         }
     }
+    // Audit mode — log a summary only, never the original content (would re-expose PII)
+    if (config?.auditMasking && totalRedacted > 0) {
+        console.log(`[toad-eye audit] Content masked: ${totalRedacted} pattern(s) applied, ${text.length} chars → ${processed.length} chars`);
+    }
     if (config?.hashContent) {
         return `sha256:${sha256(processed)}`;
     }
@@ -62,14 +103,14 @@ function recordBaseMetrics(duration, provider, model, attrs) {
     recordRequest(provider, model, attrs);
     recordRequestDuration(duration, provider, model, attrs);
 }
-function setSuccessAttributes(span, input, output) {
+function setSuccessAttributes(span, input, output, resolvedCost) {
     const completion = processContent(output.completion);
     span.setAttributes({
         ...(completion !== undefined && { [GEN_AI_ATTRS.COMPLETION]: completion }),
         [GEN_AI_ATTRS.RESPONSE_MODEL]: input.model,
         [GEN_AI_ATTRS.INPUT_TOKENS]: output.inputTokens,
         [GEN_AI_ATTRS.OUTPUT_TOKENS]: output.outputTokens,
-        [GEN_AI_ATTRS.COST]: output.cost,
+        [GEN_AI_ATTRS.COST]: resolvedCost,
         [GEN_AI_ATTRS.STATUS]: "success",
         [GEN_AI_ATTRS.FINISH_REASONS]: ["stop"],
     });
@@ -90,12 +131,18 @@ function setErrorAttributes(span, message) {
     });
 }
 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?.[ATTRS.USER_ID];
-        const override = budget.checkBefore(input.provider, input.model, userId);
+        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 = {
@@ -103,24 +150,33 @@ export async function traceLLMCall(input, fn) {
                 provider: override.provider,
                 model: override.model,
             };
-            recordBudgetDowngraded("daily");
+            recordBudgetDowngraded(override.budget);
         }
     }
-    return tracer.startActiveSpan(`gen_ai.${effectiveInput.provider}.${effectiveInput.model}`, async (span) => {
+    return tracer.startActiveSpan(`chat ${effectiveInput.model}`, async (span) => {
         const start = performance.now();
         setBaseAttributes(span, effectiveInput);
         try {
             const output = await fn();
             const duration = performance.now() - start;
             const attrs = resolveAttributes(effectiveInput);
-            setSuccessAttributes(span, effectiveInput, output);
+            const resolvedCost = output.cost ??
+                calculateCost(effectiveInput.model, output.inputTokens, output.outputTokens);
+            setSuccessAttributes(span, effectiveInput, output, resolvedCost);
             recordBaseMetrics(duration, effectiveInput.provider, effectiveInput.model, attrs);
-            recordRequestCost(output.cost, effectiveInput.provider, effectiveInput.model, attrs);
+            recordRequestCost(resolvedCost, effectiveInput.provider, effectiveInput.model, attrs);
             recordTokens(output.inputTokens + output.outputTokens, effectiveInput.provider, effectiveInput.model, attrs);
-            // Budget recording AFTER the call
+            // 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);
+            }
+            // Budget recording AFTER the call — releases the cost reservation
             if (budget) {
-                const userId = effectiveInput.attributes?.[ATTRS.USER_ID];
-                const exceeded = budget.recordCost(output.cost, effectiveInput.model, userId);
+                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)}`);
@@ -135,10 +191,13 @@ export async function traceLLMCall(input, fn) {
             setErrorAttributes(span, message);
             recordBaseMetrics(duration, effectiveInput.provider, effectiveInput.model, attrs);
             recordError(effectiveInput.provider, effectiveInput.model, attrs);
-            // If this was a budget block, record the metric
-            if (error instanceof Error &&
-                error.name === "ToadBudgetExceededError") {
-                recordBudgetBlocked("daily");
+            // Release cost reservation on any error (no cost was incurred)
+            if (budget) {
+                budget.releaseReservation(estimatedCost);
+            }
+            // If this was a budget block, record the metric with the correct budget type
+            if (error instanceof ToadBudgetExceededError) {
+                recordBudgetBlocked(error.budget);
             }
             throw error;
         }

package/dist/core/tracer.d.ts

@@ -1,9 +1,12 @@
 import type { ToadEyeConfig } from "../types/index.js";
 import { BudgetTracker } from "../budget/index.js";
-import "../instrumentations/openai.js";
-import "../instrumentations/anthropic.js";
-import "../instrumentations/gemini.js";
 export declare function getConfig(): ToadEyeConfig | null;
+/**
+ * Check if deprecated semconv aliases should be emitted.
+ * When OTEL_SEMCONV_STABILITY_OPT_IN includes "gen_ai_latest_experimental",
+ * only new (canonical) attributes are emitted — deprecated aliases are skipped.
+ */
+export declare function shouldEmitDeprecatedAttrs(): boolean;
 export declare function getBudgetTracker(): BudgetTracker | null;
 export declare function initObservability(config: ToadEyeConfig): void;
 export declare function shutdown(): Promise<void>;

package/dist/core/tracer.js

@@ -3,14 +3,13 @@ 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, } from "@opentelemetry/sdk-trace-node";
 import { ATTR_SERVICE_NAME } from "@opentelemetry/semantic-conventions";
-import { initMetrics } from "./metrics.js";
+import { initMetrics, resetMetrics } from "./metrics.js";
+import { resetCustomPricing } from "./pricing.js";
 import { enableAll, disableAll } from "../instrumentations/registry.js";
 import { BudgetTracker } from "../budget/index.js";
-// Side-effect imports: register provider instrumentations
-import "../instrumentations/openai.js";
-import "../instrumentations/anthropic.js";
-import "../instrumentations/gemini.js";
+import { ToadEyeAISpanProcessor } from "../vercel.js";
 const DEFAULT_ENDPOINT = "http://localhost:4318";
 const DEFAULT_CLOUD_ENDPOINT = "https://cloud.toad-eye.dev";
 let sdk = null;
@@ -19,6 +18,15 @@ let budgetTracker = null;
 export function getConfig() {
     return currentConfig;
 }
+/**
+ * Check if deprecated semconv aliases should be emitted.
+ * When OTEL_SEMCONV_STABILITY_OPT_IN includes "gen_ai_latest_experimental",
+ * only new (canonical) attributes are emitted — deprecated aliases are skipped.
+ */
+export function shouldEmitDeprecatedAttrs() {
+    const optIn = process.env["OTEL_SEMCONV_STABILITY_OPT_IN"] ?? "";
+    return !optIn.split(",").includes("gen_ai_latest_experimental");
+}
 export function getBudgetTracker() {
     return budgetTracker;
 }
@@ -45,8 +53,10 @@ function resolveTransport(config) {
     return { endpoint, headers, isCloudMode };
 }
 export function initObservability(config) {
-    if (sdk)
+    if (sdk) {
+        console.warn("toad-eye: initObservability() already called. Call shutdown() first to reconfigure.");
         return;
+    }
     validateConfig(config);
     const { endpoint, headers, isCloudMode } = resolveTransport(config);
     const resource = resourceFromAttributes({
@@ -64,14 +74,38 @@ export function initObservability(config) {
         exporter: metricExporter,
         exportIntervalMillis: isCloudMode ? 10_000 : 5_000,
     });
+    // Add Vercel AI SDK SpanProcessor if 'ai' is in instrument list
+    const spanProcessors = config.instrument?.includes("ai")
+        ? [new ToadEyeAISpanProcessor()]
+        : [];
+    // SDK-side head sampling (default: 1.0 = send everything to Collector)
+    const sdkRate = config.sampling?.sdkRate ?? 1.0;
+    const sampler = sdkRate < 1.0
+        ? new ParentBasedSampler({
+            root: new TraceIdRatioBasedSampler(sdkRate),
+        })
+        : undefined;
     sdk = new NodeSDK({
         resource,
         traceExporter,
         metricReader,
+        spanProcessors,
+        ...(sampler !== undefined && { sampler }),
     });
     sdk.start();
     currentConfig = config;
     initMetrics();
+    // Non-blocking connectivity check — warns the user if the OTel Collector is unreachable.
+    // Fire-and-forget: does not block initObservability(). Cloud mode skips this check.
+    if (!isCloudMode) {
+        void fetch(`${endpoint}/v1/traces`, {
+            method: "POST",
+            body: "[]",
+            signal: AbortSignal.timeout(2000),
+        }).catch(() => {
+            console.warn(`toad-eye: cannot reach OTel Collector at ${endpoint} — no telemetry will be exported. Is the stack running? Run: npx toad-eye up`);
+        });
+    }
     if (isCloudMode) {
         const masked = config.apiKey
             ? config.apiKey.slice(0, 8) + "..." + config.apiKey.slice(-4)
@@ -82,7 +116,13 @@ export function initObservability(config) {
         budgetTracker = new BudgetTracker(config.budgets, config.onBudgetExceeded ?? "warn", config.downgradeCallback);
     }
     if (config.instrument?.length) {
-        enableAll(config.instrument);
+        // Filter out 'ai' — it uses SpanProcessor, not monkey-patching
+        const patchProviders = config.instrument.filter((i) => i !== "ai");
+        if (patchProviders.length > 0) {
+            // enableAll is async (lazy-loads provider modules on first call).
+            // Fire-and-forget: patching completes before any async SDK call.
+            void enableAll(patchProviders);
+        }
     }
 }
 export async function shutdown() {
@@ -93,4 +133,6 @@ export async function shutdown() {
     sdk = null;
     currentConfig = null;
     budgetTracker = null;
+    resetMetrics();
+    resetCustomPricing();
 }

package/dist/drift/baseline.js

@@ -12,5 +12,11 @@ export function loadBaseline(filepath) {
     if (!existsSync(filepath))
         return undefined;
     const raw = readFileSync(filepath, "utf-8");
-    return JSON.parse(raw);
+    const parsed = JSON.parse(raw);
+    if (typeof parsed !== "object" ||
+        parsed === null ||
+        !Array.isArray(parsed["embeddings"])) {
+        throw new Error(`toad-eye: baseline file at "${filepath}" is malformed — missing "embeddings" array`);
+    }
+    return parsed;
 }