> ## Documentation Index
> Fetch the complete documentation index at: https://suvera.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

```yaml application.yml theme={null}
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"
```

<Warning>
  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.
</Warning>

## 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:

```bash theme={null}
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.                                                                     |

```php DatabaseHealthIndicator.php theme={null}
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');
    }
}
```

<Note>
  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`.
</Note>

## 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.

```php ApplicationInfoContributor.php theme={null}
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:

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