Spring Boot Actuator

Von Julian Sauer

19. März 2023 - 4 Minuten - 641 Wörter

Einleitung

Spring Boot Actuator ist ein Unterprojekt von Spring Boot, das uns beim Überwachen und Managen von Anwendungen hilft. Dazu stellt es Metriken, Health Checks und weitere nützliche Informationen über HTTP Endpunkte bereit.

Inhaltsverzeichnis

Spring Boot Actuator einrichten

Die Dependency lässt sich entweder über Maven in der pom.xml wie folgt einbinden:

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

oder über Gradle in der build.gradle:

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

Standardmäßig ist nur der Health Endpunkt über HTTP verfügbar. Generieren wir z.B. mit dem Spring Initializer eine Beispielanwendung mit Spring Boot 3 und der Actuator Dependency, sehen wir folgendes unter localhost:8080/actuator/health:

{
    "status": "UP"
}

Endpunkte

Eine vollständige Liste findet sich in der Dokumentation. Hier sind einige der Interessantesten:

/health: Zeigt den aktuellen Zustand der Anwendung

/info: Verschiedene Informationen über die Anwendungen

/metrics: Liefert Metriken

/env: Eigenschaften, die als Umgebungsvariablen gesetzt sind

/shutdown: Fährt die Anwendung herunter

Endpunkte aktivieren und freischalten

Bis auf shutdown sind standardmäßig alle Endpunkte aktiviert, aber nicht über HTTP verfügbar, weil sie sensible Informationen enthalten können. Um sie verfügbar zu machen, können wir sie in der application.yml freischalten:

management:
  endpoints.web.exposure.include: health,info

Die verfügbaren Endpunkte können wir uns unter http://localhost:8080/actuator ansehen:

{
    "_links": {
    "self": {
        "href": "http://localhost:8080/actuator",
        "templated": false
        },
        "info": {
            "href": "http://localhost:8080/actuator/info",
            "templated": false
        }
    }
}

Zu Testzwecken können wir alle Endpunkte durch ein "*" freischalten. In Produktion sollten wir das natürlich lassen!

management:
  endpoints.web.exposure.include: "*"

Jetzt sehen wir unter /actuator/metrics zum Beispiel eine Auflistung an möglichen Metriken. So können wir wiederholt /actuator/metrics/http.server.requests abfragen und sehen bei jedem Aufruf einen Wert hochzählen. Oder wir schauen uns unter /actuator/metrics/jvm.memory.used die Speicherauslastung unserer Anwendung an.

Für die Fehlersuche kann es nützlich sein, das Log-Level der Anwendung zu verändern. Das geht zwar auch über Umgebungsvariablen, benötigt dann aber einen Neustart. Stattdessen können wir uns diese Konfiguration unter /actuator/loggers ansehen und auch verändern. Wollen wir beispielsweise das Log-Level der gesamten Anwendung von INFO auf DEBUG setzen, schicken wir einen POST Request an /actuator/loggers/ROOT mit folgendem Inhalt:

{
    "configuredLevel": "DEBUG"
}

Schauen wir uns zuletzt an, wie man einen Endpunkt nicht nur freischaltet, sondern ihn aktiviert/deaktiviert. Als Beispiel nehmen wir den standardmäßig deaktivierten shutdown Endpunkt:

management:
  endpoint:
    shutdown.enabled: true

Schicken wir jetzt einen POST Request an /actuator/shutdown bekommen wir als Antwort

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

und unsere Anwendung fährt herunter.

Der Health Endpunkt

Schauen wir uns den Health Endpunkt etwas genauer an. Zunächst lassen wir ihn mehr Informationen anzeigen:

management:
  endpoint:
    health:
      show-details: always

Unter actuator/health erhalten wir jetzt

{
    "status": "UP",
    "components": {
        "diskSpace": {
            "status": "UP",
            "details": {...}
        },
        "ping": {
            "status": "UP"
        }
    }
}

Sofern unsere Anwendung welche benutzt, können wir hier außerdem Details über angebundene Systeme wie Datenbanken, Mail-Server, Elasticsearch oder RabbitMQ anzeigen. Sie können mit z.B. management.health.elasticsearch.enabled: true aktiviert oder deaktiviert werden. Eine vollständige Liste befindet sich hier

Den Health Endpunkt erweitern

Sollten uns diese Informationen nicht reichen, können wir weitere Indikatoren für den Zustand unserer Anwendung hinzufügen:

@Component
public class MyCustomCheckHealthIndicator implements HealthIndicator {
   @Override
   public Health health() {
     return Health
         .up()
         .withDetail("Der Anwendung gehts", "gut")
         .build();
   }
}

Unter dem Klassennamen finden wir jetzt unseren zusätzlichen Check, wenn wir erneut actuator/health aufrufen:

{
    "status": "UP",
    "components": {
        "diskSpace": {...},
        "myCustomCheck": {
            "status": "UP",
            "details": {
                "Der Anwendung gehts": "gut"
            }
        },
        "ping": {...}
    }
}

Zusammenfassung & Fazit

Spring Boot Actuator ist ein mächtiges Werkzeug, um mehr über den Zustand unserer Anwendungen im Produktivbetrieb zu erfahren und zu überwachen. Besonders bei der Fehlersuche kann es daher eine große Hilfe sein.

Viele Endpunkte sind bereits so vorkonfiguriert, dass sie direkt genutzt werden können. In diesem Artikel haben wir uns vor allem auf Health Informationen, Metriken und Logging fokussiert, um einen ersten Überblick über die Menge an Werkzeugen zu geben, die uns Spring Boot Actuator an die Hand gibt.