Проверки здоровья и метрики

Когда сервис работает на сервере или в Kubernetes, кто-то должен регулярно спрашивать его: «ты жив? готов принимать запросы?». Такие вопросы называются проверками здоровья (health checks). Если сервис не отвечает, оркестратор перезапустит его. А метрики — это числа о работе сервиса: сколько пришло запросов, сколько длился ответ, сколько создано постов. Их собирает система мониторинга, например Prometheus, и рисует графики.

Подключение

./mvnw quarkus:add-extension -Dextensions="smallrye-health,micrometer-registry-prometheus"

smallrye-health добавляет эндпоинты здоровья, micrometer-registry-prometheus — сбор метрик через библиотеку Micrometer и их выдачу в формате Prometheus.

Эндпоинты здоровья

Часть проверок Quarkus добавляет сам. Расширение для базы данных регистрирует проверку соединения — без единой строки кода.

Своя проверка

Добавим проверку готовности, которая сообщает число постов:

// src/main/java/com/example/blog/PostsHealthCheck.java
package com.example.blog;
 
import jakarta.enterprise.context.ApplicationScoped;
import org.eclipse.microprofile.health.HealthCheck;
import org.eclipse.microprofile.health.HealthCheckResponse;
import org.eclipse.microprofile.health.Readiness;
 
@Readiness
@ApplicationScoped
public class PostsHealthCheck implements HealthCheck {
 
    @Override
    public HealthCheckResponse call() {
        long count = Post.count();
        return HealthCheckResponse.named("posts")
                .up()
                .withData("count", count)
                .build();
    }
}

@Readiness относит проверку к готовности, @Liveness — к живости. Метод call() возвращает имя, состояние up() или down() и дополнительные данные. Если Post.count() бросит исключение, например база недоступна, проверка будет считаться неуспешной.

curl http://localhost:8080/q/health

{
    "status": "UP",
    "checks": [
        {
            "name": "posts",
            "status": "UP",
            "data": {
                "count": 2
            }
        },
        {
            "name": "Database connections health check",
            "status": "UP",
            "data": {
                "<default>": "UP"
            }
        }
    ]
}

Общий статус UP, только если все проверки UP. Тогда ответ имеет код 200, иначе — 503 Service Unavailable. Оркестратор смотрит именно на код.

Метрики

После подключения Micrometer метрики доступны по адресу /q/metrics. Quarkus сам считает HTTP-запросы. Добавим свой счётчик созданных постов:

// src/main/java/com/example/blog/PostResource.java
@Inject
MeterRegistry registry;
 
@POST
@Transactional
public Response create(@Valid NewPost newPost) {
    Post post = new Post();
    post.title = newPost.title();
    post.body = newPost.body();
    post.persist();
    registry.counter("blog.posts.created").increment();
    return Response.created(URI.create("/posts/" + post.id)).entity(post).build();
}

MeterRegistry (импорт io.micrometer.core.instrument.MeterRegistry) — реестр метрик. counter(...) находит или создаёт счётчик, increment() увеличивает его на единицу. Создайте пост и посмотрите метрики:

curl -s http://localhost:8080/q/metrics | grep -E "^blog_posts|^http_server_requests_seconds_count"

blog_posts_created_total 1.0
http_server_requests_seconds_count{method="POST",outcome="SUCCESS",status="201",uri="/posts"} 1.0

Имя blog.posts.created в формате Prometheus стало blog_posts_created_total. Метрика http_server_requests_seconds_count считает запросы отдельно по методу, адресу и статусу. В Windows вместо grep найдите строки поиском в браузере.

Частая ошибка

Не стоит проверять в liveness внешние сервисы, например базу данных. Если база упадёт, liveness станет DOWN, и оркестратор начнёт перезапускать все копии сервиса, хотя перезапуск базу не починит. Внешние зависимости проверяют в readiness: сервис временно перестаёт получать запросы, но продолжает работать и восстановится сам. Поэтому и наша проверка posts помечена @Readiness, а в /q/health/live проверок пока нет — ответ "checks": [] со статусом UP.