Monitor Your Application with the Winter Boot Actuator

Enable built-in HTTP endpoints to inspect beans, environment, health indicators, and application info without writing any controller code.

The Winter Boot Actuator is a built-in observability layer that exposes operational information about your running application through HTTP endpoints. Without writing any controller code you can inspect registered beans, active configuration properties, environment variables, scheduled tasks, request mappings, and the health of your application’s dependencies. The Actuator is designed for microservice environments where monitoring agents, load balancers, and orchestration platforms need a reliable, machine-readable way to query application state.

Configuration

All Actuator endpoints are disabled by default. Enable them individually — or globally — in application.yml. Each endpoint can also be mounted at a custom path.

application.yml

management:
    endpoints:
        enabled: true          # global switch — must be true for any endpoint to work
    endpoint:
        beans:
            enabled: true
            path: "acme/beans"
        configprops:
            enabled: true
            path: "acme/configprops"
        env:
            enabled: true
            path: "acme/env"
        health:
            enabled: true
            path: "acme/health"
        info:
            enabled: true
            path: "acme/info"
        mappings:
            enabled: true
            path: "acme/mappings"
        scheduledtasks:
            enabled: true
            path: "acme/scheduledtasks"
        heapdump:
            enabled: true
            path: "acme/heapdump"

Setting management.endpoints.enabled: false (or omitting it entirely) disables all endpoints regardless of individual endpoint settings. You must set it to true before any endpoint becomes accessible.

Available Endpoints

Endpoint	Default path	Description
beans	acme/beans	Lists all beans registered in the Winter Boot application context.
configprops	acme/configprops	Displays all #[ConfigurationProperties] bound values.
env	acme/env	Exposes environment variables and application properties.
health	acme/health	Aggregated health status from all registered HealthIndicator beans.
info	acme/info	Arbitrary application information contributed by InfoContributor beans.
mappings	acme/mappings	Lists all registered HTTP route mappings.
scheduledtasks	acme/scheduledtasks	Shows all tasks registered with the #[Scheduled] attribute.
heapdump	acme/heapdump	Triggers a PHP memory/heap snapshot for debugging.

Querying an Endpoint

Once an endpoint is enabled and the application is running, query it with a standard HTTP request:

curl https://your.service.domain/acme/health

curl https://your.service.domain/acme/info

Custom Health Checks with HealthIndicator

The /health endpoint aggregates the status reported by every bean that implements HealthIndicator and is annotated with #[HealthInformer]. This makes it straightforward to add health checks for databases, message brokers, external APIs, or any other dependency.

Implement the health(): Health method and return one of the Health factory methods for the appropriate state:

Method	Description
Health::up()	Service is healthy and available.
Health::down(?Throwable $ex = null)	Service is unavailable. Pass a Throwable to have the exception class and message added as the error detail.
Health::outOfService()	Service is intentionally taken out of service (e.g. maintenance).
Health::unknown()	Health state cannot be determined.
Health::status(string $statusCode)	Custom status code for non-standard states.

DatabaseHealthIndicator.php

use dev\winterframework\actuator\HealthIndicator;
use dev\winterframework\actuator\Health;
use dev\winterframework\actuator\stereotype\HealthInformer;
use dev\winterframework\stereotype\Autowired;
use dev\winterframework\pdbc\PdbcTemplate;

#[HealthInformer]
class DatabaseHealthIndicator implements HealthIndicator
{
    #[Autowired]
    private PdbcTemplate $pdbc;

    public function health(): Health
    {
        $ok = $this->pdbc->queryForScalar('select 1 from dual');

        return $ok
            ? Health::up()
            : Health::down()->withDetail('database', 'connection check failed');
    }
}

You can register as many #[HealthInformer] beans as you need. The /health endpoint combines all of their statuses: if any single indicator reports DOWN, the overall status is DOWN.

Custom Application Info with InfoContributor

The /info endpoint is populated by beans that implement InfoContributor and are annotated with #[InfoInformer]. Use it to surface metadata such as the application name, version, build timestamp, or Git revision.

Implement the contribute(InfoBuilder $info): void method and call $info->withDetail(key, value) for each piece of information you want to expose. The method is chainable.

ApplicationInfoContributor.php

use dev\winterframework\actuator\InfoContributor;
use dev\winterframework\actuator\InfoBuilder;
use dev\winterframework\actuator\stereotype\InfoInformer;

#[InfoInformer]
class ApplicationInfoContributor implements InfoContributor
{
    public function contribute(InfoBuilder $info): void
    {
        $info->withDetail('appName', 'ExampleMicroService')
             ->withDetail('appVersion', '1.0.0-1')
             ->withDetail('buildTimestamp', '2024-01-15T10:30:00Z');
    }
}

Querying the info endpoint returns a JSON object that merges all contributors:

curl https://your.service.domain/acme/info
# {"appName":"ExampleMicroService","appVersion":"1.0.0-1","buildTimestamp":"2024-01-15T10:30:00Z"}