0
# Spring Boot Starter Actuator
1
2
Spring Boot Starter Actuator provides comprehensive production-ready monitoring and management capabilities for Spring Boot applications. It automatically configures actuator endpoints that expose operational information through HTTP endpoints or JMX beans, enabling health checks, metrics collection, application information, and other management features without requiring manual configuration.
3
4
## Package Information
5
6
- **Package Name**: spring-boot-starter-actuator
7
- **Package Type**: Maven
8
- **Group ID**: org.springframework.boot
9
- **Language**: Java
10
- **Installation**: Add dependency to `pom.xml` or `build.gradle`
11
12
## Core Dependencies
13
14
Maven:
15
```xml
16
<dependency>
17
<groupId>org.springframework.boot</groupId>
18
<artifactId>spring-boot-starter-actuator</artifactId>
19
</dependency>
20
```
21
22
Gradle:
23
```gradle
24
implementation 'org.springframework.boot:spring-boot-starter-actuator'
25
```
26
27
## Basic Usage
28
29
```java
30
// Basic Spring Boot application with actuator
31
@SpringBootApplication
32
public class Application {
33
public static void main(String[] args) {
34
SpringApplication.run(Application.class, args);
35
}
36
}
37
```
38
39
Configuration in `application.properties`:
40
```properties
41
# Expose all actuator endpoints over HTTP
42
management.endpoints.web.exposure.include=*
43
# Change actuator base path (default: /actuator)
44
management.endpoints.web.base-path=/actuator
45
# Show health details to everyone
46
management.endpoint.health.show-details=always
47
```
48
49
After starting the application, actuator endpoints are available at:
50
- Health: `http://localhost:8080/actuator/health`
51
- Info: `http://localhost:8080/actuator/info`
52
- Metrics: `http://localhost:8080/actuator/metrics`
53
54
## Architecture
55
56
Spring Boot Starter Actuator is built around several key components:
57
58
- **Endpoint Framework**: Core annotation-based system for creating and exposing management endpoints
59
- **Health System**: Comprehensive health checking with built-in and custom health indicators
60
- **Metrics System**: Integration with Micrometer for collecting and exposing application metrics
61
- **Auto-Configuration**: 124+ auto-configuration classes that automatically set up monitoring capabilities
62
- **Security Integration**: Built-in security context and access control for sensitive endpoints
63
- **Multi-Transport Support**: Endpoints can be exposed via HTTP, JMX, or custom transports
64
65
## Capabilities
66
67
### Endpoint Framework
68
69
Core system for creating custom actuator endpoints using annotations and interfaces.
70
71
```java { .api }
72
// Create custom endpoints
73
@Endpoint(id = "custom")
74
public class CustomEndpoint {
75
@ReadOperation
76
public Map<String, Object> customInfo() {
77
return Map.of("status", "operational");
78
}
79
}
80
81
// Core endpoint annotations
82
@Target(ElementType.TYPE)
83
@Retention(RetentionPolicy.RUNTIME)
84
public @interface Endpoint {
85
String id();
86
Access defaultAccess() default Access.RESTRICTED;
87
}
88
89
@Target(ElementType.METHOD)
90
@Retention(RetentionPolicy.RUNTIME)
91
public @interface ReadOperation {
92
String[] produces() default {};
93
}
94
95
@Target(ElementType.METHOD)
96
@Retention(RetentionPolicy.RUNTIME)
97
public @interface WriteOperation {
98
String[] produces() default {};
99
}
100
```
101
102
[Endpoint Framework](./endpoint-framework.md)
103
104
### Health System
105
106
Comprehensive health monitoring with built-in indicators and support for custom health checks.
107
108
```java { .api }
109
// Create custom health indicators
110
@Component
111
public class CustomHealthIndicator implements HealthIndicator {
112
@Override
113
public Health health() {
114
// Check health of external service
115
if (isServiceHealthy()) {
116
return Health.up()
117
.withDetail("service", "operational")
118
.build();
119
}
120
return Health.down()
121
.withDetail("service", "unavailable")
122
.build();
123
}
124
}
125
126
// Core health interfaces
127
public interface HealthIndicator {
128
Health health();
129
default Health getHealth(boolean includeDetails) {
130
return health();
131
}
132
}
133
134
public final class Health {
135
public static Builder up() { /* ... */ }
136
public static Builder down() { /* ... */ }
137
public static Builder outOfService() { /* ... */ }
138
}
139
```
140
141
[Health System](./health-system.md)
142
143
### Built-in Endpoints
144
145
Production-ready endpoints for monitoring, management, and diagnostics.
146
147
```java { .api }
148
// Key built-in endpoints
149
@Endpoint(id = "health")
150
public class HealthEndpoint {
151
@ReadOperation
152
public HealthComponent health() { /* ... */ }
153
154
@ReadOperation
155
public HealthComponent healthForPath(@Selector String... path) { /* ... */ }
156
}
157
158
@Endpoint(id = "info")
159
public class InfoEndpoint {
160
@ReadOperation
161
public Map<String, Object> info() { /* ... */ }
162
}
163
164
@Endpoint(id = "metrics")
165
public class MetricsEndpoint {
166
@ReadOperation
167
public ListNamesResponse listNames() { /* ... */ }
168
169
@ReadOperation
170
public MetricResponse metric(@Selector String requiredMetricName,
171
@Nullable List<String> tag) { /* ... */ }
172
}
173
```
174
175
[Built-in Endpoints](./builtin-endpoints.md)
176
177
### Metrics System
178
179
Integration with Micrometer for comprehensive metrics collection and export.
180
181
```java { .api }
182
// Metrics endpoint for accessing collected metrics
183
@Endpoint(id = "metrics")
184
public class MetricsEndpoint {
185
@ReadOperation
186
public ListNamesResponse listNames() { /* ... */ }
187
188
@ReadOperation
189
public MetricResponse metric(@Selector String requiredMetricName,
190
@Nullable List<String> tag) { /* ... */ }
191
}
192
193
// Configure automatic timing
194
public class AutoTimer {
195
public static final AutoTimer ENABLED = new AutoTimer(true);
196
public static final AutoTimer DISABLED = new AutoTimer(false);
197
}
198
199
// Prometheus integration
200
@Endpoint(id = "prometheus", enableByDefault = false)
201
public class PrometheusScrapeEndpoint {
202
@ReadOperation(produces = "text/plain;version=0.0.4;charset=utf-8")
203
public String scrape() { /* ... */ }
204
}
205
```
206
207
[Metrics System](./metrics-system.md)
208
209
### Configuration Properties
210
211
Comprehensive configuration options for customizing actuator behavior.
212
213
```java { .api }
214
// Web endpoint configuration
215
@ConfigurationProperties("management.endpoints.web")
216
public class WebEndpointProperties {
217
private String basePath = "/actuator";
218
private PathMappingCache pathMapping = new PathMappingCache();
219
private Exposure exposure = new Exposure();
220
// ... getters and setters
221
}
222
223
// Health endpoint configuration
224
@ConfigurationProperties("management.endpoint.health")
225
public class HealthEndpointProperties {
226
private Show showDetails = Show.NEVER;
227
private Show showComponents = Show.ALWAYS;
228
private Map<String, GroupProperties> group = new LinkedHashMap<>();
229
// ... getters and setters
230
}
231
```
232
233
[Configuration Properties](./configuration-properties.md)
234
235
## Extension Points
236
237
Spring Boot Actuator provides several extension points for customization:
238
239
1. **Custom Endpoints**: Create endpoints with `@Endpoint` annotation
240
2. **Custom Health Indicators**: Implement `HealthIndicator` interface
241
3. **Custom Info Contributors**: Implement `InfoContributor` interface
242
4. **Custom Metrics**: Use Micrometer `MeterRegistry` integration
243
5. **Web Extensions**: Use `@EndpointWebExtension` for web-specific functionality
244
245
## Security Considerations
246
247
Actuator endpoints can expose sensitive information. Key security features:
248
249
- **Access Control**: Endpoints have configurable access levels (`RESTRICTED`, `UNRESTRICTED`)
250
- **Exposure Control**: Configure which endpoints are exposed via `management.endpoints.web.exposure.include`
251
- **Authentication**: Integrate with Spring Security for endpoint protection
252
- **Sensitive Data**: Some endpoints (like `/env`, `/configprops`) can expose sensitive configuration
253
254
## Common Configuration Examples
255
256
```properties
257
# Expose specific endpoints
258
management.endpoints.web.exposure.include=health,info,metrics
259
260
# Change management port
261
management.server.port=8081
262
263
# Show health details only when authorized
264
management.endpoint.health.show-details=when-authorized
265
266
# Configure health groups
267
management.endpoint.health.group.custom.include=db,redis
268
management.endpoint.health.group.custom.show-details=always
269
```