AI Observable Metric

1. Span Kind Overview

Distinguish different AI Agent semantic types via the gen_ai.span.kind field. Enumeration values are as follows:

Enumeration Value	Meaning
AGENT	Agent invocation
LLM	Large Language Model invocation
CHAIN	Call chain / Pipeline
EMBEDDING	Vector embedding
TOOL	Tool invocation
TASK	Task unit
RETRIEVER	Retriever
RERANKER	Reranker
MCP_CLIENT	MCP client invocation
UNKNOWN	Unknown type

---

2. Common Attributes

All Span types MUST carry the following fields (from CommonAttributes + SpanAttributes).

2.1 Core Identifiers

Field Key	Type	Description
gen_ai.span.kind	string	Span type; see table above
gen_ai.operation.name	string	Operation type; see §3
gen_ai.framework	string	AI framework name
gen_ai.span.sub_kind	string	Span sub-kind for further classification

2.2 Session & User

Field Key	Type	Description
gen_ai.conversation.id	string	Unique conversation/session ID to link multiple Spans in one interaction
gen_ai.user.id	string	Unique user identifier
gen_ai.user.name	string	User name

2.3 Input / Output

Field Key	Type	Description
input.value	string	Raw input to this Span (text or JSON string)
output.value	string	Raw output from this Span
input.mime_type	string	MIME type of input.value; default text/plain
output.mime_type	string	MIME type of output.value; default text/plain

2.4 Timing

Field Key	Type	Description
gen_ai.user.time_to_first_token	integer	User‑perceived time to first token (nanoseconds)
gen_ai.response.reasoning_time	integer	Inference model reasoning duration (milliseconds)

2.5 Extension

Field Key	Type	Description
metadata	JSON	Custom key‑value metadata
tag.tags	string[]	Tags for filtering and grouping
content	string	Generic content field

---

3. gen_ai.operation.name Enumeration

Enumeration Value	Meaning	Applicable Span Types
chat	Chat completion	LLM
text_completion	Text completion (legacy)	LLM
generate_content	Multimodal content generation	LLM
create_agent	Create Agent	AGENT
invoke_agent	Invoke Agent	AGENT
execute_tool	Execute tool	TOOL
embeddings	Vector embedding	EMBEDDING
retrieve	Retrieve	RETRIEVER

---

4. Span Type‑Specific Fields

4.1 LLM Span

Applicable operations: chat / text_completion / generate_content

Model Identification

Field Key	Type	Description
gen_ai.provider.name	string	AI provider (e.g., openai, anthropic, gcp.gemini)
gen_ai.request.model	string	Requested model name
gen_ai.response.model	string	Actual model used in response (may differ)
gen_ai.output.type	string	Output type: text / json / image / speech
gen_ai.model_name	string	⚠️ Deprecated; use gen_ai.request.model

Request Parameters

Field Key	Type	Description
gen_ai.request.temperature	float	Sampling temperature
gen_ai.request.top_p	float	Nucleus sampling parameter
gen_ai.request.top_k	float	Top‑K sampling parameter
gen_ai.request.max_tokens	integer	Max output tokens
gen_ai.request.stop_sequences	string[]	Stop sequences
gen_ai.request.frequency_penalty	float	Frequency penalty
gen_ai.request.presence_penalty	float	Presence penalty
gen_ai.request.seed	integer	Random seed for deterministic generation
gen_ai.request.choice.count	integer	Number of completions requested
gen_ai.request.is_stream	boolean	Whether streaming response
gen_ai.request.tool_calls	string	Tool call info in request
gen_ai.request.parameters	string	⚠️ Deprecated

Response

Field Key	Type	Description
gen_ai.response.id	string	Unique response ID
gen_ai.response.finish_reasons	string[]	Stop reasons: stop/length/tool_call/content_filter/error
gen_ai.response.time_to_first_token	integer	Model time to first token (nanoseconds, streaming)
gen_ai.response.time_per_output_token	integer	Average time per output token
gen_ai.response.reasoning_content	string	⚠️ Deprecated

Token Usage

Field Key	Type	Description
gen_ai.usage.input_tokens	integer	Input token count
gen_ai.usage.output_tokens	integer	Output token count
gen_ai.usage.total_tokens	integer	Total tokens (input + output)

Latency (Self‑hosted Models)

Field Key	Type	Description
gen_ai.latency.time_in_model_prefill	integer	Prefill phase duration
gen_ai.latency.time_in_model_decode	integer	Decode phase duration
gen_ai.latency.time_in_model_inference	integer	Total inference duration

Message Content (disabled by default)

Field Key	Type	Description
gen_ai.input.messages	JSON	Full input message list
gen_ai.output.messages	JSON	Full output message list
gen_ai.system_instructions	JSON	System prompt
gen_ai.tool.definitions	JSON	Tool definition schema
gen_ai.input.messages_ref	string	External reference to input messages
gen_ai.output.messages_ref	string	External reference to output messages
gen_ai.system_instructions_ref	string	External reference to system instructions

Message Structure Fields

Field Key	Type	Description
message.role	string	user/assistant/system/tool
message.content	string	Message text
message.name	string	Message or function name
message.tool_calls	JSON	Tool calls generated by model
message.function_call_name	string	Function call name
message.function_call_arguments_json	string	Function call arguments (JSON string)

---

4.2 AGENT Span

Applicable operations: create_agent / invoke_agent

AGENT Span inherits all LLMAttributes; key fields:

Field Key	Type	Description
gen_ai.operation.name	string	create_agent or invoke_agent
gen_ai.conversation.id	string	Conversation ID for cross‑Span correlation
gen_ai.data_source.id	string	Data source ID (RAG)
gen_ai.retrieval.query.text	string	Retrieval query text
gen_ai.provider.name	string	Agent service provider
gen_ai.request.model	string	Base model used by Agent
gen_ai.usage.input_tokens	integer	Total input tokens
gen_ai.usage.output_tokens	integer	Total output tokens
gen_ai.input.messages	JSON	Input message history
gen_ai.output.messages	JSON	Output messages
gen_ai.tool.definitions	JSON	Available tool definitions
gen_ai.system_instructions	JSON	Agent system instructions

---

4.3 TOOL Span

Applicable operation: execute_tool

OTEL Tool Attributes

Field Key	Type	Description
gen_ai.tool.name	string	Tool name
gen_ai.tool.description	string	Tool capability description
gen_ai.tool.call.id	string	Unique tool call ID
gen_ai.tool.type	string	function/custom/unknown

OpenInference Tool Attributes

Field Key	Type	Description
tool.parameters	JSON	Input parameter JSON Schema
tool_call.function.arguments	string	Call arguments (JSON string)
tool_call.function.thoughts	string	Model reasoning before tool call

---

4.4 EMBEDDING Span

Applicable operation: embeddings

Field Key	Type	Description
gen_ai.request.model	string	Embedding model name
gen_ai.request.encoding_formats	string[]	Encoding formats: float, base64
gen_ai.request.temperature	float	Sampling temperature
gen_ai.usage.input_tokens	integer	Input tokens for embedding
gen_ai.embeddings.dimension.count	integer	Embedding vector dimension
embedding.embeddings	JSON	Embedding results (text + vector)
embedding.model_name	string	⚠️ Deprecated; use gen_ai.request.model
embedding.embedding_output	string	⚠️ Deprecated

---

4.5 RETRIEVER Span

Applicable operation: retrieve

Field Key	Type	Description
retrieval.documents	JSON	Retrieved documents: id/score/content/metadata
retrieval.documents.list.length	integer	Number of documents returned

Document Substructure

Field Key	Type	Description
document.id	string	Unique document ID
document.score	float	Relevance score (0.0–1.0)
document.content	string	Chunk content
document.metadata	JSON	Source metadata (filename, URL, etc.)

---

4.6 RERANKER Span

Field Key	Type	Description
gen_ai.span.kind	string	Fixed: RERANKER
gen_ai.operation.name	string	Recommended: rerank
input.value	string	Query input
output.value	string	Reranked document list (JSON string)
gen_ai.conversation.id	string	Linked conversation ID
metadata	JSON	Custom metadata

---

4.7 CHAIN Span

Identified by gen_ai.span.kind = CHAIN; uses only common attributes.

Field Key	Type	Description
gen_ai.span.kind	string	Fixed: CHAIN
gen_ai.operation.name	string	Custom pipeline operation name
gen_ai.span.sub_kind	string	Chain subtype
input.value	string	Raw input
output.value	string	Final output
gen_ai.conversation.id	string	Linked conversation ID
gen_ai.framework	string	AI framework (LangChain, LlamaIndex, etc.)
metadata	JSON	Custom metadata

---

4.8 TASK Span

Identified by gen_ai.span.kind = TASK; represents an independent work unit decomposed by Agent.

Field Key	Type	Description
gen_ai.span.kind	string	Fixed: TASK
gen_ai.operation.name	string	Custom task name
gen_ai.span.sub_kind	string	Task subtype or status
input.value	string	Task input
output.value	string	Task output
gen_ai.conversation.id	string	Linked conversation ID
gen_ai.user.id	string	Linked user ID
metadata	JSON	Custom task metadata

---

4.9 MCP_CLIENT Span

Based on OTEL MCP Specification

Field Key	Type	Description
gen_ai.span.kind	string	Fixed: MCP_CLIENT
mcp.method.name	string	Required MCP method name
error.type	string	Error type (on failure)
gen_ai.prompt.name	string	MCP prompt name
gen_ai.tool.name	string	MCP tool name
gen_ai.operation.name	string	Operation type
rpc.response.status_code	string	MCP response status code
jsonrpc.protocol.version	string	JSON‑RPC version
mcp.protocol.version	string	MCP version
network.protocol.name	string	Network protocol
network.protocol.version	string	Network protocol version
network.transport	string	Transport protocol
server.address	string	MCP server address
server.port	integer	MCP server port
mcp.resource.uri	string	MCP resource URI

---

5. Enumeration Quick Reference

gen_ai.response.finish_reasons

Value	Meaning
stop	Normal stop
length	Max tokens reached
content_filter	Content filter triggered
tool_call	Model requested tool call
error	Error occurred

gen_ai.output.type

Value	Meaning
text	Plain text
json	JSON object
image	Image
speech	Speech