Monitor Your Application with the Winter Boot Actuator

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.

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"

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.

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');
    }
}

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.

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"}