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
```