toad-eye 2.8.0 → 2.9.1

package/README.md

@@ -169,4 +169,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 (273+ tests)
+TypeScript · OpenTelemetry SDK 2.x · Hono · Docker Compose (Prometheus, Jaeger, Grafana, OTel Collector) · Vitest (278+ tests)

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

@@ -0,0 +1,30 @@
+/**
+ * SpanProcessor that calls user's onSpanEnd callback with structured span data.
+ *
+ * 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";
+/** Structured span data passed to the onSpanEnd callback. */
+export interface SpanEndData {
+    readonly traceId: string;
+    readonly spanId: string;
+    readonly parentSpanId: string | undefined;
+    readonly name: string;
+    readonly kind: "client" | "server" | "internal" | "producer" | "consumer";
+    readonly status: "ok" | "error" | "unset";
+    readonly durationMs: number;
+    readonly startTime: Date;
+    readonly endTime: Date;
+    readonly attributes: Readonly<Record<string, string | number | boolean>>;
+    readonly error: string | undefined;
+}
+export type OnSpanEndCallback = (data: SpanEndData) => void | Promise<void>;
+export declare class ToadEyeSpanEndProcessor implements SpanProcessor {
+    private readonly callback;
+    constructor(callback: OnSpanEndCallback);
+    onStart(): void;
+    onEnd(span: ReadableSpan): void;
+    forceFlush(): Promise<void>;
+    shutdown(): Promise<void>;
+}

package/dist/core/span-end-processor.js

@@ -0,0 +1,78 @@
+/**
+ * SpanProcessor that calls user's onSpanEnd callback with structured span data.
+ *
+ * Extracts LLM/MCP-relevant attributes from ReadableSpan into a clean
+ * SpanEndData object — user never touches OTel SDK internals.
+ */
+import { SpanKind, SpanStatusCode } from "@opentelemetry/api";
+const SPAN_KIND_MAP = {
+    [SpanKind.CLIENT]: "client",
+    [SpanKind.SERVER]: "server",
+    [SpanKind.INTERNAL]: "internal",
+    [SpanKind.PRODUCER]: "producer",
+    [SpanKind.CONSUMER]: "consumer",
+};
+function hrtimeToDate(hrtime) {
+    return new Date(hrtime[0] * 1000 + hrtime[1] / 1_000_000);
+}
+function hrtimeDurationMs(start, end) {
+    return (end[0] - start[0]) * 1000 + (end[1] - start[1]) / 1_000_000;
+}
+function flattenAttributes(attrs) {
+    const result = {};
+    for (const [key, value] of Object.entries(attrs)) {
+        if (typeof value === "string" ||
+            typeof value === "number" ||
+            typeof value === "boolean") {
+            result[key] = value;
+        }
+    }
+    return result;
+}
+function toSpanEndData(span) {
+    const ctx = span.spanContext();
+    return {
+        traceId: ctx.traceId,
+        spanId: ctx.spanId,
+        parentSpanId: span.parentSpanId || undefined,
+        name: span.name,
+        kind: SPAN_KIND_MAP[span.kind] ?? "internal",
+        status: span.status.code === SpanStatusCode.ERROR
+            ? "error"
+            : span.status.code === SpanStatusCode.OK
+                ? "ok"
+                : "unset",
+        durationMs: hrtimeDurationMs(span.startTime, span.endTime),
+        startTime: hrtimeToDate(span.startTime),
+        endTime: hrtimeToDate(span.endTime),
+        attributes: flattenAttributes(span.attributes),
+        error: span.status.message || undefined,
+    };
+}
+export class ToadEyeSpanEndProcessor {
+    callback;
+    constructor(callback) {
+        this.callback = callback;
+    }
+    onStart() { }
+    onEnd(span) {
+        try {
+            const result = this.callback(toSpanEndData(span));
+            // If callback returns a promise, don't block — fire and forget
+            if (result instanceof Promise) {
+                result.catch((err) => {
+                    console.warn(`toad-eye: onSpanEnd callback failed: ${err instanceof Error ? err.message : err}`);
+                });
+            }
+        }
+        catch (err) {
+            console.warn(`toad-eye: onSpanEnd callback failed: ${err instanceof Error ? err.message : err}`);
+        }
+    }
+    forceFlush() {
+        return Promise.resolve();
+    }
+    shutdown() {
+        return Promise.resolve();
+    }
+}

package/dist/core/tracer.js

@@ -13,6 +13,7 @@ import { enableMcpClientInstrumentation, disableMcpClientInstrumentation, } from
 import { resetMcpMetrics } from "../mcp/metrics.js";
 import { BudgetTracker } from "../budget/index.js";
 import { ToadEyeAISpanProcessor } from "../vercel.js";
+import { ToadEyeSpanEndProcessor } from "./span-end-processor.js";
 const DEFAULT_ENDPOINT = "http://localhost:4318";
 const DEFAULT_CLOUD_ENDPOINT = "https://cloud.toad-eye.dev";
 let sdk = null;
@@ -81,11 +82,20 @@ export function initObservability(config) {
         exporter: metricExporter,
         exportIntervalMillis: isCloudMode ? 10_000 : 5_000,
     });
-    // When custom SpanProcessors are needed (e.g., Vercel AI SDK),
+    // 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.
-    const spanProcessors = config.instrument?.includes("ai")
-        ? [new BatchSpanProcessor(traceExporter), new ToadEyeAISpanProcessor()]
+    const needsCustomProcessors = config.instrument?.includes("ai") || config.onSpanEnd !== undefined;
+    const spanProcessors = needsCustomProcessors
+        ? [
+            new BatchSpanProcessor(traceExporter),
+            ...(config.instrument?.includes("ai")
+                ? [new ToadEyeAISpanProcessor()]
+                : []),
+            ...(config.onSpanEnd !== undefined
+                ? [new ToadEyeSpanEndProcessor(config.onSpanEnd)]
+                : []),
+        ]
         : [];
     // SDK-side head sampling (default: 1.0 = send everything to Collector)
     const sdkRate = config.sampling?.sdkRate ?? 1.0;

package/dist/index.d.ts

@@ -20,3 +20,4 @@ export { LLM_METRICS } from "./types/index.js";
 /** @deprecated Use GEN_AI_ATTRS instead */
 export { LLM_ATTRS } from "./types/index.js";
 export { ToadEyeAISpanProcessor, withToadEye } from "./vercel.js";
+export type { SpanEndData, OnSpanEndCallback, } from "./core/span-end-processor.js";

package/dist/types/config.d.ts

@@ -1,5 +1,6 @@
 import type { InstrumentTarget } from "./providers.js";
 import type { BudgetConfig, BudgetExceededMode, DowngradeCallback } from "../budget/types.js";
+import type { OnSpanEndCallback } from "../core/span-end-processor.js";
 /** Sampling configuration. Tail sampling runs in OTel Collector, SDK sends all spans. */
 export interface SamplingConfig {
     /** SDK-side sampling rate (0.0–1.0). Default: 1.0 (send everything to Collector). */
@@ -60,4 +61,6 @@ export interface ToadEyeConfig {
     readonly sessionId?: string | undefined;
     /** Dynamic session ID extractor — called per traceLLMCall to resolve session ID. */
     readonly sessionExtractor?: (() => string | undefined) | undefined;
+    /** Callback invoked when any span ends. Receives structured span data for eval pipelines. */
+    readonly onSpanEnd?: OnSpanEndCallback | undefined;
 }

package/dist/types/index.d.ts

@@ -11,6 +11,7 @@
 export declare const INSTRUMENTATION_NAME = "toad-eye";
 export type { LLMProvider, InstrumentTarget } from "./providers.js";
 export type { ToadEyeConfig, SamplingConfig } from "./config.js";
+export type { SpanEndData, OnSpanEndCallback, } from "../core/span-end-processor.js";
 export { GEN_AI_ATTRS, LLM_ATTRS } from "./attributes.js";
 export { GEN_AI_METRICS, LLM_METRICS } from "./metrics.js";
 export type { MetricName } from "./metrics.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toad-eye",
-  "version": "2.8.0",
+  "version": "2.9.1",
   "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",
@@ -49,7 +49,7 @@
     "build": "tsc -p tsconfig.build.json",
     "test": "vitest run",
     "test:watch": "vitest",
-    "prepublishOnly": "test -s README.md || { echo '❌ README.md is missing or empty'; exit 1; } && npm run build"
+    "prepublishOnly": "grep -q 'toad-eye' README.md || { echo '❌ README.md is missing or broken'; exit 1; } && npm run build"
   },
   "repository": {
     "type": "git",