OTEL Span Specs for GenAI Agent Tracing
Standardize OpenTelemetry spans for GenAI agents: use 'create_agent' and 'invoke_agent' operations with CLIENT kind, required provider/model attributes, and token metrics to track creation, invocation, errors, and usage.
Migration to Stable GenAI Conventions
Instrumentations using v1.36.0 or earlier GenAI conventions must not change default emissions; instead, add OTEL_SEMCONV_STABILITY_OPT_IN env var with 'gen_ai_latest_experimental' to opt into latest experimental versions without emitting old ones. This ensures backward compatibility during transition to stable. Provide sampling attributes at span creation: gen_ai.operation.name, gen_ai.provider.name, gen_ai.request.model, server.address/port. These conventions extend base GenAI spans and apply to remote services or local frameworks, based on Kaggle Agents whitepaper.
Span status follows error recording rules; error.type uses provider error codes, exceptions, or low-cardinality IDs like '_OTHER'. gen_ai.provider.name discriminates telemetry flavors (e.g., 'aws.bedrock' uses aws.bedrock.* attrs, not openai.*), even if accessed via proxies like OpenAI API.
Create Agent Span Rules
For agent creation (typically remote services), set gen_ai.operation.name='create_agent', span name='create_agent {gen_ai.agent.name}', CLIENT kind. Required: gen_ai.provider.name (e.g., 'openai', 'aws.bedrock', 'gcp.vertex_ai', full list includes 'anthropic', 'cohere', 'groq', etc.). Conditionally required if available: gen_ai.agent.id (e.g., 'asst_5j66UpCpwteGg4YSxUnt7lPY'), .name ('Math Tutor'), .description, .version ('1.0.0'), gen_ai.request.model ('gpt-4'), server.address/port. Opt-in: gen_ai.system_instructions (JSON array of text prompts like 'You are an Agent that greet users').
Predefined gen_ai.operation.name values: 'chat', 'create_agent', 'embeddings', 'execute_tool', 'generate_content', 'invoke_agent', 'retrieval', 'text_completion'. Model names must match vendor exactly; fine-tuned use specific names.
Invoke Agent Span Rules
For agent invocation, gen_ai.operation.name='invoke_agent', span name='invoke_agent {gen_ai.agent.name}' or 'invoke_agent', CLIENT kind (INTERNAL for same-process like LangChain/CrewAI). Required same as create: provider, agent details. Additional conditionals: gen_ai.conversation.id ('conv_5j66UpCpwteGg4YSxUnt7lPY' for threads/sessions), gen_ai.data_source.id ('H7STPQYOND' matching system ID, pair with db.*), gen_ai.output.type ('text'/'json'/'image'), gen_ai.request.choice.count (!=1, e.g., 3), .model, .seed (e.g., 100 for reproducibility), server.port if address set.
Recommended request params: .temperature (0.0), .top_p (1.0), .frequency_penalty/presence_penalty (0.1), .max_tokens (100), .stop_sequences ('forest','lived'). Response: .finish_reasons ('stop','length'), .id ('chatcmpl-123'), .model ('gpt-4-0613'). Usage: .input_tokens (100), .output_tokens (180), cache .input_tokens (25 creation/50 read). Opt-in: full gen_ai.input/output.messages (role/part structures with tool calls), .system_instructions, .tool.definitions (JSON schemas like get_current_weather with params/location/unit). server.address recommended for CLIENT spans.