Autorzy rozwiązania Spring Boot bardzo mocno stawiają na to, że aplikacja napisana z wykorzystaniem ich frameworku powinna być production-ready. Zgodnie z 12 factor manifesto, aplikacja sama w sobie powinna dostarczać informacji na temat swojej telemetrii. Projekt Actuator jest mechanizmem, który przybliża nas do tego celu, dostarczając podstawowe metryki oraz informacje o stanie aplikacji.

Zależności

Standardowo zaczniemy od dodania nowej zależności do naszego projektu. Tym razem będzie to spring-boot-starter-actuator:

1
2
3
4
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-actuator</artifactId>
</dependency>

Domyślna Konfiguracja

Dodanie powyższej zależności wprowadza do projektu nowe funkcjonalności. Wszystkie dodatkowe informacje o aplikacji są dostępne pod adresem /actuator. Domyślnie włączonymi adresami (endpointami) są /info oraz /health.

Health (Stan)

Endpoint /health zwraca informacje na temat statusu aplikacji w postaci:

1
2
3
4
5
6
7
{
   "status": "UP" // jeśli aplikacja działa poprawnie
}

{
   "status": "DOWN" // jeśli aplikacja działa niepoprawnie
}

Info (Informacje)

Endpoint /info zwraca informacje o aplikacji skonfigurowane przez nas (domyślnie zwraca pusty JSON). Aby ustawić wartości dla tego endpointu, wystarczy w pliku application.properties dodać wpis:

1
2
3
4
5
6
# Zawartość endpointu /info
info.app.name=Code Couple Application
info.app.description=This is my first code couple application
info.app.version=1.0.0
# Wszystko co jest po kluczu info zostanie dodane
info.dowolny.klucz=wartosc

Wszystkie właściwości pod kluczem info są dodawane do endpointu /info. W wyniku wywołania adresu /actuator/info otrzymamy:

1
2
3
4
5
6
7
8
9
10
{
  "app": {
    "name": "Code Couple Application",
    "description": "This is my first code couple application",
    "version": "1.0.0"
  },
  "dowolny": {
    "klucz": "wartosc"
 }
}

Jest to bardzo przydatny endpoint, jeśli chcemy poinformować innych o aktualnej wersji aplikacji lub gdy przygotowujemy dashboard zbierający informacje o różnych aplikacjach.

Pozostałe Endpointy Actuatora

Projekt Actuator to nie tylko /info oraz /health. Oferuje on dużą ilość metryk i informacji na temat aplikacji. Dostępne endpointy to (poniżej znajduje się lista tylko kilku najważniejszych):

  • /beans – zwraca wszystkie dostępne Bean’y w naszej aplikacji.
  • /conditions – zwraca wszystkie autokonfiguracje.
  • /flyway - zwraca informacje o migracjach bazy danych z wykorzystaniem technologii Flyway.
  • /liquibase - zwraca informacje o migracjach bazy danych z wykorzystaniem technologii Liquibase.
  • /env – zwraca wszystkie zmienne środowiskowe.
  • /heapdump – zwraca zrzut pamięci naszej aplikacji JVM.
  • /threaddump – zwraca zrzut wątków naszej aplikacji JVM.
  • /scheduledtasks – zwraca informacje o zadaniach wykonywanych w tle.
  • /sessions – zwraca informacje o sesjach HTTP z wykorzystaniem Spring Session.
  • /metrics – zwraca metryki aplikacji.
  • /prometheus - zwraca metryki aplikacji dostosowane do aplikacji Prometheus.
  • /shutdown – wyłącza aplikację poprzez żądanie POST (domyślnie jest wyłączony).

Dostępność Endpointów

Jak wspomniano wcześniej, domyślnie włączonymi adresami są /health oraz /info. Jeśli chcemy włączyć wszystkie lub kilka wybranych adresów, musimy użyć właściwości management.endpoints.web.exposure.include:

1
2
3
4
5
6
# Włącza wszystkie adresy
management.endpoints.web.exposure.include=\*
# Włącza tylko wybrane adresy
management.endpoints.web.exposure.include=info, metrics
# Wyłącza adres shutdown
management.endpoints.web.exposure.exclude=shutdown

Dodatkowo, poprzez plik application.properties możemy ustawić:

1
2
3
4
5
6
7
8
# Zmiana ścieżki bazowej /actuator
management.endpoints.web.base-path=/
# Włącza wszystkie usługi domyślnie
management.endpoints.enabled-by-default=true
# Wyłączenie endpointu metrics
management.endpoint.metrics.enabled=false
# Akceptowane nagłówki CORS
management.endpoints.web.cors.allowed-headers=\*

Całą listę dostępnych właściwości znajdziecie pod https://docs.spring.io/spring-boot/docs/current/reference/html/common-application-properties.html.

Github

Całość jak zawsze na Githubie.