Capítulo 2: Endpoints do Actuator

Introdução

O Actuator fornece diversos endpoints prontos para uso. Este capítulo explora os mais úteis e mostra como criar os seus próprios.

🎯 Objetivos do Capítulo

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

✅ Utilizar todos os endpoints nativos
✅ Entender quando usar cada endpoint
✅ Criar endpoints personalizados
✅ Filtrar e formatar as respostas

1. Lista de Endpoints

Endpoints Básicos

Endpoint	Descrição	Sensível?
`/actuator`	Lista todos os endpoints	Não
`/actuator/health`	Estado de saúde	Não
`/actuator/info`	Informações da aplicação	Não

Endpoints de Análise

Endpoint	Descrição	Sensível?
`/actuator/beans`	Lista todos os beans do Spring	Sim
`/actuator/conditions`	Condições de auto-configuração	Sim
`/actuator/configprops`	Propriedades de configuração	Sim
`/actuator/env`	Variáveis de ambiente	Sim
`/actuator/mappings`	Todos os @RequestMapping	Sim

Endpoints de Métricas

Endpoint	Descrição	Sensível?
`/actuator/metrics`	Lista as métricas	Não
`/actuator/metrics/\{name\}`	Uma métrica específica	Não
`/actuator/prometheus`	Formato Prometheus	Não

Endpoints de Debugging

Endpoint	Descrição	Sensível?
`/actuator/loggers`	Níveis de log	Sim
`/actuator/threaddump`	Dump de threads	Sim
`/actuator/heapdump`	Dump de memória (arquivo)	Sim
`/actuator/httptrace`	Histórico HTTP	Sim

Endpoints de Ações

Endpoint	Descrição	Sensível?
`/actuator/shutdown`	Parar a aplicação	Sim
`/actuator/refresh`	Atualizar a configuração	Sim

2. Endpoints em Detalhe

/actuator/beans

Lista todos os beans Spring da aplicação:

curl http://localhost:8080/actuator/beans

{
  "contexts": {
    "application": {
      "beans": {
        "userService": {
          "aliases": [],
          "scope": "singleton",
          "type": "com.example.service.UserService",
          "dependencies": ["userRepository"]
        },
        "userController": {
          "aliases": [],
          "scope": "singleton",
          "type": "com.example.controller.UserController",
          "dependencies": ["userService"]
        }
      }
    }
  }
}

Utilidade: Depurar a injeção de dependências.

/actuator/conditions

Mostra por que as auto-configurações foram aplicadas ou não:

curl http://localhost:8080/actuator/conditions

{
  "contexts": {
    "application": {
      "positiveMatches": {
        "DataSourceAutoConfiguration": [{
          "condition": "OnClassCondition",
          "message": "@ConditionalOnClass found required classes 'javax.sql.DataSource'"
        }]
      },
      "negativeMatches": {
        "RedisAutoConfiguration": {
          "notMatched": [{
            "condition": "OnClassCondition",
            "message": "@ConditionalOnClass did not find required class 'org.springframework.data.redis.core.RedisOperations'"
          }]
        }
      }
    }
  }
}

Utilidade: Entender por que uma feature está ativada/desativada.

/actuator/env

Exibe todas as fontes de configuração:

curl http://localhost:8080/actuator/env

{
  "activeProfiles": ["dev"],
  "propertySources": [
    {
      "name": "systemProperties",
      "properties": {
        "java.version": {"value": "17.0.1"}
      }
    },
    {
      "name": "applicationConfig: [classpath:/application.properties]",
      "properties": {
        "spring.datasource.url": {"value": "jdbc:h2:mem:testdb"}
      }
    }
  ]
}

Uma propriedade específica:

curl http://localhost:8080/actuator/env/spring.datasource.url

/actuator/mappings

Lista todos os endpoints HTTP da aplicação:

curl http://localhost:8080/actuator/mappings

{
  "contexts": {
    "application": {
      "mappings": {
        "dispatcherServlets": {
          "dispatcherServlet": [
            {
              "handler": "com.example.controller.UserController#getAll()",
              "predicate": "{GET /api/users}",
              "details": {
                "requestMappingConditions": {
                  "methods": ["GET"],
                  "patterns": ["/api/users"]
                }
              }
            }
          ]
        }
      }
    }
  }
}

Utilidade: Ver todos os endpoints disponíveis.

/actuator/loggers

Ver e modificar os níveis de log em tempo real:

# Ver todos os loggers
curl http://localhost:8080/actuator/loggers

# Um logger específico
curl http://localhost:8080/actuator/loggers/com.example.service

{
  "configuredLevel": null,
  "effectiveLevel": "DEBUG"
}

Alterar um nível em tempo real (POST):

curl -X POST http://localhost:8080/actuator/loggers/com.example.service \
  -H "Content-Type: application/json" \
  -d '{"configuredLevel": "DEBUG"}'

Utilidade: Ativar DEBUG em produção sem reiniciar!

/actuator/threaddump

Exibe o estado de todas as threads:

curl http://localhost:8080/actuator/threaddump

{
  "threads": [
    {
      "threadName": "http-nio-8080-exec-1",
      "threadId": 23,
      "blockedTime": -1,
      "blockedCount": 0,
      "waitedTime": -1,
      "waitedCount": 2,
      "lockName": null,
      "threadState": "RUNNABLE",
      "stackTrace": [
        {
          "className": "java.net.SocketInputStream",
          "methodName": "socketRead0",
          "lineNumber": -2,
          "nativeMethod": true
        }
      ]
    }
  ]
}

Utilidade: Detectar deadlocks, threads bloqueadas.

/actuator/heapdump

Gera um arquivo de heap dump (atenção: pesado!):

curl -O http://localhost:8080/actuator/heapdump
# Gera um arquivo heapdump que você pode analisar com VisualVM ou MAT

Utilidade: Analisar vazamentos de memória.

/actuator/shutdown (Perigoso!)

Encerra a aplicação de forma limpa:

# Deve ser explicitamente ativado
management.endpoint.shutdown.enabled=true

curl -X POST http://localhost:8080/actuator/shutdown

{
  "message": "Shutting down, bye..."
}

⚠️ Deve ser absolutamente protegido!

3. Endpoints Personalizados

Criar um Endpoint Simples

import org.springframework.boot.actuate.endpoint.annotation.Endpoint;
import org.springframework.boot.actuate.endpoint.annotation.ReadOperation;
import org.springframework.stereotype.Component;

@Component
@Endpoint(id = "custom")
public class CustomEndpoint {

    @ReadOperation
    public Map<String, Object> customInfo() {
        return Map.of(
            "status", "operational",
            "timestamp", LocalDateTime.now(),
            "version", "1.0.0"
        );
    }
}

curl http://localhost:8080/actuator/custom

{
  "status": "operational",
  "timestamp": "2024-01-15T10:30:00",
  "version": "1.0.0"
}

Endpoint com Parâmetros

@Component
@Endpoint(id = "features")
public class FeaturesEndpoint {

    private final Map<String, Boolean> features = new ConcurrentHashMap<>();

    @ReadOperation
    public Map<String, Boolean> getAllFeatures() {
        return features;
    }

    @ReadOperation
    public Boolean getFeature(@Selector String name) {
        return features.getOrDefault(name, false);
    }

    @WriteOperation
    public void setFeature(@Selector String name, boolean enabled) {
        features.put(name, enabled);
    }

    @DeleteOperation
    public void deleteFeature(@Selector String name) {
        features.remove(name);
    }
}

# Ler todas as features
curl http://localhost:8080/actuator/features

# Ler uma feature
curl http://localhost:8080/actuator/features/dark-mode

# Ativar uma feature
curl -X POST "http://localhost:8080/actuator/features/dark-mode?enabled=true"

# Remover uma feature
curl -X DELETE http://localhost:8080/actuator/features/dark-mode

Endpoint para Estatísticas de Negócio

@Component
@Endpoint(id = "business-stats")
@RequiredArgsConstructor
public class BusinessStatsEndpoint {

    private final OrderRepository orderRepository;
    private final UserRepository userRepository;

    @ReadOperation
    public Map<String, Object> getStats() {
        return Map.of(
            "totalUsers", userRepository.count(),
            "totalOrders", orderRepository.count(),
            "ordersToday", orderRepository.countByCreatedAtAfter(LocalDate.now().atStartOfDay()),
            "revenue", orderRepository.sumTotalAmount()
        );
    }
}

4. Web Endpoints vs JMX

Exposição Web (HTTP)

# Expor via HTTP
management.endpoints.web.exposure.include=health,info,metrics

Exposição JMX

# Expor via JMX (para JConsole, VisualVM)
management.endpoints.jmx.exposure.include=*

# Desabilitar JMX se não for utilizado
spring.jmx.enabled=false

5. Resumo

Endpoints Recomendados em Produção

Endpoint	Exposição	Uso
`/health`	Público	Load balancer, K8s
`/info`	Público	Versão, build
`/metrics`	Interno	Prometheus
`/prometheus`	Interno	Scraping
`/loggers`	Admin	Debug em tempo real

Endpoints a Proteger

/actuator/env         → Expõe segredos!
/actuator/heapdump    → Dados sensíveis!
/actuator/shutdown    → Para o app!
/actuator/beans       → Arquitetura interna

Criar um Endpoint

@Component
@Endpoint(id = "my-endpoint")
public class MyEndpoint {
    
    @ReadOperation    // GET
    public Data read() { }
    
    @WriteOperation   // POST
    public void write() { }
    
    @DeleteOperation  // DELETE
    public void delete() { }
}

🎯 Próximo Passo

Endpoints são ótimos, mas como medir a performance? Hora das métricas!

➡️ Capítulo 3: Métricas com Micrometer

⬅️ Voltar ao Módulo 11

Introdução​

🎯 Objetivos do Capítulo​

1. Lista de Endpoints​

Endpoints Básicos​

Endpoints de Análise​

Endpoints de Métricas​

Endpoints de Debugging​

Endpoints de Ações​

2. Endpoints em Detalhe​

/actuator/beans​

/actuator/conditions​

/actuator/env​

/actuator/mappings​

/actuator/loggers​

/actuator/threaddump​

/actuator/heapdump​

/actuator/shutdown (Perigoso!)​

3. Endpoints Personalizados​

Criar um Endpoint Simples​

Endpoint com Parâmetros​

Endpoint para Estatísticas de Negócio​

4. Web Endpoints vs JMX​

Exposição Web (HTTP)​

Exposição JMX​

5. Resumo​

Endpoints Recomendados em Produção​

Endpoints a Proteger​

Criar um Endpoint​

🎯 Próximo Passo​