🔭 Spring Boot 4 OTel: traces, métricas e logs em 1 dependência

A maioria dos devs Java ainda configura observabilidade manualmente — 8 dependências, logback-spring.xml customizado e horas de debug para traces que nem aparecem nos logs. Existe uma solução mais inteligente: o spring-boot-starter-opentelemetry do Spring Boot 4 entrega traces distribuídos, métricas OTLP e logs correlacionados com 1 dependência e 15 linhas de YAML. Descubra como implementar observabilidade de nível enterprise na sua API Java hoje.

O problema: observabilidade manual é um pesadelo de dependências

Se você manteve uma stack de observabilidade no Spring Boot 2 ou 3, sabe bem o que estou falando. Para ter traces, métricas e logs funcionando em conjunto — do jeito certo, com correlation IDs aparecendo nos logs, spans cobrindo todas as chamadas de banco e HTTP — você precisava de algo assim no pom.xml:

<!-- Spring Boot 3 — observabilidade manual (jeito antigo) -->
<dependency><groupId>io.micrometer</groupId><artifactId>micrometer-tracing-bridge-brave</artifactId></dependency>
<dependency><groupId>io.zipkin.reporter2</groupId><artifactId>zipkin-reporter-brave</artifactId></dependency>
<dependency><groupId>io.micrometer</groupId><artifactId>micrometer-registry-prometheus</artifactId></dependency>
<dependency><groupId>net.logstash.logback</groupId><artifactId>logstash-logback-encoder</artifactId><version>7.4</version></dependency>
<!-- + logback-spring.xml customizado + bean ObservationRegistry + conflitos de versão -->

Na empresa em que trabalhei como Tech Leader antes de criar o Meu Universo Nerd, chegamos a ter um ticket de 3 dias só para fazer o traceId aparecer nos logs do Kibana de forma consistente entre todos os microsserviços. Esse nível de complexidade acidental é o que o Spring Boot 4 eliminou.

A solução: spring-boot-starter-opentelemetry em 1 linha

Com Spring Boot 4 (a partir do 4.0.x), a Pivotal adotou OpenTelemetry como padrão de observabilidade nativo, substituindo o Brave como implementação padrão do Micrometer Tracing. O resultado é um starter que entrega tudo junto:

<!-- Spring Boot 4 — observabilidade completa com 1 dependência -->
<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-opentelemetry</artifactId>
</dependency>

Isso adiciona ao seu projeto: Tracing automático via OpenTelemetry SDK, Export OTLP para qualquer backend (Grafana Tempo, Jaeger, Datadog, New Relic), Correlação automática de logs com traceId/spanId injetados no MDC do Logback/Log4j2, Métricas via Micrometer integradas ao mesmo contexto de observabilidade, e Propagação W3C TraceContext por padrão.

Pensa no starter como aquela marmita completa: vem com arroz, feijão, proteína e salada — você não precisa montar cada componente separado. Antes você ia ao mercado comprar cada ingrediente separado e ainda precisava saber a receita de cabeça.

Configuração completa: 15 linhas de YAML

Após adicionar o starter, a configuração mínima para um ambiente com Grafana LGTM Stack fica assim:

spring:
  application:
    name: meu-servico  # aparece como service.name nos spans

management:
  tracing:
    sampling:
      probability: 1.0  # 100% em dev; ajustar para 0.1 em prod
  otlp:
    tracing:
      endpoint: http://localhost:4318/v1/traces
    metrics:
      export:
        enabled: true
        url: http://localhost:4318/v1/metrics

logging:
  pattern:
    level: "%5p [${spring.application.name},%X{traceId},%X{spanId}]"

Só isso. Sem logback-spring.xml customizado para injetar o traceId. Sem bean de ObservationRegistry. O auto-configure do Spring Boot 4 detecta o starter e registra tudo automaticamente — do jeito certo, como os sêniores fazem.

# Output esperado no log após uma request HTTP
INFO [meu-servico,65d3a1b2c4e5f6a7b8c9d0e1,a1b2c3d4e5f6a7b8] com.example.PedidoController : GET /pedidos/42 processado em 34ms
#           traceId (16 bytes hex)            spanId (8 bytes hex)

Instrumentação automática: o que vem de graça

O starter instrumenta automaticamente: Spring MVC / WebFlux, JDBC / Spring Data JPA (com SQL sanitizado), RestClient / WebClient / RestTemplate (propagação de traceId), Spring Messaging / Kafka / RabbitMQ, e @Scheduled tasks.

Para instrumentação customizada em métodos de negócio:

import io.micrometer.observation.annotation.Observed;
import io.opentelemetry.api.trace.Tracer;

@Service
public class ProcessamentoPedidoService {
    private final Tracer tracer;

    // Opção 1: @Observed — cria span + métrica automaticamente
    @Observed(name = "pedido.processar", contextualName = "processar-pedido")
    public Pedido processar(Long pedidoId) {
        return buscarEProcessar(pedidoId);
    }

    // Opção 2: API programática para controle fino dos atributos do span
    public void notificarParceiro(Pedido pedido) {
        var span = tracer.spanBuilder("notificar-parceiro")
            .setAttribute("parceiro.id", pedido.getParceiroId())
            .startSpan();
        try (var scope = span.makeCurrent()) {
            parceiroClient.notificar(pedido);
        } catch (Exception e) {
            span.recordException(e);
            throw e;
        } finally {
            span.end();
        }
    }
}

Migração do Spring Boot 3: passo a passo sem big bang

Se você está migrando de Spring Boot 3 com Brave/Zipkin:

<!-- 1. Remover: micrometer-tracing-bridge-brave, zipkin-reporter-brave -->
<!-- 2. Adicionar: -->
<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-opentelemetry</artifactId>
</dependency>

# DE: management.zipkin.tracing.endpoint: http://zipkin:9411/api/v2/spans
# PARA:
management:
  otlp:
    tracing:
      endpoint: http://tempo:4318/v1/traces
  tracing:
    sampling:
      probability: 1.0

Se o seu Zipkin está na versão 10.x+, ele também aceita OTLP via receiver. Tá? Sem big bang.

FAQ — Perguntas frequentes

O starter funciona com Spring Boot 3? Não na forma nativa. No SB3, use micrometer-tracing-bridge-otel como bridge.

Posso usar junto com o Java Agent OTel? Não — haverá instrumentação duplicada. Escolha um dos dois.

O overhead em produção é aceitável? Com 10% de sampling, o overhead é inferior a 2%. Para 100%, pode chegar a 8-12% — use apenas em dev/staging.

Como exportar para Datadog ou New Relic? Eles aceitam OTLP nativo — mude apenas o endpoint e adicione o header de autenticação.

MongoDB e Redis são instrumentados automaticamente? Sim para ambos via drivers nativos.

Conclusão: observabilidade enterprise com 1 linha

• 1 dependência substitui 5-7 libs manuais de observabilidade do Spring Boot 3
• Correlação automática de logs com traceId/spanId — zero configuração de MDC
• Funciona com qualquer backend OTLP: Grafana, Datadog, New Relic, Jaeger

No mercado de hoje, observabilidade com OTel é o padrão nas fintechs brasileiras. Stone, Nubank e C6 Bank declararam adoção do OTLP como protocolo padrão nos últimos 12 meses. Dominar esse tema significa estar na frente nas entrevistas para posições sênior que pedem "experiência com observabilidade distribuída".

Você já está usando OpenTelemetry na sua stack Java? Conta nos comentários — quero saber como está sendo essa transição nas equipes de vocês.

Na próxima semana: como configurar o Grafana LGTM Stack localmente com Docker Compose para testar toda essa observabilidade sem subir nada em cloud.