Capítulo 1: Introdução ao Spring Boot Actuator

Introdução

Spring Boot Actuator adiciona funcionalidades de monitoramento e gestão à sua aplicação. Ele expõe endpoints HTTP que permitem monitorar o estado de saúde, métricas e diagnosticar problemas.

---

🎯 Objetivos do Capítulo

Ao final deste capítulo, você saberá:

1. ✅ O que é o Actuator e por que utilizá-lo
2. ✅ Adicionar o Actuator ao seu projeto
3. ✅ Configurar os endpoints
4. ✅ Proteger o acesso aos endpoints

---

1. O que é o Actuator?

Funcionalidades Principais

Spring Boot Actuator fornece:
├── Health Checks: A aplicação está funcionando?
├── Métricas: Performance, uso de memória, requisições/segundo
├── Info: Informações sobre a aplicação (versão, build)
├── Environment: Configuração e variáveis de ambiente
├── Loggers: Alterar níveis de log em tempo real
├── Thread Dump: Analisar as threads
├── Heap Dump: Analisar a memória
└── HTTP Trace: Histórico de requisições

Casos de Uso

1. Kubernetes: Probes de liveness/readiness
2. Load Balancer: Verificar se a instância está saudável
3. Prometheus: Coletar métricas
4. Debugging: Diagnosticar em produção
5. DevOps: Automatizar os deploys

---

2. Instalação

Dependência Maven

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-actuator</artifactId>
</dependency>

Gradle

implementation 'org.springframework.boot:spring-boot-starter-actuator'

---

3. Configuração Básica

Ativar os Endpoints

Por padrão, apenas /actuator/health é exposto via HTTP.

# application.properties

# Expor todos os endpoints via HTTP
management.endpoints.web.exposure.include=*

# Ou expor apenas alguns endpoints
management.endpoints.web.exposure.include=health,info,metrics,prometheus

# Excluir endpoints sensíveis
management.endpoints.web.exposure.exclude=env,beans

Verificar a Instalação

# Iniciar a aplicação
mvn spring-boot:run

# Listar todos os endpoints disponíveis
curl http://localhost:8080/actuator

Resposta:

{
  "_links": {
    "self": {"href": "http://localhost:8080/actuator"},
    "health": {"href": "http://localhost:8080/actuator/health"},
    "info": {"href": "http://localhost:8080/actuator/info"},
    "metrics": {"href": "http://localhost:8080/actuator/metrics"},
    "loggers": {"href": "http://localhost:8080/actuator/loggers"}
  }
}

---

4. Porta e Path Personalizados

Separar a Porta de Management

# Porta separada para o Actuator (recomendado em produção)
management.server.port=8081

# A aplicação permanece em 8080
# Actuator acessível em 8081

Vantagens:

• Isolar o tráfego de monitoramento
• Configurar um firewall diferente
• Não expor na Internet

Personalizar o Path

# Alterar o path base
management.endpoints.web.base-path=/admin/monitoring

# Os endpoints estarão em:
# /admin/monitoring/health
# /admin/monitoring/info
# etc.

---

5. Segurança dos Endpoints

Com Spring Security

@Configuration
@EnableWebSecurity
public class SecurityConfig {

    @Bean
    public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
        http
            .authorizeHttpRequests(auth -> auth
                // Endpoints públicos
                .requestMatchers("/actuator/health").permitAll()
                .requestMatchers("/actuator/info").permitAll()
                
                // Endpoints para Prometheus (apenas IP interno)
                .requestMatchers("/actuator/prometheus").permitAll()
                
                // Todos os outros endpoints Actuator: apenas ADMIN
                .requestMatchers("/actuator/**").hasRole("ADMIN")
                
                // Resto da aplicação
                .anyRequest().authenticated()
            )
            .httpBasic(Customizer.withDefaults());
        
        return http.build();
    }
}

Desabilitar Endpoints

# Desabilitar completamente um endpoint
management.endpoint.shutdown.enabled=false
management.endpoint.env.enabled=false

# Desabilitar todos, depois habilitar seletivamente
management.endpoints.enabled-by-default=false
management.endpoint.health.enabled=true
management.endpoint.info.enabled=true
management.endpoint.metrics.enabled=true

---

6. Endpoints Essenciais

/actuator/health

curl http://localhost:8080/actuator/health

{
  "status": "UP"
}

Com detalhes:

management.endpoint.health.show-details=always

{
  "status": "UP",
  "components": {
    "db": {
      "status": "UP",
      "details": {
        "database": "H2",
        "validationQuery": "isValid()"
      }
    },
    "diskSpace": {
      "status": "UP",
      "details": {
        "total": 499963174912,
        "free": 234567891234,
        "threshold": 10485760
      }
    }
  }
}

/actuator/info

# Adicionar informações personalizadas
info.app.name=My Application
info.app.version=1.0.0
info.app.description=Aplicação de demo
info.contact.email=support@example.com

# Informações do Git (se spring-boot-maven-plugin configurado)
management.info.git.mode=full

curl http://localhost:8080/actuator/info

{
  "app": {
    "name": "My Application",
    "version": "1.0.0",
    "description": "Aplicação de demo"
  },
  "contact": {
    "email": "support@example.com"
  }
}

/actuator/metrics

# Listar todas as métricas
curl http://localhost:8080/actuator/metrics

# Uma métrica específica
curl http://localhost:8080/actuator/metrics/jvm.memory.used

{
  "name": "jvm.memory.used",
  "measurements": [
    {"statistic": "VALUE", "value": 123456789}
  ],
  "availableTags": [
    {"tag": "area", "values": ["heap", "nonheap"]},
    {"tag": "id", "values": ["G1 Eden Space", "G1 Old Gen"]}
  ]
}

---

7. Configuração Completa Recomendada

# ===== ACTUATOR =====

# Expor os endpoints necessários
management.endpoints.web.exposure.include=health,info,metrics,prometheus,loggers

# Porta separada (opcional, mas recomendado em produção)
# management.server.port=8081

# Health com detalhes
management.endpoint.health.show-details=when_authorized
management.endpoint.health.show-components=when_authorized

# Info personalizado
info.app.name=@project.name@
info.app.version=@project.version@
info.app.encoding=@project.build.sourceEncoding@
info.java.version=@java.version@

# Ativar informações de build
management.info.build.enabled=true
management.info.git.enabled=true
management.info.env.enabled=true

# Métricas
management.metrics.tags.application=${spring.application.name}

---

8. Resumo

Instalação

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-actuator</artifactId>
</dependency>

Configuração Mínima

management.endpoints.web.exposure.include=health,info,metrics
management.endpoint.health.show-details=always

Endpoints Principais

Endpoint	Uso
/actuator/health	Estado de saúde
/actuator/info	Informações da aplicação
/actuator/metrics	Métricas de performance
/actuator/loggers	Níveis de log
/actuator/env	Variáveis de ambiente

---

🎯 Próximo Passo

Vamos explorar em detalhes todos os endpoints disponíveis.

➡️ Capítulo 2: Os Endpoints

---

⬅️ Voltar ao Módulo 11