Tracing com OpenTelemetry sem tocar na sua infraestrutura

A maioria dos guias de “adicione observabilidade à sua aplicação Rails” começa levantando um coletor. A parte que realmente dá trabalho não é o coletor — é colocar as variáveis de ambiente certas em todo ambiente de forma consistente, manualmente, sem erro de digitação, toda vez que um serviço novo entra.

O que a plataforma realmente define

Settings → General → OpenTelemetry recebe um endpoint OTLP, um protocolo (http/protobuf, http/json ou grpc), e headers opcionais — uma chave de API do Honeycomb, por exemplo. Os headers são armazenados criptografados. No próximo deploy, a Railyard define exatamente o que todo SDK do OpenTelemetry já espera ler:

• OTEL_EXPORTER_OTLP_ENDPOINT, OTEL_EXPORTER_OTLP_PROTOCOL, OTEL_EXPORTER_OTLP_HEADERS
• OTEL_SERVICE_NAME — o próprio nome da aplicação, não algo pra inventar
• OTEL_RESOURCE_ATTRIBUTES — carrega o SHA do commit, o ambiente, a aplicação e a equipe, então um trace pode ser atribuído a um deploy exato sem você configurar isso manualmente

Defina qualquer uma dessas você mesmo e o seu valor prevalece — isso é um padrão, não um lock-in.

O que vem com a sua aplicação, não com a plataforma

As variáveis são do lado da plataforma. A instrumentação de fato ainda é o SDK neutro em relação a fornecedor, que você adiciona como qualquer outra dependência:

• Rails: opentelemetry-sdk, opentelemetry-exporter-otlp, opentelemetry-instrumentation-all com c.use_all, em http/protobuf.
• Node: @opentelemetry/auto-instrumentations-node/register.
• Python: opentelemetry-instrument.

Nada nisso é específico da Railyard — o mesmo SDK funciona sem modificação contra qualquer coletor OTLP, que é exatamente o ponto do protocolo. O trabalho da plataforma termina em acertar as variáveis toda vez, não em substituir a camada de instrumentação.

As próprias métricas da plataforma, no mesmo canal

Marque também enviar as métricas de CPU, memória e requisições da Railyard e a plataforma publica os próprios números em <endpoint>/v1/metrics a cada minuto, via OTLP HTTP — então as métricas de infraestrutura e os traces da aplicação caem no mesmo backend em vez de dois painéis separados que você tem que correlacionar mentalmente.

Onde isso se encaixa junto com logs e alertas

O OpenTelemetry cobre traces e métricas; a busca de logs do dia a dia, buscas salvas com alertas, e drains de log pro seu próprio destino são um caminho separado e mais simples que não precisa de SDK nenhum — útil quando um trace é um exagero e você só precisa dar um grep na saída de produção. Os alertas de métrica (tempo de resposta p95, taxa de 5xx, memória, CPU) funcionam independentemente de o OTel estar configurado ou não.

Referência completa: Logs, métricas e alertas.