toad-eye 2.3.0 → 2.4.0

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.0",
   "description": "Auto-instrumentation, cost tracking, budget guards, and observability for LLM services",
   "type": "module",
   "main": "dist/index.js",