LLM trace fields - Application Real-Time Monitoring Service - Centro de documentación de Alibaba Cloud

Alibaba Cloud define los campos de traza de modelos de lenguaje grandes (LLM) con base en el estándar OpenTelemetry y en conceptos del dominio de aplicaciones de LLM. Estos campos amplían los atributos, los recursos y los eventos para describir la semántica de los datos de traza de las aplicaciones de LLM. Capturan operaciones clave, como las solicitudes de entrada y salida del LLM y el consumo de tokens. Además, proporcionan datos semánticos detallados y conscientes del contexto para escenarios como Completion, Chat, generación aumentada por recuperación (RAG), Agent y Tool Calling, lo que permite un seguimiento y una generación de informes eficaces.

Esta especificación semántica evoluciona junto con la comunidad. Si su aplicación está desarrollada en Python, debe recopilar manualmente los datos de observability. Para integrar y recopilar los datos, utilice el componente loongsuite-util-genai. Para más información, consulte el archivo README.

Las definiciones de campos a nivel de span siguen los estándares abiertos de OpenTelemetry. Para consultar las descripciones detalladas de los campos de traza de nivel superior almacenados en Managed Service for OpenTelemetry de Alibaba Cloud, consulte Trace Explorer parameters.

Nota

El SpanKind específico de LLM es un atributo, no el tipo de span definido en la especificación de trazas de OpenTelemetry. Esta especificación semántica amplía las convenciones semánticas GenAI de OpenTelemetry. Dicha especificación se encuentra en desarrollo activo y podría cambiar en futuras versiones de mantenimiento.

Sección común

Atributos

Clave del atributo	Descripción	Tipo	Valor de ejemplo	Nivel de obligatoriedad
`gen_ai.session.id`	Identificador de sesión	string	`ddde34343-f93a-4477-33333-sdfsdaf`	Obligatorio si está disponible
`gen_ai.user.id`	Identificador del usuario final	string	`u-lK8JddD`	Obligatorio si está disponible
`gen_ai.span.kind`	Tipo de operación [1]	string	`See LLM Span Kind`	Obligatorio
`gen_ai.operation.name`	Tipo de operación secundaria [2]	string	`See LLM Operation Name`	Obligatorio
`gen_ai.framework`	Tipo de framework utilizado	string	`langchain`;`llama_index`	Obligatorio si está disponible

[1] gen_ai.span.kind: se asigna a gen_ai.operation.name de la siguiente manera:

`gen_ai.span.kind`	`gen_ai.operation.name`	Descripción
RETRIEVER	`retrieval`	Recuperación de documentos
LLM	`chat`;`generate_content`;`text_completion`	Invocación del modelo
EMBEDDING	`embeddings`	Embedding
TOOL	`execute_tool`	Llamada a herramienta
AGENT	`create_agent`;`invoke_agent`	Invocación de agente
RERANKER	-	Invocación de reordenamiento
CHAIN	-	Cadena (unidad de invocación)
TASK	-	Invocación de tarea
ENTRY	-	Marcador de invocación de entrada
STEP	-	Marcador de ronda ReAct

[2] gen_ai.operation.name: tipo de operación secundaria. Utilice uno de los siguientes valores enumerados o defina un valor personalizado:

Valor	Descripción
`chat`	Operación de finalización de chat
`create_agent`	Operación de creación de agente GenAI
`embeddings`	Operación de embedding de palabras
`execute_tool`	Operación de llamada a herramienta
`generate_content`	Operación de generación de contenido multimodal
`invoke_agent`	Operación de invocación de agente GenAI
`retrieval`	Operación de recuperación de documentos
`text_completion`	Operación de finalización de texto

Recursos

Clave del recurso	Descripción	Tipo	Valor de ejemplo	Nivel de obligatoriedad
`service.name`	Nombre de la aplicación	string	`test-easy-rag`	Obligatorio
`acs.cms.workspace`	Espacio de trabajo de Cloud Monitor	string	`arms-test`	Obligatorio si está disponible
`acs.arms.service.id`	Identificador del servicio de Cloud Monitor	string	`ggxw4lnjuz@b63ba5a1d60b517ae374f`	Obligatorio si está disponible
`ali.trace.source`	Origen de la aplicación	string	`mse-gateway`;`alb`	Obligatorio si está disponible
`acs.arms.service.feature`	Función de la aplicación	string	`genai_app`	Obligatorio Nota `acs.arms.service.feature` = genai_app. Este valor identifica y etiqueta automáticamente la aplicación como una aplicación de IA. Es obligatorio para escenarios de LLM o Agent.

Chain

Una Chain es una herramienta que conecta LLM y otros componentes para ejecutar tareas complejas, como recuperación, embedding, invocaciones de LLM y cadenas anidadas.

Asigne al span el nombre chain {chain_name}. Si no es posible obtener chain_name, asígnele el nombre chain.

Nota

La comunidad de OpenTelemetry aún no ha definido una convención semántica para este tipo de span. Actualmente, los spans de Chain solo aplican al framework LangChain.

Atributos

Clave del atributo	Descripción	Tipo	Ejemplo	Nivel de obligatoriedad
`gen_ai.span.kind`	Tipo de operación [1]	string	`CHAIN`	Obligatorio
`gen_ai.operation.name`	Tipo de operación secundaria	string	`workflow`; `task`	Obligatorio si está disponible
`input.value`	Contenido de entrada	string	`Who Are You!`	Recomendado
`output.value`	Contenido de respuesta	string	`I am ChatBot`	Recomendado
`gen_ai.user.time_to_first_token`	Tiempo hasta el primer token [2]	integer	1000000	Recomendado

[1] gen_ai.span.kind: enumeración dedicada para el spanKind de LLM. En una Chain, este valor debe ser CHAIN.

[2] gen_ai.user.time_to_first_token: tiempo transcurrido desde que el servidor recibe la solicitud del usuario hasta que regresa el primer paquete de respuesta. Unidad: nanosegundos.

Retriever

Un Retriever accede a almacenes de vectores o bases de datos para recuperar datos. Por lo general, complementa el contexto para mejorar la precisión y la eficiencia de las respuestas del LLM.

Establezca gen_ai.operation.name como retrieval. Cuando gen_ai.operation.name es retrieval, infiera gen_ai.span.kind como RETRIEVER.

Asigne al span el nombre {gen_ai.operation.name} {gen_ai.data_source.id}. En casos especiales, se admiten otros formatos de nomenclatura.

Atributos

Clave del atributo	Descripción	Tipo	Ejemplo	Nivel de obligatoriedad
`gen_ai.span.kind`	Tipo de operación [1]	string	`RETRIEVER`	Obligatorio
`gen_ai.operation.name`	Tipo de operación secundaria [2]	string	`retrieval`	Obligatorio
`gen_ai.data_source.id`	Identificador único del origen de datos [3]	string	`H7STPQYOND`	Obligatorio si está disponible
`gen_ai.provider.name`	Proveedor del LLM	string	`openai`	Obligatorio si está disponible
`gen_ai.request.model`	Nombre del modelo especificado en la solicitud	string	`gpt-4`	Obligatorio si está disponible
`gen_ai.request.top_k`	Valor Top-K especificado en la solicitud	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`	Fragmento de texto de consulta	string	`what is the topic in xxx?`	Opcional

[1] gen_ai.span.kind: enumeración dedicada para el spanKind de LLM. En un Retriever, este valor debe ser RETRIEVER.

[2] gen_ai.operation.name: tipo de operación secundaria.

[3] gen_ai.data_source.id: identificador único del origen de datos. Se trata del origen de datos del que dependen los agentes de IA o las aplicaciones de RAG. Puede ser una base de datos externa, Object Storage Service, un conjunto de documentos, un sitio web u otro sistema de almacenamiento.

[4] gen_ai.retrieval.documents: registra la lista de documentos recuperados. Cada objeto de documento debe contener como mínimo estas propiedades: id (string): identificador único del documento. score (número de punto flotante de doble precisión): puntuación de relevancia.

Reranker

El Reranker evalúa la relevancia de varios documentos de entrada según la consulta, los ordena y puede devolver los K documentos principales como entrada para el LLM.

Asigne al span el nombre rerank {reranker.model_name}. Si no es posible obtener reranker.model_name, asígnele el nombre rerank.

Nota

La comunidad de OpenTelemetry aún no ha definido una convención semántica para este tipo de span.

Atributos

Clave del atributo	Descripción	Tipo	Ejemplo	Nivel de obligatoriedad
`gen_ai.span.kind`	Tipo de operación [1]	string	`RERANKER`	Obligatorio
`reranker.query`	Parámetro de solicitud del Reranker	string	`How to format timestamp?`	Opcional
`reranker.model_name`	Nombre del modelo que utiliza el Reranker	string	`cross-encoder/ms-marco-MiniLM-L-12-v2`	Opcional
`reranker.top_k`	Posición después del reordenamiento	integer	`3`	Opcional
`reranker.input_document`	Metadatos de los documentos de entrada [2]	string	`See example`	Obligatorio
`reranker.output_document`	Metadatos de los documentos de salida [3]	string	`See example`	Obligatorio

[1] gen_ai.span.kind: enumeración dedicada para el spanKind de LLM. En un Reranker, este valor debe ser RERANKER.

[2] reranker.output_document: documentos de entrada para el reordenamiento. Estructura de arreglo JSON. Los metadatos contienen información básica del documento, como la ruta, el nombre del archivo y el origen.

[3] reranker.output_document: documentos de salida después del reordenamiento. Estructura de arreglo JSON. Los metadatos contienen información básica del documento, como la ruta, el nombre del archivo y el origen.

LLM

Un span de LLM representa una llamada o un proceso de inference de LLM. Algunos ejemplos incluyen el uso de un SDK o de openapi para invocar distintos LLM y generar inference o texto.

Establezca gen_ai.operation.name como chat, generate_content o text_completion. Cuando gen_ai.operation.name es chat, generate_content o text_completion, infiera gen_ai.span.kind como LLM.

Asigne al span el nombre {gen_ai.operation.name} {gen_ai.request.model}. En casos especiales, se admiten otros formatos de nomenclatura.

Atributos

Clave del atributo	Descripción	Tipo	Ejemplo	Nivel de obligatoriedad
`gen_ai.span.kind`	Tipo de operación [1]	string	`LLM`	Obligatorio
`gen_ai.operation.name`	Tipo de operación secundaria [2]	string	`chat`; `generate_content`; `text_completion`	Obligatorio
`gen_ai.provider.name`	Proveedor del LLM	string	`openai`	Obligatorio
`gen_ai.conversation.id`	Identificador único de conversación [3]	string	`conv_5j66UpCpwteGg4YSxUnt7lPY`	Obligatorio si está disponible
`gen_ai.output.type`	Tipo de salida especificado en la solicitud del LLM [4]	string	`text`;`json`;`image`;`audio`	Obligatorio si está disponible
`gen_ai.request.choice.count`	Número de generaciones candidatas solicitadas en la solicitud del LLM	int	`3`	Obligatorio si no es 1
`gen_ai.request.model`	Nombre del modelo especificado en la solicitud del LLM	string	`gpt-4`	Obligatorio
`gen_ai.request.seed`	Semilla especificada en la solicitud del LLM	string	`gpt-4`	Obligatorio si está disponible
`gen_ai.request.frequency_penalty`	Penalización de frecuencia establecida en la solicitud del LLM	float	`0.1`	Recomendado
`gen_ai.request.max_tokens`	Cantidad máxima de tokens especificada en la solicitud del LLM	integer	`100`	Recomendado
`gen_ai.request.presence_penalty`	Penalización de presencia establecida en la solicitud del LLM	float	`0.1`	Recomendado
`gen_ai.request.temperature`	Temperatura especificada en la solicitud del LLM	float	`0.1`	Recomendado
`gen_ai.request.top_p`	Valor Top-P especificado en la solicitud del LLM	float	`1.0`	Recomendado
`gen_ai.request.top_k`	Valor Top-K especificado en la solicitud del LLM	float	`1.0`	Recomendado
`gen_ai.request.stop_sequences`	Secuencias de detención para el LLM	string[]	`["stop"]`	Recomendado
`gen_ai.response.id`	Identificador único generado por el LLM	string	`chatcmpl-9J3uIL87gldCFtiIbyaOvTeYBRA3l`	Recomendado
`gen_ai.response.model`	Nombre del modelo utilizado para la generación del LLM	string	`gpt-4-0613`	Recomendado
`gen_ai.response.finish_reasons`	Motivo por el que el LLM dejó de generar	string[]	`["stop"]`	Recomendado
`gen_ai.response.time_to_first_token`	Latencia del primer token del LLM en escenarios de respuesta en streaming [5]	integer	`1000000`	Recomendado
`gen_ai.response.reasoning_time`	Tiempo de inference para modelos de razonamiento [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 salida 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 escritos en la caché del proveedor del modelo [7]	integer	`25`	Recomendado
`gen_ai.usage.cache_read.input_tokens`	Número de tokens leídos de la caché del proveedor del modelo [8]	integer	`50`	Recomendado
`gen_ai.input.messages`	Contenido de entrada del 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`	Contenido de salida del 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`	Contenido del prompt del sistema [11]	string	`[{"type": "text", "content": "You are a helpful assistant"}]`	Opcional
`gen_ai.tool.definitions`	Lista de definiciones de herramientas [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`	Latencia de prellenado del LLM. Unidad: nanosegundos	integer	`1000`	Recomendado
`gen_ai.latency.time_in_model_decode`	Latencia de decodificación del LLM. Unidad: nanosegundos	integer	`1000`	Recomendado
`gen_ai.latency.time_in_model_inference`	Tiempo de inference del LLM. Equivale a la suma del tiempo de prellenado y de decodificación. Unidad: nanosegundos	integer	`1000`	Recomendado
`gen_ai.input.multimodal_metadata`	Datos multimodales incluidos en el contenido de entrada del LLM [13]	string[]	`[{"type":"uri","mime_type":"image/jpeg","uri":"sls://project/logstore/date/object","modality":"image"}]`	Recomendado
`gen_ai.output.multimodal_metadata`	Datos multimodales incluidos en el contenido de salida del LLM [14]	string[]	`[{"type":"uri","mime_type":"image/jpeg","uri":"sls://project/logstore/date/object","modality":"image"}]`	Recomendado

[1] gen_ai.span.kind: enumeración dedicada para el spanKind de LLM. En un span de LLM, este valor debe ser LLM.

[2] gen_ai.operation.name: tipo de operación secundaria.

[3] gen_ai.conversation.id: identificador único de conversación. Recopílelo si puede obtenerlo fácilmente.

[4] gen_ai.output.type: recopílelo si la solicitud especifica un tipo de salida (como un formato de salida). Los valores deben corresponder a una de las siguientes enumeraciones o a un valor personalizado:

Valor	Descripción
`image`	Imagen
`json`	Objeto JSON con formato correcto
`speech`	Voz
`text`	Texto sin formato

[5] gen_ai.user.time_to_first_token: tiempo transcurrido desde que el servidor recibe la solicitud del usuario hasta que regresa el primer paquete de respuesta. Unidad: nanosegundos.

[6] gen_ai.response.reasoning_time: duración del proceso de razonamiento. Unidad: milisegundos.

[7] gen_ai.usage.cache_creation.input_tokens: este valor ya debe estar incluido en gen_ai.usage.input_tokens.

[8] gen_ai.usage.cache_read.input_tokens: este valor ya debe estar incluido en gen_ai.usage.input_tokens.

[9] gen_ai.input.messages: registra el contenido de entrada de la llamada al LLM. Los mensajes deben proporcionarse en el orden en que se enviaron al modelo o al agente. Siga gen_ai.input.messages.json.

Recopílelos únicamente cuando la marca OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT esté habilitada. Esta marca está habilitada de forma predeterminada.

[10] gen_ai.output.messages: registra el contenido de salida del modelo. Los mensajes deben proporcionarse en el orden en que se enviaron al modelo o al agente. Siga gen_ai.output.messages.json.

Recopílelos únicamente cuando la marca OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT esté habilitada. Esta marca está habilitada de forma predeterminada.

[11] gen_ai.system_instructions: registra por separado el contenido del prompt o de las instrucciones del sistema. Utilice este campo si puede obtener dicho contenido de forma independiente. De lo contrario, regístrelo en el atributo gen_ai.input.messages. Siga gen_ai.system_instructions.json.

Recopílelo únicamente cuando la marca OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT esté habilitada. Esta marca está habilitada de forma predeterminada.

[12] gen_ai.tool.definitions: registra las definiciones de herramientas que se pasan al LLM. Este atributo puede ser muy extenso. De forma predeterminada, recopile solo los campos type y name. Recopile el resto de los campos únicamente cuando la marca OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT esté habilitada. Esta marca está habilitada de forma predeterminada.

[13] gen_ai.input.multimodal_metadata: agrega los datos multimodales a los que hace referencia el contenido de entrada del modelo. Incluye únicamente mensajes UriPart. Siga gen_ai.input.messages.json.

Recopílelos únicamente cuando la marca OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT esté habilitada. Esta marca está habilitada de forma predeterminada.

[14] gen_ai.output.multimodal_metadata: agrega los datos multimodales a los que hace referencia el contenido de salida del modelo. Incluye únicamente mensajes UriPart. Siga gen_ai.output.messages.json.

Recopílelos únicamente cuando la marca OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT esté habilitada. Esta marca está habilitada de forma predeterminada.

Registro de prompts, entradas y salidas

Puede omitir el registro de las entradas del usuario y las respuestas del modelo, registrarlas en los atributos del span o registrarlas como eventos (registros). Para más información, consulte Control LLM Application Conversation History Collection Behavior.

Embedding

Un embedding representa un proceso individual, como aplicar embedding a un texto con un LLM. Después, puede usar consultas de similitud para optimizar la resolución de problemas.

Establezca gen_ai.operation.name como embeddings. Cuando gen_ai.operation.name es embeddings, infiera gen_ai.span.kind como EMBEDDING.

Asigne al span el nombre {gen_ai.operation.name} {gen_ai.request.model}. En casos especiales, se admiten otros formatos de nomenclatura.

Atributos

Clave del atributo	Descripción	Tipo	Ejemplo	Nivel de obligatoriedad
`gen_ai.span.kind`	Tipo de operación [1]	string	`EMBEDDING`	Obligatorio
`gen_ai.operation.name`	Tipo de operación secundaria [2]	string	`embeddings`	Obligatorio
`gen_ai.provider.name`	Proveedor del LLM	string	`openai`	Obligatorio
`gen_ai.request.model`	Nombre del modelo especificado en la solicitud	string	`gpt-4`	Obligatorio si está disponible
`gen_ai.embeddings.dimension.count`	Número de dimensiones esperadas para la operación de embedding	integer	`1024`	Recomendado
`gen_ai.request.encoding_formats`	Formatos de codificación solicitados para la operación de embedding	string[]	`["base64"]`; `["float", "binary"]`	Recomendado
`gen_ai.usage.input_tokens`	Cantidad de tokens consumidos por el texto de entrada	integer	`10`	Opcional
`gen_ai.usage.total_tokens`	Cantidad total de tokens consumidos por el embedding	integer	`10`	Opcional

[1] gen_ai.span.kind: enumeración dedicada para el spanKind de LLM. En un span de Embedding, este valor debe ser EMBEDDING.

[2] gen_ai.operation.name: tipo de operación secundaria.

Tool

Los spans de Tool representan llamadas a herramientas externas. Algunos ejemplos son llamar a una calculadora o solicitar el clima más reciente a una API meteorológica.

Establezca gen_ai.operation.name como execute_tool. Cuando gen_ai.operation.name es execute_tool, infiera gen_ai.span.kind como TOOL.

Asigne al span el nombre {gen_ai.operation.name} {gen_ai.tool.name}. En casos especiales, se admiten otros formatos de nomenclatura.

Si la ejecución de una herramienta carga una skill, establezca los campos gen_ai.skill.* correspondientes. Entre los escenarios comunes se incluyen llamadas a herramientas como load_skill, read_skill u operaciones similares.

Atributos

Clave del atributo	Descripción	Tipo	Ejemplo	Nivel de obligatoriedad
`gen_ai.span.kind`	Tipo de operación [1]	string	`TOOL`	Obligatorio
`gen_ai.operation.name`	Tipo de operación secundaria [2]	string	`execute_tool`	Obligatorio
`gen_ai.tool.call.id`	Identificador de la herramienta	string	`call_mszuSIzqtI65i1wAUOE8w5H4`	Recomendado
`gen_ai.tool.description`	Descripción de la herramienta	string	`Multiply two numbers`	Recomendado
`gen_ai.tool.name`	Nombre de la herramienta	string	Recomendado
`gen_ai.tool.type`	Tipo de herramienta	string	`function`;`extension`;`datastore`	Recomendado
`gen_ai.skill.id`	Identificador único de la skill de GenAI.	string	`skill_29bbe8a7`	Obligatorio al cargar una skill.
`gen_ai.skill.name`	Nombre de la skill de GenAI.	string	`code_review`;`change_workitem`	Obligatorio al cargar una skill.
`gen_ai.skill.description`	Descripción de formato libre de la skill de GenAI, proporcionada por la aplicación.	string	`Execute code review on GitHub repositories`	Recomendado
`gen_ai.skill.version`	Versión de la skill de GenAI.	string	`0.2.0`;`v2.1.0`	Recomendado
`gen_ai.tool.call.arguments`	Parámetros de entrada de la llamada a la herramienta [2]	string	`{"location": "San Francisco?","date": "2025-10-01"}`	Opcional
`gen_ai.tool.call.result`	Valor devuelto por la llamada a la herramienta [3]	string	`{"temperature_range": {"high": 75,"low": 60},"conditions": "sunny"}`	Opcional

[1] gen_ai.span.kind: enumeración dedicada para el spanKind de LLM. En un span de Tool, este valor debe ser TOOL.

[2] gen_ai.tool.call.arguments: parámetros de entrada de la llamada a la herramienta, como una cadena JSON. Recopílelos únicamente cuando la marca OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT esté habilitada. Esta marca está habilitada de forma predeterminada.

[3] gen_ai.tool.call.result: valor devuelto por la llamada a la herramienta, como una cadena JSON. Recopílelo únicamente cuando la marca OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT esté habilitada. Esta marca está habilitada de forma predeterminada.

Agent

Un span de tipo Agent representa un escenario de agente inteligente, es decir, una cadena (Chain) más compleja. El agente utiliza los resultados de inference del LLM para decidir el siguiente paso. Este proceso puede implicar varias llamadas a LLM y Tool, las cuales avanzan paso a paso hasta obtener una respuesta final.

Establezca gen_ai.operation.name como invoke_agent o create_agent. Cuando gen_ai.operation.name es invoke_agent o create_agent, infiera gen_ai.span.kind como AGENT.

Asigne al span el nombre {gen_ai.operation.name} {gen_ai.agent.name}. En casos especiales se admiten otros formatos de nomenclatura.

Atributos

Clave del atributo	Descripción	Tipo	Ejemplo	Nivel de obligatoriedad
`gen_ai.span.kind`	Tipo de operación [1]	string	`AGENT`	Obligatorio
`gen_ai.operation.name`	Tipo de operación secundario [2]	string	`invoke_agent`; `create_agent`	Obligatorio
`gen_ai.conversation.id`	Identificador único de la conversación [3]	string	`conv_5j66UpCpwteGg4YSxUnt7lPY`	Obligatorio si está disponible
`gen_ai.agent.description`	Descripción del agente	string	`Helps with math problems`; `Generates fiction stories`	Obligatorio si está disponible
`gen_ai.agent.id`	Identificador único del agente	string	`asst_5j66UpCpwteGg4YSxUnt7lPY`	Obligatorio si está disponible
`gen_ai.agent.name`	Nombre del agente	string	`Math Tutor`; `Fiction Writer`	Obligatorio si está disponible
`gen_ai.data_source.id`	Identificador único de la fuente de datos [4]	string	`H7STPQYOND`	Obligatorio si está disponible
`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 salida 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 escritos en la caché del proveedor del modelo [5]	integer	`25`	Recomendado
`gen_ai.usage.cache_read.input_tokens`	Número de tokens leídos de la caché del proveedor del modelo [6]	integer	`50`	Recomendado
`gen_ai.input.messages`	Contenido de entrada del 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`	Contenido de salida del 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`	Contenido del prompt del sistema [9]	string	`[{"type": "text", "content": "You are a helpful assistant"}]`	Opcional
`gen_ai.tool.definitions`	Lista de definiciones de herramientas [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`	Latencia de respuesta del primer token del agente	integer	`1000000`	Recomendado

[1] gen_ai.span.kind: Enumeración dedicada para el spanKind del LLM. En un span de tipo Agent, este valor debe ser AGENT.

[2] gen_ai.operation.name: Tipo de operación secundario.

[3] gen_ai.conversation.id: Identificador único de la conversación. Recopílelo si lo obtiene fácilmente.

[4] gen_ai.data_source.id: Identificador único de la fuente de datos. Se trata de la fuente de datos de la que dependen los agentes de IA o las aplicaciones RAG. Puede ser una base de datos externa, Object Storage Service, un conjunto de documentos, un sitio web u otro sistema de almacenamiento.

[5] gen_ai.usage.cache_creation.input_tokens: Este valor ya debe estar incluido en gen_ai.usage.input_tokens.

[6] gen_ai.usage.cache_read.input_tokens: Este valor ya debe estar incluido en gen_ai.usage.input_tokens.

[7] gen_ai.input.messages: Registra el contenido de entrada de la llamada al LLM. Los mensajes deben proporcionarse en el orden en que se enviaron al modelo o al agente. Siga gen_ai.input.messages.json.

Recopile esta información solo cuando la bandera OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT esté habilitada. Esta bandera está habilitada de forma predeterminada.

[8] gen_ai.output.messages: Registra el contenido de salida del modelo. Los mensajes deben proporcionarse en el orden en que se enviaron al modelo o al agente. Siga gen_ai.output.messages.json.

Recopile esta información solo cuando la bandera OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT esté habilitada. Esta bandera está habilitada de forma predeterminada.

[9] gen_ai.system_instructions: Registra por separado el contenido del prompt o de la instrucción del sistema. Utilice este campo si obtiene dicho contenido de manera independiente. De lo contrario, regístrelo en el atributo gen_ai.input.messages. Siga gen_ai.system_instructions.json.

Recopile esta información solo cuando la bandera OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT esté habilitada. Esta bandera está habilitada de forma predeterminada.

[10] gen_ai.tool.definitions: Registra las definiciones de herramientas que se pasan al LLM. Este atributo puede ser muy extenso. De forma predeterminada, recopile únicamente los campos type y name. Recopile el resto de los campos solo cuando la bandera OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT esté habilitada. Esta bandera está habilitada de forma predeterminada.

Task

Un span de tipo Task representa una llamada interna personalizada a un método. Por ejemplo, la invocación de una función local o de otra lógica definida por la aplicación.

Asigne al span el nombre run_task {gen_ai.task.name}. En casos especiales se admiten otros formatos de nomenclatura.

Nota

La comunidad de OpenTelemetry aún no ha definido una convención semántica para este tipo de span. Por lo tanto, gen_ai.operation.name podría cambiar.

Atributos

Clave del atributo	Descripción	Tipo	Ejemplo	Nivel de obligatoriedad
`gen_ai.span.kind`	Tipo de operación [1]	string	`TASK`	Obligatorio
`gen_ai.operation.name`	Tipo de operación secundario	string	`run_task`	Obligatorio
`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 salida	string	`text/plain`; `application/json`	Opcional

[1] gen_ai.span.kind: Enumeración dedicada para el spanKind del LLM. En un span de tipo Task, este valor debe ser TASK.

Entry

Un span de tipo Entry marca el punto de entrada de una llamada a un sistema de aplicación de IA.

Asigne al span el nombre enter_ai_application_system. En casos especiales se admiten otros formatos de nomenclatura.

Nota

La comunidad de OpenTelemetry aún no ha definido una convención semántica para este tipo de span. Por lo tanto, gen_ai.operation.name podría cambiar.

Atributos

Clave del atributo	Descripción	Tipo	Ejemplo	Nivel de obligatoriedad
`gen_ai.span.kind`	Tipo de operación [1]	string	`ENTRY`	Obligatorio
`gen_ai.operation.name`	Tipo de operación secundario	string	`enter`	Recomendado
`gen_ai.session.id`	Identificador de sesión	string	`ddde34343-f93a-4477-33333-sdfsdaf`	Obligatorio si está disponible
`gen_ai.user.id`	Identificador del usuario final	string	`u-lK8JddD`	Obligatorio si está disponible
`gen_ai.input.messages`	Contenido de entrada del 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`	Contenido de salida del 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`	Latencia de respuesta del primer token en escenarios de respuesta en streaming [4]	integer	`1000000`	Recomendado

[1] gen_ai.span.kind: Enumeración dedicada para el spanKind del LLM. En un span de tipo Entry, este valor debe ser ENTRY.

[2] gen_ai.input.messages: Registra el contenido de entrada de la llamada al LLM. Los mensajes deben proporcionarse en el orden en que se enviaron al modelo o al agente. Siga gen_ai.input.messages.json.

Recopile esta información solo cuando la bandera OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT esté habilitada. Esta bandera está habilitada de forma predeterminada.

[3] gen_ai.output.messages: Registra el contenido de salida del modelo. Los mensajes deben proporcionarse en el orden en que se enviaron al modelo o al agente. Siga gen_ai.output.messages.json.

Recopile esta información solo cuando la bandera OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT esté habilitada. Esta bandera está habilitada de forma predeterminada.

[4] gen_ai.response.time_to_first_token: Tiempo transcurrido desde que el servidor recibe la solicitud del usuario hasta que devuelve el primer paquete de respuesta. Unidad: nanosegundos.

Paso de ReAct

Un span de tipo Step marca un proceso de iteración de razonamiento y acción (Reasoning-Acting) dentro de un agente.

Asigne al span el nombre react step. En casos especiales se admiten otros formatos de nomenclatura.

Nota

La comunidad de OpenTelemetry aún no ha definido una convención semántica para este tipo de span. Por lo tanto, gen_ai.operation.name podría cambiar.

Atributos

Clave del atributo	Descripción	Tipo	Ejemplo	Nivel de obligatoriedad
`gen_ai.span.kind`	Tipo de operación [1]	string	`STEP`	Obligatorio
`gen_ai.operation.name`	Tipo de operación secundario	string	`react`	Recomendado
`gen_ai.react.finish_reason`	Motivo de finalización de esta ronda de ReAct	string	`error`	Recomendado
`gen_ai.react.round`	Número de ronda de esta iteración de ReAct [2]	integer	`1`	Recomendado

[1] gen_ai.span.kind: Enumeración dedicada para el spanKind del LLM. En un span de paso de ReAct, este valor debe ser STEP.

[2] gen_ai.react.round: Los números de ronda de ReAct deben comenzar en 1 e incrementarse en 1 con cada iteración.