toad-eye 1.1.0 → 2.0.0

package/dist/spans.js

@@ -1,34 +1,61 @@
+import { createHash } from "node:crypto";
 import { trace, SpanStatusCode } from "@opentelemetry/api";
-import { LLM_ATTRS, INSTRUMENTATION_NAME } from "./types.js";
+import { GEN_AI_ATTRS, INSTRUMENTATION_NAME } from "./types/index.js";
 import { recordRequestDuration, recordRequestCost, recordTokens, recordRequest, recordError, } from "./metrics.js";
 import { getConfig } from "./tracer.js";
 const tracer = trace.getTracer(INSTRUMENTATION_NAME);
-function shouldRecordContent() {
-    return getConfig()?.recordContent !== false;
+function sha256(text) {
+    return createHash("sha256").update(text).digest("hex");
+}
+function processContent(text) {
+    const config = getConfig();
+    if (config?.recordContent === false)
+        return undefined;
+    let processed = text;
+    if (config?.redactPatterns?.length) {
+        for (const pattern of config.redactPatterns) {
+            processed = processed.replace(pattern, "[REDACTED]");
+        }
+    }
+    if (config?.hashContent) {
+        return `sha256:${sha256(processed)}`;
+    }
+    return processed;
+}
+function resolveSessionId() {
+    const config = getConfig();
+    return config?.sessionExtractor?.() ?? config?.sessionId;
 }
 function setBaseAttributes(span, input) {
+    const prompt = processContent(input.prompt);
+    const sessionId = resolveSessionId();
     span.setAttributes({
-        [LLM_ATTRS.PROVIDER]: input.provider,
-        [LLM_ATTRS.MODEL]: input.model,
-        [LLM_ATTRS.TEMPERATURE]: input.temperature ?? 1.0,
-        ...(shouldRecordContent() && { [LLM_ATTRS.PROMPT]: input.prompt }),
+        [GEN_AI_ATTRS.PROVIDER]: input.provider,
+        [GEN_AI_ATTRS.REQUEST_MODEL]: input.model,
+        [GEN_AI_ATTRS.TEMPERATURE]: input.temperature ?? 1.0,
+        [GEN_AI_ATTRS.OPERATION]: "chat",
+        ...(prompt !== undefined && { [GEN_AI_ATTRS.PROMPT]: prompt }),
+        ...(sessionId !== undefined && { [GEN_AI_ATTRS.SESSION_ID]: sessionId }),
     });
 }
 export async function traceLLMCall(input, fn) {
-    return tracer.startActiveSpan(`llm.${input.provider}.${input.model}`, async (span) => {
+    return tracer.startActiveSpan(`gen_ai.${input.provider}.${input.model}`, async (span) => {
         const start = performance.now();
         setBaseAttributes(span, input);
         try {
             const output = await fn();
             const duration = performance.now() - start;
+            const completion = processContent(output.completion);
             span.setAttributes({
-                ...(shouldRecordContent() && {
-                    [LLM_ATTRS.COMPLETION]: output.completion,
+                ...(completion !== undefined && {
+                    [GEN_AI_ATTRS.COMPLETION]: completion,
                 }),
-                [LLM_ATTRS.INPUT_TOKENS]: output.inputTokens,
-                [LLM_ATTRS.OUTPUT_TOKENS]: output.outputTokens,
-                [LLM_ATTRS.COST]: output.cost,
-                [LLM_ATTRS.STATUS]: "success",
+                [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.STATUS]: "success",
+                [GEN_AI_ATTRS.FINISH_REASONS]: ["stop"],
             });
             span.setStatus({ code: SpanStatusCode.OK });
             recordRequest(input.provider, input.model);
@@ -41,12 +68,11 @@ export async function traceLLMCall(input, fn) {
             const duration = performance.now() - start;
             const message = error instanceof Error ? error.message : String(error);
             span.setAttributes({
-                [LLM_ATTRS.COMPLETION]: "",
-                [LLM_ATTRS.INPUT_TOKENS]: 0,
-                [LLM_ATTRS.OUTPUT_TOKENS]: 0,
-                [LLM_ATTRS.COST]: 0,
-                [LLM_ATTRS.STATUS]: "error",
-                [LLM_ATTRS.ERROR]: message,
+                [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,
             });
             span.setStatus({ code: SpanStatusCode.ERROR, message });
             recordRequest(input.provider, input.model);

package/dist/tracer.d.ts

@@ -1,4 +1,7 @@
-import type { ToadEyeConfig } from "./types.js";
+import type { ToadEyeConfig } from "./types/index.js";
+import "./instrumentations/openai.js";
+import "./instrumentations/anthropic.js";
+import "./instrumentations/gemini.js";
 export declare function getConfig(): ToadEyeConfig | null;
 export declare function initObservability(config: ToadEyeConfig): void;
 export declare function shutdown(): Promise<void>;

package/dist/tracer.js

@@ -5,6 +5,11 @@ import { OTLPMetricExporter } from "@opentelemetry/exporter-metrics-otlp-http";
 import { PeriodicExportingMetricReader } from "@opentelemetry/sdk-metrics";
 import { ATTR_SERVICE_NAME } from "@opentelemetry/semantic-conventions";
 import { initMetrics } from "./metrics.js";
+import { enableAll, disableAll } from "./instrumentations/registry.js";
+// Side-effect imports: register provider instrumentations
+import "./instrumentations/openai.js";
+import "./instrumentations/anthropic.js";
+import "./instrumentations/gemini.js";
 const DEFAULT_ENDPOINT = "http://localhost:4318";
 let sdk = null;
 let currentConfig = null;
@@ -36,10 +41,14 @@ export function initObservability(config) {
     sdk.start();
     currentConfig = config;
     initMetrics();
+    if (config.instrument?.length) {
+        enableAll(config.instrument);
+    }
 }
 export async function shutdown() {
     if (!sdk)
         return;
+    disableAll();
     await sdk.shutdown();
     sdk = null;
     currentConfig = null;

package/dist/types/attributes.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Span attribute keys following OTel GenAI semantic conventions.
+ * See: https://opentelemetry.io/docs/specs/semconv/gen-ai/
+ *
+ * Standard attributes use `gen_ai.*` prefix.
+ * toad-eye extensions use `gen_ai.toad_eye.*` prefix.
+ */
+export declare const GEN_AI_ATTRS: {
+    readonly PROVIDER: "gen_ai.provider.name";
+    readonly REQUEST_MODEL: "gen_ai.request.model";
+    readonly RESPONSE_MODEL: "gen_ai.response.model";
+    readonly INPUT_TOKENS: "gen_ai.usage.input_tokens";
+    readonly OUTPUT_TOKENS: "gen_ai.usage.output_tokens";
+    readonly TEMPERATURE: "gen_ai.request.temperature";
+    readonly OPERATION: "gen_ai.operation.name";
+    readonly FINISH_REASONS: "gen_ai.response.finish_reasons";
+    readonly ERROR: "error.type";
+    readonly PROMPT: "gen_ai.toad_eye.prompt";
+    readonly COMPLETION: "gen_ai.toad_eye.completion";
+    readonly COST: "gen_ai.toad_eye.cost";
+    readonly STATUS: "gen_ai.toad_eye.status";
+    readonly SESSION_ID: "session.id";
+};
+/** @deprecated Use GEN_AI_ATTRS instead. Kept for backward compatibility. */
+export declare const LLM_ATTRS: {
+    readonly PROVIDER: "gen_ai.provider.name";
+    readonly MODEL: "gen_ai.request.model";
+    readonly PROMPT: "gen_ai.toad_eye.prompt";
+    readonly COMPLETION: "gen_ai.toad_eye.completion";
+    readonly INPUT_TOKENS: "gen_ai.usage.input_tokens";
+    readonly OUTPUT_TOKENS: "gen_ai.usage.output_tokens";
+    readonly COST: "gen_ai.toad_eye.cost";
+    readonly TEMPERATURE: "gen_ai.request.temperature";
+    readonly STATUS: "gen_ai.toad_eye.status";
+    readonly ERROR: "error.type";
+};

package/dist/types/attributes.js

@@ -0,0 +1,38 @@
+/**
+ * Span attribute keys following OTel GenAI semantic conventions.
+ * See: https://opentelemetry.io/docs/specs/semconv/gen-ai/
+ *
+ * Standard attributes use `gen_ai.*` prefix.
+ * toad-eye extensions use `gen_ai.toad_eye.*` prefix.
+ */
+export const GEN_AI_ATTRS = {
+    // OTel GenAI standard
+    PROVIDER: "gen_ai.provider.name",
+    REQUEST_MODEL: "gen_ai.request.model",
+    RESPONSE_MODEL: "gen_ai.response.model",
+    INPUT_TOKENS: "gen_ai.usage.input_tokens",
+    OUTPUT_TOKENS: "gen_ai.usage.output_tokens",
+    TEMPERATURE: "gen_ai.request.temperature",
+    OPERATION: "gen_ai.operation.name",
+    FINISH_REASONS: "gen_ai.response.finish_reasons",
+    ERROR: "error.type",
+    // toad-eye extensions
+    PROMPT: "gen_ai.toad_eye.prompt",
+    COMPLETION: "gen_ai.toad_eye.completion",
+    COST: "gen_ai.toad_eye.cost",
+    STATUS: "gen_ai.toad_eye.status",
+    SESSION_ID: "session.id",
+};
+/** @deprecated Use GEN_AI_ATTRS instead. Kept for backward compatibility. */
+export const LLM_ATTRS = {
+    PROVIDER: GEN_AI_ATTRS.PROVIDER,
+    MODEL: GEN_AI_ATTRS.REQUEST_MODEL,
+    PROMPT: GEN_AI_ATTRS.PROMPT,
+    COMPLETION: GEN_AI_ATTRS.COMPLETION,
+    INPUT_TOKENS: GEN_AI_ATTRS.INPUT_TOKENS,
+    OUTPUT_TOKENS: GEN_AI_ATTRS.OUTPUT_TOKENS,
+    COST: GEN_AI_ATTRS.COST,
+    TEMPERATURE: GEN_AI_ATTRS.TEMPERATURE,
+    STATUS: GEN_AI_ATTRS.STATUS,
+    ERROR: GEN_AI_ATTRS.ERROR,
+};

package/dist/types/config.d.ts

@@ -0,0 +1,20 @@
+import type { LLMProvider } from "./providers.js";
+/**
+ * Configuration for initObservability().
+ * This is what the user passes when connecting toad-eye to their service.
+ */
+export interface ToadEyeConfig {
+    readonly serviceName: string;
+    readonly endpoint?: string | undefined;
+    /** Set to false to disable recording prompt/completion text in spans. */
+    readonly recordContent?: boolean | undefined;
+    /** Record SHA-256 hash of content instead of plain text. Allows prompt comparison without reading. */
+    readonly hashContent?: boolean | undefined;
+    /** Regex patterns to redact from prompt/completion text before recording. */
+    readonly redactPatterns?: readonly RegExp[] | undefined;
+    readonly instrument?: readonly LLMProvider[] | undefined;
+    /** Static session ID — all spans will carry this value as `session.id`. */
+    readonly sessionId?: string | undefined;
+    /** Dynamic session ID extractor — called per traceLLMCall to resolve session ID. */
+    readonly sessionExtractor?: (() => string | undefined) | undefined;
+}

package/dist/types/config.js

@@ -0,0 +1 @@
+export {};

package/dist/types/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Central type definitions for toad-eye.
+ *
+ * Organized by concern:
+ * - providers.ts  — supported LLM provider names
+ * - config.ts     — ToadEyeConfig (initObservability options)
+ * - attributes.ts — OTel span attribute keys (GEN_AI_ATTRS)
+ * - metrics.ts    — OTel metric names (GEN_AI_METRICS)
+ * - spans.ts      — span-related types (LLMSpanAttributes, SpanStatus)
+ */
+export declare const INSTRUMENTATION_NAME = "toad-eye";
+export type { LLMProvider } from "./providers.js";
+export type { ToadEyeConfig } from "./config.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";
+export type { SpanStatus, LLMSpanAttributes } from "./spans.js";

package/dist/types/index.js

@@ -0,0 +1,13 @@
+/**
+ * Central type definitions for toad-eye.
+ *
+ * Organized by concern:
+ * - providers.ts  — supported LLM provider names
+ * - config.ts     — ToadEyeConfig (initObservability options)
+ * - attributes.ts — OTel span attribute keys (GEN_AI_ATTRS)
+ * - metrics.ts    — OTel metric names (GEN_AI_METRICS)
+ * - spans.ts      — span-related types (LLMSpanAttributes, SpanStatus)
+ */
+export const INSTRUMENTATION_NAME = "toad-eye";
+export { GEN_AI_ATTRS, LLM_ATTRS } from "./attributes.js";
+export { GEN_AI_METRICS, LLM_METRICS } from "./metrics.js";

package/dist/types/metrics.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Metric names exported to Prometheus via OTel.
+ *
+ * Naming follows OTel GenAI semantic conventions:
+ * - `gen_ai.client.*` prefix for client-side metrics
+ * - Prometheus auto-converts dots to underscores
+ * - Prometheus adds _total suffix to counters automatically
+ */
+export declare const GEN_AI_METRICS: {
+    readonly REQUEST_DURATION: "gen_ai.client.operation.duration";
+    readonly TOKEN_USAGE: "gen_ai.client.token.usage";
+    readonly REQUEST_COST: "gen_ai.client.request.cost";
+    readonly REQUESTS: "gen_ai.client.requests";
+    readonly ERRORS: "gen_ai.client.errors";
+};
+/** @deprecated Use GEN_AI_METRICS instead. Kept for backward compatibility. */
+export declare const LLM_METRICS: {
+    readonly REQUEST_DURATION: "gen_ai.client.operation.duration";
+    readonly REQUEST_COST: "gen_ai.client.request.cost";
+    readonly TOKENS: "gen_ai.client.token.usage";
+    readonly REQUESTS: "gen_ai.client.requests";
+    readonly ERRORS: "gen_ai.client.errors";
+};
+/** Type-safe metric name — only values from GEN_AI_METRICS are allowed. */
+export type MetricName = (typeof GEN_AI_METRICS)[keyof typeof GEN_AI_METRICS];

package/dist/types/metrics.js

@@ -0,0 +1,23 @@
+/**
+ * Metric names exported to Prometheus via OTel.
+ *
+ * Naming follows OTel GenAI semantic conventions:
+ * - `gen_ai.client.*` prefix for client-side metrics
+ * - Prometheus auto-converts dots to underscores
+ * - Prometheus adds _total suffix to counters automatically
+ */
+export const GEN_AI_METRICS = {
+    REQUEST_DURATION: "gen_ai.client.operation.duration",
+    TOKEN_USAGE: "gen_ai.client.token.usage",
+    REQUEST_COST: "gen_ai.client.request.cost",
+    REQUESTS: "gen_ai.client.requests",
+    ERRORS: "gen_ai.client.errors",
+};
+/** @deprecated Use GEN_AI_METRICS instead. Kept for backward compatibility. */
+export const LLM_METRICS = {
+    REQUEST_DURATION: GEN_AI_METRICS.REQUEST_DURATION,
+    REQUEST_COST: GEN_AI_METRICS.REQUEST_COST,
+    TOKENS: GEN_AI_METRICS.TOKEN_USAGE,
+    REQUESTS: GEN_AI_METRICS.REQUESTS,
+    ERRORS: GEN_AI_METRICS.ERRORS,
+};

package/dist/types/providers.d.ts

@@ -0,0 +1,5 @@
+/**
+ * LLM providers supported by toad-eye.
+ * Values follow OTel GenAI semconv `gen_ai.provider.name`.
+ */
+export type LLMProvider = "anthropic" | "gemini" | "openai";

package/dist/types/providers.js

@@ -0,0 +1 @@
+export {};

package/dist/types/spans.d.ts

@@ -0,0 +1,19 @@
+import type { LLMProvider } from "./providers.js";
+/** Span status values used in trace attributes. */
+export type SpanStatus = "success" | "error";
+/**
+ * Attributes attached to every LLM span (trace).
+ * These become searchable fields in Jaeger and filterable dimensions in Grafana.
+ */
+export interface LLMSpanAttributes {
+    readonly provider: LLMProvider;
+    readonly model: string;
+    readonly prompt: string;
+    readonly completion: string;
+    readonly inputTokens: number;
+    readonly outputTokens: number;
+    readonly cost: number;
+    readonly temperature: number;
+    readonly status: SpanStatus;
+    readonly error?: string | undefined;
+}

package/dist/types/spans.js

@@ -0,0 +1 @@
+export {};

package/dist/types.d.ts

@@ -1,6 +1,7 @@
 export declare const INSTRUMENTATION_NAME = "toad-eye";
 /**
- * LLM providers supported by toad-eye
+ * LLM providers supported by toad-eye.
+ * Values follow OTel GenAI semconv `gen_ai.provider.name`.
  */
 export type LLMProvider = "anthropic" | "gemini" | "openai";
 /**
@@ -26,44 +27,78 @@ export interface LLMSpanAttributes {
 /**
  * Metric names exported to Prometheus.
  *
- * Naming convention follows OpenTelemetry semantic conventions:
- * - dots as separators: "llm.request.duration"
- * - Prometheus auto-converts dots to underscores: llm_request_duration
- * - Prometheus adds _total suffix to counters automatically — do NOT include it in the name
+ * Naming follows OTel GenAI semantic conventions where possible:
+ * - `gen_ai.client.*` prefix for client-side metrics
+ * - Prometheus auto-converts dots to underscores
+ * - Prometheus adds _total suffix to counters automatically
  */
+export declare const GEN_AI_METRICS: {
+    readonly REQUEST_DURATION: "gen_ai.client.operation.duration";
+    readonly TOKEN_USAGE: "gen_ai.client.token.usage";
+    readonly REQUEST_COST: "gen_ai.client.request.cost";
+    readonly REQUESTS: "gen_ai.client.requests";
+    readonly ERRORS: "gen_ai.client.errors";
+};
+/** @deprecated Use GEN_AI_METRICS instead. Kept for backward compatibility. */
 export declare const LLM_METRICS: {
-    readonly REQUEST_DURATION: "llm.request.duration";
-    readonly REQUEST_COST: "llm.request.cost";
-    readonly TOKENS: "llm.tokens";
-    readonly REQUESTS: "llm.requests";
-    readonly ERRORS: "llm.errors";
+    readonly REQUEST_DURATION: "gen_ai.client.operation.duration";
+    readonly REQUEST_COST: "gen_ai.client.request.cost";
+    readonly TOKENS: "gen_ai.client.token.usage";
+    readonly REQUESTS: "gen_ai.client.requests";
+    readonly ERRORS: "gen_ai.client.errors";
 };
 /**
- * Span attribute keys attached to every LLM span.
- * Using constants prevents typos and enables rename-refactoring.
+ * Span attribute keys following OTel GenAI semantic conventions.
+ * See: https://opentelemetry.io/docs/specs/semconv/gen-ai/
  */
+export declare const GEN_AI_ATTRS: {
+    readonly PROVIDER: "gen_ai.provider.name";
+    readonly REQUEST_MODEL: "gen_ai.request.model";
+    readonly RESPONSE_MODEL: "gen_ai.response.model";
+    readonly INPUT_TOKENS: "gen_ai.usage.input_tokens";
+    readonly OUTPUT_TOKENS: "gen_ai.usage.output_tokens";
+    readonly TEMPERATURE: "gen_ai.request.temperature";
+    readonly OPERATION: "gen_ai.operation.name";
+    readonly FINISH_REASONS: "gen_ai.response.finish_reasons";
+    readonly PROMPT: "gen_ai.toad_eye.prompt";
+    readonly COMPLETION: "gen_ai.toad_eye.completion";
+    readonly COST: "gen_ai.toad_eye.cost";
+    readonly STATUS: "gen_ai.toad_eye.status";
+    readonly ERROR: "error.type";
+    readonly SESSION_ID: "session.id";
+};
+/** @deprecated Use GEN_AI_ATTRS instead. Kept for backward compatibility. */
 export declare const LLM_ATTRS: {
-    readonly PROVIDER: "llm.provider";
-    readonly MODEL: "llm.model";
-    readonly PROMPT: "llm.prompt";
-    readonly COMPLETION: "llm.completion";
-    readonly INPUT_TOKENS: "llm.input_tokens";
-    readonly OUTPUT_TOKENS: "llm.output_tokens";
-    readonly COST: "llm.cost";
-    readonly TEMPERATURE: "llm.temperature";
-    readonly STATUS: "llm.status";
-    readonly ERROR: "llm.error";
+    readonly PROVIDER: "gen_ai.provider.name";
+    readonly MODEL: "gen_ai.request.model";
+    readonly PROMPT: "gen_ai.toad_eye.prompt";
+    readonly COMPLETION: "gen_ai.toad_eye.completion";
+    readonly INPUT_TOKENS: "gen_ai.usage.input_tokens";
+    readonly OUTPUT_TOKENS: "gen_ai.usage.output_tokens";
+    readonly COST: "gen_ai.toad_eye.cost";
+    readonly TEMPERATURE: "gen_ai.request.temperature";
+    readonly STATUS: "gen_ai.toad_eye.status";
+    readonly ERROR: "error.type";
 };
 /**
- * Type-safe metric name — only values from LLM_METRICS are allowed
+ * Type-safe metric name
  */
-export type MetricName = (typeof LLM_METRICS)[keyof typeof LLM_METRICS];
+export type MetricName = (typeof GEN_AI_METRICS)[keyof typeof GEN_AI_METRICS];
 /**
  * Configuration for initObservability().
- * This is what the user passes when connecting toad-eye to their service.
  */
 export interface ToadEyeConfig {
     readonly serviceName: string;
     readonly endpoint?: string | undefined;
+    /** Set to false to disable recording prompt/completion text in spans. */
     readonly recordContent?: boolean | undefined;
+    /** Record SHA-256 hash of content instead of plain text. Allows prompt comparison without reading. */
+    readonly hashContent?: boolean | undefined;
+    /** Regex patterns to redact from prompt/completion text before recording. */
+    readonly redactPatterns?: readonly RegExp[] | undefined;
+    readonly instrument?: readonly LLMProvider[] | undefined;
+    /** Static session ID — all spans will carry this value as `session.id`. */
+    readonly sessionId?: string | undefined;
+    /** Dynamic session ID extractor — called per traceLLMCall to resolve session ID. */
+    readonly sessionExtractor?: (() => string | undefined) | undefined;
 }

package/dist/types.js

@@ -2,31 +2,57 @@ export const INSTRUMENTATION_NAME = "toad-eye";
 /**
  * Metric names exported to Prometheus.
  *
- * Naming convention follows OpenTelemetry semantic conventions:
- * - dots as separators: "llm.request.duration"
- * - Prometheus auto-converts dots to underscores: llm_request_duration
- * - Prometheus adds _total suffix to counters automatically — do NOT include it in the name
+ * Naming follows OTel GenAI semantic conventions where possible:
+ * - `gen_ai.client.*` prefix for client-side metrics
+ * - Prometheus auto-converts dots to underscores
+ * - Prometheus adds _total suffix to counters automatically
  */
+export const GEN_AI_METRICS = {
+    REQUEST_DURATION: "gen_ai.client.operation.duration",
+    TOKEN_USAGE: "gen_ai.client.token.usage",
+    REQUEST_COST: "gen_ai.client.request.cost",
+    REQUESTS: "gen_ai.client.requests",
+    ERRORS: "gen_ai.client.errors",
+};
+/** @deprecated Use GEN_AI_METRICS instead. Kept for backward compatibility. */
 export const LLM_METRICS = {
-    REQUEST_DURATION: "llm.request.duration",
-    REQUEST_COST: "llm.request.cost",
-    TOKENS: "llm.tokens",
-    REQUESTS: "llm.requests",
-    ERRORS: "llm.errors",
+    REQUEST_DURATION: GEN_AI_METRICS.REQUEST_DURATION,
+    REQUEST_COST: GEN_AI_METRICS.REQUEST_COST,
+    TOKENS: GEN_AI_METRICS.TOKEN_USAGE,
+    REQUESTS: GEN_AI_METRICS.REQUESTS,
+    ERRORS: GEN_AI_METRICS.ERRORS,
 };
 /**
- * Span attribute keys attached to every LLM span.
- * Using constants prevents typos and enables rename-refactoring.
+ * Span attribute keys following OTel GenAI semantic conventions.
+ * See: https://opentelemetry.io/docs/specs/semconv/gen-ai/
  */
+export const GEN_AI_ATTRS = {
+    PROVIDER: "gen_ai.provider.name",
+    REQUEST_MODEL: "gen_ai.request.model",
+    RESPONSE_MODEL: "gen_ai.response.model",
+    INPUT_TOKENS: "gen_ai.usage.input_tokens",
+    OUTPUT_TOKENS: "gen_ai.usage.output_tokens",
+    TEMPERATURE: "gen_ai.request.temperature",
+    OPERATION: "gen_ai.operation.name",
+    FINISH_REASONS: "gen_ai.response.finish_reasons",
+    // Not in OTel semconv yet — toad-eye extensions
+    PROMPT: "gen_ai.toad_eye.prompt",
+    COMPLETION: "gen_ai.toad_eye.completion",
+    COST: "gen_ai.toad_eye.cost",
+    STATUS: "gen_ai.toad_eye.status",
+    ERROR: "error.type",
+    SESSION_ID: "session.id",
+};
+/** @deprecated Use GEN_AI_ATTRS instead. Kept for backward compatibility. */
 export const LLM_ATTRS = {
-    PROVIDER: "llm.provider",
-    MODEL: "llm.model",
-    PROMPT: "llm.prompt",
-    COMPLETION: "llm.completion",
-    INPUT_TOKENS: "llm.input_tokens",
-    OUTPUT_TOKENS: "llm.output_tokens",
-    COST: "llm.cost",
-    TEMPERATURE: "llm.temperature",
-    STATUS: "llm.status",
-    ERROR: "llm.error",
+    PROVIDER: GEN_AI_ATTRS.PROVIDER,
+    MODEL: GEN_AI_ATTRS.REQUEST_MODEL,
+    PROMPT: GEN_AI_ATTRS.PROMPT,
+    COMPLETION: GEN_AI_ATTRS.COMPLETION,
+    INPUT_TOKENS: GEN_AI_ATTRS.INPUT_TOKENS,
+    OUTPUT_TOKENS: GEN_AI_ATTRS.OUTPUT_TOKENS,
+    COST: GEN_AI_ATTRS.COST,
+    TEMPERATURE: GEN_AI_ATTRS.TEMPERATURE,
+    STATUS: GEN_AI_ATTRS.STATUS,
+    ERROR: GEN_AI_ATTRS.ERROR,
 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "toad-eye",
-  "version": "1.1.0",
-  "description": "One-line OpenTelemetry instrumentation for LLM services",
+  "version": "2.0.0",
+  "description": "Auto-instrumentation, cost tracking, and observability for LLM services",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -30,7 +30,13 @@
     "observability",
     "tracing",
     "metrics",
-    "grafana"
+    "grafana",
+    "openai",
+    "anthropic",
+    "gemini",
+    "cost-tracking",
+    "auto-instrumentation",
+    "gen-ai"
   ],
   "license": "ISC",
   "dependencies": {
@@ -40,6 +46,11 @@
     "@opentelemetry/resources": "^2.6.0",
     "@opentelemetry/sdk-metrics": "^2.6.0",
     "@opentelemetry/sdk-node": "^0.213.0",
-    "@opentelemetry/semantic-conventions": "^1.40.0"
+    "@opentelemetry/semantic-conventions": "^1.40.0",
+    "nodemailer": "^6.9.0",
+    "yaml": "^2.7.0"
+  },
+  "devDependencies": {
+    "@types/nodemailer": "^7.0.11"
   }
 }

package/templates/alerts.example.yml

@@ -0,0 +1,54 @@
+# toad-eye alerts configuration
+# Copy to alerts.yml and customize
+
+# prometheusUrl: http://localhost:9090
+# grafanaUrl: http://localhost:3100
+# evalIntervalSeconds: 30
+# cooldownMinutes: 30
+
+# channels:
+#   telegram:
+#     type: telegram
+#     token: "BOT_TOKEN"
+#     chatId: "CHAT_ID"
+#   slack:
+#     type: slack_webhook
+#     url: "https://hooks.slack.com/services/..."
+
+alerts:
+  # Cost spike: $10 in 1 hour
+  - name: cost_spike
+    metric: gen_ai.client.request.cost
+    condition: sum_1h > 10
+    channels: [slack]
+
+  # Daily budget: $50 in 24 hours
+  - name: budget_daily
+    metric: gen_ai.client.request.cost
+    condition: sum_24h > 50
+    channels: [slack]
+
+  # Latency anomaly: p95 increased >50% vs 7-day baseline
+  - name: latency_anomaly
+    metric: gen_ai.client.operation.duration
+    condition: p95_pct_5m_7d > 50
+    channels: [slack]
+
+  # Latency critical: p95 increased >100% vs 7-day baseline
+  - name: latency_critical
+    metric: gen_ai.client.operation.duration
+    condition: p95_pct_5m_7d > 100
+    channels: [slack]
+
+  # Error rate warning: >5% over 15 minutes
+  - name: error_rate_warning
+    metric: gen_ai.client.errors
+    condition: ratio_15m > 0.05
+    channels: [slack]
+
+  # Error rate critical: >20% over 5 minutes (provider likely down)
+  - name: error_rate_critical
+    metric: gen_ai.client.errors
+    condition: ratio_5m > 0.2
+    channels: [slack]
+    cooldown: 15

package/templates/docker-compose.yml

@@ -28,8 +28,7 @@ services:
     image: grafana/grafana:latest
     volumes:
       - ./grafana/datasources.yml:/etc/grafana/provisioning/datasources/datasources.yml
-      - ./grafana/dashboards/dashboards.yml:/etc/grafana/provisioning/dashboards/dashboards.yml
-      - ./grafana/dashboards/llm-overview.json:/etc/grafana/provisioning/dashboards/llm-overview.json
+      - ./grafana/dashboards:/etc/grafana/provisioning/dashboards
     environment:
       - GF_SECURITY_ADMIN_PASSWORD=admin
       - GF_DASHBOARDS_DEFAULT_HOME_DASHBOARD_PATH=/etc/grafana/provisioning/dashboards/llm-overview.json