Um dos recursos que mais gosto no Spring Boot e que normalmente negligenciado por quem usa o framework o Actuator: natural, dado que o foco normalmente est no cdigo sendo escrito e no aps ter sido implantado.

O Actuator um recurso do Spring Boot que nos permite monitorar e gerenciar aplicaes escritas neste framework em seu ambiente de implantao. bastante rico e fcil de ser usado: j vm com diversos recursos prontos pra uso sem que voc precise escrever uma nica linha de cdigo e ser nosso assunto aqui.

A curiosa histria deste texto e dos prximos

Quando comecei a escrever este texto lembrei que pouca gente conhecia um recurso similar que temos no Java SE chamado JMX, ento escrevi aquele post apresentando a tecnologia. Quando finalmente voltei ao objetivo inicial o resultado foi um texto imenso. Sendo assim resolvi dividi-lo em partes: nesta primeira vou apresentar uma viso geral sobre o Actuator e nos restantes vamos ver os recursos que mais usamos em nosso dia a dia.

Vou te mostrar o que o Actuator, suas principais aplicaes (por alto, vou detalhar tudo isto nos posts mais a frente (j esto prontos, "s falta testar")), as principais configuraes e, finalmente, pontos fundamentais relativos segurana do seu projeto.

O que o Actuator?

Talvez o Actuator no seja to usado e conhecido pelo modo como apresentado pela equipe do Spring Boot e traduzido para o portugus: "production-ready features", a traduzem como "funcionalidades para o ambiente de produo". Pior: a maior parte dos livros em portugus tem como foco a escrita de cdigo e no mximo a implantao, ignorando aquela que pra mim a fase mais importante: a ps implantao.

O Spring Boot oferece equipe de desenvolvimento todo o ferramental necessrio para que possa monitorar e gerenciar sua aplicao aps ter sido implantada. Com ele voc pode:

• Monitorar a aplicao, isto , acompanhar diversos aspectos da sua execuo aps implantada.
• Gerenciar a aplicao, ou seja, interagir com o sistema com ele em execuo operando aes neste como, por exemplo, limpeza de cache, tarefas administrativas, alterao de configuraes e muito mais.

Ok, voc leu o meu texto sobre JMX e viu as mesmas frases. Ento qual a diferena? H algumas.

• O protocolo padro o HTTP usando REST como padro, o que facilita seu uso (h riscos de segurana que vou ensinar a minimizar mais a frente).
• Alm do protocolo HTTP tambm pode usar JMX, que o mecanismo padro de instrumentao do Java.
• Assim como o JMX j vm com uma srie de indicadores relativos ao funcionamento da JVM por padro, o Actuator trs diversas outras categorias de indicadores, a maior parte voltados para o contexto de aplicaes web.
• Tem como base o Spring Boot - est amarrado ao framework portanto, voc no conseguir us-lo de forma fcil em outros frameworks.
• Fornece a plataforma para que diversos mdulos do Spring Boot possam fornecer seus prprios.

Resumindo: o Actuator nos d todos os recursos que precisamos para monitorar e gerenciar aplicaes no contexto web, o que vital se voc implementa uma arquitetura baseada em micro servios.

Lembra do texto do Martin Fowler que popularizou os micro servios? Um dos pontos fundamentais era justamente o monitoramento, e o Actuator entra exatamente a. No leu o texto? Aqui o link.

Monitorar o que?

Toda esta conversa sobre monitoramento muito bonita mas talvez voc se sinta perdido pois h inmeras opes. Que aspectos relativos execuo do seu projeto interessam ser monitorados? Quais novos indicadores o Actuator trs pra ns?

Indicadores customizados pelo desenvolvedor

Se voc leu meu texto sobre JMX, temos aqui o mesmo conceito dos MBeans. Voc pode implementar beans aqui capazes de oferecer as seguintes funcionalidades:

• Obteno de dados - verificar espao em disco, por exemplo.
• Executar aes - tarefas administrativas como limpeza de cache, remoo de arquivos temporrios ou qualquer outro tipo de funcionalidade administrativa que voc precise em produo.

Sua imaginao e necessidade so os limites aqui. Voc poderia implementar isto como endpoints convencionais do Spring que executassem estas operaes, verdade, mas para o caso de tarefas administrativas o ideal que at por questes de segurana seja um cdigo isolado.

Checagem de qualidade de servio (health checks)

Talvez meu uso favorito do Actuator: cdigo de health checking aquele responsvel por verificar se o sistema est executando em condies adequadas. Vamos a alguns exemplos:

• Verificar espao em disco.
• Quantidade de memria disponvel.
• Acesso ao banco de dados (checagem dos data sources).
• Se voc realiza interao com outros servios externos, se consegue se conectar a estes.
• Integridade do sistema de arquivos.

Um dos textos desta srie justamente sobre health checking. interessante aqui observar que diversos mdulos do Spring Boot (como Redis, JPA e muitos outros) adicionam seus prprios testes de verificao de qualidade sem que voc precise escrever uma linha de cdigo sequer. A imagem a seguir expe um exemplo de health checking detalhado usando o que j vm com o mdulo JPA:

Bem legal hein? E eu no escrevi uma linha sequer de cdigo pra verificar se o acesso ao banco de dados est funcionando. Observe que tambm h um teste sobre espao em disco: tambm no escrevi este teste, veio de graa com o Actuator!

E eu te contei que voc pode escrever seus prprios testes? Vamos ver isto no prximo post!

Logging

O Actuator pode facilitar bastante o acesso ao contedo do arquivo de log da aplicao. E este um uso bastante til, essencialmente, para ver o log principal da aplicao voc apenas acessa o endpoint /actuator/logfile e boom: o log principal da aplicao est ali. Abaixo voc pode ver um exemplo de sada:

possvel at mesmo usando o comando curl obter a sua prpria verso do "tail", veja este exemplo:

curl 'http://localhost:8080/actuator/logfile' -i -X GET

possvel tambm ver a lista de todos os loggers presentes na aplicao, assim como seus nveis de acesso.

No pretendo me aprofundar neste tema, mas se voc quiser, este o link a seguir.

Mtricas (metrics) - profilando sua aplicao

No caso das mtricas temos aqui a medio de um aspecto da aplicao especfico (consumo de CPU, memria, conexes ativas com banco de dados, etc), no momento atual. Essencialmente este indicador responde a seguinte questo: "qual o valor do indicador X agora?".

Isto te permite montar grficos que possibilitam acompanhar ao longo do tempo o desempenho destes componentes, tal como o grfico abaixo, que expe o uso de CPU ao longo do tempo:

Infelizmente o Actuator no vm com o ferramental que produz este tipo de grfico, mas prov conectores para diversas ferramentas que podem gerar isto para voc, tais como JMX, New Relic, Datadog, Dynatrace, Elastic e muitos outros que voc pode ver neste link.

Mas no acaba a! Voc tambm pode monitorar o tempo de resposta dos seus endpoints com estas mtricas. Veja o exemplo a seguir, real, extrado da API do /dev/All:

Quando adicionamos a anotao @Timed (io.micrometer.core.annotation.Timed) na classe do nosso controlador, podemos extrair mtricas como nmero de requisies recebidas, tempo mximo de processamento e outros detalhes, apenas acessando o endereo /actuator/metrics/site (notou que "site" o valor que passei pra anotao @Timed?). Veja o print a seguir:

possvel anotar apenas alguns endpoints tambm, o que te permite acompanhar a evoluo do desempenho dos mesmos. Notou que obtive tudo isto incluindo apenas uma anotao? Pode aguardar que tem post detalhando este assunto vindo.

Informaes genricas (Info)

Outro grupo de informaes muito til o info: quem nunca precisou verificar qual a verso da aplicao est em produo? Mas no se limita a apenas isto: voc pode incluir literalmente qualquer coisa aqui, at mesmo informaes relativas ao Git.

Sim, h um post s sobre este ponto aqui saindo no futuro. Neste primeiro momento pense nas informaes genricas como "a sua base chave/valor de dados no Actuator".

Menes honrosas

Meu objetivo neste e nos prximos posts mostrar quais os recursos do Actuator que acho mais interessantes com base na minha experincia. Mas h alguns outros recursos providos por padro que devem ser mencionados:

• Auditoria - te possibilita registrar e monitorar eventos de autenticao bem ou mal sucedida e acesso no autorizado aos seus endpoints. Muito til, leia mais neste link.
• Listagem de rotas - muito til, especialmente quando voc est lidando com sistemas pr-existentes. Mais detalhes aqui.
• Gesto do processo principal - sabia que voc pode finalizar o processo da sua aplicao pelo Actuator? Yeap, voc pode: o endpoint /actuator/shutdown. Em momentos crticos pode te ajudar bastante (pense num bug bruto em produo gerando prejuzos por segundo). Leia mais aqui.

Actuator na prtica

O Actuator est presente desde a primeira verso do Spring Boot. Neste texto estou falando da ltima verso do framework (2.4.1), e inclu-lo em sua aplicao muito simples. Se est usando Maven, basta incluir a dependncia a seguir:

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

Usa Gradle? To fcil quanto: inclua a dependncia tal como no exemplo a seguir:

dependencies {    implementation 'org.springframework.boot:spring-boot-starter-actuator' }

Inicie seu projeto e, na sequncia, acesse este endereo: http://localhost:8080/actuator (imaginando que seu contexto seja "/"). Voc ver uma resposta similar a esta:

Super legal: o Actuator est te mostrando quais os endpoints de monitoramento/gerenciamento disponveis. Por padro esto visveis apenas os endpoints de sade (health) e informaes gerais (info). Experimente navegar por eles, ser uma experincia frustrante aps ter lido este meu texto, pois voc no v nada do que prometi. Vamos resolver isto agora.

Endpoints - expostos vs habilitados

A unidade base do Actuator o endpoint. Qualquer ao que voc realize no Actuator envolve o acesso a um dos endereos disponibilizados pelo framework. Por segurana no temos todos os endpoints expostos, especialmente por que estamos usando um protocolo que, por padro, no seguro, o HTTP (no confundir com HTTPS, que tambm no to seguro assim quanto as propagandas da internet ("Ops!") vendem).

Sendo assim necessrio alterar as configuraes do Spring Boot (no sabe como fazer com segurana? J escrevi sobre elas aqui) para identificar quais os itens que sero expostos. Quer expor todos? Ento mude o valor da configurao management.endpoints.web.exposure.include com o valor * tal como no exemplo abaixo:

management.endpoints.web.exposure.include=*

Ateno: se sua configurao estiver no formato yaml, digite '*' ao invs de *. Acesse novamente o endereo base do Actuator: http://localhost:8080/actuator

Olha a um monte de endpoints disponveis pra voc agora (inclusive o "shutdown", que habilitei de propsito e desabilitado por padro). H dois conceitos aqui:

• Endpoints ativos - todos (com exceo de um (ento no so todos, qual este? o shutdown)) so ativos por padro, isto , podem ser executados.
• Endpoints expostos - so os endpoints que podem ser acessados remotamente por HTTP ou JMX.

O endpoint pode estar visvel por essencialmente dois protocolos quando estamos tratando do Actuator: JMX ou HTTP. Neste post vamos falar s de HTTP, mas voc pode aprender mais sobre o que o JMX neste meu texto e como trabalhar com JMX e Actuator neste link da documentao.

No uma boa ideia expor todos os endpoints. O ideal que voc exponha apenas o que realmente faz sentido, pois quanto mais pontos de monitoramento estiverem visveis, maior a rea de ataque aos seus sistemas. Sendo assim entra um novo conceito aqui: o identificador do endpoint.

Todo indicador (endpoint) no Actuator tem seu prprio identificador. A lista dos identificadores padro pode ser conferida neste link.

Como ativar endpoints

Voc deve seguir a seguinte sintaxe para ativar um endpoint individualmente:

management.endpoint.[identificador do endpoint].enabled=(true|false)

Vamos a alguns exemplos, habilitando o info e desabilitando o shutdown:

management.endpoint.info.enabled=true
management.endpoint.shutdown.enabled=false

Como mencionei agora h pouco, todos os endpoints esto ativados por padro com exceo do "shutdown". Mas e se voc no quiser este comportamento? E se quiser habilitar um a um os endpoints que deseja? A basta alterar a configurao management.endpoints.enabled-by-default tal como no exemplo a seguir:

# pronto, agora voc vai ter de definir um a um os endpoints ativos
management.endpoints.enabled-by-default=false

Como expor endpoints

Por padro apenas os endpoints info e health esto expostos por padro ao protocolo HTTP. muito importante que voc leve segurana em considerao aqui, sendo assim recomendo que voc exponha apenas os endpoints que sejam realmente importantes para sua equipe.

Novamente, vamos lidar com algumas configuraes do Spring Boot aqui. A primeira delas diz quais os endpoints que voc quer expor: management.endpoints.web.exposure.include. Ela pode receber dois valores: "*" ou a lista de identificadores separados por vrgula, tal como no exemplo a seguir:

# expondo todos os endpoints
management.endpoints.web.exposure.include=*
# expondo apenas os endpoints que nos interessam: health, info, metrics
management.endpoints.web.exposure.include=health,info,metrics

Mas pra complicar (ou no) um pouquinho as coisas h outra propriedade que tambm define os endpoints que desejamos ocultar. a configurao management.endpoints.web.exposure.exclude. Exclude tem precedncia sobre o que ser exposto. E a mesma sintaxe que temos para o include, temos para o exclude.

Segurana

Tudo muito bonito: com o Actuator podemos ver praticamente tudo sobre o estado corrente da nossa aplicao e tambm o ambiente no qual ela est sendo executada. E com as configuraes padro inclusive quem no deveria ter acesso a estas informaes.

Algum interessado em lhe causar problemas sabe tudo sobre sua aplicao: quais pontos da aplicao podem no estar funcionando corretamente (healthcheck), quanta memria est disponvel, idem espao de armazenamento, quantas requisies por segundo sua aplicao recebe, o que sai no log, como est seu banco de dados... enfim, o prato cheio pra quem quer invadir sua plataforma. E claro, usando um protocolo disponvel a todos: HTTP. Com um browser qualquer descubro como lhe causar pesadelos. Vejamos como evitar isto.

Spring Security

Se sua aplicao usa Spring Security (use), relativamente fcil limitar o acesso aos endpoints do Actuator com base nas permisses do usurio. O caminho mais popular estender a classe de configurao WebSecurityConfigurerAdapter sobrescrevendo o mtodo configure tal como no exemplo a seguir:

@Configuration@EnableWebSecurity@EnableGlobalMethodSecurity(securedEnabled = true, prePostEnabled = true)public class WebSecurityConfig extends WebSecurityConfigurerAdapter {   @Override   protected void configure(HttpSecurity http) throws Exception {     http       .sessionManagement()       .sessionCreationPolicy(SessionCreationPolicy.NEVER)       .and()         .authorizeRequests()         .antMatchers("/actuator/").hasAuthority("ROLE_ADMIN")         .anyRequest().authenticated()      .and()        .csrf().disable();   }}

Observe, este um cdigo de mera referncia, vai dar um pouquinho mais de trabalho no seu projeto, pegue apenas a ideia geral. Neste caso, apenas os usurios com a permisso (authority) ROLE_ADMIN tero acesso aos endpoints.

Caso queira mais exemplos, sugiro que voc confira este e este link. Mas o ponto : restrinja o acesso.

Caso o Spring Security no seja uma opo, h outras: voc pode implementar um filtro, por exemplo, e neste adotar outro tipo de autenticao, como Basic Auth (no recomendo) por exemplo ou mesmo headers de API Keys.

Mude as configuraes padro

Mudando o base path padro

Se eu quiser varrer sua rede em busca de informaes sobre sua infra a primeira coisa que farei buscar endereos padro. O endereo padro do Actuator "/actuator". Sendo assim, vamos mudar esta configurao? simples, voc usa a chave management.endpoints.web.base-path , tal como no exemplo abaixo:

# mudando de /actuator para /segredos
management.endpoints.web.base-path=/segredos

Recomendo que voc use sua criatividade neste nome, o que pelo menos ir dar um pouco mais de trabalho para quem estiver tentando encontrar seu endereo base do Actuator.

Use outra porta

Esta outra boa dica. Voc pode configurar o Actuator para usar uma porta diferente daquela adotada por sua aplicao. Sendo assim sua API poderia operar na porta 443 (HTTPS) por exemplo, e o Actuator na porta 1979. Com isto, configurando seu firewall (ou regras de acesso a portas do seu servio cloud) voc consegue limitar quais endereos podero ter acesso ao Actuator na porta customizada. A chave de configurao usada a management.server.port. O exemplo abaixo define a porta 1979 para o Actuator:

management.server.port=1979

Tente acessar o Actuator pela porta padro da aplicao e o que voc recebe? 404!

Configure CORS

Se voc quer que cdigo JavaScript cliente acesse seus endpoints do Actuator (tem certeza disto?) possvel habilitar CORS para os endpoints usando as chaves expostas no exemplo a seguir:

# as origensmanagement.endpoints.web.cors.allowed-origins=https://itexto.com.br# quais mtodosmanagement.endpoints.web.cors.allowed-methods=GET,POST

No sabe o que CORS? Leia este texto. Mais detalhes sobre o uso de CORS na documentao oficial do Actuator aqui.

SSL

J que voc definiu uma porta diferente pro seu servidor, por que no jogar um certificado SSL no mesmo pra deixar a coisa ainda mais segura?

A configurao a seguir expe exatamente isto:

# a porta customizada do servidormanagement.server.port=1979 # habilitando SSL nesta portamanagement.server.ssl.enabled=true # o keystore que contm seu certificadomanagement.server.ssl.key-store=classpath:management.jks # a senha de acesso ao keystoremanagement.server.ssl.key-password=secret

Maiores detalhes neste link.

Concluindo a introduo e preparando a jornada

Nosso caminho com Actuator est s comeando. Meu objetivo neste post foi te mostrar o que esta ferramenta, abrir seus olhos para algumas das possibilidades que ela nos d e, principalmente, te preparar para o maior risco que vm com ela: a exposio de dados sensveis a partir dos endpoints disponibilizados.

A partir de agora meu objetivo ir pra prtica: vou te ensinar a implementar seus prprios endpoints de health checking, como enriquecer as informaes apresentadas pelo seu sistema, lidar com auditoria e implementar seus prprios endpoints.

At l!

Para saber mais

Documentao oficial do Actuator - https://docs.spring.io/spring-boot/docs/current/reference/html/production-ready-features.html

API do Actuator - te expe todos os detalhes sobre os endpoints padro disponibilizados pela ferramenta - https://docs.spring.io/spring-boot/docs/2.4.1/actuator-api/htmlsingle/

Entendendo as configuraes do Spring Boot - fundamental que voc entenda como as configuraes do Spring Boot funcionam. Ento escrevi este texto.

Conhea JMX - o texto que nasceu deste aqui e que contm muitos conceitos que voc deve conhecer tambm. Leia aqui.

Documentao oficial do Spring Security - https://docs.spring.io/spring-security/site/docs/5.4.2/reference/html5/