toad-eye 2.10.0 → 2.11.0

package/dist/alerts/conditions.js

@@ -11,6 +11,7 @@ const METRIC_MAP = {
     "gen_ai.mcp.tool.duration": "gen_ai_mcp_tool_duration",
     "gen_ai.mcp.resource.reads": "gen_ai_mcp_resource_reads_total",
     "gen_ai.mcp.tool.callers": "gen_ai_mcp_tool_callers_total",
+    "gen_ai.mcp.tool.hallucinations": "gen_ai_mcp_tool_hallucinations_total",
     // Legacy names (backward compat)
     "llm.request.cost": "gen_ai_client_request_cost_USD_sum",
     "llm.request.duration": "gen_ai_client_operation_duration_milliseconds",

package/dist/cli.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import { execFileSync, spawn } from "node:child_process";
+import { createConnection } from "node:net";
 import { cpSync, existsSync, mkdirSync, realpathSync, writeFileSync, } from "node:fs";
 import { join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -73,17 +74,66 @@ function requireDocker() {
         process.exit(1);
     }
 }
+const PORT_CONFIG = [
+    { env: "COLLECTOR_PORT", default: 4318, service: "OTel Collector" },
+    { env: "PROMETHEUS_PORT", default: 9090, service: "Prometheus" },
+    { env: "JAEGER_PORT", default: 16686, service: "Jaeger" },
+    { env: "GRAFANA_PORT", default: 3100, service: "Grafana" },
+];
+function getPort(env, defaultPort) {
+    const val = process.env[env];
+    return val ? parseInt(val, 10) : defaultPort;
+}
+function checkPort(port) {
+    return new Promise((resolve) => {
+        const socket = createConnection({ port, host: "127.0.0.1" });
+        socket.setTimeout(500);
+        socket.on("connect", () => {
+            socket.destroy();
+            resolve(true); // port is in use
+        });
+        socket.on("error", () => resolve(false)); // port is free
+        socket.on("timeout", () => {
+            socket.destroy();
+            resolve(false);
+        });
+    });
+}
+async function checkPorts() {
+    const conflicts = [];
+    for (const { env, default: defaultPort, service } of PORT_CONFIG) {
+        const port = getPort(env, defaultPort);
+        const inUse = await checkPort(port);
+        if (inUse) {
+            conflicts.push(`  ❌ Port ${port} is already in use (${service})\n     Fix: stop the other service, or set ${env}=${port + 1}`);
+        }
+    }
+    if (conflicts.length > 0) {
+        console.error("Port conflicts detected:\n");
+        console.error(conflicts.join("\n\n"));
+        console.error();
+        process.exit(1);
+    }
+}
 function up() {
     requireDocker();
     const composeFile = requireInfra();
     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.");
+    // Check ports synchronously via async wrapper — CLI is short-lived
+    const checkAndStart = async () => {
+        await checkPorts();
+        execFileSync("docker", ["compose", "-f", composeFile, "up", "-d"], {
+            stdio: "inherit",
+        });
+        console.log();
+        status();
+        console.log("   Dashboards will be empty until data arrives.\n");
+        console.log("   Next steps:");
+        console.log("     npx toad-eye demo          ← send mock traffic, see data in Grafana");
+        console.log("     or add toad-eye to your app  (see README)");
+    };
+    void checkAndStart();
 }
 function down() {
     const composeFile = requireInfra("Nothing to stop.");
@@ -175,19 +225,37 @@ async function demo() {
     });
     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();
         process.exit(0);
     });
+    let opened = false;
+    function openGrafana() {
+        if (opened)
+            return;
+        opened = true;
+        const url = "http://localhost:3100";
+        const cmd = process.platform === "darwin"
+            ? "open"
+            : process.platform === "win32"
+                ? "start"
+                : "xdg-open";
+        try {
+            spawn(cmd, [url], { detached: true, stdio: "ignore" }).unref();
+            console.log(`\n  📊 Opened Grafana: ${url}\n`);
+        }
+        catch {
+            console.log(`\n  📊 Open Grafana: ${url} (admin/admin)\n`);
+        }
+    }
     const tick = async () => {
         const { provider, model } = pickRandom(DEMO_MODELS);
         const prompt = pickRandom(DEMO_PROMPTS);
         try {
             await traceLLMCall({ provider, model, prompt, temperature: 0.7 }, () => simulateLLMCall(provider, model, prompt));
             console.log(`  \u2705 [${provider}/${model}] ${prompt}`);
+            openGrafana();
         }
         catch (err) {
             const msg = err instanceof Error ? err.message : String(err);

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

@@ -0,0 +1,17 @@
+/**
+ * Console span exporter — pretty-prints completed spans to stderr.
+ *
+ * Used in "light mode" (output: "console") — no Docker, no OTel Collector,
+ * just immediate feedback in the terminal.
+ *
+ * Format:
+ *   🐸 tools/call calculate  [42ms] ✅
+ *   🐸 chat gpt-4o  [1.2s] $0.003 ✅
+ *   🐸 tools/call broken  [12ms] ❌ TypeError
+ */
+import type { SpanExporter, ReadableSpan } from "@opentelemetry/sdk-trace-base";
+import { type ExportResult } from "@opentelemetry/core";
+export declare class ToadEyeConsoleExporter implements SpanExporter {
+    export(spans: ReadableSpan[], resultCallback: (result: ExportResult) => void): void;
+    shutdown(): Promise<void>;
+}

package/dist/core/console-exporter.js

@@ -0,0 +1,55 @@
+/**
+ * Console span exporter — pretty-prints completed spans to stderr.
+ *
+ * Used in "light mode" (output: "console") — no Docker, no OTel Collector,
+ * just immediate feedback in the terminal.
+ *
+ * Format:
+ *   🐸 tools/call calculate  [42ms] ✅
+ *   🐸 chat gpt-4o  [1.2s] $0.003 ✅
+ *   🐸 tools/call broken  [12ms] ❌ TypeError
+ */
+import { SpanStatusCode } from "@opentelemetry/api";
+import { ExportResultCode } from "@opentelemetry/core";
+function formatDuration(ms) {
+    if (ms < 1)
+        return "<1ms";
+    if (ms < 1000)
+        return `${Math.round(ms)}ms`;
+    return `${(ms / 1000).toFixed(1)}s`;
+}
+function getAttr(span, key) {
+    const val = span.attributes[key];
+    if (typeof val === "string" || typeof val === "number")
+        return val;
+    return undefined;
+}
+function formatSpan(span) {
+    const durationMs = (span.endTime[0] - span.startTime[0]) * 1000 +
+        (span.endTime[1] - span.startTime[1]) / 1_000_000;
+    const isError = span.status.code === SpanStatusCode.ERROR;
+    const icon = isError ? "❌" : "✅";
+    const cost = getAttr(span, "gen_ai.toad_eye.cost");
+    const costStr = typeof cost === "number" && cost > 0 ? ` $${cost.toFixed(4)}` : "";
+    const errorType = isError ? getAttr(span, "error.type") : undefined;
+    const errorStr = errorType ? ` ${errorType}` : "";
+    return `  🐸 ${span.name}  [${formatDuration(durationMs)}]${costStr} ${icon}${errorStr}`;
+}
+// Filter out internal spans that add noise in console mode
+const SKIP_PREFIXES = ["gen_ai.agent.step."];
+function shouldShow(span) {
+    return !SKIP_PREFIXES.some((p) => span.name.startsWith(p));
+}
+export class ToadEyeConsoleExporter {
+    export(spans, resultCallback) {
+        for (const span of spans) {
+            if (shouldShow(span)) {
+                process.stderr.write(formatSpan(span) + "\n");
+            }
+        }
+        resultCallback({ code: ExportResultCode.SUCCESS });
+    }
+    shutdown() {
+        return Promise.resolve();
+    }
+}

package/dist/core/metrics.d.ts

@@ -20,3 +20,4 @@ export declare function recordResponseEmpty(provider: string, model: string, att
 export declare function recordResponseLatencyPerToken(msPerToken: number, provider: string, model: string, attrs?: Record<string, string>): void;
 export declare function recordContextUtilization(utilization: number, provider: string, model: string): void;
 export declare function recordContextBlocked(model: string): void;
+export declare function recordThinkingRatio(ratio: number, provider: string, model: string): void;

package/dist/core/metrics.js

@@ -19,6 +19,7 @@ let responseEmpty;
 let responseLatencyPerToken;
 let contextUtilization;
 let contextBlocked;
+let thinkingRatio;
 let initialized = false;
 export function initMetrics() {
     if (initialized)
@@ -86,6 +87,9 @@ export function initMetrics() {
     contextBlocked = meter.createCounter(GEN_AI_METRICS.CONTEXT_BLOCKED, {
         description: "Number of LLM calls blocked by context guard",
     });
+    thinkingRatio = meter.createHistogram(GEN_AI_METRICS.THINKING_RATIO, {
+        description: "Ratio of thinking/reasoning tokens to total output (0.0–1.0). High values indicate deep reasoning.",
+    });
     initialized = true;
 }
 /** Reset metrics state so the next initMetrics() creates fresh instruments. Called from shutdown(). */
@@ -219,3 +223,11 @@ export function recordContextBlocked(model) {
         [GEN_AI_ATTRS.REQUEST_MODEL]: model,
     });
 }
+export function recordThinkingRatio(ratio, provider, model) {
+    if (!isReady())
+        return;
+    thinkingRatio.record(ratio, {
+        [GEN_AI_ATTRS.PROVIDER]: provider,
+        [GEN_AI_ATTRS.REQUEST_MODEL]: model,
+    });
+}

package/dist/core/spans.d.ts

@@ -17,6 +17,10 @@ export interface LLMCallOutput {
     readonly outputTokens: number;
     /** Cost in USD. If omitted, auto-calculated from model pricing table. */
     readonly cost?: number | undefined;
+    /** Thinking/reasoning content from thinking models (o1, Claude extended thinking, Gemini). */
+    readonly thinkingContent?: string | undefined;
+    /** Thinking/reasoning tokens used (separate from outputTokens). */
+    readonly thinkingTokens?: 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,7 +1,7 @@
 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, } from "./metrics.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";
@@ -124,6 +124,26 @@ function setSuccessAttributes(span, input, output, resolvedCost) {
         [GEN_AI_ATTRS.STATUS]: "success",
         [GEN_AI_ATTRS.FINISH_REASONS]: ["stop"],
     });
+    // Thinking model support (o1, Claude extended thinking, Gemini)
+    if (output.thinkingTokens !== undefined && output.thinkingTokens > 0) {
+        span.setAttribute("gen_ai.usage.reasoning_tokens", output.thinkingTokens);
+        const ratio = output.thinkingTokens / (output.outputTokens + output.thinkingTokens);
+        span.setAttribute("gen_ai.toad_eye.thinking.ratio", ratio);
+        recordThinkingRatio(ratio, input.provider, input.model);
+    }
+    if (output.thinkingContent !== undefined) {
+        const config = getConfig();
+        const recordThinking = config?.recordContent !== false;
+        if (recordThinking) {
+            const processed = processContent(output.thinkingContent);
+            if (processed !== undefined) {
+                span.addEvent("gen_ai.thinking", {
+                    "gen_ai.toad_eye.thinking.content": processed,
+                });
+            }
+        }
+        span.setAttribute("gen_ai.toad_eye.thinking.content_length", output.thinkingContent.length);
+    }
     span.setStatus({ code: SpanStatusCode.OK });
 }
 function setErrorAttributes(span, message) {

package/dist/core/tracer.js

@@ -14,6 +14,7 @@ import { resetMcpMetrics } from "../mcp/metrics.js";
 import { BudgetTracker } from "../budget/index.js";
 import { ToadEyeAISpanProcessor } from "../vercel.js";
 import { ToadEyeSpanEndProcessor } from "./span-end-processor.js";
+import { ToadEyeConsoleExporter } from "./console-exporter.js";
 const DEFAULT_ENDPOINT = "http://localhost:4318";
 const DEFAULT_CLOUD_ENDPOINT = "https://cloud.toad-eye.dev";
 let sdk = null;
@@ -66,22 +67,29 @@ export function initObservability(config) {
         return;
     }
     validateConfig(config);
-    const { endpoint, headers, isCloudMode } = resolveTransport(config);
+    const isConsoleMode = config.output === "console";
+    const { endpoint, headers, isCloudMode } = isConsoleMode
+        ? { endpoint: "", headers: {}, isCloudMode: false }
+        : resolveTransport(config);
     const resource = resourceFromAttributes({
         [ATTR_SERVICE_NAME]: config.serviceName,
     });
-    const traceExporter = new OTLPTraceExporter({
-        url: `${endpoint}/v1/traces`,
-        headers,
-    });
-    const metricExporter = new OTLPMetricExporter({
-        url: `${endpoint}/v1/metrics`,
-        headers,
-    });
-    const metricReader = new PeriodicExportingMetricReader({
-        exporter: metricExporter,
-        exportIntervalMillis: isCloudMode ? 10_000 : 5_000,
-    });
+    const traceExporter = isConsoleMode
+        ? new ToadEyeConsoleExporter()
+        : new OTLPTraceExporter({
+            url: `${endpoint}/v1/traces`,
+            headers,
+        });
+    // In console mode, skip metric export — no Prometheus to send to
+    const metricReader = isConsoleMode
+        ? undefined
+        : new PeriodicExportingMetricReader({
+            exporter: new OTLPMetricExporter({
+                url: `${endpoint}/v1/metrics`,
+                headers,
+            }),
+            exportIntervalMillis: isCloudMode ? 10_000 : 5_000,
+        });
     // When custom SpanProcessors are needed (e.g., Vercel AI SDK, onSpanEnd),
     // we must also include a BatchSpanProcessor for trace export —
     // NodeSDK won't create one automatically when spanProcessors is provided.
@@ -107,16 +115,19 @@ export function initObservability(config) {
     sdk = new NodeSDK({
         resource,
         traceExporter,
-        metricReader,
+        ...(metricReader !== undefined && { metricReader }),
         ...(spanProcessors.length > 0 && { spanProcessors }),
         ...(sampler !== undefined && { sampler }),
     });
     sdk.start();
     currentConfig = config;
     initMetrics();
+    if (isConsoleMode) {
+        console.log(`toad-eye: console mode — spans will be printed to stderr. No Docker needed.`);
+    }
     // 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) {
+    // Fire-and-forget: does not block initObservability(). Cloud/console mode skips this check.
+    if (!isCloudMode && !isConsoleMode) {
         void fetch(`${endpoint}/v1/traces`, {
             method: "POST",
             body: "[]",

package/dist/instrumentations/create.js

@@ -4,7 +4,6 @@ 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 { ToadBudgetExceededError } from "../budget/index.js";
 import { GEN_AI_ATTRS, INSTRUMENTATION_NAME } from "../types/index.js";
 const require = createRequire(import.meta.url);
 function isModuleInstalled(moduleName) {

package/dist/mcp/client.js

@@ -8,6 +8,7 @@
 import { createRequire } from "node:module";
 import { trace, context, propagation, SpanKind } from "@opentelemetry/api";
 import { MCP_METHODS, endSpanSuccess, endSpanError } from "./spans.js";
+import { recordMcpToolHallucination } from "./metrics.js";
 const require = createRequire(import.meta.url);
 const TRACER_NAME = "toad-eye-mcp-client";
 const PATCHED_FLAG = "__toad_eye_mcp_client_patched";
@@ -92,6 +93,11 @@ function patchClient(Client) {
         }
         catch (error) {
             endSpanError(span, error);
+            // JSON-RPC -32601 = Method not found = agent hallucinated a tool name
+            const code = error?.code;
+            if (code === -32601) {
+                recordMcpToolHallucination(toolName);
+            }
             throw error;
         }
     };

package/dist/mcp/index.d.ts

@@ -3,3 +3,4 @@ export type { TraceSamplingOptions, ToadEyeMiddlewareDispose, } from "./middlewa
 export type { ToadMcpOptions } from "./types.js";
 export { MCP_METHODS } from "./spans.js";
 export { enableMcpClientInstrumentation, disableMcpClientInstrumentation, } from "./client.js";
+export { recordMcpToolHallucination } from "./metrics.js";

package/dist/mcp/index.js

@@ -1,3 +1,4 @@
 export { toadEyeMiddleware, traceSampling } from "./middleware.js";
 export { MCP_METHODS } from "./spans.js";
 export { enableMcpClientInstrumentation, disableMcpClientInstrumentation, } from "./client.js";
+export { recordMcpToolHallucination } from "./metrics.js";

package/dist/mcp/metrics.d.ts

@@ -10,6 +10,7 @@ export declare function recordMcpToolCall(toolName: string, durationMs: number,
 export declare function recordMcpToolError(toolName: string, errorType: string): void;
 export declare function recordMcpResourceRead(uri: string): void;
 export declare function recordMcpSessionStart(): void;
+export declare function recordMcpToolHallucination(toolName: string): void;
 export declare function recordMcpSessionEnd(): void;
 /** Reset MCP metrics state — must be called from shutdown() alongside resetMetrics(). */
 export declare function resetMcpMetrics(): void;

package/dist/mcp/metrics.js

@@ -13,6 +13,7 @@ const METER_NAME = "toad-eye-mcp";
 let toolDuration;
 let toolCalls;
 let toolErrors;
+let toolHallucinations;
 let resourceReads;
 let sessionActive;
 let toolCallers;
@@ -32,6 +33,9 @@ function ensureInit() {
     toolErrors = meter.createCounter(GEN_AI_METRICS.MCP_TOOL_ERRORS, {
         description: "MCP tool errors by tool name and error type",
     });
+    toolHallucinations = meter.createCounter(GEN_AI_METRICS.MCP_TOOL_HALLUCINATIONS, {
+        description: "Agent tried to call a non-existent tool (JSON-RPC -32601)",
+    });
     resourceReads = meter.createCounter(GEN_AI_METRICS.MCP_RESOURCE_READS, {
         description: "MCP resource read count by URI",
     });
@@ -79,6 +83,13 @@ export function recordMcpSessionStart() {
     ensureInit();
     sessionActive.add(1);
 }
+export function recordMcpToolHallucination(toolName) {
+    ensureInit();
+    toolHallucinations.add(1, {
+        "gen_ai.tool.name": toolName,
+        "mcp.method.name": MCP_METHODS.TOOLS_CALL,
+    });
+}
 export function recordMcpSessionEnd() {
     ensureInit();
     sessionActive.add(-1);

package/dist/types/config.d.ts

@@ -22,6 +22,8 @@ export interface SamplingConfig {
 export interface ToadEyeConfig {
     readonly serviceName: string;
     readonly endpoint?: string | undefined;
+    /** Output mode: "otlp" (default) sends to OTel Collector, "console" prints spans to stderr (no Docker needed). */
+    readonly output?: "otlp" | "console" | undefined;
     /** API key for toad-eye cloud. When set, transport switches to HTTPS cloud endpoint automatically. */
     readonly apiKey?: string | undefined;
     /** Custom cloud endpoint override. Defaults to https://cloud.toad-eye.dev. */

package/dist/types/metrics.d.ts

@@ -26,12 +26,14 @@ export declare const GEN_AI_METRICS: {
     readonly RESPONSE_LATENCY_PER_TOKEN: "gen_ai.toad_eye.response.latency_per_token";
     readonly CONTEXT_UTILIZATION: "gen_ai.toad_eye.context_utilization";
     readonly CONTEXT_BLOCKED: "gen_ai.toad_eye.context.blocked";
+    readonly THINKING_RATIO: "gen_ai.toad_eye.thinking.ratio";
     readonly MCP_TOOL_DURATION: "gen_ai.mcp.tool.duration";
     readonly MCP_TOOL_CALLS: "gen_ai.mcp.tool.calls";
     readonly MCP_TOOL_ERRORS: "gen_ai.mcp.tool.errors";
     readonly MCP_RESOURCE_READS: "gen_ai.mcp.resource.reads";
     readonly MCP_SESSION_ACTIVE: "gen_ai.mcp.session.active";
     readonly MCP_TOOL_CALLERS: "gen_ai.mcp.tool.callers";
+    readonly MCP_TOOL_HALLUCINATIONS: "gen_ai.mcp.tool.hallucinations";
 };
 /** @deprecated Use GEN_AI_METRICS instead. Kept for backward compatibility. */
 export declare const LLM_METRICS: {

package/dist/types/metrics.js

@@ -33,6 +33,8 @@ export const GEN_AI_METRICS = {
     // Context utilization
     CONTEXT_UTILIZATION: "gen_ai.toad_eye.context_utilization",
     CONTEXT_BLOCKED: "gen_ai.toad_eye.context.blocked",
+    // Thinking/reasoning models
+    THINKING_RATIO: "gen_ai.toad_eye.thinking.ratio",
     // MCP metrics
     MCP_TOOL_DURATION: "gen_ai.mcp.tool.duration",
     MCP_TOOL_CALLS: "gen_ai.mcp.tool.calls",
@@ -40,6 +42,7 @@ export const GEN_AI_METRICS = {
     MCP_RESOURCE_READS: "gen_ai.mcp.resource.reads",
     MCP_SESSION_ACTIVE: "gen_ai.mcp.session.active",
     MCP_TOOL_CALLERS: "gen_ai.mcp.tool.callers",
+    MCP_TOOL_HALLUCINATIONS: "gen_ai.mcp.tool.hallucinations",
 };
 /** @deprecated Use GEN_AI_METRICS instead. Kept for backward compatibility. */
 export const LLM_METRICS = {

package/package.json

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

package/templates/docker-compose.yml

@@ -4,7 +4,7 @@ services:
     volumes:
       - ./otel-collector.yml:/etc/otelcol-contrib/config.yaml
     ports:
-      - "4318:4318"
+      - "${COLLECTOR_PORT:-4318}:4318"
     depends_on:
       - jaeger
       - prometheus
@@ -14,14 +14,14 @@ services:
     volumes:
       - ./prometheus.yml:/etc/prometheus/prometheus.yml
     ports:
-      - "9090:9090"
+      - "${PROMETHEUS_PORT:-9090}:9090"
 
   jaeger:
     image: jaegertracing/all-in-one:1.58
     environment:
       - COLLECTOR_OTLP_ENABLED=true
     ports:
-      - "16686:16686"
+      - "${JAEGER_PORT:-16686}:16686"
       - "4317:4317"
 
   grafana:
@@ -33,7 +33,7 @@ services:
       - GF_SECURITY_ADMIN_PASSWORD=admin
       - GF_DASHBOARDS_DEFAULT_HOME_DASHBOARD_PATH=/etc/grafana/provisioning/dashboards/llm-overview.json
     ports:
-      - "3100:3000"
+      - "${GRAFANA_PORT:-3100}:3000"
     depends_on:
       - prometheus
       - jaeger

package/templates/grafana/dashboards/agent-workflow.json

@@ -46,7 +46,8 @@
                 "value": 20
               }
             ]
-          }
+          },
+          "noValue": "No data yet — run: npx toad-eye demo"
         },
         "overrides": []
       }
@@ -72,7 +73,8 @@
       ],
       "fieldConfig": {
         "defaults": {
-          "unit": "short"
+          "unit": "short",
+          "noValue": "No data yet — run: npx toad-eye demo"
         },
         "overrides": []
       }
@@ -98,7 +100,8 @@
       ],
       "fieldConfig": {
         "defaults": {
-          "unit": "short"
+          "unit": "short",
+          "noValue": "No data yet — run: npx toad-eye demo"
         },
         "overrides": []
       }
@@ -124,7 +127,8 @@
       ],
       "fieldConfig": {
         "defaults": {
-          "unit": "short"
+          "unit": "short",
+          "noValue": "No data yet — run: npx toad-eye demo"
         },
         "overrides": []
       }
@@ -157,6 +161,11 @@
           "values": ["value", "percent"]
         },
         "pieType": "donut"
+      },
+      "fieldConfig": {
+        "defaults": {
+          "noValue": "No data yet — run: npx toad-eye demo"
+        }
       }
     },
     {
@@ -179,7 +188,12 @@
           "legendFormat": "{{gen_ai_tool_name}}",
           "refId": "A"
         }
-      ]
+      ],
+      "fieldConfig": {
+        "defaults": {
+          "noValue": "No data yet — run: npx toad-eye demo"
+        }
+      }
     },
     {
       "title": "Steps per Query Over Time",
@@ -211,7 +225,8 @@
           "unit": "short",
           "custom": {
             "fillOpacity": 10
-          }
+          },
+          "noValue": "No data yet — run: npx toad-eye demo"
         },
         "overrides": []
       }
@@ -244,7 +259,8 @@
             "stacking": {
               "mode": "normal"
             }
-          }
+          },
+          "noValue": "No data yet — run: npx toad-eye demo"
         },
         "overrides": []
       }
@@ -274,7 +290,8 @@
         "defaults": {
           "custom": {
             "fillOpacity": 80
-          }
+          },
+          "noValue": "No data yet — run: npx toad-eye demo"
         },
         "overrides": []
       }