Defina os atributos de extensão do OpenTelemetry para o MLflow.

Ao enviar rastreamentos de um aplicativo personalizado instrumentado com OpenTelemetry (OTel) para o Databricks MLflow, você deve definir atributos de intervalo específicos para renderizar corretamente os dados de rastreamento na interface do usuário do MLflow. Esta página mostra quais atributos da Convenção Semântica GenAI do OpenTelemetry devem ser configurados.

Se você usar uma integração pré-configurada como o Langfuse, essa integração definirá esses atributos automaticamente. Esta página destina-se a aplicações com instrumentação OTel personalizada.

nota

Os atributos no Databricks gerenciam MLflow que difere do MLflow de código aberto. Para o mapeamento de atributos do MLflow de código aberto, consulte a documentação do MLflow.

Requisitos

Antes de começar, certifique-se de ter:

• Um workspace Databricks com a pré-visualização de rastreamento OTel ativada.
• O exportador OTLP foi configurado para enviar rastreamentos para seu workspace. Consulte os registros de log nas tabelas Unity Catalog.
• Uma aplicação instrumentada com o SDK OpenTelemetry

Definir tipo de intervalo

Cada trecho (span) no seu rastreamento precisa de um rótulo de tipo para que MLflow possa identificar que tipo de operação ele representa. Defina gen_ai.operation.name para um dos valores na tabela a seguir chamando span.set_attribute("gen_ai.operation.name", "<value>"). O MLflow lê esse atributo e exibe o tipo de extensão MLflow correspondente na interface de rastreamento.

Valor OTel gen_ai.operation.name	tipo de extensão MLflow
chat	CHAT_MODEL
text_completion	LLM
generate_content	LLM
response	LLM
embeddings	EMBEDDING
execute_tool	TOOL
create_agent	AGENT
invoke_agent	AGENT

Python

span.set_attribute("gen_ai.operation.name", "chat")

Configurar entradas e saídas

Defina gen_ai.input.messages e gen_ai.output.messages em cada intervalo que deve exibir entradas e saídas. Ao configurá-los no span raiz, também preenchem as pré-visualizações de solicitação e resposta em nível de rastreamento.

Atributo OTel	Atributo MLflow
gen_ai.input.messages	mlflow.spanInputs
gen_ai.output.messages	mlflow.spanOutputs

Os valores podem ser strings simples ou strings serializadas em JSON . O uso de arrays JSON de objetos de mensagem com campos role e content permite uma renderização mais rica na interface do usuário MLflow (por exemplo, balões com os rótulos "Usuário" e "Assistente"):

Python

import json

# Plain string — displays as-is in the UI
span.set_attribute("gen_ai.input.messages", "What is the weather today?")

# JSON message array — renders with role labels in the UI
span.set_attribute("gen_ai.input.messages", json.dumps([
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "What is the weather today?"}
]))
span.set_attribute("gen_ai.output.messages", json.dumps([
    {"role": "assistant", "content": "It is sunny and 72°F in San Francisco."}
]))

Definir uso de tokens

Para exibir a contagem de tokens no resumo de rastreamento da interface do usuário, defina gen_ai.usage.input_tokens e gen_ai.usage.output_tokens chamando span.set_attribute() no span raiz. O MLflow lê esses valores especificamente do span raiz porque agrega contagens no nível de rastreamento.

Atributo OTel gen_ai.usage.*	Campo de tokens MLflow
gen_ai.usage.input_tokens	Contagem de tokens de entrada
gen_ai.usage.output_tokens	Contagem de tokens de saída
(não definido — calculado automaticamente)	Contagem total de tokens

Python

root.set_attribute("gen_ai.usage.input_tokens", 150)
root.set_attribute("gen_ai.usage.output_tokens", 42)

Exemplo completo: instrumentar um agente Python

O exemplo a seguir reúne todas as três categorias de atributos em um agente simples com um span filho LLM. Isso pressupõe que você já tenha configurado o exportador OTLP para enviar rastreamentos para o Databricks.

Python

import json
from opentelemetry import trace

tracer = trace.get_tracer("my-agent")

def run_agent(query: str) -> str:
    with tracer.start_as_current_span("agent-run") as root:
        # Child LLM span — set gen_ai attributes for this individual call
        with tracer.start_as_current_span("chat") as llm:
            llm.set_attribute("gen_ai.operation.name", "chat")
            messages = [
                {"role": "system", "content": "You are a helpful assistant."},
                {"role": "user", "content": query}
            ]
            response = call_llm(messages)
            llm.set_attribute("gen_ai.input.messages", json.dumps(messages))
            llm.set_attribute("gen_ai.output.messages", json.dumps([
                {"role": "assistant", "content": response}
            ]))
            llm.set_attribute("gen_ai.usage.input_tokens", 150)
            llm.set_attribute("gen_ai.usage.output_tokens", 42)

        # Root span — MLflow reads inputs, outputs, and token usage from the
        # root span to populate the trace summary in the UI.
        root.set_attribute("gen_ai.operation.name", "chat")
        root.set_attribute("gen_ai.input.messages", json.dumps([
            {"role": "user", "content": query}
        ]))
        root.set_attribute("gen_ai.output.messages", json.dumps([
            {"role": "assistant", "content": response}
        ]))
        root.set_attribute("gen_ai.usage.input_tokens", 150)
        root.set_attribute("gen_ai.usage.output_tokens", 42)
        return response

Verifique na interface do usuário do MLflow.

Depois de chamar run_agent(), abra a tab MLflow Traces em seu experimento. Um traçado corretamente instrumentado mostra:

• Tipos de span : Cada span exibe seu rótulo de tipo (por exemplo, chat) em vez de UNKNOWN
• Solicitação e resposta : O span raiz exibe as mensagens de entrada e as mensagens de saída.
• Uso de tokens : O resumo do rastreamento exibe a entrada, a saída e a contagem total de tokens.