AgentLoop:Instrumente aplicações de LLM com o OpenTelemetry GenAI Utils

Casos de uso

Com a expansão das aplicações de LLM e AI Agent, a observabilidade torna-se essencial. Você precisa de uma forma unificada para coletar e analisar interações de múltiplos turnos entre Agents e ferramentas do Model Context Protocol (MCP), além de rastrear agendamentos de motores de inferência como vLLM e SGLang, bem como métricas de uso de tokens e Time to First Token (TTFT). O ARMS Application Monitoring fornece probes prontos para cenários comuns de GenAI. A end-to-end trace based on the MCP protocol demonstra como o probe Python instrumenta a cadeia de chamadas de LangChain Agents e MCP Servers sem exigir alterações no código. O guia sobre observability for vLLM/SGLang inference engines aborda Spans no nível de requisição, atributos gen_ai.latency.* e métricas como TTFT e TPOT. Para frameworks personalizados, arquiteturas multilíngues ou cenários que demandam controle refinado de Spans, instrumente manualmente as chamadas de LLM, a orquestração de Agents e a execução de Tools diretamente no código da aplicação. O GenAI Utils atende exatamente a esses casos.

O GenAI Utils complementa os probes do Application Monitoring, mas não os substitui. Os probes instrumentam automaticamente frameworks conhecidos (LangChain, vLLM, MCP) com abordagem de pouco ou nenhum código, ideais para implantações padronizadas. Já o GenAI Utils exige chamadas explícitas à Handler API no código da aplicação, adequando-se a frameworks de Agent personalizados, atributos de Span customizados ou integrações ainda não cobertas pelos probes. Ambos geram telemetria seguindo as mesmas Convenções Semânticas de GenAI e permitem análise conjunta no console do ARMS ou em qualquer backend compatível com OpenTelemetry.

Como funciona

O GenAI Utils é uma biblioteca compartilhada de telemetria para operações de IA generativa. Ele mapeia operações como inferência de LLM, chamadas de Agent, embedding, execução de Tool e recuperação para Spans, Events e métricas padrão que seguem as Convenções Semânticas de GenAI do OpenTelemetry. Também disponibiliza APIs unificadas de ciclo de vida, como start, stop e fail.

A comunidade OpenTelemetry lançou inicialmente uma implementação de referência em Python, a opentelemetry-util-genai. Implementações equivalentes para Java, Go e Node.js vieram em seguida, todas utilizando o mesmo design de API e Convenções Semânticas.

O fluxo típico de dados ocorre da seguinte forma:

Application code + GenAI Utils (generates Spans)
        ↓
OpenTelemetry SDK / Exporter (configures endpoint and authentication)
        ↓
ARMS Tracing OpenTelemetry Edition
        ↓
ARMS console Trace Explorer

Pré-requisitos

O GenAI Utils gera Spans e métricas que seguem as Convenções Semânticas, mas o envio desses dados ao ARMS Tracing OpenTelemetry Edition exige um SDK e um Exporter do OpenTelemetry configurados. Conclua os pré-requisitos abaixo antes de escrever o código da sua aplicação:

1. Ative o service ARMS Tracing OpenTelemetry Edition.

2. Obtenha o domínio do endpoint, a porta e o token de autenticação da sua região.

3. Configure o SDK ou o Collector do OpenTelemetry para enviar dados de rastro ao ARMS usando um protocolo como OTLP.

Para detalhes de integração, endpoints regionais, mapeamento de portas e protocolos, além da configuração do SDK ou Collector, consulte a integration guide. Ela aborda:

• Pré-requisitos: como obter endpoints, portas e tokens de autenticação.

• Integração com OpenTelemetry: como configurar o envio de dados com o SDK ou Collector do OpenTelemetry.

• Outros métodos de integração de clientes (Jaeger, Zipkin, SkyWalking, etc.).

Se a sua aplicação estiver implantada fora da Alibaba Cloud, abra as portas exigidas e conceda permissões de acesso ao domínio conforme descrito na integration guide.

Início rápido (exemplo em Python)

Python foi a primeira linguagem a receber o GenAI Utils, e seu design de API serve de referência para as demais. O exemplo a seguir usa o TelemetryHandler para coletar um Span GenAI padrão referente a uma chamada de LLM.

Instale o GenAI Utils e os pacotes dependentes do SDK e Exporter do OpenTelemetry:

pip install opentelemetry-util-genai

from opentelemetry.util.genai.handler import get_telemetry_handler
from opentelemetry.util.genai.types import InputMessage, LLMInvocation, OutputMessage, Text

handler = get_telemetry_handler()

invocation = LLMInvocation(
    provider="openai",
    request_model="gpt-4o-mini",
    input_messages=[
        InputMessage(role="user", parts=[Text(content="Explain OpenTelemetry in one sentence.")]),
    ],
)
with handler.llm(invocation) as inv:
    # Call the actual model API here
    inv.output_messages = [
        OutputMessage(
            role="assistant",
            parts=[Text(content="OpenTelemetry is an open standard and implementation for observability.")],
            finish_reason="stop",
        )
    ]
    inv.input_tokens = 10
    inv.output_tokens = 20

As etapas de integração são: instale dependências → inicialize o Provider do OpenTelemetry → crie um handler → envolva a chamada à API do modelo com with handler.llm(...). Para outros tipos de operação ou políticas de coleta de conteúdo de mensagens, consulte a documentação da sua linguagem de programação.

Verifique o envio de dados

Após executar o código de exemplo, faça login no console do ARMS. Na página Trace Explorer, visualize o Span GenAI enviado. O Span deve conter atributos padrão como gen_ai.system, gen_ai.request.model e gen_ai.usage.*, correspondentes aos valores de provider, request_model e uso de tokens definidos no seu código.

Documentação do GenAI Utils

Todas as implementações por linguagem seguem as mesmas Convenções Semânticas e o mesmo design de Handler API. Para instalação, referências de API e exemplos de código, consulte a documentação específica da sua linguagem: