LLM trace fields - Application Real-Time Monitoring Service: Central de Documentação do Alibaba Cloud

As definições de campos no nível de span seguem os padrões abertos do OpenTelemetry. Para descrições detalhadas dos campos de rastreamento de nível superior armazenados no Managed Service for OpenTelemetry da Alibaba Cloud, consulte Trace Explorer parameters.

Nota

O SpanKind específico para LLM é um atributo, e não o span kind definido na especificação de rastreamento do OpenTelemetry. Esta especificação semântica estende as Convenções Semânticas de GenAI do OpenTelemetry. Essa especificação está em desenvolvimento ativo e pode sofrer alterações em futuras versões de manutenção.

Seção comum

Atributos

Chave do atributo	Descrição	Tipo	Valor de exemplo	Nível de obrigatoriedade
`gen_ai.session.id`	ID da sessão	string	`ddde34343-f93a-4477-33333-sdfsdaf`	Obrigatório se disponível
`gen_ai.user.id`	Identificador do usuário final	string	`u-lK8JddD`	Obrigatório se disponível
`gen_ai.span.kind`	Tipo de operação [1]	string	`Ver LLM Span Kind`	Obrigatório
`gen_ai.operation.name`	Tipo secundário de operação [2]	string	`Ver LLM Operation Name`	Obrigatório
`gen_ai.framework`	Tipo de framework utilizado	string	`langchain`;`llama_index`	Obrigatório se disponível

[1] gen_ai.span.kind: Mapeia para gen_ai.operation.name da seguinte forma:

gen_ai.span.kind	gen_ai.operation.name	Descrição
RETRIEVER	`retrieval`	Recuperação de documentos
LLM	`chat`;`generate_content`;`text_completion`	Invocação de modelo
EMBEDDING	`embeddings`	Embedding
TOOL	`execute_tool`	Chamada de ferramenta
AGENT	`create_agent`;`invoke_agent`	Invocação de agente
RERANKER	-	Invocação de reranking
CHAIN	-	Cadeia (unidade de invocação)
TASK	-	Invocação de tarefa
ENTRY	-	Marcador de invocação de entrada
STEP	-	Marcador de rodada ReAct

[2] gen_ai.operation.name: Tipo secundário de operação. Use uma das enumerações abaixo ou defina um valor personalizado:

Valor	Descrição
`chat`	Operação de conclusão de chat
`create_agent`	Operação de criação de agente GenAI
`embeddings`	Operação de embedding de palavras
`execute_tool`	Operação de chamada de ferramenta
`generate_content`	Operação de geração de conteúdo multimodal
`invoke_agent`	Operação de invocação de agente GenAI
`retrieval`	Operação de recuperação de documentos
`text_completion`	Operação de conclusão de texto

Recursos

Chave do recurso	Descrição	Tipo	Valor de exemplo	Nível de obrigatoriedade
`service.name`	Nome da aplicação	string	`test-easy-rag`	Obrigatório
`acs.cms.workspace`	Workspace do Cloud Monitor	string	`arms-test`	Obrigatório se disponível
`acs.arms.service.id`	ID do service Cloud Monitor	string	`ggxw4lnjuz@b63ba5a1d60b517ae374f`	Obrigatório se disponível
`ali.trace.source`	source da aplicação	string	`mse-gateway`;`alb`	Obrigatório se disponível
`acs.arms.service.feature`	Recurso da aplicação	string	`genai_app`	Obrigatório Nota `acs.arms.service.feature` = genai_app. Este valor identifica e marca automaticamente a aplicação como uma aplicação de IA. É obrigatório para cenários de LLM ou Agent.

Chain

Uma Chain é uma ferramenta que conecta LLMs e outros componentes para executar tarefas complexas, como Recuperação, Embedding, invocações de LLM e Chains aninhadas.

Nomeie o span como chain {chain_name}. Caso não seja possível obter o chain_name, utilize o nome chain.

Nota

A comunidade OpenTelemetry ainda não definiu uma convenção semântica para este tipo de span. Atualmente, os spans de Chain aplicam-se apenas ao framework LangChain.

Atributos

Chave do atributo	Descrição	Tipo	Exemplo	Nível de obrigatoriedade
`gen_ai.span.kind`	Tipo de operação [1]	string	`CHAIN`	Obrigatório
`gen_ai.operation.name`	Tipo secundário de operação	string	`workflow`; `task`	Obrigatório se disponível
`input.value`	Conteúdo de entrada	string	`Who Are You!`	Recomendado
`output.value`	Conteúdo da resposta	string	`I am ChatBot`	Recomendado
`gen_ai.user.time_to_first_token`	Tempo até o primeiro token [2]	integer	1000000	Recomendado

[1] gen_ai.span.kind: Enumeração dedicada para spanKind de LLM. Em uma Chain, este valor deve ser CHAIN.

[2] gen_ai.user.time_to_first_token: Tempo decorrido entre o recebimento da solicitação do usuário pelo servidor e o retorno do primeiro pacote de resposta. Unidade: nanossegundos.

Retriever

Um Retriever acessa bancos de dados vetoriais ou bases de dados para recuperar informações. Geralmente, complementa o contexto para melhorar a precisão e a eficiência das respostas do LLM.

Defina gen_ai.operation.name como retrieval. Quando gen_ai.operation.name for retrieval, deduza gen_ai.span.kind como RETRIEVER.

Nomeie o span como {gen_ai.operation.name} {gen_ai.data_source.id}. Outros formatos de nomenclatura são aceitáveis em casos especiais.

Atributos

Chave do atributo	Descrição	Tipo	Exemplo	Nível de obrigatoriedade
`gen_ai.span.kind`	Tipo de operação [1]	string	`RETRIEVER`	Obrigatório
`gen_ai.operation.name`	Tipo secundário de operação [2]	string	`retrieval`	Obrigatório
`gen_ai.data_source.id`	Identificador único da fonte de dados [3]	string	`H7STPQYOND`	Obrigatório se disponível
`gen_ai.provider.name`	Provedor do LLM	string	`openai`	Obrigatório se disponível
`gen_ai.request.model`	Nome do modelo especificado na solicitação	string	`gpt-4`	Obrigatório se disponível
`gen_ai.request.top_k`	Valor Top-K especificado na solicitação	float	`1.0`	Recomendado
`gen_ai.retrieval.documents`	Lista de documentos recuperados [4]	string	`[{"id": "doc_123","score": 0.95},{"id": "doc_456","score": 0.87},{"id": "doc_789","score": 0.82}]`	Opcional
`gen_ai.retrieval.query.text`	Trecho de texto da consulta	string	`what is the topic in xxx?`	Opcional

[1] gen_ai.span.kind: Enumeração dedicada para spanKind de LLM. Em um Retriever, este valor deve ser RETRIEVER.

[2] gen_ai.operation.name: Tipo secundário de operação.

[3] gen_ai.data_source.id: ID único da fonte de dados. Refere-se à fonte de dados da qual AI Agents ou aplicações RAG dependem. Pode ser um banco de dados externo, Object Storage Service, conjunto de documentos, site ou outro sistema de armazenamento.

[4] gen_ai.retrieval.documents: Registra a lista de documentos recuperados. Cada objeto de documento deve conter pelo menos estas propriedades: id (string): Identificador único do documento. score (número de ponto flutuante de precisão dupla): Pontuação de relevância.

Reranker

O Reranker avalia a relevância de múltiplos documentos de entrada com base na consulta, ordena-os e pode retornar os documentos Top-K como entrada para o LLM.

Nomeie o span como rerank {reranker.model_name}. Se não for possível obter reranker.model_name, utilize o nome rerank.

Nota

A comunidade OpenTelemetry ainda não definiu uma convenção semântica para este tipo de span.

Atributos

Chave do atributo	Descrição	Tipo	Exemplo	Nível de obrigatoriedade
`gen_ai.span.kind`	Tipo de operação [1]	string	`RERANKER`	Obrigatório
`reranker.query`	Parâmetro de solicitação do Reranker	string	`How to format timestamp?`	Opcional
`reranker.model_name`	Nome do modelo usado pelo Reranker	string	`cross-encoder/ms-marco-MiniLM-L-12-v2`	Opcional
`reranker.top_k`	Classificação após o reranking	integer	`3`	Opcional
`reranker.input_document`	Metadados dos documentos de entrada [2]	string	`Ver exemplo`	Obrigatório
`reranker.output_document`	Metadados dos documentos de saída [3]	string	`Ver exemplo`	Obrigatório

[1] gen_ai.span.kind: Enumeração dedicada para spanKind de LLM. Em um Reranker, este valor deve ser RERANKER.

[2] reranker.output_document: Documentos de entrada para reranking. Estrutura de array JSON. Os metadados contêm informações básicas do documento, como caminho, nome do arquivo e origem.

[3] reranker.output_document: Documentos de saída após o reranking. Estrutura de array JSON. Os metadados contêm informações básicas do documento, como caminho, nome do arquivo e origem.

LLM

Um span de LLM representa uma chamada ou processo de inferência de LLM. Exemplos incluem o uso de um SDK ou OpenAPI para invocar diferentes LLMs para inferência ou geração de texto.

Defina gen_ai.operation.name como chat, generate_content ou text_completion. Quando gen_ai.operation.name for chat, generate_content ou text_completion, deduza gen_ai.span.kind como LLM.

Nomeie o span como {gen_ai.operation.name} {gen_ai.request.model}. Outros formatos de nomenclatura são aceitáveis em casos especiais.

Atributos

Chave do atributo	Descrição	Tipo	Exemplo	Nível de obrigatoriedade
`gen_ai.span.kind`	Tipo de operação [1]	string	`LLM`	Obrigatório
`gen_ai.operation.name`	Tipo secundário de operação [2]	string	`chat`; `generate_content`; `text_completion`	Obrigatório
`gen_ai.provider.name`	Provedor do LLM	string	`openai`	Obrigatório
`gen_ai.conversation.id`	ID único da conversa [3]	string	`conv_5j66UpCpwteGg4YSxUnt7lPY`	Obrigatório se disponível
`gen_ai.output.type`	Tipo de saída especificado na solicitação do LLM [4]	string	`text`;`json`;`image`;`audio`	Obrigatório se disponível
`gen_ai.request.choice.count`	Número de gerações candidatas solicitadas na requisição do LLM	int	`3`	Obrigatório se diferente de 1
`gen_ai.request.model`	Nome do modelo especificado na solicitação do LLM	string	`gpt-4`	Obrigatório
`gen_ai.request.seed`	Seed especificada na solicitação do LLM	string	`gpt-4`	Obrigatório se disponível
`gen_ai.request.frequency_penalty`	Penalidade de frequência definida na solicitação do LLM	float	`0.1`	Recomendado
`gen_ai.request.max_tokens`	Contagem máxima de tokens especificada na solicitação do LLM	integer	`100`	Recomendado
`gen_ai.request.presence_penalty`	Penalidade de presença definida na solicitação do LLM	float	`0.1`	Recomendado
`gen_ai.request.temperature`	Temperatura especificada na solicitação do LLM	float	`0.1`	Recomendado
`gen_ai.request.top_p`	Valor Top-P especificado na solicitação do LLM	float	`1.0`	Recomendado
`gen_ai.request.top_k`	Valor Top-K especificado na solicitação do LLM	float	`1.0`	Recomendado
`gen_ai.request.stop_sequences`	Sequências de parada para o LLM	string[]	`["stop"]`	Recomendado
`gen_ai.response.id`	ID único gerado pelo LLM	string	`chatcmpl-9J3uIL87gldCFtiIbyaOvTeYBRA3l`	Recomendado
`gen_ai.response.model`	Nome do modelo usado para geração do LLM	string	`gpt-4-0613`	Recomendado
`gen_ai.response.finish_reasons`	Motivo pelo qual o LLM parou a geração	string[]	`["stop"]`	Recomendado
`gen_ai.response.time_to_first_token`	Latência do primeiro token para o LLM em cenários de resposta em streaming [5]	integer	`1000000`	Recomendado
`gen_ai.response.reasoning_time`	Tempo de inferência para modelos de raciocínio [6]	integer	`1248`	Recomendado
`gen_ai.usage.input_tokens`	Número de tokens de entrada utilizados	integer	`100`	Recomendado
`gen_ai.usage.output_tokens`	Número de tokens de saída utilizados	integer	`200`	Recomendado
`gen_ai.usage.total_tokens`	Número total de tokens utilizados	integer	`300`	Recomendado
`gen_ai.usage.cache_creation.input_tokens`	Número de tokens gravados no cache do provedor do modelo [7]	integer	`25`	Recomendado
`gen_ai.usage.cache_read.input_tokens`	Número de tokens lidos do cache do provedor do modelo [8]	integer	`50`	Recomendado
`gen_ai.input.messages`	Conteúdo de entrada do modelo [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"}]}]`	Opcional
`gen_ai.output.messages`	Conteúdo de saída do modelo [10]	string	`[ { "role": "assistant", "parts": [ { "content": "Split into A(3), B(3), C(2). Weigh A vs B, then narrow down to the heavy group and weigh again.", "type": "reasoning" }, { "content": "Split into A(3), B(3), C(2).\n- Weigh 1: A vs B → heavier side contains it; if balanced, it's in C\n- Weigh 2: From the 3-ball group, weigh 1 vs 1 → heavier wins; if balanced, it's the 3rd. From C, weigh 1 vs 1 directly.", "type": "text" } ], "finish_reason": "end_turn" }]`	Opcional
`gen_ai.system_instructions`	Conteúdo do prompt do sistema [11]	string	`[{"type": "text", "content": "You are a helpful assistant"}]`	Opcional
`gen_ai.tool.definitions`	Lista de definições de ferramentas [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"]}}]`	Opcional
`gen_ai.latency.time_in_model_prefill`	Latência de prefill do LLM. Unidade: nanossegundos	integer	`1000`	Recomendado
`gen_ai.latency.time_in_model_decode`	Latência de decode do LLM. Unidade: nanossegundos	integer	`1000`	Recomendado
`gen_ai.latency.time_in_model_inference`	Tempo de inferência do LLM. Equivale à soma dos tempos de prefill e decode. Unidade: nanossegundos	integer	`1000`	Recomendado
`gen_ai.input.multimodal_metadata`	Dados multimodais envolvidos no conteúdo de entrada do LLM [13]	string[]	`[{"type":"uri","mime_type":"image/jpeg","uri":"sls://project/logstore/date/object","modality":"image"}]`	Recomendado
`gen_ai.output.multimodal_metadata`	Dados multimodais envolvidos no conteúdo de saída do LLM [14]	string[]	`[{"type":"uri","mime_type":"image/jpeg","uri":"sls://project/logstore/date/object","modality":"image"}]`	Recomendado

[1] gen_ai.span.kind: Enumeração dedicada para spanKind de LLM. Em um span de LLM, este valor deve ser LLM.

[2] gen_ai.operation.name: Tipo secundário de operação.

[3] gen_ai.conversation.id: ID único da conversa. Colete este dado se puder obtê-lo facilmente.

[4] gen_ai.output.type: Colete este dado se a solicitação especificar um tipo de saída (como um formato de saída). Os valores devem ser uma das seguintes enumerações ou um valor personalizado:

Valor	Descrição
`image`	Imagem
`json`	Objeto JSON bem formatado
`speech`	Voz
`text`	Texto simples

[5] gen_ai.user.time_to_first_token: Tempo decorrido entre o recebimento da solicitação do usuário pelo servidor e o retorno do primeiro pacote de resposta. Unidade: nanossegundos.

[6] gen_ai.response.reasoning_time: Duração do processo de raciocínio. Unidade: milissegundos.

[7] gen_ai.usage.cache_creation.input_tokens: Este valor já deve estar incluído em gen_ai.usage.input_tokens.

[8] gen_ai.usage.cache_read.input_tokens: Este valor já deve estar incluído em gen_ai.usage.input_tokens.

[9] gen_ai.input.messages: Registra o conteúdo de entrada para a chamada do LLM. As mensagens devem ser fornecidas na ordem em que foram enviadas ao modelo ou agente. Siga gen_ai.input.messages.json.

Colete apenas quando o sinalizador OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT estiver ativado. Este sinalizador vem ativado por padrão.

[10] gen_ai.output.messages: Registra o conteúdo de saída do modelo. As mensagens devem ser fornecidas na ordem em que foram enviadas ao modelo ou agente. Siga gen_ai.output.messages.json.

Colete apenas quando o sinalizador OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT estiver ativado. Este sinalizador vem ativado por padrão.

[11] gen_ai.system_instructions: Registra separadamente o conteúdo do prompt ou instrução do sistema. Use este campo se conseguir obter o prompt do sistema ou o conteúdo da instrução de forma independente. Caso contrário, registre-o no atributo gen_ai.input.messages. Siga gen_ai.system_instructions.json.

Colete apenas quando o sinalizador OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT estiver ativado. Este sinalizador vem ativado por padrão.

[12] gen_ai.tool.definitions: Registra as definições de ferramentas passadas ao LLM. Este atributo pode ser muito extenso. Por padrão, colete apenas os campos type e name. Colete todos os outros campos somente quando o sinalizador OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT estiver ativado. Este sinalizador vem ativado por padrão.

[13] gen_ai.input.multimodal_metadata: Agrega dados multimodais referenciados no conteúdo de entrada do modelo. Inclui apenas mensagens UriPart. Siga gen_ai.input.messages.json.

Colete apenas quando o sinalizador OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT estiver ativado. Este sinalizador vem ativado por padrão.

[14] gen_ai.output.multimodal_metadata: Agrega dados multimodais referenciados no conteúdo de saída do modelo. Inclui apenas mensagens UriPart. Siga gen_ai.output.messages.json.

Colete apenas quando o sinalizador OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT estiver ativado. Este sinalizador vem ativado por padrão.

Registrar prompts, entradas e saídas

É possível omitir o registro de entradas do usuário e respostas do modelo, registrá-las nos atributos do span ou como eventos (logs). Para mais detalhes, consulte Control LLM Application Conversation History Collection Behavior.

Embedding

Um embedding representa um processo único, como a vetorização de texto com um LLM. Posteriormente, consultas de similaridade podem otimizar a solução de problemas.

Defina gen_ai.operation.name como embeddings. Quando gen_ai.operation.name for embeddings, deduza gen_ai.span.kind como EMBEDDING.

Nomeie o span como {gen_ai.operation.name} {gen_ai.request.model}. Outros formatos de nomenclatura são aceitáveis em casos especiais.

Atributos

Chave do atributo	Descrição	Tipo	Exemplo	Nível de obrigatoriedade
`gen_ai.span.kind`	Tipo de operação [1]	string	`EMBEDDING`	Obrigatório
`gen_ai.operation.name`	Tipo secundário de operação [2]	string	`embeddings`	Obrigatório
`gen_ai.provider.name`	Provedor do LLM	string	`openai`	Obrigatório
`gen_ai.request.model`	Nome do modelo especificado na solicitação	string	`gpt-4`	Obrigatório se disponível
`gen_ai.embeddings.dimension.count`	Número de dimensões esperado para a operação de embedding	integer	`1024`	Recomendado
`gen_ai.request.encoding_formats`	Formatos de codificação solicitados para a operação de embedding	string[]	`["base64"]`; `["float", "binary"]`	Recomendado
`gen_ai.usage.input_tokens`	Contagem de tokens consumidos pelo texto de entrada	integer	`10`	Opcional
`gen_ai.usage.total_tokens`	Contagem total de tokens consumidos pelo embedding	integer	`10`	Opcional

[1] gen_ai.span.kind: Enumeração dedicada para spanKind de LLM. Em um span de Embedding, este valor deve ser EMBEDDING.

[2] gen_ai.operation.name: Tipo secundário de operação.

Tool

Spans de Tool representam chamadas a ferramentas externas. Exemplos incluem chamar uma calculadora ou solicitar a previsão do tempo mais recente de uma API meteorológica.

Defina gen_ai.operation.name como execute_tool. Quando gen_ai.operation.name for execute_tool, deduza gen_ai.span.kind como TOOL.

Nomeie o span como {gen_ai.operation.name} {gen_ai.tool.name}. Outros formatos de nomenclatura são aceitáveis em casos especiais.

Se a execução de uma ferramenta carregar uma skill, defina os campos relevantes gen_ai.skill.*. Cenários comuns incluem chamadas de ferramentas como load_skill, read_skill ou operações similares.

Atributos

Chave do atributo	Descrição	Tipo	Exemplo	Nível de obrigatoriedade
`gen_ai.span.kind`	Tipo de operação [1]	string	`TOOL`	Obrigatório
`gen_ai.operation.name`	Tipo secundário de operação [2]	string	`execute_tool`	Obrigatório
`gen_ai.tool.call.id`	ID da ferramenta	string	`call_mszuSIzqtI65i1wAUOE8w5H4`	Recomendado
`gen_ai.tool.description`	Descrição da ferramenta	string	`Multiply two numbers`	Recomendado
`gen_ai.tool.name`	Nome da ferramenta	string	Recomendado
`gen_ai.tool.type`	Tipo da ferramenta	string	`function`;`extension`;`datastore`	Recomendado
`gen_ai.skill.id`	Identificador único da skill GenAI.	string	`skill_29bbe8a7`	Obrigatório ao carregar uma skill.
`gen_ai.skill.name`	Nome da skill GenAI.	string	`code_review`;`change_workitem`	Obrigatório ao carregar uma skill.
`gen_ai.skill.description`	Descrição em formato livre da skill GenAI, fornecida pela aplicação.	string	`Execute code review on GitHub repositories`	recomendado
`gen_ai.skill.version`	Versão da skill GenAI.	string	`0.2.0`;`v2.1.0`	recomendado
`gen_ai.tool.call.arguments`	Parâmetros de entrada da chamada de ferramenta [2]	string	`{"location": "San Francisco?","date": "2025-10-01"}`	Opcional
`gen_ai.tool.call.result`	Valor de retorno da chamada de ferramenta [3]	string	`{"temperature_range": {"high": 75,"low": 60},"conditions": "sunny"}`	Opcional

[1] gen_ai.span.kind: Enumeração dedicada para spanKind de LLM. Em um span de Tool, este valor deve ser TOOL.

[2] gen_ai.tool.call.arguments: Parâmetros de entrada da chamada de ferramenta, como uma string JSON. Colete apenas quando o sinalizador OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT estiver ativado. Este sinalizador vem ativado por padrão.

[3] gen_ai.tool.call.result: Valor de retorno da chamada de ferramenta, como uma string JSON. Colete apenas quando o sinalizador OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT estiver ativado. Este sinalizador vem ativado por padrão.

Agent

Um span de Agent representa um cenário de agente inteligente — uma Chain mais complexa. O agente usa resultados de inferência do LLM para decidir a próxima etapa. Isso pode envolver múltiplas chamadas de LLM e Tool, progredindo passo a passo até alcançar uma resposta final.

Defina gen_ai.operation.name como invoke_agent ou create_agent. Quando gen_ai.operation.name for invoke_agent ou create_agent, deduza gen_ai.span.kind como AGENT.

Nomeie o span como {gen_ai.operation.name} {gen_ai.agent.name}. Outros formatos de nomenclatura são aceitáveis em casos especiais.

Atributos

Chave do atributo	Descrição	Tipo	Exemplo	Nível de obrigatoriedade
`gen_ai.span.kind`	Tipo de operação [1]	string	`AGENT`	Obrigatório
`gen_ai.operation.name`	Tipo secundário de operação [2]	string	`invoke_agent`; `create_agent`	Obrigatório
`gen_ai.conversation.id`	ID único da conversa [3]	string	`conv_5j66UpCpwteGg4YSxUnt7lPY`	Obrigatório se disponível
`gen_ai.agent.description`	Descrição do agente	string	`Helps with math problems`; `Generates fiction stories`	Obrigatório se disponível
`gen_ai.agent.id`	Identificador único do agente	string	`asst_5j66UpCpwteGg4YSxUnt7lPY`	Obrigatório se disponível
`gen_ai.agent.name`	Nome do agente	string	`Math Tutor`; `Fiction Writer`	Obrigatório se disponível
`gen_ai.data_source.id`	Identificador único da fonte de dados [4]	string	`H7STPQYOND`	Obrigatório se disponível
`gen_ai.usage.input_tokens`	Número de tokens de entrada utilizados	integer	`100`	Recomendado
`gen_ai.usage.output_tokens`	Número de tokens de saída utilizados	integer	`200`	Recomendado
`gen_ai.usage.total_tokens`	Número total de tokens utilizados	integer	`300`	Recomendado
`gen_ai.usage.cache_creation.input_tokens`	Número de tokens gravados no cache do provedor do modelo [5]	integer	`25`	Recomendado
`gen_ai.usage.cache_read.input_tokens`	Número de tokens lidos do cache do provedor do modelo [6]	integer	`50`	Recomendado
`gen_ai.input.messages`	Conteúdo de entrada do modelo [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"}]}]`	Opcional
`gen_ai.output.messages`	Conteúdo de saída do modelo [8]	string	`[{"role":"assistant","parts":[{"type":"text","content":"The weather in Paris is currently rainy with a temperature of 57°F."}],"finish_reason":"stop"}]`	Opcional
`gen_ai.system_instructions`	Conteúdo do prompt do sistema [9]	string	`[{"type": "text", "content": "You are a helpful assistant"}]`	Opcional
`gen_ai.tool.definitions`	Lista de definições de ferramentas [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"]}}]`	Opcional
`gen_ai.response.time_to_first_token`	Latência de resposta do primeiro token do agente	integer	`1000000`	Recomendado

[1] gen_ai.span.kind: Enumeração dedicada para spanKind de LLM. Em um span de Agent, este valor deve ser AGENT.

[2] gen_ai.operation.name: Tipo secundário de operação.

[3] gen_ai.conversation.id: ID único da conversa. Colete este dado se puder obtê-lo facilmente.

[4] gen_ai.data_source.id: ID único da fonte de dados. Refere-se à fonte de dados da qual AI Agents ou aplicações RAG dependem. Pode ser um banco de dados externo, Object Storage Service, conjunto de documentos, site ou outro sistema de armazenamento.

[5] gen_ai.usage.cache_creation.input_tokens: Este valor já deve estar incluído em gen_ai.usage.input_tokens.

[6] gen_ai.usage.cache_read.input_tokens: Este valor já deve estar incluído em gen_ai.usage.input_tokens.

[7] gen_ai.input.messages: Registra o conteúdo de entrada para a chamada do LLM. As mensagens devem ser fornecidas na ordem em que foram enviadas ao modelo ou agente. Siga gen_ai.input.messages.json.

Colete apenas quando o sinalizador OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT estiver ativado. Este sinalizador vem ativado por padrão.

[8] gen_ai.output.messages: Registra o conteúdo de saída do modelo. As mensagens devem ser fornecidas na ordem em que foram enviadas ao modelo ou agente. Siga gen_ai.output.messages.json.

Colete apenas quando o sinalizador OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT estiver ativado. Este sinalizador vem ativado por padrão.

[9] gen_ai.system_instructions: Registra separadamente o conteúdo do prompt ou instrução do sistema. Use este campo se conseguir obter o prompt do sistema ou o conteúdo da instrução de forma independente. Caso contrário, registre-o no atributo gen_ai.input.messages. Siga gen_ai.system_instructions.json.

Colete apenas quando o sinalizador OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT estiver ativado. Este sinalizador vem ativado por padrão.

[10] gen_ai.tool.definitions: Registra as definições de ferramentas passadas ao LLM. Este atributo pode ser muito extenso. Por padrão, colete apenas os campos type e name. Colete todos os outros campos somente quando o sinalizador OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT estiver ativado. Este sinalizador vem ativado por padrão.

Task

Um span de Task representa uma chamada de método interno personalizado, como a invocação de uma função local ou outra lógica definida pela aplicação.

Nomeie o span como run_task {gen_ai.task.name}. Outros formatos de nomenclatura são aceitáveis em casos especiais.

Nota

A comunidade OpenTelemetry ainda não definiu uma convenção semântica para este tipo de span. Portanto, gen_ai.operation.name pode sofrer alterações.

Atributos

Chave do atributo	Descrição	Tipo	Exemplo	Nível de obrigatoriedade
`gen_ai.span.kind`	Tipo de operação [1]	string	`TASK`	Obrigatório
`gen_ai.operation.name`	Tipo secundário de operação	string	`run_task`	Obrigatório
`input.value`	Parâmetros de entrada	string	`Input parameters, custom JSON format`	Opcional
`input.mime_type`	Tipo MIME de entrada	string	`text/plain`; `application/json`	Opcional
`output.mime_type`	Tipo MIME de saída	string	`text/plain`; `application/json`	Opcional

[1] gen_ai.span.kind: Enumeração dedicada para spanKind de LLM. Em um span de Task, este valor deve ser TASK.

Entry

Um span de Entry marca o ponto de entrada para uma chamada a um sistema de aplicação de IA.

Nomeie o span como enter_ai_application_system. Outros formatos de nomenclatura são aceitáveis em casos especiais.

Nota

A comunidade OpenTelemetry ainda não definiu uma convenção semântica para este tipo de span. Portanto, gen_ai.operation.name pode sofrer alterações.

Atributos

Chave do atributo	Descrição	Tipo	Exemplo	Nível de obrigatoriedade
`gen_ai.span.kind`	Tipo de operação [1]	string	`ENTRY`	Obrigatório
`gen_ai.operation.name`	Tipo secundário de operação	string	`enter`	Recomendado
`gen_ai.session.id`	ID da sessão	string	`ddde34343-f93a-4477-33333-sdfsdaf`	Obrigatório se disponível
`gen_ai.user.id`	Identificador do usuário final	string	`u-lK8JddD`	Obrigatório se disponível
`gen_ai.input.messages`	Conteúdo de entrada do modelo [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"}]}]`	Opcional
`gen_ai.output.messages`	Conteúdo de saída do modelo [3]	string	`[{"role":"assistant","parts":[{"type":"text","content":"The weather in Paris is currently rainy with a temperature of 57°F."}],"finish_reason":"stop"}]`	Opcional
`gen_ai.response.time_to_first_token`	Latência de resposta do primeiro token em cenários de resposta em streaming [4]	integer	`1000000`	Recomendado

[1] gen_ai.span.kind: Enumeração dedicada para spanKind de LLM. Em um span de Entry, este valor deve ser ENTRY.

[2] gen_ai.input.messages: Registra o conteúdo de entrada para a chamada do LLM. As mensagens devem ser fornecidas na ordem em que foram enviadas ao modelo ou agente. Siga gen_ai.input.messages.json.

Colete apenas quando o sinalizador OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT estiver ativado. Este sinalizador vem ativado por padrão.

[3] gen_ai.output.messages: Registra o conteúdo de saída do modelo. As mensagens devem ser fornecidas na ordem em que foram enviadas ao modelo ou agente. Siga gen_ai.output.messages.json.

Colete apenas quando o sinalizador OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT estiver ativado. Este sinalizador vem ativado por padrão.

[4] gen_ai.response.time_to_first_token: Tempo decorrido entre o recebimento da solicitação do usuário pelo servidor e o retorno do primeiro pacote de resposta. Unidade: nanossegundos.

Etapa ReAct

Um span de Step marca um processo de iteração Reasoning-Acting dentro de um Agent.

Nomeie o span como react step. Outros formatos de nomenclatura são aceitáveis em casos especiais.

Nota

A comunidade OpenTelemetry ainda não definiu uma convenção semântica para este tipo de span. Portanto, gen_ai.operation.name pode sofrer alterações.

Atributos

Chave do atributo	Descrição	Tipo	Exemplo	Nível de obrigatoriedade
`gen_ai.span.kind`	Tipo de operação [1]	string	`STEP`	Obrigatório
`gen_ai.operation.name`	Tipo secundário de operação	string	`react`	Recomendado
`gen_ai.react.finish_reason`	Motivo para o término desta rodada ReAct	string	`error`	Recomendado
`gen_ai.react.round`	Número da rodada para esta iteração ReAct [2]	integer	`1`	Recomendado

[1] gen_ai.span.kind: Enumeração dedicada para spanKind de LLM. Em um span de etapa ReAct, este valor deve ser STEP.

[2] gen_ai.react.round: Os números das rodadas ReAct devem começar em 1 e incrementar de 1 a cada iteração.