
# spring_boot_actuator

The actuator tells what a running application knows about itself: whether it works, which version it is, which addresses it answers. A load balancer asks `/actuator/health` whether to send requests; Kubernetes asks `/actuator/health/liveness` and `/readiness`; an operator asks `/actuator/info` which build runs. The answers have Spring Boot's paths, properties and JSON, so every Spring tool reads them.

Two packages make it up:

| Package | What it is | Who lists it |
|---|---|---|
| `spring_boot_starter_actuator` | The starter: declares the endpoints as beans and answers them over `spring_boot_starter_web` under `/actuator`. Re-exports `spring_boot_actuator` | Applications |
| `spring_boot_actuator` | The endpoints without HTTP: the health model, info contributors, mappings, `@Endpoint`, the `management.*` property classes | Libraries that contribute to the endpoints (the data starter's `db` indicator, the security starter's `EndpointRequest`) |

They are the Dart counterparts of `spring-boot-starter-actuator` and `spring-boot-actuator` (Spring Boot 4's `spring-boot-health` for the health model).

## Why

Without the actuator, each application writes its own health controller, in its own shape, and each monitoring setup is configured anew. With it, adding the dependency is enough: the health check aggregates every indicator, the probes follow the application's availability, and the answers are those Spring Boot gives.

## Setup

```yaml
# pubspec.yaml
dependencies:
  spring_boot_starter_actuator: ^0.9.0   # brings spring_boot_actuator and needs the web starter

dev_dependencies:
  build_runner: ^2.17.0
  spring_core_dart_generator: ^0.9.0
```

```bash
dart run build_runner build
```

## Example

```dart
// bin/main.dart
import 'package:spring_boot_starter_actuator/spring_boot_starter_actuator.dart';

import 'spring_gen/main.spring.dart';

@SpringBootApplication()
void main(List<String> args) => runApplication(args);
```

```console
$ curl -i localhost:8080/actuator/health
HTTP/1.1 200 OK
content-type: application/vnd.spring-boot.actuator.v3+json

{"status":"UP"}
```

The answer is `503` when the application is `DOWN` or `OUT_OF_SERVICE`. Only `health` is exposed by default, as in Spring Boot; the others are added with a property:

```yaml
# lib/resources/application.yml
management:
  endpoints:
    web:
      exposure:
        include: health,info,mappings
  endpoint:
    health:
      show-details: always
      probes:
        enabled: true
  info:
    env:
      enabled: true
info:
  app:
    team: neon-books
```

```console
$ curl localhost:8080/actuator/health
{"status":"UP","components":{"diskSpace":{"status":"UP","details":{"total":499963174912,"free":91300605952,"threshold":10485760,"path":"/srv/shop/.","exists":true}},"livenessState":{"status":"UP"},"ping":{"status":"UP"},"readinessState":{"status":"UP"}},"groups":["liveness","readiness"]}

$ curl localhost:8080/actuator/info
{"app":{"team":"neon-books"}}
```

## The endpoints

| Endpoint | Path | Shows | Page |
|---|---|---|---|
| discovery | `/actuator` | `_links` to every exposed endpoint | [Endpoints](endpoints.md) |
| `health` | `/actuator/health`, `/actuator/health/{*path}` | The aggregated status, the components, the groups, the probes | [Health](health.md) |
| `info` | `/actuator/info` | The build, git, `info.*` properties, the OS and Dart version | [Info](info.md) |
| `mappings` | `/actuator/mappings` | The web server's handlers and, with the navigation starter, the app's screens | [Mappings](mappings.md) |
| `jsonschemas` | `/actuator/jsonschemas`, `/actuator/jsonschemas/{name}` | The JSON Schemas of the registry and of every `@Introspected` class | [JSON Schemas](json-schemas.md) |
| `isolates` | `/actuator/isolates` | Every isolate of the application with its load: busy share, lag, requests in flight, memory | [Isolates](isolates.md) |
| `qps` | `/actuator/qps`, `/actuator/qps/now` | Requests per second, latency and errors, per isolate and in total; only with the web starter's debug feature `qps` in the build | [Requests per second](qps.md) |

## What is inside

- [Endpoints](endpoints.md): enabling, exposing, paths, media types and the discovery page.
- [Health](health.md): indicators, details, status aggregation, groups and Kubernetes probes.
- [Info](info.md): build and git information, `info.*` properties, OS and Dart.
- [Mappings](mappings.md): the handlers of the web server and the app's screens.
- [JSON Schemas](json-schemas.md): the schemas of the registry and of the application's classes.
- [Isolates](isolates.md): the load of every isolate, the task manager as JSON.
- [Requests per second](qps.md): the numbers of the web starter's debug feature `qps`.
- [Endpoints of your own](custom-endpoints.md): `@Endpoint`, `@ReadOperation`, `@Selector`, web extensions.
- [Security](security.md): `EndpointRequest` and `show-details=when-authorized`.
- [All properties](properties.md): every `management.*`, `spring.info.*` and `info.*` key.
- [Differences from Spring](differences.md): what works differently than in Spring Boot Actuator.

## In Spring (Java)

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

```properties
management.endpoints.web.exposure.include=health,info
management.endpoint.health.show-details=always
```

The same properties and JSON. Differences that matter:

- Of Spring Boot's endpoints only `health`, `info` and `mappings` exist so far; `jsonschemas`, `isolates` and `qps` are this actuator's own. Read operations only.
- There is no separate management port: the endpoints are on the main server.
- The full list is on [Differences from Spring](differences.md).

## See also

- [spring_boot_starter_web](../spring-boot-starter-web/index.md)
- [Events and availability](../spring-boot-dart/events.md)
- [spring_boot_dart](../spring-boot-dart/index.md)
- [What a build contains](optimizations.md)
