Como Adicionar Monitoramento a um Projeto Go Sem Alterações no Código

Pense em quantas vezes você adiou a implementação de tracing completo em um projeto apenas porque era muito tedioso passar contexts através de cada método? Ou pior, quando você precisava rastrear um caminho de requisição dentro de uma biblioteca de terceiros cujo código-fonte você não controla. Geralmente, nesses casos, você precisava reescrever metade da lógica de negócio para se adequar à API do OpenTelemetry, ou aceitar "pontos cegos" no seu monitoramento.

O time do OpenTelemetry parece ter encontrado uma forma de eliminar esse trabalho tedioso. O repositório opentelemetry-go-compile-instrumentation oferece uma ferramenta que injeta telemetria diretamente durante o processo de build da aplicação.

O que é essa mágica

O projeto é um utilitário otelc. Ele funciona como uma camada sobre o compilador padrão do Go. Em vez de você importar manualmente as bibliotecas do OpenTelemetry e posicionar spans, a ferramenta faz isso por você em tempo de compilação. Ela encontra os lugares certos no seu código e nas suas dependências, e então insere as chamadas necessárias.

Isso não é apenas "automação"—é uma mudança de paradigma. Você escreve código limpo focado em tarefas de negócio, e a observabilidade se torna uma camada de infraestrutura que fica por cima.

Para que isso é útil na prática

O destaque principal aqui é a completa ausência de alterações no código-fonte. Se amanhã você decidir trocar de fornecedor de monitoramento ou abandonar o tracing completamente, não será necessário limpar centenas de imports em todo o projeto.

Funcionalidades interessantes da ferramenta:

• Trabalho com bibliotecas de terceiros. Você pode obter traces de dentro do código de outra pessoa que está conectado via go. mod.
• Zero overhead em runtime. Como o código é injetado em tempo de build, o programa não precisa gastar recursos com análise dinâmica ou reflection durante a execução.
• Integração flexível. A ferramenta se encaixa facilmente em pipelines de CI/CD. Essencialmente, você só muda o comando de build.

Como funciona internamente

A ferramenta modifica o processo de build. Em vez do familiar go build você usa otelc go build. Nos bastidores, o utilitário analisa a árvore de sintaxe abstrata (AST) do seu código e suas dependências. Com base em regras pré-descritas (Instrumentation Rules), ele injeta os snippets de código necessários.

O repositório contém guias de arquitetura detalhados. Se você tiver curiosidade sobre exatamente como a substituição de chamadas funciona e como descrever regras para novas bibliotecas, dê uma olhada na pasta docs/. Tudo está documentado lá: desde o design da API até as convenções semânticas.

Por onde começar

Primeiro, você precisa fazer o build da própria ferramenta. Este é um procedimento padrão para projetos Go:

git clone https://github.com/open-telemetry/opentelemetry-go-compile-instrumentation.git
cd opentelemetry-go-compile-instrumentation
make build

Depois disso, você terá o binário otelc. Para testar em ação, você pode executar a aplicação demo do repositório. O processo inteiro se resume a um comando:

cd demo/app/basic
../../otelc go build
./basic

Se tudo correu bem, sua aplicação começará a gerar dados de telemetria, embora você não encontrará uma única menção ao OpenTelemetry no seu código-fonte.

Quem se beneficiaria disso

O projeto parece uma excelente ferramenta para quem mantém sistemas legados ou monoliths gigantes onde a implementação manual de tracing levaria meses. Também é um salva-vidas para times que querem manter seu código "estéril" de dependências de infraestrutura.

No entanto, vale a pena considerar que o projeto exige compreensão de como as regras de instrumentação funcionam. Se você precisar de algo específico que não seja coberto pelas regras padrão, será necessário mergulhar nos configs YAML e possivelmente escrever seus próprios hooks.

Definitivamente vale a pena experimentar a ferramenta se você está cansado de boilerplate ao redor de contexts e spans. Este é um passo em direção ao que a experiência moderna do desenvolvedor deveria ser: coisas complexas como observabilidade funcionam "out of the box" e não atrapalham a escrita de código.