🔭 Spring Boot 4 tem observabilidade nativa sem Actuator

Existe uma forma de configurar traces, métricas e logs no Spring Boot 4 sem depender do Actuator como intermediário. A maioria dos devs ainda não sabe que o starter oficial de OpenTelemetry mudou tudo. Com 2 dependências no pom.xml você tem instrumentação automática de produção pronta para enviar dados a qualquer backend: Grafana, Jaeger, Datadog ou o seu próprio coletor OTLP.

Nesse artigo você vai entender por que o modelo anterior (Actuator + Micrometer + bridge OTEL) criava fricção desnecessária, como o novo starter do Spring Boot 4 simplifica tudo isso, e ver o código de configuração completo para colocar sua app em produção observável hoje.

O problema com a stack de observabilidade anterior

Antes do Spring Boot 4, configurar observabilidade completa exigia montar uma cadeia de dependências que poucos conseguiam acertar de primeira. O fluxo típico era: Actuator como base, Micrometer para métricas, micrometer-tracing-bridge-otel para conectar ao OpenTelemetry, e ainda um exportador específico por backend.

Na empresa em que trabalhei como Tech Leader, vimos times inteiros perdendo dias depurando por que os traces não apareciam no Grafana Tempo, apenas para descobrir que a versão do bridge estava incompatível com a versão do Micrometer. O problema não era o código de negócio, era a configuração de observabilidade.

O pom.xml de uma app bem instrumentada em Spring Boot 3.x parecia assim:

<!-- Spring Boot 3.x: a cadeia de dependências manual -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-actuator</artifactId>
</dependency>
<dependency>
    <groupId>io.micrometer</groupId>
    <artifactId>micrometer-tracing-bridge-otel</artifactId>
</dependency>
<dependency>
    <groupId>io.opentelemetry</groupId>
    <artifactId>opentelemetry-exporter-otlp</artifactId>
</dependency>

Cada dependência tem seu ciclo de release independente. Quando o Spring Boot atualiza o Micrometer e o bridge ainda não acompanhou, você fica com spans aparecendo incompletos ou simplesmente não chegando ao backend. Esse era o estado da arte até o Spring Boot 4.

O que o Spring Boot 4 muda com o starter oficial de OTel

O Spring Boot 4 lançou o spring-boot-starter-opentelemetry, um starter que encapsula toda a instrumentação OpenTelemetry como cidadão de primeira classe no ecossistema Spring, sem necessidade do Actuator como intermediário para o pipeline de traces.

A diferença conceitual é importante: o Actuator foi pensado para expor métricas e health checks via HTTP. O OpenTelemetry foi projetado desde o início para exportar dados de observabilidade via protocolo OTLP para qualquer backend. São propósitos diferentes, e o Spring Boot 4 reconhece isso separando as responsabilidades.

O pom.xml com o starter oficial fica assim:

<!-- Spring Boot 4: starter oficial de OpenTelemetry -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-opentelemetry</artifactId>
</dependency>

<!-- Exportador OTLP (HTTP ou gRPC para seu coletor) -->
<dependency>
    <groupId>io.opentelemetry</groupId>
    <artifactId>opentelemetry-exporter-otlp</artifactId>
</dependency>

Duas dependências e sua app já instrumenta automaticamente: requests HTTP, chamadas JDBC, operações de cache, chamadas a serviços externos via RestClient ou WebClient. Tudo sem nenhuma anotação no código de negócio.

Configuração completa para produção

O application.yml de uma app Spring Boot 4 com OTel configurado para enviar para um OpenTelemetry Collector local se parece assim:

spring:
  application:
    name: minha-api          # nome do servico nos traces

management:
  tracing:
    sampling:
      probability: 1.0       # 100% em dev, 0.1 (10%) em producao

otel:
  exporter:
    otlp:
      endpoint: http://localhost:4318/v1/traces
      protocol: http/protobuf
  resource:
    attributes:
      deployment.environment: producao
      service.version: ${APP_VERSION:1.0.0}

No Spring Boot 4, a configuração está centralizada sob o namespace otel.* com auto-configuração que detecta o exportador e configura o pipeline inteiro automaticamente.

Instrumentação automática: o que vem out of the box

O starter do Spring Boot 4 habilita instrumentação automática para as integrações mais comuns do ecossistema Spring sem nenhuma configuração adicional:

• HTTP requests: spans criados automaticamente para cada request recebido, com atributos de URL, método, status code e latência
• Spring Data / JDBC: spans para queries SQL com a query sanitizada (sem valores de parâmetro por padrão, por segurança)
• RestClient e WebClient: propagação automática do contexto de trace em chamadas HTTP outbound (header traceparent injetado automaticamente)
• Spring Messaging / Kafka: propagação de contexto em mensagens assíncronas via W3C TraceContext
• Scheduled tasks: spans para métodos anotados com @Scheduled

Para verificar que a instrumentação está funcionando, adicione um controller simples e observe os logs estruturados que o starter gera automaticamente:

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

@RestController
public class PedidoController {

    private static final Logger log = LoggerFactory.getLogger(PedidoController.class);

    @GetMapping("/pedidos")
    public String listarPedidos() {
        log.info("Listando pedidos");
        return "ok";
    }
}

O log gerado automaticamente inclui o traceId e spanId do request atual, sem nenhuma configuração adicional no Logback ou Log4j2:

INFO [minha-api,4bf92f3577b34da6a3ce929d0e0e4736,00f067aa0ba902b7] PedidoController - Listando pedidos

Esse formato com traceId embutido no log é o que permite correlacionar um log de erro com o trace completo no Grafana Tempo ou Jaeger — basta copiar o traceId e colar na busca do backend de traces. Isso é o que o mercado chama de correlação de logs e traces, e no Spring Boot 4 vem configurado por padrão.

Jeito errado vs jeito certo: migração do Actuator para o starter OTel

Se você tem uma app Spring Boot 3.x com Actuator configurada para observabilidade, a migração para o Spring Boot 4 com o starter OTel segue esse caminho:

<!-- ANTES (Spring Boot 3.x) -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-actuator</artifactId>
</dependency>
<dependency>
    <groupId>io.micrometer</groupId>
    <artifactId>micrometer-tracing-bridge-otel</artifactId>
    <version>1.3.4</version> <!-- versão fixada por incompatibilidade -->
</dependency>
<dependency>
    <groupId>io.opentelemetry</groupId>
    <artifactId>opentelemetry-exporter-zipkin</artifactId>
</dependency>

<!-- DEPOIS (Spring Boot 4) -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-opentelemetry</artifactId>
    <!-- sem versão fixada: BOM do Spring Boot gerencia -->
</dependency>
<dependency>
    <groupId>io.opentelemetry</groupId>
    <artifactId>opentelemetry-exporter-otlp</artifactId>
</dependency>

Uma analogia para quem não é do mundo de observabilidade: pense no Actuator como um painel de controle de avião que foi adaptado para também mostrar o radar. Funciona, mas o radar foi pensado para ter seu próprio painel. O starter OTel do Spring Boot 4 é o painel de radar próprio, construído do zero para a função certa.

O Actuator ainda tem seu lugar no Spring Boot 4 para health checks, beans endpoint e métricas JVM expostas via HTTP. Mas para o pipeline de observabilidade distribuída (traces + métricas + logs exportados para um backend), o starter OTel é a escolha certa no mercado de hoje.

Impacto prático: o que muda para o dev e para a empresa

Para o desenvolvedor, a mudança mais imediata é a eliminação do problema de compatibilidade de versões entre Micrometer, o bridge OTEL e o exportador. Com o BOM do Spring Boot 4 gerenciando as versões do OpenTelemetry SDK, você não precisa mais fixar versões manualmente nem torcer para que o upgrade do Spring Boot não quebre a cadeia de observabilidade.

Para a empresa, o impacto vai além da ergonomia. O protocolo OTLP (OpenTelemetry Protocol) é o padrão de fato do mercado para exportação de dados de observabilidade. Isso significa que sua stack de observabilidade deixa de ser dependente de um vendor específico: você pode trocar de Datadog para Grafana, de Zipkin para Jaeger, ou adicionar múltiplos backends sem mudar uma linha do código da aplicação, apenas reconfigurando o coletor OTLP.

Benchmarks publicados no blog oficial do Spring mostram que o overhead de instrumentação automática do starter OTel em aplicações Spring Boot 4 fica entre 2-5% de latência adicional por request com sampling de 100%, aceitável para a maioria dos cenários de produção. Com sampling de 10% (padrão recomendado para produção), o overhead é praticamente imperceptível.

Quando manter o Actuator e quando usar apenas o starter OTel

O Actuator e o starter OTel não são mutuamente exclusivos — você pode usar os dois. A decisão depende do que você precisa:

Use apenas o starter OTel quando:

• Você precisa de distributed tracing, métricas e logs exportados para um backend externo
• Sua stack de observabilidade usa OTLP (Grafana, Datadog, Dynatrace, Honeycomb)
• Você quer eliminar as versões fixadas do bridge Micrometer

Mantenha o Actuator também quando:

• Você usa health checks do Actuator em probes de Kubernetes (/actuator/health/liveness)
• Você expõe métricas JVM via /actuator/prometheus para scraping do Prometheus
• Você usa o /actuator/beans ou /actuator/env para debugging em produção

Nos projetos que gerencio como Tech Leader, a configuração padrão virou: starter OTel para o pipeline de traces/logs, Actuator apenas para health probes e o endpoint Prometheus. O pipeline de observabilidade distribuída fica 100% no domínio do OTel, que é onde foi desenhado para estar.

FAQ: OpenTelemetry no Spring Boot 4

Preciso do Java Agent do OpenTelemetry se uso o starter?
Não. O starter do Spring Boot 4 usa o OpenTelemetry SDK diretamente, com instrumentação via Spring AOP e auto-configuração. O Java Agent é uma alternativa para apps sem controle do build (apps legadas), mas para apps Spring Boot 4 novas o starter é a abordagem preferida e oficialmente suportada.

O starter OTel do Spring Boot 4 substitui completamente o Micrometer?
Não completamente. O Micrometer ainda é usado internamente para métricas no Spring Boot 4. O que mudou é que o bridge micrometer-tracing-bridge-otel agora é gerenciado pelo BOM do Spring Boot, eliminando o problema de versões incompatíveis que afetava o Boot 3.x.

Posso usar o starter OTel com Spring Boot 3.x?
O starter oficial spring-boot-starter-opentelemetry é exclusivo do Spring Boot 4. No 3.x, a abordagem é via micrometer-tracing-bridge-otel. A migração para o Boot 4 é o caminho para adotar o starter oficial.

O starter suporta export de logs além de traces e métricas?
Sim. O Spring Boot 4 com o starter OTel suporta exportação de logs via OTLP também, usando o appender OTel para Logback/Log4j2. Os três pilares da observabilidade (traces, métricas, logs) ficam no mesmo pipeline OTLP para o mesmo backend.

Como testar que os traces chegam ao backend sem um coletor rodando?
Adicione o exportador opentelemetry-exporter-logging nas dependências de teste e configure otel.exporter.otlp.endpoint apontando para http://localhost:4318 com um coletor local em Docker. Para testes unitários, use o InMemorySpanExporter do SDK para assertar spans gerados sem depender de infraestrutura.

Conclusão: observabilidade como cidadã de primeira classe no Spring Boot 4

O starter oficial de OpenTelemetry no Spring Boot 4 não é apenas uma conveniência, é uma mudança de paradigma. Observabilidade deixa de ser uma preocupação de configuração e passa a ser um contrato do framework, da mesma forma que segurança e gerenciamento de transações sempre foram.

Os três takeaways principais do que vimos nesse artigo:

• Menos dependências, menos conflitos: o BOM do Spring Boot 4 gerencia as versões do OTel SDK, eliminando o problema crônico de versões incompatíveis do bridge Micrometer
• Instrumentação automática out of the box: HTTP, JDBC, RestClient, Kafka instrumentados sem uma linha de código de negócio
• Vendor-neutral por design: OTLP como protocolo padrão significa liberdade de trocar backends sem mudar a aplicação

Você já está usando OpenTelemetry na sua stack Spring Boot? Faz sentido migrar do Actuator para o starter OTel ou você prefere manter os dois rodando juntos? Conta nos comentários como está sendo na sua realidade de produção.

Nos próximos artigos vou mostrar como configurar a stack LGTM completa (Loki + Grafana + Tempo + Mimir) com Docker Compose para ter uma plataforma de observabilidade enterprise de graça, e como usar o Spring Boot 4 com Virtual Threads para escalar junto com a observabilidade nativa.