0
# Spring Boot Actuator
1
2
Spring Boot Actuator provides production-ready monitoring and management features for Spring Boot applications. It includes built-in endpoints for health checks, metrics collection, auditing, and application introspection, with support for both HTTP and JMX access.
3
4
## Package Information
5
6
- **Package Name**: spring-boot-actuator
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Installation**:
10
```xml
11
<dependency>
12
<groupId>org.springframework.boot</groupId>
13
<artifactId>spring-boot-actuator</artifactId>
14
<version>3.5.3</version>
15
</dependency>
16
```
17
18
## Core Imports
19
20
```java
21
import org.springframework.boot.actuate.endpoint.annotation.Endpoint;
22
import org.springframework.boot.actuate.endpoint.annotation.ReadOperation;
23
import org.springframework.boot.actuate.health.HealthIndicator;
24
import org.springframework.boot.actuate.health.ReactiveHealthIndicator;
25
import org.springframework.boot.actuate.health.Health;
26
import org.springframework.boot.actuate.info.InfoContributor;
27
import org.springframework.boot.actuate.info.Info;
28
import org.springframework.boot.actuate.audit.AuditEvent;
29
import org.springframework.boot.actuate.metrics.MetricsEndpoint;
30
```
31
32
## Basic Usage
33
34
### Creating a Custom Health Indicator
35
36
```java
37
import org.springframework.boot.actuate.health.HealthIndicator;
38
import org.springframework.boot.actuate.health.Health;
39
import org.springframework.stereotype.Component;
40
41
@Component
42
public class CustomHealthIndicator implements HealthIndicator {
43
44
@Override
45
public Health health() {
46
// Perform your health check logic
47
boolean healthy = checkSystemHealth();
48
49
if (healthy) {
50
return Health.up()
51
.withDetail("status", "All systems operational")
52
.build();
53
} else {
54
return Health.down()
55
.withDetail("error", "System unavailable")
56
.build();
57
}
58
}
59
60
private boolean checkSystemHealth() {
61
// Your health check implementation
62
return true;
63
}
64
}
65
```
66
67
### Creating a Custom Endpoint
68
69
```java
70
import org.springframework.boot.actuate.endpoint.annotation.Endpoint;
71
import org.springframework.boot.actuate.endpoint.annotation.ReadOperation;
72
import org.springframework.stereotype.Component;
73
import java.util.Map;
74
75
@Endpoint(id = "custom")
76
@Component
77
public class CustomEndpoint {
78
79
@ReadOperation
80
public Map<String, Object> customInfo() {
81
return Map.of(
82
"status", "active",
83
"version", "1.0.0",
84
"uptime", getUptime()
85
);
86
}
87
88
private String getUptime() {
89
// Calculate uptime
90
return "5 days, 3 hours";
91
}
92
}
93
```
94
95
## Architecture
96
97
Spring Boot Actuator is built around several key architectural components:
98
99
- **Endpoint Framework**: Annotation-based system for creating monitoring endpoints accessible via HTTP and JMX
100
- **Health System**: Extensible health checking with built-in indicators for databases, messaging, and infrastructure
101
- **Metrics Integration**: Micrometer-based metrics collection with support for various monitoring systems
102
- **Info System**: Application metadata and build information contributors
103
- **Audit Framework**: Security and application event auditing capabilities
104
- **Auto-Configuration**: Automatic setup and configuration of actuator components
105
106
## Capabilities
107
108
### Endpoint Framework
109
110
Core framework for creating custom actuator endpoints with support for HTTP and JMX access. Provides annotations for defining operations and automatic integration with Spring Boot's management infrastructure.
111
112
```java { .api }
113
// Endpoint creation annotations
114
@Target(ElementType.TYPE)
115
@Retention(RetentionPolicy.RUNTIME)
116
public @interface Endpoint {
117
String id() default "";
118
@Deprecated(since = "3.4.0", forRemoval = true)
119
boolean enableByDefault() default true;
120
Access defaultAccess() default Access.UNRESTRICTED;
121
}
122
123
@Target(ElementType.METHOD)
124
@Retention(RetentionPolicy.RUNTIME)
125
public @interface ReadOperation {
126
String[] produces() default {};
127
Class<? extends Producible> producesFrom() default Producible.class;
128
}
129
130
@Target(ElementType.METHOD)
131
@Retention(RetentionPolicy.RUNTIME)
132
public @interface WriteOperation {
133
String[] produces() default {};
134
Class<? extends Producible> producesFrom() default Producible.class;
135
}
136
137
@Target(ElementType.METHOD)
138
@Retention(RetentionPolicy.RUNTIME)
139
public @interface DeleteOperation {
140
String[] produces() default {};
141
Class<? extends Producible> producesFrom() default Producible.class;
142
}
143
```
144
145
[Endpoint Framework](./endpoints.md)
146
147
### Health Monitoring
148
149
Comprehensive health checking system with built-in indicators for databases, messaging systems, and infrastructure components. Supports both blocking and reactive implementations.
150
151
```java { .api }
152
public interface HealthIndicator {
153
Health health();
154
}
155
156
public interface ReactiveHealthIndicator {
157
Mono<Health> health();
158
}
159
160
public final class Health {
161
public static Builder up();
162
public static Builder down();
163
public static Builder unknown();
164
public static Builder status(Status status);
165
}
166
```
167
168
[Health Monitoring](./health.md)
169
170
### Metrics Collection
171
172
Integration with Micrometer for comprehensive application metrics including JVM, HTTP, database, and custom metrics. Supports various monitoring system exports including Prometheus, CloudWatch, and more.
173
174
```java { .api }
175
public class MetricsEndpoint {
176
public MetricsEndpoint(MeterRegistry registry);
177
public MetricNamesDescriptor listNames();
178
public MetricDescriptor metric(String requiredMetricName, List<String> tag);
179
}
180
181
// Auto-configuration for metrics binders
182
public interface MeterBinder {
183
void bindTo(MeterRegistry registry);
184
}
185
```
186
187
[Metrics Collection](./metrics.md)
188
189
### Application Information
190
191
System for contributing application metadata, build information, Git details, and environment information accessible via the info endpoint.
192
193
```java { .api }
194
public interface InfoContributor {
195
void contribute(Info.Builder builder);
196
}
197
198
public final class Info {
199
public Map<String, Object> getDetails();
200
201
public static final class Builder {
202
public Builder withDetail(String key, Object value);
203
public Builder withDetails(Map<String, Object> details);
204
public Info build();
205
}
206
}
207
```
208
209
[Application Information](./info.md)
210
211
### Audit Framework
212
213
Event auditing system for tracking authentication events, authorization failures, and custom application events with pluggable storage backends.
214
215
```java { .api }
216
public class AuditEvent {
217
public AuditEvent(String principal, String type, Map<String, Object> data);
218
public AuditEvent(String principal, String type, String... data);
219
public AuditEvent(Instant timestamp, String principal, String type, Map<String, Object> data);
220
221
public Instant getTimestamp();
222
public String getPrincipal();
223
public String getType();
224
public Map<String, Object> getData();
225
}
226
227
public interface AuditEventRepository {
228
void add(AuditEvent event);
229
List<AuditEvent> find(String principal, Instant after, String type);
230
}
231
```
232
233
[Audit Framework](./audit.md)
234
235
### Built-in Endpoints
236
237
Comprehensive set of pre-built endpoints for application management including beans, environment, configuration properties, thread dumps, heap dumps, and more.
238
239
```java { .api }
240
// Key built-in endpoints
241
public class BeansEndpoint { /* Application context beans */ }
242
public class EnvironmentEndpoint { /* Environment properties */ }
243
public class ConfigurationPropertiesEndpoint { /* Configuration properties */ }
244
public class ThreadDumpEndpoint { /* Thread dump generation */ }
245
public class HeapDumpEndpoint { /* Heap dump generation */ }
246
public class ShutdownEndpoint { /* Graceful shutdown */ }
247
```
248
249
[Built-in Endpoints](./builtin-endpoints.md)
250
251
## Types
252
253
### Core Types
254
255
```java { .api }
256
// Endpoint access level enumeration
257
public enum Access {
258
/** No access to the endpoint is permitted */
259
NONE,
260
/** Read-only access to the endpoint is permitted */
261
READ_ONLY,
262
/** Unrestricted access to the endpoint is permitted */
263
UNRESTRICTED;
264
265
/** Cap access to a maximum permitted level */
266
public Access cap(Access maxPermitted);
267
}
268
269
// Health status enumeration
270
public final class Status {
271
public static final Status UP;
272
public static final Status DOWN;
273
public static final Status OUT_OF_SERVICE;
274
public static final Status UNKNOWN;
275
276
public Status(String code, String description);
277
public String getCode();
278
public String getDescription();
279
}
280
281
// Endpoint identifier
282
public final class EndpointId {
283
public static EndpointId of(String value);
284
public String getValue();
285
}
286
287
// Security context for operations
288
public final class SecurityContext {
289
public static SecurityContext of(Principal principal, String... roles);
290
public Principal getPrincipal();
291
public boolean isUserInRole(String role);
292
}
293
294
// Web endpoint response wrapper
295
public final class WebEndpointResponse<T> {
296
public WebEndpointResponse(T body, int status);
297
public T getBody();
298
public int getStatus();
299
}
300
```