LLM Trace field definitions - Application Real-Time Monitoring Service

LLM Trace fields are defined by Alibaba Cloud based on the OpenTelemetry standard and concepts from the large language model (LLM) application domain. These fields extend Attributes, Resource, and Event to describe the semantics of LLM application trace data. They capture key operations such as LLM input and output requests and token consumption. They provide rich, context-aware semantic data for scenarios such as Completion, Chat, Retrieval-Augmented Generation (RAG), Agent, and Tool Calling—enabling effective data tracing and reporting.

This semantic specification evolves with the community. If your application is a Python application, you must manually collect observable data. You can use the loongsuite-util-genai component to help integrate data collection. For details, see the README.

Span-level field definitions follow the OpenTelemetry open standard. For detailed descriptions of top-level trace fields stored in Alibaba Cloud Managed Service for OpenTelemetry, see Trace Analysis Parameter Definitions.

Note

The LLM-specific SpanKind is an Attribute—not the Span kind defined in the OpenTelemetry Trace specification. This semantic specification extends the OpenTelemetry GenAI Semantic Conventions. That specification is under active development and may change in future maintenance releases.

Common Section

Attributes

AttributeKey	Description	Type	Example Value	Requirement Level
`gen_ai.session.id`	Session ID	string	`ddde34343-f93a-4477-33333-sdfsdaf`	Required if available
`gen_ai.user.id`	End-user identifier	string	`u-lK8JddD`	Required if available
`gen_ai.span.kind`	Operation type [1]	string	`See LLM Span Kind`	Required
`gen_ai.operation.name`	Secondary operation type [2]	string	`See LLM Operation Name`	Required
`gen_ai.framework`	Framework type used	string	`langchain`;`llama_index`	Required if available

[1] gen_ai.span.kind: Maps to gen_ai.operation.name as follows:

`gen_ai.span.kind`	`gen_ai.operation.name`	Description
RETRIEVER	`retrieval`	Document retrieval
LLM	`chat`;`generate_content`;`text_completion`	Model invocation
EMBEDDING	`embeddings`	Embedding
TOOL	`execute_tool`	Tool calling
AGENT	`create_agent`;`invoke_agent`	Agent invocation
RERANKER	-	Reranking invocation
CHAIN	-	Chain (invocation unit)
TASK	-	Task invocation
ENTRY	-	Entry invocation marker
STEP	-	ReAct round marker

[2] gen_ai.operation.name: Secondary operation type. Use one of the following enumerations or define a custom value:

Value	Description
`chat`	Chat completion operation
`create_agent`	Create GenAI agent operation
`embeddings`	Word embedding operation
`execute_tool`	Tool calling operation
`generate_content`	Multimodal content generation operation
`invoke_agent`	Invoke GenAI agent operation
`retrieval`	Document retrieval operation
`text_completion`	Text completion operation

Resources

ResourceKey	Description	Type	Example Value	Requirement Level
`service.name`	Application name	string	`test-easy-rag`	Required
`acs.cms.workspace`	Cloud Monitor workspace	string	`arms-test`	Required if available
`acs.arms.service.id`	Cloud Monitor service ID	string	`ggxw4lnjuz@b63ba5a1d60b517ae374f`	Required if available
`ali.trace.source`	Application source	string	`mse-gateway`;`alb`	Required if available
`acs.arms.service.feature`	Application feature	string	`genai_app`	Required Note `acs.arms.service.feature` = genai_app. This value automatically identifies and tags the application as an AI application. It is required for LLM or Agent scenarios.

Chain

A Chain is a tool that connects LLMs and other components to perform complex tasks, such as Retrieval, Embedding, LLM invocations, and nested Chains.

Name the span chain {chain_name}. If chain_name cannot be obtained, name it chain.

Note

The OpenTelemetry community has not yet defined a semantic convention for this span type. Currently, Chain spans apply only to the LangChain framework.

Attributes

AttributeKey	Description	Type	Example	Requirement Level
`gen_ai.span.kind`	Operation type [1]	string	`CHAIN`	Required
`gen_ai.operation.name`	Secondary operation type	string	`workflow`; `task`	Required if available
`input.value`	Input content	string	`Who Are You!`	Recommended
`output.value`	Response content	string	`I am ChatBot`	Recommended
`gen_ai.user.time_to_first_token`	Time to First Byte [2]	integer	1000000	Recommended

[1] gen_ai.span.kind: Dedicated enumeration for LLM spanKind. In a Chain, this value must be CHAIN.

[2] gen_ai.user.time_to_first_token: Time from the server's receipt of the user request until the first response packet returns. Unit: nanoseconds.

Retriever

A Retriever accesses vector stores or databases to retrieve data. It typically supplements context to improve LLM response accuracy and efficiency.

Set gen_ai.operation.name to retrieval. When gen_ai.operation.name is retrieval, infer gen_ai.span.kind as RETRIEVER.

Name the span {gen_ai.operation.name} {gen_ai.data_source.id}. Other naming formats are acceptable in special cases.

Attributes

AttributeKey	Description	Type	Example	Requirement Level
`gen_ai.span.kind`	Operation type [1]	string	`RETRIEVER`	Required
`gen_ai.operation.name`	Secondary operation type [2]	string	`retrieval`	Required
`gen_ai.data_source.id`	Data source unique identifier [3]	string	`H7STPQYOND`	Required if available
`gen_ai.provider.name`	Large language model provider	string	`openai`	Required if available
`gen_ai.request.model`	Model name specified in the request	string	`gpt-4`	Required if available
`gen_ai.request.top_k`	Top-K value specified in the request	float	`1.0`	Recommended
`gen_ai.retrieval.documents`	Retrieved document list [4]	string	`[{"id": "doc_123","score": 0.95},{"id": "doc_456","score": 0.87},{"id": "doc_789","score": 0.82}]`	Optional
`gen_ai.retrieval.query.text`	Query text snippet	string	`what is the topic in xxx?`	Optional

[1] gen_ai.span.kind: Dedicated enumeration for LLM spanKind. In a Retriever, this value must be RETRIEVER.

[2] gen_ai.operation.name: Secondary operation type.

[3] gen_ai.data_source.id: Unique data source ID. This is the data source that AI Agents or RAG applications depend on. It can be an external database, Object Storage Service, document set, website, or other storage system.

[4] gen_ai.retrieval.documents: Records the retrieved document list. Each document object must contain at least these properties: id (string): Unique document identifier. score (double-precision floating-point number): Relevance score.

Reranker

The Reranker assesses the relevance of multiple input documents based on the query, sorts them, and may return the top-K documents as input to the LLM.

Name the span rerank {reranker.model_name}. If reranker.model_name cannot be retrieved, name it rerank.

Note

The OpenTelemetry community has not yet defined a semantic convention for this span type.

Attributes

AttributeKey	Description	Type	Example	Requirement Level
`gen_ai.span.kind`	Operation type [1]	string	`RERANKER`	Required
`reranker.query`	Reranker request parameter	string	`How to format timestamp?`	Optional
`reranker.model_name`	Model name used by the Reranker	string	`cross-encoder/ms-marco-MiniLM-L-12-v2`	Optional
`reranker.top_k`	Rank after reranking	integer	`3`	Optional
`reranker.input_document`	Output the document metadata[2]	string	`See example`	Required
`reranker.output_document`	Metadata for output documents [3]	string	`See example`	Required

[1] gen_ai.span.kind: Dedicated enumeration for LLM spanKind. In a Reranker, this value must be RERANKER.

[2] reranker.output_document: Input documents for reranking. JSON array structure. Metadata contains basic document information such as path, filename, and source.

[3] reranker.output_document: Output documents after reranking. JSON array structure. Metadata contains basic document information such as path, filename, and source.

LLM

An LLM span represents an LLM call or inference process. Examples include using an SDK or OpenAPI to invoke different LLMs for inference or text generation.

Set gen_ai.operation.name to one of chat, generate_content, or text_completion. When gen_ai.operation.name is chat, generate_content, or text_completion, infer gen_ai.span.kind as LLM.

Name the span {gen_ai.operation.name} {gen_ai.request.model}. Other naming formats are acceptable in special cases.

Attributes

AttributeKey	Description	Type	Example	Requirement Level
`gen_ai.span.kind`	Operation type [1]	string	`LLM`	Required
`gen_ai.operation.name`	Secondary operation type [2]	string	`chat`; `generate_content`; `text_completion`	Required
`gen_ai.provider.name`	Large language model provider	string	`openai`	Required
`gen_ai.conversation.id`	Unique conversation ID [3]	string	`conv_5j66UpCpwteGg4YSxUnt7lPY`	Required if available
`gen_ai.output.type`	Output type specified in the LLM request [4]	string	`text`;`json`;`image`;`audio`	Required if available
`gen_ai.request.choice.count`	Number of candidate generations requested in the LLM request	int	`3`	Required if not 1
`gen_ai.request.model`	Model name specified in the LLM request	string	`gpt-4`	Required
`gen_ai.request.seed`	Seed specified in the LLM request	string	`gpt-4`	Required if available
`gen_ai.request.frequency_penalty`	Frequency penalty set in the LLM request	float	`0.1`	Recommended
`gen_ai.request.max_tokens`	Maximum token count specified in the LLM request	integer	`100`	Recommended
`gen_ai.request.presence_penalty`	Presence penalty set in the LLM request	float	`0.1`	Recommended
`gen_ai.request.temperature`	Temperature specified in the LLM request	float	`0.1`	Recommended
`gen_ai.request.top_p`	Top-P value specified in the LLM request	float	`1.0`	Recommended
`gen_ai.request.top_k`	Top-K value specified in the LLM request	float	`1.0`	Recommended
`gen_ai.request.stop_sequences`	Stop sequences for the LLM	string[]	`["stop"]`	Recommended
`gen_ai.response.id`	Unique ID generated by the LLM	string	`gpt-4-0613`	Recommended
`gen_ai.response.model`	Model name used for LLM generation	string	`gpt-4-0613`	Recommended
`gen_ai.response.finish_reasons`	Reason the LLM stopped generating	string[]	`["stop"]`	Recommended
`gen_ai.response.time_to_first_token`	First-token latency for the LLM in streaming-response scenarios [5]	integer	`1000000`	Recommended
`gen_ai.response.reasoning_time`	Inference time for reasoning models [6]	integer	`1248`	Recommended
`gen_ai.usage.input_tokens`	Number of input tokens used	integer	`100`	Recommended
`gen_ai.usage.output_tokens`	Number of output tokens used	integer	`200`	Recommended
`gen_ai.usage.total_tokens`	Total number of tokens used	integer	`300`	Recommended
`gen_ai.usage.cache_creation.input_tokens`	Number of tokens written to the model provider's cache [7]	integer	`25`	Recommended
`gen_ai.usage.cache_read.input_tokens`	Number of tokens read from the model provider's cache [8]	integer	`50`	Recommended
`gen_ai.input.messages`	Model input content [9]	string	`[{"role": "user", "parts": [{"type": "text", "content": "Weather in Paris?"}]}, {"role": "assistant", "parts": [{"type": "tool_call", "id": "call_VSPygqKTWdrhaFErNvMV18Yl", "name":"get_weather", "arguments":{"location":"Paris"}}]}, {"role": "tool", "parts": [{"type": "tool_call_response", "id":" call_VSPygqKTWdrhaFErNvMV18Yl", "result":"rainy, 57°F"}]}]`	Optional
`gen_ai.output.messages`	Model output content [10]	string	`[{"role":"assistant","parts":[{"type":"text","content":"The weather in Paris is currently rainy with a temperature of 57°F."}],"finish_reason":"stop"}]`	Optional
`gen_ai.system_instructions`	System prompt content [11]	string	`[{"type": "text", "content": "You are a helpful assistant"}]`	Optional
`gen_ai.tool.definitions`	Tool definition list [12]	string	`[{"type":"function","name":"get_current_weather","description": "Get the current weather in a given location","parameters":{"type":"object","properties":{"location":{"type":"string","description":"The city and state, e.g. San Francisco, CA"},"unit": {"type":"string","enum":["celsius","fahrenheit"]}},"required":["location","unit"]}}]`	Optional
`gen_ai.latency.time_in_model_prefill`	LLM prefill latency. Unit: nanoseconds	integer	`1000`	Recommended
`gen_ai.latency.time_in_model_decode`	LLM decode latency. Unit: nanoseconds	integer	`1000`	Recommended
`gen_ai.latency.time_in_model_inference`	LLM inference time. Equals the sum of prefill and decode time. Unit: nanoseconds	integer	`1000`	Recommended
`gen_ai.input.multimodal_metadata`	Multi-modal data involved in the LLM input content [13]	string[]	`[{"type":"uri","mime_type":"image/jpeg","uri":"sls://project/logstore/date/object","modality":"image"}]`	Recommended
`gen_ai.output.multimodal_metadata`	Multi-modal data involved in the LLM output content [14]	string[]	`[{"type":"uri","mime_type":"image/jpeg","uri":"sls://project/logstore/date/object","modality":"image"}]`	Recommended

[1] gen_ai.span.kind: Dedicated enumeration for LLM spanKind. In an LLM span, this value must be LLM.

[2] gen_ai.operation.name: Secondary operation type.

[3] gen_ai.conversation.id: Unique conversation ID. Collect this if you can easily obtain it.

[4] gen_ai.output.type: Collect this if the request specifies an output type (such as an output format). Values must be one of the following enumerations or a custom value:

Value	Description
`image`	Image
`json`	Well-formatted JSON object
`speech`	Voice
`text`	Plain text

[5] gen_ai.user.time_to_first_token: Time from the server's receipt of the user request until the first response packet returns. Unit: nanoseconds.

[6] gen_ai.response.reasoning_time: Duration of the reasoning process. Unit: milliseconds.

[7] gen_ai.usage.cache_creation.input_tokens: This value must already be included in gen_ai.usage.input_tokens.

[8] gen_ai.usage.cache_read.input_tokens: This value must already be included in gen_ai.usage.input_tokens.

[9] gen_ai.input.messages: Records the input content for the LLM call. Messages must be provided in the order sent to the model or agent. Follow gen_ai.input.messages.json.

Collect only when the OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT flag is enabled. This flag is enabled by default.

[10] gen_ai.output.messages: Records the model's output content. Messages must be provided in the order sent to the model or agent. Follow gen_ai.output.messages.json.

Collect only when the OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT flag is enabled. This flag is enabled by default.

[11] gen_ai.system_instructions: Records system prompt or instruction content separately. Use this field if you can obtain the system prompt or instruction content independently. Otherwise, record it in the gen_ai.input.messages attribute. Follow gen_ai.system_instructions.json.

Collect only when the OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT flag is enabled. This flag is enabled by default.

[12] gen_ai.tool.definitions: Records tool definitions passed to the LLM. This attribute may be very large. By default, collect only the type and name fields. Collect all other fields only when the OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT flag is enabled. This flag is enabled by default.

[13] gen_ai.input.multimodal_metadata: Aggregates multi-modal data referenced in the model's input content. Only includes UriPart messages. Follow gen_ai.input.messages.json.

Collect only when the OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT flag is enabled. This flag is enabled by default.

[14] gen_ai.output.multimodal_metadata: Aggregates multi-modal data referenced in the model's output content. Only includes UriPart messages. Follow gen_ai.output.messages.json.

Collect only when the OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT flag is enabled. This flag is enabled by default.

Record Prompts, Inputs, and Outputs

You can omit recording user inputs and model responses, record them in the span's attributes, or record them as events (logs). For details, see Control LLM Application Conversation History Collection Behavior.

Embedding

An embedding represents a single process, such as embedding text with a Large Language Model (LLM). You can then use similarity queries to optimize solutions to problems.

Set gen_ai.operation.name to embeddings. When gen_ai.operation.name is embeddings, infer gen_ai.span.kind as EMBEDDING.

Name the span {gen_ai.operation.name} {gen_ai.request.model}. Other naming formats are acceptable in special cases.

Attributes

AttributeKey	Description	Type	Example	Requirement Level
`gen_ai.span.kind`	Operation type [1]	string	`EMBEDDING`	Required
`gen_ai.operation.name`	Secondary operation type [2]	string	`embeddings`	Required
`gen_ai.provider.name`	Large language model provider	string	`openai`	Required
`gen_ai.request.model`	Model name specified in the request	string	`gpt-4`	Required if available
`gen_ai.embeddings.dimension.count`	Number of dimensions expected for the embedding operation	integer	`1024`	Recommended
`gen_ai.request.encoding_formats`	Encoding formats requested for the embedding operation	string[]	`["base64"]`; `["float", "binary"]`	Recommended
`gen_ai.usage.input_tokens`	Token count consumed by the input text	integer	`10`	Optional
`gen_ai.usage.total_tokens`	Total token count consumed by the embedding	integer	`10`	Optional

[1] gen_ai.span.kind: Dedicated enumeration for LLM spanKind. In an Embedding span, this value must be EMBEDDING.

[2] gen_ai.operation.name: Secondary operation type.

Tool

Tool spans represent calls to external tools. Examples include calling a calculator or requesting the latest weather from a weather API.

Set gen_ai.operation.name to execute_tool. When gen_ai.operation.name is execute_tool, infer gen_ai.span.kind as TOOL.

Name the span {gen_ai.operation.name} {gen_ai.tool.name}. Other naming formats are acceptable in special cases.

Attributes

AttributeKey	Description	Type	Example	Requirement Level
`gen_ai.span.kind`	Operation type [1]	string	`TOOL`	Required
`gen_ai.operation.name`	Secondary operation type [2]	string	`execute_tool`	Required
`gen_ai.tool.call.id`	Tool ID	string	`call_mszuSIzqtI65i1wAUOE8w5H4`	Recommended
`gen_ai.tool.description`	Tool description	string	`Multiply two numbers`	Recommended
`gen_ai.tool.name`	Tool name	string	Recommended
`gen_ai.tool.type`	Tool type	string	`function`;`extension`;`datastore`	Recommended
`gen_ai.tool.call.arguments`	Tool call input parameters [2]	string	`{"location": "San Francisco?","date": "2025-10-01"}`	Optional
`gen_ai.tool.call.result`	Tool call return value [3]	string	`{"temperature_range": {"high": 75,"low": 60},"conditions": "sunny"}`	Optional

[1] gen_ai.span.kind: Dedicated enumeration for LLM spanKind. In a Tool span, this value must be TOOL.

[2] gen_ai.tool.call.arguments: Tool call input parameters, as a JSON string. Collect only when the OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT flag is enabled. This flag is enabled by default.

[3] gen_ai.tool.call.result: Tool call return value, as a JSON string. Collect only when the OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT flag is enabled. This flag is enabled by default.

Agent

An Agent span represents an intelligent agent scenario—a more complex Chain. The agent uses LLM inference results to decide the next step. This may involve multiple LLM and Tool calls, progressing step-by-step to reach a final answer.

Set gen_ai.operation.name to invoke_agent or create_agent. When gen_ai.operation.name is invoke_agent or create_agent, infer gen_ai.span.kind as AGENT.

Name the span {gen_ai.operation.name} {gen_ai.agent.name}. Other naming formats are acceptable in special cases.

Attributes

AttributeKey	Description	Type	Example	Requirement Level
`gen_ai.span.kind`	Operation type [1]	string	`AGENT`	Required
`gen_ai.operation.name`	Secondary operation type [2]	string	`invoke_agent`; `create_agent`	Required
`gen_ai.conversation.id`	Unique conversation ID [3]	string	`conv_5j66UpCpwteGg4YSxUnt7lPY`	Required if available
`gen_ai.agent.description`	Agent description	string	`Helps with math problems`; `Generates fiction stories`	Required if available
`gen_ai.agent.id`	Unique agent identifier	string	`asst_5j66UpCpwteGg4YSxUnt7lPY`	Required if available
`gen_ai.agent.name`	Agent name	string	`Math Tutor`; `Fiction Writer`	Required if available
`gen_ai.data_source.id`	Data source unique identifier [4]	string	`H7STPQYOND`	Required if available
`gen_ai.usage.input_tokens`	Number of input tokens used	integer	`100`	Recommended
`gen_ai.usage.output_tokens`	Number of output tokens used	integer	`200`	Recommended
`gen_ai.usage.total_tokens`	Total number of tokens used	integer	`300`	Recommended
`gen_ai.usage.cache_creation.input_tokens`	Number of tokens written to the model provider's cache [5]	integer	`25`	Recommended
`gen_ai.usage.cache_read.input_tokens`	Number of tokens read from the model provider's cache [6]	integer	`50`	Recommended
`gen_ai.input.messages`	Model input content [7]	string	`[{"role": "user", "parts": [{"type": "text", "content": "Weather in Paris?"}]}, {"role": "assistant", "parts": [{"type": "tool_call", "id": "call_VSPygqKTWdrhaFErNvMV18Yl", "name":"get_weather", "arguments":{"location":"Paris"}}]}, {"role": "tool", "parts": [{"type": "tool_call_response", "id":" call_VSPygqKTWdrhaFErNvMV18Yl", "result":"rainy, 57°F"}]}]`	Optional
`gen_ai.output.messages`	Model output content [8]	string	`[{"role":"assistant","parts":[{"type":"text","content":"The weather in Paris is currently rainy with a temperature of 57°F."}],"finish_reason":"stop"}]`	Optional
`gen_ai.system_instructions`	System prompt content [9]	string	`[{"type": "text", "content": "You are a helpful assistant"}]`	Optional
`gen_ai.tool.definitions`	Tool definition list [10]	string	`[{"type":"function","name":"get_current_weather","description": "Get the current weather in a given location","parameters":{"type":"object","properties":{"location":{"type":"string","description":"The city and state, e.g. San Francisco, CA"},"unit": {"type":"string","enum":["celsius","fahrenheit"]}},"required":["location","unit"]}}]`	Optional
`gen_ai.response.time_to_first_token`	Agent's first-token response latency	integer	`1000000`	Recommended

[1] gen_ai.span.kind: Dedicated enumeration for LLM spanKind. In an Agent span, this value must be AGENT.

[2] gen_ai.operation.name: Secondary operation type.

[3] gen_ai.conversation.id: Unique conversation ID. Collect this if you can easily obtain it.

[4] gen_ai.data_source.id: Unique data source ID. This is the data source that AI Agents or RAG applications depend on. It can be an external database, Object Storage Service, document set, website, or other storage system.

[5] gen_ai.usage.cache_creation.input_tokens: This value must already be included in gen_ai.usage.input_tokens.

[6] gen_ai.usage.cache_read.input_tokens: This value must already be included in gen_ai.usage.input_tokens.

[7] gen_ai.input.messages: Records the input content for the LLM call. Messages must be provided in the order sent to the model or agent. Follow gen_ai.input.messages.json.

Collect only when the OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT flag is enabled. This flag is enabled by default.

[8] gen_ai.output.messages: Records the model's output content. Messages must be provided in the order sent to the model or agent. Follow gen_ai.output.messages.json.

Collect only when the OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT flag is enabled. This flag is enabled by default.

[9] gen_ai.system_instructions: Records system prompt or instruction content separately. Use this field if you can obtain the system prompt or instruction content independently. Otherwise, record it in the gen_ai.input.messages attribute. Follow gen_ai.system_instructions.json.

Collect only when the OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT flag is enabled. This flag is enabled by default.

[10] gen_ai.tool.definitions: Records tool definitions passed to the LLM. This attribute may be very large. By default, collect only the type and name fields. Collect all other fields only when the OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT flag is enabled. This flag is enabled by default.

Task

A Task span represents a custom internal method call, such as invoking a local function or other application-defined logic.

Name the span run_task {gen_ai.task.name}. Other naming formats are acceptable in special cases.

Note

The OpenTelemetry community has not yet defined a semantic convention for this span type. Therefore, gen_ai.operation.name may change.

Attributes

AttributeKey	Description	Type	Example	Requirement Level
`gen_ai.span.kind`	Operation type [1]	string	`TASK`	Required
`gen_ai.operation.name`	Secondary operation type	string	`run_task`	Required
`input.value`	Input parameters	string	`Input parameters, custom JSON format`	Optional
`input.mime_type`	Input MIME type	string	`text/plain`; `application/json`	Optional
`output.mime_type`	Output MIME type	string	`text/plain`; `application/json`	Optional

[1] gen_ai.span.kind: Dedicated enumeration for LLM spanKind. In a Task span, this value must be TASK.

Entry

An Entry span marks the entry point for a call to an AI application system.

Name the span enter_ai_application_system. Other naming formats are acceptable in special cases.

Note

The OpenTelemetry community has not yet defined a semantic convention for this span type. Therefore, gen_ai.operation.name may change.

Attributes

AttributeKey	Description	Type	Example	Requirement Level
`gen_ai.span.kind`	Operation type [1]	string	`ENTRY`	Required
`gen_ai.operation.name`	Secondary operation type	string	`enter`	Recommended
`gen_ai.session.id`	Session ID	string	`ddde34343-f93a-4477-33333-sdfsdaf`	Required if available
`gen_ai.user.id`	End-user identifier	string	`u-lK8JddD`	Required if available
`gen_ai.input.messages`	Model input content [2]	string	`[{"role": "user", "parts": [{"type": "text", "content": "Weather in Paris?"}]}, {"role": "assistant", "parts": [{"type": "tool_call", "id": "call_VSPygqKTWdrhaFErNvMV18Yl", "name":"get_weather", "arguments":{"location":"Paris"}}]}, {"role": "tool", "parts": [{"type": "tool_call_response", "id":" call_VSPygqKTWdrhaFErNvMV18Yl", "result":"rainy, 57°F"}]}]`	Optional
`gen_ai.output.messages`	Model output content [3]	string	`[{"role":"assistant","parts":[{"type":"text","content":"The weather in Paris is currently rainy with a temperature of 57°F."}],"finish_reason":"stop"}]`	Optional
`gen_ai.response.time_to_first_token`	First-token response latency in streaming-response scenarios [4]	integer	`1000000`	Recommended

[1] gen_ai.span.kind: Dedicated enumeration for LLM spanKind. In an Entry span, this value must be ENTRY.

[2] gen_ai.input.messages: Records the input content for the LLM call. Messages must be provided in the order sent to the model or agent. Follow gen_ai.input.messages.json.

Collect only when the OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT flag is enabled. This flag is enabled by default.

[3] gen_ai.output.messages: Records the model's output content. Messages must be provided in the order sent to the model or agent. Follow gen_ai.output.messages.json.

Collect only when the OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT flag is enabled. This flag is enabled by default.

[4] gen_ai.response.time_to_first_token: Time from the server's receipt of the user request until the first response packet returns. Unit: nanoseconds.

ReAct Step

A Step span marks a Reasoning-Acting iteration process within an Agent.

Name the span react step. Other naming formats are acceptable in special cases.

Note

The OpenTelemetry community has not yet defined a semantic convention for this span type. Therefore, gen_ai.operation.name may change.

Attributes

AttributeKey	Description	Type	Example	Requirement Level
`gen_ai.span.kind`	Operation type [1]	string	`STEP`	Required
`gen_ai.operation.name`	Secondary operation type	string	`react`	Recommended
`gen_ai.react.finish_reason`	Reason for this ReAct round's termination	string	`error`	Recommended
`gen_ai.react.round`	Round number for this ReAct iteration [2]	integer	`1`	Recommended

[1] gen_ai.span.kind: Dedicated enumeration for LLM spanKind. In a ReAct Step span, this value must be STEP.

[2] gen_ai.react.round: ReAct round numbers should start from 1 and increment by 1 for each iteration.