toad-eye 2.3.0 → 2.4.1

package/README.md

@@ -18,6 +18,8 @@ You don't know what your LLMs cost, how slow they are, or why they fail. toad-ey
 
 ## Quick start
 
+**Prerequisites:** [Docker Desktop](https://docs.docker.com/get-started/get-docker/) (or Docker Engine + Compose plugin)
+
 ```bash
 npm install toad-eye
 npx toad-eye init       # scaffold observability stack
@@ -25,6 +27,8 @@ npx toad-eye up         # start Grafana + Prometheus + Jaeger
 npx toad-eye demo       # send mock LLM traffic, see data immediately
 ```
 
+> Dashboards will be empty until data arrives. Run `npx toad-eye demo` to send mock traffic and verify the stack works.
+
 ```typescript
 import { initObservability } from "toad-eye";
 
@@ -36,6 +40,8 @@ initObservability({
 // That's it. Every SDK call is auto-traced — including streaming.
 ```
 
+> ⚠️ By default, toad-eye records prompt and completion text in spans. Set `recordContent: false` for PII-sensitive workloads (healthcare, finance, legal).
+
 Open [localhost:3100](http://localhost:3100) (Grafana, admin/admin) to see your dashboards.
 
 ## What you get
@@ -46,16 +52,24 @@ Open [localhost:3100](http://localhost:3100) (Grafana, admin/admin) to see your
 | **8 Grafana dashboards** | Overview, Cost, Latency, Errors, Model Comparison, FinOps, Provider Health, Agent Workflow |
 | **Cost tracking**        | Per-request USD cost, daily totals, projected monthly spend                                |
 | **Budget guards**        | Daily/per-user/per-model spend limits — warn, block, or auto-downgrade                     |
-| **Multi-agent tracing**  | ReAct steps, handoffs, loop detection, maxSteps guard                                      |
-| **Shadow guardrails**    | Record what _would_ be blocked without blocking — tune thresholds on live traffic          |
-| **Quality proxy**        | Empty response rate, latency per token — zero-dependency quality metrics                   |
-| **Semantic drift**       | Detect silent quality degradation via embedding comparison                                 |
 | **Privacy controls**     | Built-in PII redaction (email, SSN, CC, phone), hashing, content masking                   |
-| **Tail sampling**        | Keep 100% errors + slow traces, sample healthy traffic via OTel Collector                  |
-| **Alerting**             | Cost spikes, latency anomalies, error rate — via Telegram, Slack, email, webhook           |
-| **FinOps attribution**   | Break down costs by team, user, feature, environment                                       |
-| **TTFT metric**          | Time To First Token for streaming — separate from total duration                           |
-| **Trace export**         | Convert production Jaeger traces into regression test cases                                |
+
+<details>
+<summary>Advanced features</summary>
+
+| Feature                 | Description                                                                       |
+| ----------------------- | --------------------------------------------------------------------------------- |
+| **Multi-agent tracing** | ReAct steps, handoffs, loop detection, maxSteps guard                             |
+| **Shadow guardrails**   | Record what _would_ be blocked without blocking — tune thresholds on live traffic |
+| **Quality proxy**       | Empty response rate, latency per token — zero-dependency quality metrics          |
+| **Semantic drift**      | Detect silent quality degradation via embedding comparison                        |
+| **Tail sampling**       | Keep 100% errors + slow traces, sample healthy traffic via OTel Collector         |
+| **Alerting**            | Cost spikes, latency anomalies, error rate — via Telegram, Slack, email, webhook  |
+| **FinOps attribution**  | Break down costs by team, user, feature, environment                              |
+| **TTFT metric**         | Time To First Token for streaming — separate from total duration                  |
+| **Trace export**        | Convert production Jaeger traces into regression test cases                       |
+
+</details>
 
 ## Auto-instrumentation 🤖
 
@@ -77,17 +91,35 @@ Vercel AI SDK uses a SpanProcessor (not monkey-patching) — add `instrument: ['
 <details>
 <summary>Manual instrumentation (custom providers)</summary>
 
+Use `traceLLMCall` when you need to instrument a provider not in the auto-instrument list, or want explicit control over span data:
+
 ```typescript
+import OpenAI from "openai";
 import { initObservability, traceLLMCall } from "toad-eye";
 
 initObservability({ serviceName: "my-app" });
 
+const openai = new OpenAI();
+
 const result = await traceLLMCall(
-  { provider: "anthropic", model: "claude-sonnet-4-20250514", prompt: "hello" },
-  () => callYourLLM(),
+  { provider: "openai", model: "gpt-4o", prompt: "Hello" },
+  async () => {
+    const res = await openai.chat.completions.create({
+      model: "gpt-4o",
+      messages: [{ role: "user", content: "Hello" }],
+    });
+    return {
+      completion: res.choices[0]?.message.content ?? "",
+      inputTokens: res.usage?.prompt_tokens ?? 0,
+      outputTokens: res.usage?.completion_tokens ?? 0,
+      // cost is auto-calculated from model + tokens if omitted
+    };
+  },
 );
 ```
 
+> Or skip this entirely — use `instrument: ['openai']` for zero-code instrumentation.
+
 </details>
 
 ## Budget guards
@@ -114,11 +146,36 @@ initObservability({
 
 ## Agent observability
 
-Structured tracing for ReAct agents with multi-agent support, handoffs, and loop detection.
+Structured tracing for ReAct agents with multi-agent support, handoffs, and loop detection. Span names follow [OTel GenAI semantic conventions](https://opentelemetry.io/docs/specs/semconv/gen-ai/gen-ai-agent-spans/).
 
 ```typescript
 import { traceAgentQuery } from "toad-eye";
 
+const result = await traceAgentQuery(
+  {
+    query: "What's the weather like?",
+    agentName: "weather-bot", // → gen_ai.agent.name (OTel semconv)
+  },
+  async (step) => {
+    step({ type: "think", stepNumber: 1, content: "Need weather data" });
+    const data = await getWeather();
+    step({
+      type: "act",
+      stepNumber: 2,
+      toolName: "get_weather",
+      toolType: "function",
+    });
+    step({ type: "answer", stepNumber: 3, content: data.summary });
+    return { answer: data.summary };
+  },
+);
+// Produces spans: invoke_agent weather-bot → execute_tool get_weather
+```
+
+<details>
+<summary>Full ReAct pattern (think → act → observe → answer)</summary>
+
+```typescript
 const result = await traceAgentQuery(
   "Is anything dangerous near Earth?",
   async (step) => {
@@ -144,6 +201,8 @@ const result = await traceAgentQuery(
 );
 ```
 
+</details>
+
 ## FinOps attribution
 
 Track costs by team, user, feature, or any business dimension:
@@ -201,6 +260,14 @@ monitor.checkInBackground(response, "openai", "gpt-4o");
 
 ### Privacy controls
 
+| Goal                        | Config                           |
+| --------------------------- | -------------------------------- |
+| Don't store text at all     | `recordContent: false`           |
+| Remove common PII           | `redactDefaults: true`           |
+| Remove custom patterns      | `redactPatterns: [/regex/g]`     |
+| Store hashes only (no text) | `hashContent: true, salt: "..."` |
+| Audit what was masked       | `auditMasking: true`             |
+
 ```typescript
 initObservability({
   serviceName: "my-app",
@@ -289,11 +356,25 @@ Self-hosted mode remains the default. Cloud mode activates automatically when `a
 | **Provider Health**    | Provider status (healthy/degraded/down), uptime, error breakdown |
 | **Agent Workflow**     | Steps per query, tool usage frequency, step type breakdown       |
 
+## Subpath imports
+
+Advanced modules are available as separate entry points to keep your bundle lean:
+
+```typescript
+import { initObservability, traceLLMCall } from "toad-eye"; // core
+import { AlertManager } from "toad-eye/alerts"; // alerting
+import { createDriftMonitor } from "toad-eye/drift"; // semantic drift
+import { exportTrace } from "toad-eye/export"; // trace → YAML
+import { ToadEyeAISpanProcessor, withToadEye } from "toad-eye/vercel"; // Vercel AI SDK
+```
+
+> Everything is also re-exported from the main `"toad-eye"` entry point for convenience.
+
 ## CLI
 
 | Command                          | Description                                     |
 | -------------------------------- | ----------------------------------------------- |
-| `npx toad-eye init`              | Scaffold Docker Compose + observability configs |
+| `npx toad-eye init [--force]`    | Scaffold Docker Compose + observability configs |
 | `npx toad-eye up`                | Start the stack                                 |
 | `npx toad-eye down`              | Stop the stack                                  |
 | `npx toad-eye status`            | Show running services and URLs                  |
@@ -330,22 +411,26 @@ Self-hosted mode remains the default. Cloud mode activates automatically when `a
 | `gen_ai.toad_eye.response.empty`             | Counter   | Empty/whitespace responses  |
 | `gen_ai.toad_eye.response.latency_per_token` | Histogram | Generation speed (ms/token) |
 
-### Span attributes
-
-| Attribute                    | Description                                  |
-| ---------------------------- | -------------------------------------------- |
-| `gen_ai.provider.name`       | `anthropic`, `gemini`, `openai`              |
-| `gen_ai.request.model`       | Model identifier                             |
-| `gen_ai.usage.input_tokens`  | Tokens in the prompt                         |
-| `gen_ai.usage.output_tokens` | Tokens in the completion                     |
-| `gen_ai.request.temperature` | Temperature parameter                        |
-| `gen_ai.toad_eye.cost`       | Cost in USD                                  |
-| `gen_ai.agent.step.type`     | Agent step: think/act/observe/answer/handoff |
-| `gen_ai.agent.tool.name`     | Tool name for agent act steps                |
-| `gen_ai.agent.handoff.to`    | Target agent for handoff steps               |
-| `gen_ai.agent.loop_count`    | Agent loop iterations (observe→think)        |
-| `gen_ai.toad_eye.guard.mode` | Guard mode: shadow/enforce                   |
-| `session.id`                 | Session identifier (if configured)           |
+### Span attributes (OTel GenAI semconv)
+
+| Attribute                          | Description                                     |
+| ---------------------------------- | ----------------------------------------------- |
+| `gen_ai.operation.name`            | `chat`, `invoke_agent`, `execute_tool`          |
+| `gen_ai.provider.name`             | `anthropic`, `gemini`, `openai`                 |
+| `gen_ai.request.model`             | Model identifier                                |
+| `gen_ai.usage.input_tokens`        | Tokens in the prompt                            |
+| `gen_ai.usage.output_tokens`       | Tokens in the completion                        |
+| `gen_ai.request.temperature`       | Temperature parameter                           |
+| `gen_ai.agent.name`                | Agent name (for agent spans)                    |
+| `gen_ai.agent.id`                  | Agent identifier                                |
+| `gen_ai.tool.name`                 | Tool name for execute_tool spans                |
+| `gen_ai.tool.type`                 | `function`, `extension`, `retrieval`, `builtin` |
+| `gen_ai.toad_eye.cost`             | Cost in USD                                     |
+| `gen_ai.toad_eye.agent.step.type`  | ReAct step: think/act/observe/answer/handoff    |
+| `gen_ai.toad_eye.agent.handoff.to` | Target agent for handoff steps                  |
+| `gen_ai.toad_eye.agent.loop_count` | Agent loop iterations (observe→think)           |
+| `gen_ai.toad_eye.guard.mode`       | Guard mode: shadow/enforce                      |
+| `session.id`                       | Session identifier (if configured)              |
 
 </details>
 
@@ -358,9 +443,17 @@ Self-hosted mode remains the default. Cloud mode activates automatically when `a
 | Prometheus     | [localhost:9090](http://localhost:9090)                 |
 | OTel Collector | [localhost:4318](http://localhost:4318)                 |
 
+## OTel GenAI semconv
+
+toad-eye follows [OTel GenAI semantic conventions](https://opentelemetry.io/docs/specs/semconv/gen-ai/) for span names, attributes, and metrics. Traces are natively compatible with Jaeger, Arize Phoenix, SigNoz, Datadog, Langfuse, and other OTel backends.
+
+See [COMPATIBILITY.md](https://github.com/vola-trebla/toad-eye/blob/main/packages/instrumentation/COMPATIBILITY.md) for a full backend support matrix.
+
+Set `OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental` to disable deprecated attribute aliases and emit only the latest conventions.
+
 ## Tech stack
 
 - TypeScript, OpenTelemetry SDK 2.x, OTel GenAI semantic conventions
 - Hono (demo server + cloud ingestion server)
 - Docker Compose (Prometheus, Jaeger, Grafana, OTel Collector)
-- Vitest (143+ tests)
+- Vitest (252+ tests)

package/dist/agent.d.ts

@@ -1,4 +1,4 @@
-import type { AgentStepInput, AgentQueryOptions } from "./types/index.js";
+import type { AgentStepInput, AgentQueryOptions, AgentQueryInput } from "./types/index.js";
 /**
  * Record a single agent step as a child span (ReAct pattern).
  * Supports: think, act, observe, answer, handoff.
@@ -7,6 +7,9 @@ declare function traceAgentStep(input: AgentStepInput): void;
 /**
  * Wrap an entire agent query in a parent span with ReAct tracing.
  *
+ * Accepts either a string query (backward-compatible) or an object with
+ * agent metadata per OTel GenAI spec (agentName, agentId).
+ *
  * Supports multi-agent via nesting — child traceAgentQuery calls
  * automatically become child spans in Jaeger.
  *
@@ -15,18 +18,27 @@ declare function traceAgentStep(input: AgentStepInput): void;
  *
  * @example
  * ```ts
+ * // Simple form (backward-compatible)
+ * await traceAgentQuery('Is anything dangerous?', async (step) => { ... });
+ *
+ * // Object form with agent metadata (OTel GenAI spec)
+ * await traceAgentQuery(
+ *   { query: 'Is anything dangerous?', agentName: 'space-monitor', agentId: 'agent-001' },
+ *   async (step) => { ... }
+ * );
+ *
  * // Multi-agent: orchestrator delegates to specialist
- * await traceAgentQuery('orchestrator', async (step) => {
+ * await traceAgentQuery({ query: 'Analyze data', agentName: 'orchestrator' }, async (step) => {
  *   step({ type: 'think', stepNumber: 1, content: 'Need domain expert' });
  *   step({ type: 'handoff', stepNumber: 2, toAgent: 'specialist', handoffReason: 'domain expertise' });
  *
- *   const result = await traceAgentQuery('specialist', async (step) => {
- *     step({ type: 'act', stepNumber: 1, toolName: 'analyze' });
+ *   const result = await traceAgentQuery({ query: 'Analyze', agentName: 'specialist' }, async (step) => {
+ *     step({ type: 'act', stepNumber: 1, toolName: 'analyze', toolType: 'function' });
  *     step({ type: 'answer', stepNumber: 2, content: 'analysis complete' });
  *     return { answer: 'done' };
  *   });
  * });
  * ```
  */
-export declare function traceAgentQuery<T>(query: string, fn: (step: (input: AgentStepInput) => void) => Promise<T>, options?: AgentQueryOptions): Promise<T>;
+export declare function traceAgentQuery<T>(queryOrInput: string | AgentQueryInput, fn: (step: (input: AgentStepInput) => void) => Promise<T>, options?: AgentQueryOptions): Promise<T>;
 export { traceAgentStep };

package/dist/agent.js

@@ -1,7 +1,7 @@
 import { trace, SpanStatusCode } from "@opentelemetry/api";
 import { GEN_AI_ATTRS, INSTRUMENTATION_NAME } from "./types/index.js";
 import { recordAgentSteps, recordAgentToolUsage } from "./core/metrics.js";
-import { getConfig } from "./core/tracer.js";
+import { getConfig, shouldEmitDeprecatedAttrs } from "./core/tracer.js";
 const tracer = trace.getTracer(INSTRUMENTATION_NAME);
 const DEFAULT_MAX_STEPS = 25;
 /**
@@ -9,25 +9,52 @@ const DEFAULT_MAX_STEPS = 25;
  * Supports: think, act, observe, answer, handoff.
  */
 function traceAgentStep(input) {
-    const span = tracer.startSpan(`agent.step.${input.type}`);
+    const spanName = input.type === "act" && input.toolName !== undefined
+        ? `execute_tool ${input.toolName}`
+        : `gen_ai.agent.step.${input.type}`;
+    const span = tracer.startSpan(spanName);
     const config = getConfig();
     const recordContent = config?.recordContent !== false;
+    const emitDeprecated = shouldEmitDeprecatedAttrs();
     span.setAttributes({
-        [GEN_AI_ATTRS.AGENT_STEP_TYPE]: input.type,
-        [GEN_AI_ATTRS.AGENT_STEP_NUMBER]: input.stepNumber,
+        // Canonical toad_eye namespace
+        [GEN_AI_ATTRS.TOAD_AGENT_STEP_TYPE]: input.type,
+        [GEN_AI_ATTRS.TOAD_AGENT_STEP_NUMBER]: input.stepNumber,
+        // Deprecated aliases (skipped when OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental)
+        ...(emitDeprecated && {
+            [GEN_AI_ATTRS.AGENT_STEP_TYPE]: input.type,
+            [GEN_AI_ATTRS.AGENT_STEP_NUMBER]: input.stepNumber,
+        }),
         ...(input.toolName !== undefined && {
-            [GEN_AI_ATTRS.AGENT_TOOL_NAME]: input.toolName,
+            // OTel spec attribute
+            [GEN_AI_ATTRS.TOOL_NAME]: input.toolName,
+            // Deprecated alias
+            ...(emitDeprecated && {
+                [GEN_AI_ATTRS.AGENT_TOOL_NAME]: input.toolName,
+            }),
+        }),
+        ...(input.toolType !== undefined && {
+            [GEN_AI_ATTRS.TOOL_TYPE]: input.toolType,
         }),
         ...(recordContent &&
             input.content !== undefined && {
-            [GEN_AI_ATTRS.AGENT_STEP_CONTENT]: input.content,
+            [GEN_AI_ATTRS.TOAD_AGENT_STEP_CONTENT]: input.content,
+            ...(emitDeprecated && {
+                [GEN_AI_ATTRS.AGENT_STEP_CONTENT]: input.content,
+            }),
         }),
         // Handoff attributes
         ...(input.toAgent !== undefined && {
-            [GEN_AI_ATTRS.AGENT_HANDOFF_TO]: input.toAgent,
+            [GEN_AI_ATTRS.TOAD_AGENT_HANDOFF_TO]: input.toAgent,
+            ...(emitDeprecated && {
+                [GEN_AI_ATTRS.AGENT_HANDOFF_TO]: input.toAgent,
+            }),
         }),
         ...(input.handoffReason !== undefined && {
-            [GEN_AI_ATTRS.AGENT_HANDOFF_REASON]: input.handoffReason,
+            [GEN_AI_ATTRS.TOAD_AGENT_HANDOFF_REASON]: input.handoffReason,
+            ...(emitDeprecated && {
+                [GEN_AI_ATTRS.AGENT_HANDOFF_REASON]: input.handoffReason,
+            }),
         }),
     });
     if (input.type === "act" && input.toolName !== undefined) {
@@ -39,6 +66,9 @@ function traceAgentStep(input) {
 /**
  * Wrap an entire agent query in a parent span with ReAct tracing.
  *
+ * Accepts either a string query (backward-compatible) or an object with
+ * agent metadata per OTel GenAI spec (agentName, agentId).
+ *
  * Supports multi-agent via nesting — child traceAgentQuery calls
  * automatically become child spans in Jaeger.
  *
@@ -47,26 +77,52 @@ function traceAgentStep(input) {
  *
  * @example
  * ```ts
+ * // Simple form (backward-compatible)
+ * await traceAgentQuery('Is anything dangerous?', async (step) => { ... });
+ *
+ * // Object form with agent metadata (OTel GenAI spec)
+ * await traceAgentQuery(
+ *   { query: 'Is anything dangerous?', agentName: 'space-monitor', agentId: 'agent-001' },
+ *   async (step) => { ... }
+ * );
+ *
  * // Multi-agent: orchestrator delegates to specialist
- * await traceAgentQuery('orchestrator', async (step) => {
+ * await traceAgentQuery({ query: 'Analyze data', agentName: 'orchestrator' }, async (step) => {
  *   step({ type: 'think', stepNumber: 1, content: 'Need domain expert' });
  *   step({ type: 'handoff', stepNumber: 2, toAgent: 'specialist', handoffReason: 'domain expertise' });
  *
- *   const result = await traceAgentQuery('specialist', async (step) => {
- *     step({ type: 'act', stepNumber: 1, toolName: 'analyze' });
+ *   const result = await traceAgentQuery({ query: 'Analyze', agentName: 'specialist' }, async (step) => {
+ *     step({ type: 'act', stepNumber: 1, toolName: 'analyze', toolType: 'function' });
  *     step({ type: 'answer', stepNumber: 2, content: 'analysis complete' });
  *     return { answer: 'done' };
  *   });
  * });
  * ```
  */
-export async function traceAgentQuery(query, fn, options) {
-    return tracer.startActiveSpan(`agent.query`, async (span) => {
+export async function traceAgentQuery(queryOrInput, fn, options) {
+    const resolved = typeof queryOrInput === "string"
+        ? { query: queryOrInput, agentName: undefined, agentId: undefined }
+        : queryOrInput;
+    const spanName = resolved.agentName
+        ? `invoke_agent ${resolved.agentName}`
+        : `invoke_agent`;
+    return tracer.startActiveSpan(spanName, async (span) => {
         const config = getConfig();
         const recordContent = config?.recordContent !== false;
+        const emitDeprecated = shouldEmitDeprecatedAttrs();
         const maxSteps = options?.maxSteps ?? DEFAULT_MAX_STEPS;
+        // OTel GenAI agent attributes
+        if (resolved.agentName !== undefined) {
+            span.setAttribute(GEN_AI_ATTRS.AGENT_NAME, resolved.agentName);
+        }
+        if (resolved.agentId !== undefined) {
+            span.setAttribute(GEN_AI_ATTRS.AGENT_ID, resolved.agentId);
+        }
         if (recordContent) {
-            span.setAttribute(GEN_AI_ATTRS.AGENT_STEP_CONTENT, query);
+            span.setAttribute(GEN_AI_ATTRS.TOAD_AGENT_STEP_CONTENT, resolved.query);
+            if (emitDeprecated) {
+                span.setAttribute(GEN_AI_ATTRS.AGENT_STEP_CONTENT, resolved.query);
+            }
         }
         let stepCount = 0;
         let loopCount = 0;
@@ -91,13 +147,19 @@ export async function traceAgentQuery(query, fn, options) {
                 }
                 traceAgentStep(input);
             });
-            span.setAttribute(GEN_AI_ATTRS.AGENT_LOOP_COUNT, loopCount);
+            span.setAttribute(GEN_AI_ATTRS.TOAD_AGENT_LOOP_COUNT, loopCount);
+            if (emitDeprecated) {
+                span.setAttribute(GEN_AI_ATTRS.AGENT_LOOP_COUNT, loopCount);
+            }
             span.setStatus({ code: SpanStatusCode.OK });
             return result;
         }
         catch (error) {
             const message = error instanceof Error ? error.message : String(error);
-            span.setAttribute(GEN_AI_ATTRS.AGENT_LOOP_COUNT, loopCount);
+            span.setAttribute(GEN_AI_ATTRS.TOAD_AGENT_LOOP_COUNT, loopCount);
+            if (emitDeprecated) {
+                span.setAttribute(GEN_AI_ATTRS.AGENT_LOOP_COUNT, loopCount);
+            }
             span.setStatus({ code: SpanStatusCode.ERROR, message });
             throw error;
         }

package/dist/core/metrics.js

@@ -107,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) {

package/dist/core/spans.js

@@ -153,7 +153,7 @@ export async function traceLLMCall(input, fn) {
             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 {

package/dist/core/tracer.d.ts

@@ -1,6 +1,12 @@
 import type { ToadEyeConfig } from "../types/index.js";
 import { BudgetTracker } from "../budget/index.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

@@ -18,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;
 }

package/dist/instrumentations/create.js

@@ -84,7 +84,7 @@ original, patch, providerName) {
                 recordBudgetDowngraded(override.budget);
             }
         }
-        const span = tracer.startSpan(`gen_ai.${effectiveProvider}.${effectiveModel}`);
+        const span = tracer.startSpan(`chat ${effectiveModel}`);
         const ctx = trace.setSpan(context.active(), span);
         const sessionId = config?.sessionExtractor?.() ?? config?.sessionId;
         span.setAttributes({

package/dist/types/attributes.d.ts

@@ -15,12 +15,29 @@ export declare const GEN_AI_ATTRS: {
     readonly OPERATION: "gen_ai.operation.name";
     readonly FINISH_REASONS: "gen_ai.response.finish_reasons";
     readonly ERROR: "error.type";
+    readonly AGENT_NAME: "gen_ai.agent.name";
+    readonly AGENT_ID: "gen_ai.agent.id";
+    readonly TOOL_NAME: "gen_ai.tool.name";
+    readonly TOOL_TYPE: "gen_ai.tool.type";
+    readonly TOAD_AGENT_STEP_TYPE: "gen_ai.toad_eye.agent.step.type";
+    readonly TOAD_AGENT_STEP_NUMBER: "gen_ai.toad_eye.agent.step.number";
+    readonly TOAD_AGENT_STEP_CONTENT: "gen_ai.toad_eye.agent.step.content";
+    readonly TOAD_AGENT_HANDOFF_TO: "gen_ai.toad_eye.agent.handoff.to";
+    readonly TOAD_AGENT_HANDOFF_REASON: "gen_ai.toad_eye.agent.handoff.reason";
+    readonly TOAD_AGENT_LOOP_COUNT: "gen_ai.toad_eye.agent.loop_count";
+    /** @deprecated Use TOAD_AGENT_STEP_TYPE instead. Will be removed in v3.0. */
     readonly AGENT_STEP_TYPE: "gen_ai.agent.step.type";
+    /** @deprecated Use TOAD_AGENT_STEP_NUMBER instead. Will be removed in v3.0. */
     readonly AGENT_STEP_NUMBER: "gen_ai.agent.step.number";
+    /** @deprecated Use TOOL_NAME instead. Will be removed in v3.0. */
     readonly AGENT_TOOL_NAME: "gen_ai.agent.tool.name";
+    /** @deprecated Use TOAD_AGENT_STEP_CONTENT instead. Will be removed in v3.0. */
     readonly AGENT_STEP_CONTENT: "gen_ai.agent.step.content";
+    /** @deprecated Use TOAD_AGENT_HANDOFF_TO instead. Will be removed in v3.0. */
     readonly AGENT_HANDOFF_TO: "gen_ai.agent.handoff.to";
+    /** @deprecated Use TOAD_AGENT_HANDOFF_REASON instead. Will be removed in v3.0. */
     readonly AGENT_HANDOFF_REASON: "gen_ai.agent.handoff.reason";
+    /** @deprecated Use TOAD_AGENT_LOOP_COUNT instead. Will be removed in v3.0. */
     readonly AGENT_LOOP_COUNT: "gen_ai.agent.loop_count";
     readonly GUARD_MODE: "gen_ai.toad_eye.guard.mode";
     readonly GUARD_PASSED: "gen_ai.toad_eye.guard.passed";

package/dist/types/attributes.js

@@ -16,13 +16,32 @@ export const GEN_AI_ATTRS = {
     OPERATION: "gen_ai.operation.name",
     FINISH_REASONS: "gen_ai.response.finish_reasons",
     ERROR: "error.type",
-    // Agent step attributes
+    // OTel GenAI agent attributes
+    AGENT_NAME: "gen_ai.agent.name",
+    AGENT_ID: "gen_ai.agent.id",
+    TOOL_NAME: "gen_ai.tool.name",
+    TOOL_TYPE: "gen_ai.tool.type",
+    // toad-eye ReAct extensions (gen_ai.toad_eye.agent.* — correct namespace)
+    TOAD_AGENT_STEP_TYPE: "gen_ai.toad_eye.agent.step.type",
+    TOAD_AGENT_STEP_NUMBER: "gen_ai.toad_eye.agent.step.number",
+    TOAD_AGENT_STEP_CONTENT: "gen_ai.toad_eye.agent.step.content",
+    TOAD_AGENT_HANDOFF_TO: "gen_ai.toad_eye.agent.handoff.to",
+    TOAD_AGENT_HANDOFF_REASON: "gen_ai.toad_eye.agent.handoff.reason",
+    TOAD_AGENT_LOOP_COUNT: "gen_ai.toad_eye.agent.loop_count",
+    // Agent step attributes — @deprecated aliases (will be removed in v3.0)
+    /** @deprecated Use TOAD_AGENT_STEP_TYPE instead. Will be removed in v3.0. */
     AGENT_STEP_TYPE: "gen_ai.agent.step.type",
+    /** @deprecated Use TOAD_AGENT_STEP_NUMBER instead. Will be removed in v3.0. */
     AGENT_STEP_NUMBER: "gen_ai.agent.step.number",
+    /** @deprecated Use TOOL_NAME instead. Will be removed in v3.0. */
     AGENT_TOOL_NAME: "gen_ai.agent.tool.name",
+    /** @deprecated Use TOAD_AGENT_STEP_CONTENT instead. Will be removed in v3.0. */
     AGENT_STEP_CONTENT: "gen_ai.agent.step.content",
+    /** @deprecated Use TOAD_AGENT_HANDOFF_TO instead. Will be removed in v3.0. */
     AGENT_HANDOFF_TO: "gen_ai.agent.handoff.to",
+    /** @deprecated Use TOAD_AGENT_HANDOFF_REASON instead. Will be removed in v3.0. */
     AGENT_HANDOFF_REASON: "gen_ai.agent.handoff.reason",
+    /** @deprecated Use TOAD_AGENT_LOOP_COUNT instead. Will be removed in v3.0. */
     AGENT_LOOP_COUNT: "gen_ai.agent.loop_count",
     // Guard (shadow mode) attributes
     GUARD_MODE: "gen_ai.toad_eye.guard.mode",

package/dist/types/index.d.ts

@@ -14,4 +14,4 @@ export type { ToadEyeConfig, SamplingConfig } 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, AgentStepType, AgentStepInput, AgentQueryOptions, GuardMode, GuardResult, } from "./spans.js";
+export type { SpanStatus, LLMSpanAttributes, AgentStepType, AgentStepInput, AgentQueryOptions, AgentQueryInput, GuardMode, GuardResult, } from "./spans.js";

package/dist/types/spans.d.ts

@@ -9,6 +9,8 @@ export interface AgentStepInput {
     readonly stepNumber: number;
     readonly content?: string | undefined;
     readonly toolName?: string | undefined;
+    /** Tool type per OTel GenAI spec: function, extension, retrieval, builtin */
+    readonly toolType?: "function" | "extension" | "retrieval" | "builtin" | undefined;
     /** Target agent name for handoff steps */
     readonly toAgent?: string | undefined;
     /** Reason for handoff */
@@ -19,6 +21,14 @@ export interface AgentQueryOptions {
     /** Max steps before recording a warning. Default: 25 */
     readonly maxSteps?: number | undefined;
 }
+/** Input for traceAgentQuery — object form with agent metadata */
+export interface AgentQueryInput {
+    readonly query: string;
+    /** Agent name — maps to gen_ai.agent.name and span name invoke_agent {agentName} */
+    readonly agentName?: string | undefined;
+    /** Agent identifier — maps to gen_ai.agent.id */
+    readonly agentId?: string | undefined;
+}
 /** Guard execution mode */
 export type GuardMode = "shadow" | "enforce";
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toad-eye",
-  "version": "2.3.0",
+  "version": "2.4.1",
   "description": "Auto-instrumentation, cost tracking, budget guards, and observability for LLM services",
   "type": "module",
   "main": "dist/index.js",