Pular para o conteúdo
LabS Atlas
Agentic AI
Entrar

OpenTelemetry

Ir para notas que citam esta
atualizado há 25 diasEntre para perguntar ao Labinho sobre esta notaO Labinho é o assistente que responde com as notas e as sessões do LabS e mostra de onde tirou cada resposta.

OpenTelemetry é um padrão aberto para capturar, exportar e transportar métricas, eventos, logs e traces de uma aplicação até um backend de observabilidade como Grafana ou Prometheus.

Ele existe porque observabilidade depende de relacionar dados que nascem em lugares diferentes: o consumo de tokens de um agente, o erro de uma chamada, o tempo gasto numa busca. Sem um formato comum, cada ferramenta exporta do seu jeito e cada destino precisa de um conector próprio. O OpenTelemetry resolve isso definindo três coisas ao mesmo tempo: como pensar os sinais, como separá-los por tipo e como enviá-los de um lugar para outro. Aparece também como OTel e OTLP.

Não se trata de uma aplicação que se instala e abre na tela. É um protocolo, e a analogia mais próxima é o HTTP: ele se apoia em protocolos de transporte como gRPC e HTTP e define o formato da mensagem que viaja por cima deles. Quem acumula, relaciona e exibe os dados é o backend do outro lado, montado à parte, como descrito em Stack de Observabilidade com Grafana.

Os quatro sinais e o que cada um responde

  • Métrica: um dado contido sobre uma parte observável do sistema, atualizado ao longo do tempo como série temporal. Uso de CPU a cada instante, tokens por minuto ou tokens gastos num prompt específico são métricas.
  • Evento: algo que acontece sem estar necessariamente preso a um processo específico. O aviso de que um processamento em lote terminou é um evento.
  • Log: o retorno do estado da aplicação num dado momento, isto é, o que ela fez e qual foi o resultado, por exemplo o envio de algo para um cliente e a resposta obtida.
  • Trace: o conjunto de marcações de tempo que junta tudo o que aconteceu dentro de uma mesma requisição. Uma chamada que chega a um agente, aciona uma busca de RAG, volta com a informação, segue para o modelo e retorna ao cliente vira um único trace, com o tempo de cada etapa.

Cada sinal responde a uma pergunta diferente: a métrica mostra quanto e quando, o log o que a aplicação fez, o trace por onde a requisição passou e onde demorou. É cruzando os quatro que se chega ao porquê de um comportamento.

Por que um padrão neutro importa em ferramenta agêntica

Ferramentas de IA mudam de formato com frequência: um modelo novo passa a interpretar a chamada de outro jeito, um tipo de telemetria sai de beta e muda de estrutura. Instrumentar sobre um padrão aberto isola essa volatilidade. A ferramenta emite no formato comum, e o destino pode trocar de Prometheus para Grafana, de uma instância local para um servidor na nuvem, sem mexer na forma como os dados são gerados.

Os provedores de IA já seguem esse padrão, o que tira do time a tarefa de escrever software de telemetria do zero. O trabalho que sobra é decidir quais métricas importam de fato, já que há muito mais sinal disponível do que vale a pena olhar.

Suporte parcial e em evolução

No Claude Code, o envio de traces ainda estava em beta, com mensagens de erro genéricas e comportamento sujeito a mudança. Métricas e eventos são a parte mais estável para montar painéis.

Como o dado sai da ferramenta e chega ao backend

A arquitetura é de cliente e servidor. No Claude Code, a telemetria é ligada por variáveis de ambiente que apontam para um endpoint OpenTelemetry; a partir daí a ferramenta passa a emitir sozinha, sem código adicional. Há dois caminhos de envio:

  • Direto: a ferramenta manda os sinais ao servidor de observabilidade.
  • Via coletor: a ferramenta fala com um coletor OpenTelemetry rodando na própria máquina ou na rede, e o coletor encaminha ao backend. É o arranjo mais comum em ambiente corporativo, porque centraliza filtragem e roteamento.

Em qualquer dos dois, o que chega ao servidor é o que alimenta a Telemetria de Uso e Custo do Claude Code. O padrão também se estende a protocolos de agentes: a especificação do MCP passou a apontar o tratamento de logs e o rastreio distribuído para o OpenTelemetry.