Initial commit
This commit is contained in:
Zhongwei Li
519
skills/spring-boot-actuator/references/auditing.md
Normal file
519
skills/spring-boot-actuator/references/auditing.md
Normal file
@@ -0,0 +1,519 @@
|
||||
# Auditing with Spring Boot Actuator
|
||||
|
||||
Once Spring Security is in play, Spring Boot Actuator has a flexible audit framework that publishes events (by default, "authentication success", "failure" and "access denied" exceptions). This feature can be very useful for reporting and for implementing a lock-out policy based on authentication failures.
|
||||
|
||||
You can enable auditing by providing a bean of type `AuditEventRepository` in your application's configuration. For convenience, Spring Boot offers an `InMemoryAuditEventRepository`. `InMemoryAuditEventRepository` has limited capabilities, and we recommend using it only for development environments. For production environments, consider creating your own alternative `AuditEventRepository` implementation.
|
||||
|
||||
## Basic Audit Configuration
|
||||
|
||||
### In-Memory Audit Repository (Development)
|
||||
|
||||
```java
|
||||
@Configuration
|
||||
public class AuditConfiguration {
|
||||
|
||||
@Bean
|
||||
public AuditEventRepository auditEventRepository() {
|
||||
return new InMemoryAuditEventRepository();
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Database Audit Repository (Production)
|
||||
|
||||
```java
|
||||
@Entity
|
||||
@Table(name = "audit_events")
|
||||
public class PersistentAuditEvent {
|
||||
|
||||
@Id
|
||||
@GeneratedValue(strategy = GenerationType.IDENTITY)
|
||||
private Long id;
|
||||
|
||||
@Column(name = "principal", nullable = false)
|
||||
private String principal;
|
||||
|
||||
@Column(name = "audit_event_type", nullable = false)
|
||||
private String auditEventType;
|
||||
|
||||
@Column(name = "audit_event_date", nullable = false)
|
||||
private Instant auditEventDate;
|
||||
|
||||
@ElementCollection
|
||||
@MapKeyColumn(name = "name")
|
||||
@Column(name = "value")
|
||||
@CollectionTable(name = "audit_event_data",
|
||||
joinColumns = @JoinColumn(name = "event_id"))
|
||||
private Map<String, String> data = new HashMap<>();
|
||||
|
||||
// Constructors, getters, setters
|
||||
}
|
||||
|
||||
@Repository
|
||||
public class CustomAuditEventRepository implements AuditEventRepository {
|
||||
|
||||
private final PersistentAuditEventRepository repository;
|
||||
|
||||
public CustomAuditEventRepository(PersistentAuditEventRepository repository) {
|
||||
this.repository = repository;
|
||||
}
|
||||
|
||||
@Override
|
||||
public void add(AuditEvent event) {
|
||||
PersistentAuditEvent persistentEvent = new PersistentAuditEvent();
|
||||
persistentEvent.setPrincipal(event.getPrincipal());
|
||||
persistentEvent.setAuditEventType(event.getType());
|
||||
persistentEvent.setAuditEventDate(event.getTimestamp());
|
||||
persistentEvent.setData(event.getData());
|
||||
repository.save(persistentEvent);
|
||||
}
|
||||
|
||||
@Override
|
||||
public List<AuditEvent> find(String principal, Instant after, String type) {
|
||||
List<PersistentAuditEvent> events = repository.findByPrincipalAndAuditEventDateAfterAndAuditEventType(
|
||||
principal, after, type);
|
||||
return events.stream()
|
||||
.map(this::convertToAuditEvent)
|
||||
.collect(Collectors.toList());
|
||||
}
|
||||
|
||||
private AuditEvent convertToAuditEvent(PersistentAuditEvent persistentEvent) {
|
||||
return new AuditEvent(persistentEvent.getAuditEventDate(),
|
||||
persistentEvent.getPrincipal(),
|
||||
persistentEvent.getAuditEventType(),
|
||||
persistentEvent.getData());
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Custom Auditing
|
||||
|
||||
### Custom Audit Events
|
||||
|
||||
You can publish custom audit events using `AuditEventRepository`:
|
||||
|
||||
```java
|
||||
@Service
|
||||
public class UserService {
|
||||
|
||||
private final AuditEventRepository auditEventRepository;
|
||||
private final UserRepository userRepository;
|
||||
|
||||
public UserService(AuditEventRepository auditEventRepository,
|
||||
UserRepository userRepository) {
|
||||
this.auditEventRepository = auditEventRepository;
|
||||
this.userRepository = userRepository;
|
||||
}
|
||||
|
||||
public User createUser(CreateUserRequest request) {
|
||||
User user = userRepository.save(request.toUser());
|
||||
|
||||
// Publish audit event
|
||||
Map<String, String> data = new HashMap<>();
|
||||
data.put("userId", user.getId().toString());
|
||||
data.put("username", user.getUsername());
|
||||
data.put("email", user.getEmail());
|
||||
|
||||
AuditEvent event = new AuditEvent(getCurrentUsername(), "USER_CREATED", data);
|
||||
auditEventRepository.add(event);
|
||||
|
||||
return user;
|
||||
}
|
||||
|
||||
public void deleteUser(Long userId) {
|
||||
User user = userRepository.findById(userId)
|
||||
.orElseThrow(() -> new UserNotFoundException(userId));
|
||||
|
||||
userRepository.delete(user);
|
||||
|
||||
// Publish audit event
|
||||
Map<String, String> data = new HashMap<>();
|
||||
data.put("userId", userId.toString());
|
||||
data.put("username", user.getUsername());
|
||||
|
||||
AuditEvent event = new AuditEvent(getCurrentUsername(), "USER_DELETED", data);
|
||||
auditEventRepository.add(event);
|
||||
}
|
||||
|
||||
private String getCurrentUsername() {
|
||||
Authentication auth = SecurityContextHolder.getContext().getAuthentication();
|
||||
return auth != null ? auth.getName() : "system";
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Custom Audit Event Publisher
|
||||
|
||||
```java
|
||||
@Component
|
||||
public class AuditEventPublisher {
|
||||
|
||||
private final AuditEventRepository auditEventRepository;
|
||||
|
||||
public AuditEventPublisher(AuditEventRepository auditEventRepository) {
|
||||
this.auditEventRepository = auditEventRepository;
|
||||
}
|
||||
|
||||
public void publishEvent(String type, Map<String, String> data) {
|
||||
String principal = getCurrentPrincipal();
|
||||
AuditEvent event = new AuditEvent(principal, type, data);
|
||||
auditEventRepository.add(event);
|
||||
}
|
||||
|
||||
public void publishSecurityEvent(String type, String details) {
|
||||
Map<String, String> data = new HashMap<>();
|
||||
data.put("details", details);
|
||||
data.put("timestamp", Instant.now().toString());
|
||||
data.put("source", "security");
|
||||
publishEvent(type, data);
|
||||
}
|
||||
|
||||
public void publishBusinessEvent(String type, String entityId, String action) {
|
||||
Map<String, String> data = new HashMap<>();
|
||||
data.put("entityId", entityId);
|
||||
data.put("action", action);
|
||||
data.put("timestamp", Instant.now().toString());
|
||||
publishEvent(type, data);
|
||||
}
|
||||
|
||||
private String getCurrentPrincipal() {
|
||||
Authentication auth = SecurityContextHolder.getContext().getAuthentication();
|
||||
return auth != null ? auth.getName() : "anonymous";
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Method-Level Auditing
|
||||
|
||||
### Using AOP for Automatic Auditing
|
||||
|
||||
```java
|
||||
@Target({ElementType.METHOD})
|
||||
@Retention(RetentionPolicy.RUNTIME)
|
||||
public @interface Auditable {
|
||||
String value() default "";
|
||||
String type() default "";
|
||||
boolean includeArgs() default false;
|
||||
boolean includeResult() default false;
|
||||
}
|
||||
|
||||
@Aspect
|
||||
@Component
|
||||
public class AuditableAspect {
|
||||
|
||||
private final AuditEventPublisher auditEventPublisher;
|
||||
|
||||
public AuditableAspect(AuditEventPublisher auditEventPublisher) {
|
||||
this.auditEventPublisher = auditEventPublisher;
|
||||
}
|
||||
|
||||
@Around("@annotation(auditable)")
|
||||
public Object auditMethod(ProceedingJoinPoint joinPoint, Auditable auditable) throws Throwable {
|
||||
String methodName = joinPoint.getSignature().getName();
|
||||
String className = joinPoint.getTarget().getClass().getSimpleName();
|
||||
String auditType = auditable.type().isEmpty() ?
|
||||
className + "." + methodName : auditable.type();
|
||||
|
||||
Map<String, String> data = new HashMap<>();
|
||||
data.put("method", methodName);
|
||||
data.put("class", className);
|
||||
|
||||
if (auditable.includeArgs()) {
|
||||
Object[] args = joinPoint.getArgs();
|
||||
for (int i = 0; i < args.length; i++) {
|
||||
data.put("arg" + i, String.valueOf(args[i]));
|
||||
}
|
||||
}
|
||||
|
||||
try {
|
||||
Object result = joinPoint.proceed();
|
||||
|
||||
if (auditable.includeResult() && result != null) {
|
||||
data.put("result", String.valueOf(result));
|
||||
}
|
||||
|
||||
data.put("status", "success");
|
||||
auditEventPublisher.publishEvent(auditType, data);
|
||||
|
||||
return result;
|
||||
} catch (Exception ex) {
|
||||
data.put("status", "failure");
|
||||
data.put("error", ex.getMessage());
|
||||
auditEventPublisher.publishEvent(auditType, data);
|
||||
throw ex;
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Usage Example
|
||||
|
||||
```java
|
||||
@Service
|
||||
public class OrderService {
|
||||
|
||||
@Auditable(type = "ORDER_CREATED", includeArgs = true)
|
||||
public Order createOrder(CreateOrderRequest request) {
|
||||
// Order creation logic
|
||||
return new Order();
|
||||
}
|
||||
|
||||
@Auditable(type = "ORDER_CANCELLED", includeResult = true)
|
||||
public Order cancelOrder(Long orderId) {
|
||||
// Order cancellation logic
|
||||
return cancelledOrder;
|
||||
}
|
||||
|
||||
@Auditable(type = "PAYMENT_PROCESSED")
|
||||
public PaymentResult processPayment(PaymentRequest request) {
|
||||
// Payment processing logic
|
||||
return new PaymentResult();
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Security Audit Events
|
||||
|
||||
### Authentication Events
|
||||
|
||||
Spring Boot automatically publishes authentication events when using Spring Security:
|
||||
|
||||
- `AUTHENTICATION_SUCCESS`
|
||||
- `AUTHENTICATION_FAILURE`
|
||||
- `ACCESS_DENIED`
|
||||
|
||||
### Custom Security Events
|
||||
|
||||
```java
|
||||
@Component
|
||||
public class SecurityAuditService {
|
||||
|
||||
private final AuditEventPublisher auditEventPublisher;
|
||||
|
||||
public SecurityAuditService(AuditEventPublisher auditEventPublisher) {
|
||||
this.auditEventPublisher = auditEventPublisher;
|
||||
}
|
||||
|
||||
@EventListener
|
||||
public void handleAuthenticationSuccess(AuthenticationSuccessEvent event) {
|
||||
Map<String, String> data = new HashMap<>();
|
||||
data.put("username", event.getAuthentication().getName());
|
||||
data.put("authorities", event.getAuthentication().getAuthorities().toString());
|
||||
data.put("source", getClientIP());
|
||||
|
||||
auditEventPublisher.publishEvent("AUTHENTICATION_SUCCESS", data);
|
||||
}
|
||||
|
||||
@EventListener
|
||||
public void handleAuthenticationFailure(AbstractAuthenticationFailureEvent event) {
|
||||
Map<String, String> data = new HashMap<>();
|
||||
data.put("username", event.getAuthentication().getName());
|
||||
data.put("exception", event.getException().getClass().getSimpleName());
|
||||
data.put("message", event.getException().getMessage());
|
||||
data.put("source", getClientIP());
|
||||
|
||||
auditEventPublisher.publishEvent("AUTHENTICATION_FAILURE", data);
|
||||
}
|
||||
|
||||
@EventListener
|
||||
public void handleAccessDenied(AuthorizationDeniedEvent event) {
|
||||
Map<String, String> data = new HashMap<>();
|
||||
data.put("username", event.getAuthentication().getName());
|
||||
data.put("resource", event.getAuthorizationDecision().toString());
|
||||
data.put("source", getClientIP());
|
||||
|
||||
auditEventPublisher.publishEvent("ACCESS_DENIED", data);
|
||||
}
|
||||
|
||||
private String getClientIP() {
|
||||
RequestAttributes requestAttributes = RequestContextHolder.getRequestAttributes();
|
||||
if (requestAttributes instanceof ServletRequestAttributes) {
|
||||
HttpServletRequest request = ((ServletRequestAttributes) requestAttributes).getRequest();
|
||||
return request.getRemoteAddr();
|
||||
}
|
||||
return "unknown";
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Password Change Auditing
|
||||
|
||||
```java
|
||||
@Service
|
||||
public class PasswordService {
|
||||
|
||||
private final AuditEventPublisher auditEventPublisher;
|
||||
private final PasswordEncoder passwordEncoder;
|
||||
|
||||
public PasswordService(AuditEventPublisher auditEventPublisher,
|
||||
PasswordEncoder passwordEncoder) {
|
||||
this.auditEventPublisher = auditEventPublisher;
|
||||
this.passwordEncoder = passwordEncoder;
|
||||
}
|
||||
|
||||
public void changePassword(String oldPassword, String newPassword) {
|
||||
String username = getCurrentUsername();
|
||||
|
||||
try {
|
||||
// Validate old password
|
||||
if (!isCurrentPassword(oldPassword)) {
|
||||
Map<String, String> data = new HashMap<>();
|
||||
data.put("username", username);
|
||||
data.put("reason", "invalid_old_password");
|
||||
auditEventPublisher.publishEvent("PASSWORD_CHANGE_FAILED", data);
|
||||
throw new InvalidPasswordException("Invalid old password");
|
||||
}
|
||||
|
||||
// Change password
|
||||
updatePassword(newPassword);
|
||||
|
||||
// Audit success
|
||||
Map<String, String> data = new HashMap<>();
|
||||
data.put("username", username);
|
||||
auditEventPublisher.publishEvent("PASSWORD_CHANGED", data);
|
||||
|
||||
} catch (Exception ex) {
|
||||
Map<String, String> data = new HashMap<>();
|
||||
data.put("username", username);
|
||||
data.put("error", ex.getMessage());
|
||||
auditEventPublisher.publishEvent("PASSWORD_CHANGE_ERROR", data);
|
||||
throw ex;
|
||||
}
|
||||
}
|
||||
|
||||
private boolean isCurrentPassword(String password) {
|
||||
// Implementation
|
||||
return true;
|
||||
}
|
||||
|
||||
private void updatePassword(String newPassword) {
|
||||
// Implementation
|
||||
}
|
||||
|
||||
private String getCurrentUsername() {
|
||||
Authentication auth = SecurityContextHolder.getContext().getAuthentication();
|
||||
return auth != null ? auth.getName() : "anonymous";
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Audit Events Endpoint
|
||||
|
||||
The `/actuator/auditevents` endpoint exposes audit events:
|
||||
|
||||
```
|
||||
GET /actuator/auditevents
|
||||
GET /actuator/auditevents?principal=user&after=2023-01-01T00:00:00Z&type=USER_CREATED
|
||||
```
|
||||
|
||||
Response format:
|
||||
|
||||
```json
|
||||
{
|
||||
"events": [
|
||||
{
|
||||
"timestamp": "2023-12-01T10:30:00Z",
|
||||
"principal": "admin",
|
||||
"type": "USER_CREATED",
|
||||
"data": {
|
||||
"userId": "123",
|
||||
"username": "newuser",
|
||||
"email": "user@example.com"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Production Configuration
|
||||
|
||||
### Secure Audit Endpoint
|
||||
|
||||
```java
|
||||
@Configuration
|
||||
public class AuditSecurityConfig {
|
||||
|
||||
@Bean
|
||||
@Order(1)
|
||||
public SecurityFilterChain auditSecurityFilterChain(HttpSecurity http) throws Exception {
|
||||
return http
|
||||
.requestMatcher(EndpointRequest.to("auditevents"))
|
||||
.authorizeHttpRequests(requests ->
|
||||
requests.anyRequest().hasRole("AUDITOR"))
|
||||
.httpBasic(withDefaults())
|
||||
.build();
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Audit Configuration
|
||||
|
||||
```yaml
|
||||
management:
|
||||
endpoint:
|
||||
auditevents:
|
||||
enabled: true
|
||||
cache:
|
||||
time-to-live: 10s
|
||||
endpoints:
|
||||
web:
|
||||
exposure:
|
||||
include: "auditevents"
|
||||
|
||||
# Custom audit properties
|
||||
audit:
|
||||
retention-days: 90
|
||||
max-events-per-request: 100
|
||||
sensitive-data-masking: true
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Data Sensitivity**: Never include sensitive data (passwords, tokens) in audit events
|
||||
2. **Performance**: Consider async processing for high-volume audit events
|
||||
3. **Retention**: Implement audit data retention policies
|
||||
4. **Security**: Secure the audit endpoint and audit data storage
|
||||
5. **Monitoring**: Monitor audit system health and performance
|
||||
6. **Compliance**: Ensure audit events meet regulatory requirements
|
||||
7. **Immutability**: Ensure audit events cannot be modified after creation
|
||||
|
||||
### Async Audit Processing
|
||||
|
||||
```java
|
||||
@Configuration
|
||||
@EnableAsync
|
||||
public class AsyncAuditConfiguration {
|
||||
|
||||
@Bean
|
||||
public TaskExecutor auditTaskExecutor() {
|
||||
ThreadPoolTaskExecutor executor = new ThreadPoolTaskExecutor();
|
||||
executor.setCorePoolSize(2);
|
||||
executor.setMaxPoolSize(5);
|
||||
executor.setQueueCapacity(100);
|
||||
executor.setThreadNamePrefix("audit-");
|
||||
executor.initialize();
|
||||
return executor;
|
||||
}
|
||||
}
|
||||
|
||||
@Service
|
||||
public class AsyncAuditEventRepository implements AuditEventRepository {
|
||||
|
||||
private final AuditEventRepository delegate;
|
||||
|
||||
public AsyncAuditEventRepository(AuditEventRepository delegate) {
|
||||
this.delegate = delegate;
|
||||
}
|
||||
|
||||
@Override
|
||||
@Async("auditTaskExecutor")
|
||||
public void add(AuditEvent event) {
|
||||
delegate.add(event);
|
||||
}
|
||||
|
||||
@Override
|
||||
public List<AuditEvent> find(String principal, Instant after, String type) {
|
||||
return delegate.find(principal, after, type);
|
||||
}
|
||||
}
|
||||
```
|
||||
48
skills/spring-boot-actuator/references/cloud-foundry.md
Normal file
48
skills/spring-boot-actuator/references/cloud-foundry.md
Normal file
@@ -0,0 +1,48 @@
|
||||
# Cloud Foundry Support
|
||||
|
||||
Spring Boot Actuator includes additional support when you deploy to a compatible Cloud Foundry instance. The `/cloudfoundryapplication` path provides an alternative secured route to all `@Endpoint` beans.
|
||||
|
||||
## Cloud Foundry Configuration
|
||||
|
||||
When running on Cloud Foundry, Spring Boot automatically configures:
|
||||
|
||||
- Cloud Foundry-specific health indicators
|
||||
- Cloud Foundry application information
|
||||
- Secure endpoint access through Cloud Foundry's security model
|
||||
|
||||
### Basic Configuration
|
||||
|
||||
```yaml
|
||||
management:
|
||||
cloudfoundry:
|
||||
enabled: true
|
||||
endpoints:
|
||||
web:
|
||||
exposure:
|
||||
include: "*"
|
||||
```
|
||||
|
||||
### Cloud Foundry Health
|
||||
|
||||
```java
|
||||
@Component
|
||||
public class CloudFoundryHealthIndicator implements HealthIndicator {
|
||||
|
||||
@Override
|
||||
public Health health() {
|
||||
// Cloud Foundry specific health checks
|
||||
return Health.up()
|
||||
.withDetail("cloud-foundry", "available")
|
||||
.withDetail("instance-index", System.getenv("CF_INSTANCE_INDEX"))
|
||||
.withDetail("application-id", System.getenv("VCAP_APPLICATION"))
|
||||
.build();
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Security**: Use Cloud Foundry's built-in security for actuator endpoints
|
||||
2. **Service Binding**: Leverage VCAP_SERVICES for automatic configuration
|
||||
3. **Health Checks**: Configure appropriate health endpoints for load balancer checks
|
||||
4. **Metrics**: Export metrics to Cloud Foundry monitoring systems
|
||||
28
skills/spring-boot-actuator/references/enabling.md
Normal file
28
skills/spring-boot-actuator/references/enabling.md
Normal file
@@ -0,0 +1,28 @@
|
||||
# Enabling Actuator
|
||||
|
||||
The `spring-boot-actuator` module provides all of Spring Boot's production-ready features. The recommended way to enable the features is to add a dependency on the `spring-boot-starter-actuator` starter.
|
||||
|
||||
> **Definition of Actuator**
|
||||
>
|
||||
> An actuator is a manufacturing term that refers to a mechanical device for moving or controlling something. Actuators can generate a large amount of motion from a small change.
|
||||
|
||||
## Adding the Actuator Dependency
|
||||
|
||||
To add the actuator to a Maven-based project, add the following starter dependency:
|
||||
|
||||
```xml
|
||||
<dependencies>
|
||||
<dependency>
|
||||
<groupId>org.springframework.boot</groupId>
|
||||
<artifactId>spring-boot-starter-actuator</artifactId>
|
||||
</dependency>
|
||||
</dependencies>
|
||||
```
|
||||
|
||||
For Gradle, use the following declaration:
|
||||
|
||||
```gradle
|
||||
dependencies {
|
||||
implementation 'org.springframework.boot:spring-boot-starter-actuator'
|
||||
}
|
||||
```
|
||||
165
skills/spring-boot-actuator/references/endpoint-reference.md
Normal file
165
skills/spring-boot-actuator/references/endpoint-reference.md
Normal file
@@ -0,0 +1,165 @@
|
||||
# Endpoint Reference
|
||||
|
||||
This document provides a comprehensive reference for all available Spring Boot Actuator endpoints.
|
||||
|
||||
## Built-in Endpoints
|
||||
|
||||
| Endpoint | HTTP Method | Description | Default Exposure |
|
||||
|----------|-------------|-------------|------------------|
|
||||
| `auditevents` | GET | Audit events for the application | JMX |
|
||||
| `beans` | GET | Complete list of Spring beans | JMX |
|
||||
| `caches` | GET, DELETE | Available caches | JMX |
|
||||
| `conditions` | GET | Configuration and auto-configuration conditions | JMX |
|
||||
| `configprops` | GET | Configuration properties | JMX |
|
||||
| `env` | GET, POST | Environment properties | JMX |
|
||||
| `flyway` | GET | Flyway database migrations | JMX |
|
||||
| `health` | GET | Application health information | Web, JMX |
|
||||
| `heapdump` | GET | Heap dump | JMX |
|
||||
| `httpexchanges` | GET | HTTP exchange information | JMX |
|
||||
| `info` | GET | Application information | Web, JMX |
|
||||
| `integrationgraph` | GET | Spring Integration graph | JMX |
|
||||
| `logfile` | GET | Application log file | JMX |
|
||||
| `loggers` | GET, POST | Logger configuration | JMX |
|
||||
| `liquibase` | GET | Liquibase database migrations | JMX |
|
||||
| `mappings` | GET | Request mapping information | JMX |
|
||||
| `metrics` | GET | Application metrics | JMX |
|
||||
| `prometheus` | GET | Prometheus metrics | None |
|
||||
| `quartz` | GET | Quartz scheduler information | JMX |
|
||||
| `scheduledtasks` | GET | Scheduled tasks | JMX |
|
||||
| `sessions` | GET, DELETE | User sessions | JMX |
|
||||
| `shutdown` | POST | Graceful application shutdown | JMX |
|
||||
| `startup` | GET | Application startup information | JMX |
|
||||
| `threaddump` | GET | Thread dump | JMX |
|
||||
|
||||
## Endpoint URLs
|
||||
|
||||
### Web Endpoints
|
||||
- Base path: `/actuator`
|
||||
- Example: `GET /actuator/health`
|
||||
- Custom base path: `management.endpoints.web.base-path`
|
||||
|
||||
### JMX Endpoints
|
||||
- Domain: `org.springframework.boot`
|
||||
- Example: `org.springframework.boot:type=Endpoint,name=Health`
|
||||
|
||||
## Endpoint Configuration
|
||||
|
||||
### Global Configuration
|
||||
|
||||
```yaml
|
||||
management:
|
||||
endpoints:
|
||||
enabled-by-default: true
|
||||
web:
|
||||
exposure:
|
||||
include: "health,info,metrics"
|
||||
exclude: "env,beans"
|
||||
base-path: "/actuator"
|
||||
path-mapping:
|
||||
health: "status"
|
||||
jmx:
|
||||
exposure:
|
||||
include: "*"
|
||||
```
|
||||
|
||||
### Individual Endpoint Configuration
|
||||
|
||||
```yaml
|
||||
management:
|
||||
endpoint:
|
||||
health:
|
||||
enabled: true
|
||||
show-details: when-authorized
|
||||
show-components: always
|
||||
cache:
|
||||
time-to-live: 10s
|
||||
metrics:
|
||||
enabled: true
|
||||
cache:
|
||||
time-to-live: 0s
|
||||
info:
|
||||
enabled: true
|
||||
```
|
||||
|
||||
## Security Configuration
|
||||
|
||||
### Web Security
|
||||
|
||||
```java
|
||||
@Configuration
|
||||
public class ActuatorSecurityConfiguration {
|
||||
|
||||
@Bean
|
||||
@Order(1)
|
||||
public SecurityFilterChain actuatorSecurityFilterChain(HttpSecurity http) throws Exception {
|
||||
return http
|
||||
.requestMatcher(EndpointRequest.toAnyEndpoint())
|
||||
.authorizeHttpRequests(requests ->
|
||||
requests
|
||||
.requestMatchers(EndpointRequest.to("health", "info")).permitAll()
|
||||
.anyRequest().hasRole("ACTUATOR")
|
||||
)
|
||||
.httpBasic(withDefaults())
|
||||
.build();
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Method-level Security
|
||||
|
||||
```java
|
||||
@PreAuthorize("hasRole('ADMIN')")
|
||||
@GetMapping("/actuator/shutdown")
|
||||
public Object shutdown() {
|
||||
// Shutdown logic
|
||||
}
|
||||
```
|
||||
|
||||
## Custom Endpoints
|
||||
|
||||
### Creating Custom Endpoints
|
||||
|
||||
```java
|
||||
@Component
|
||||
@Endpoint(id = "custom")
|
||||
public class CustomEndpoint {
|
||||
|
||||
@ReadOperation
|
||||
public Map<String, Object> customEndpoint() {
|
||||
return Map.of("custom", "data");
|
||||
}
|
||||
|
||||
@WriteOperation
|
||||
public void writeOperation(@Selector String name, String value) {
|
||||
// Write operation
|
||||
}
|
||||
|
||||
@DeleteOperation
|
||||
public void deleteOperation(@Selector String name) {
|
||||
// Delete operation
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Web-specific Endpoints
|
||||
|
||||
```java
|
||||
@Component
|
||||
@WebEndpoint(id = "web-custom")
|
||||
public class WebCustomEndpoint {
|
||||
|
||||
@ReadOperation
|
||||
public WebEndpointResponse<Map<String, Object>> webCustomEndpoint() {
|
||||
Map<String, Object> data = Map.of("web", "specific");
|
||||
return new WebEndpointResponse<>(data, 200);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Security**: Always secure actuator endpoints in production
|
||||
2. **Exposure**: Only expose necessary endpoints
|
||||
3. **Performance**: Configure appropriate caching for endpoints
|
||||
4. **Monitoring**: Monitor actuator endpoint usage
|
||||
5. **Documentation**: Document custom endpoints thoroughly
|
||||
390
skills/spring-boot-actuator/references/endpoints.md
Normal file
390
skills/spring-boot-actuator/references/endpoints.md
Normal file
@@ -0,0 +1,390 @@
|
||||
# Actuator Endpoints
|
||||
|
||||
Actuator endpoints let you monitor and interact with your application. Spring Boot includes a number of built-in endpoints and lets you add your own. For example, the `health` endpoint provides basic application health information.
|
||||
|
||||
You can control access to each individual endpoint and expose them (make them remotely accessible) over HTTP or JMX. An endpoint is considered to be available when access to it is permitted and it is exposed. The built-in endpoints are auto-configured only when they are available. Most applications choose exposure over HTTP, where the ID of the endpoint and a prefix of `/actuator` is mapped to a URL. For example, by default, the `health` endpoint is mapped to `/actuator/health`.
|
||||
|
||||
> **TIP**
|
||||
>
|
||||
> To learn more about the Actuator's endpoints and their request and response formats, see the [Spring Boot Actuator API documentation](https://docs.spring.io/spring-boot/docs/current/actuator-api/htmlsingle/).
|
||||
|
||||
## Available Endpoints
|
||||
|
||||
The following technology-agnostic endpoints are available:
|
||||
|
||||
| ID | Description |
|
||||
|----|----|
|
||||
| `auditevents` | Exposes audit events information for the current application. Requires an `AuditEventRepository` bean. |
|
||||
| `beans` | Displays a complete list of all the Spring beans in your application. |
|
||||
| `caches` | Exposes available caches. |
|
||||
| `conditions` | Shows the conditions that were evaluated on configuration and auto-configuration classes and the reasons why they did or did not match. |
|
||||
| `configprops` | Displays a collated list of all `@ConfigurationProperties`. Subject to sanitization. |
|
||||
| `env` | Exposes properties from Spring's `ConfigurableEnvironment`. Subject to sanitization. |
|
||||
| `flyway` | Shows any Flyway database migrations that have been applied. Requires one or more `Flyway` beans. |
|
||||
| `health` | Shows application health information. |
|
||||
| `httpexchanges` | Displays HTTP exchange information (by default, the last 100 HTTP request-response exchanges). Requires an `HttpExchangeRepository` bean. |
|
||||
| `info` | Displays arbitrary application info. |
|
||||
| `integrationgraph` | Shows the Spring Integration graph. Requires a dependency on `spring-integration-core`. |
|
||||
| `loggers` | Shows and modifies the configuration of loggers in the application. |
|
||||
| `liquibase` | Shows any Liquibase database migrations that have been applied. Requires one or more `Liquibase` beans. |
|
||||
| `metrics` | Shows metrics information for the current application. |
|
||||
| `mappings` | Displays a collated list of all `@RequestMapping` paths. |
|
||||
| `quartz` | Shows information about Quartz Scheduler jobs. Subject to sanitization. |
|
||||
| `scheduledtasks` | Displays the scheduled tasks in your application. |
|
||||
| `sessions` | Allows retrieval and deletion of user sessions from a Spring Session-backed session store. Requires a servlet-based web application that uses Spring Session. |
|
||||
| `shutdown` | Lets the application be gracefully shutdown. Only works when using jar packaging. Disabled by default. |
|
||||
| `startup` | Shows the startup steps data collected by the `ApplicationStartup`. Requires the `SpringApplication` to be configured with a `BufferingApplicationStartup`. |
|
||||
| `threaddump` | Performs a thread dump. |
|
||||
|
||||
If your application is a web application (Spring MVC, Spring WebFlux, or Jersey), you can use the following additional endpoints:
|
||||
|
||||
| ID | Description |
|
||||
|----|----|
|
||||
| `heapdump` | Returns a heap dump file. On a HotSpot JVM, an `HPROF`-format file is returned. On an OpenJ9 JVM, a `PHD`-format file is returned. |
|
||||
| `logfile` | Returns the contents of the logfile (if the `logging.file.name` or the `logging.file.path` property has been set). Supports the use of the HTTP `Range` header to retrieve part of the log file's content. |
|
||||
| `prometheus` | Exposes metrics in a format that can be scraped by a Prometheus server. Requires a dependency on `micrometer-registry-prometheus`. |
|
||||
|
||||
## Controlling Access to Endpoints
|
||||
|
||||
By default, access to all endpoints except for `shutdown` and `heapdump` is unrestricted. To configure the permitted access to an endpoint, use its `management.endpoint.<id>.access` property. The following example allows unrestricted access to the `shutdown` endpoint:
|
||||
|
||||
```yaml
|
||||
management:
|
||||
endpoint:
|
||||
shutdown:
|
||||
access: unrestricted
|
||||
```
|
||||
|
||||
If you prefer access to be opt-in rather than opt-out, set the `management.endpoints.access.default` property to `none` and use individual endpoint `access` properties to opt back in. The following example allows read-only access to the `loggers` endpoint and denies access to all other endpoints:
|
||||
|
||||
```yaml
|
||||
management:
|
||||
endpoints:
|
||||
access:
|
||||
default: none
|
||||
endpoint:
|
||||
loggers:
|
||||
access: read-only
|
||||
```
|
||||
|
||||
> **NOTE**
|
||||
>
|
||||
> Inaccessible endpoints are removed entirely from the application context. If you want to change only the technologies over which an endpoint is exposed, use the `include` and `exclude` properties instead.
|
||||
|
||||
### Limiting Access
|
||||
|
||||
Application-wide endpoint access can be limited using the `management.endpoints.access.max-permitted` property. This property takes precedence over the default access or an individual endpoint's access level. Set it to `none` to make all endpoints inaccessible. Set it to `read-only` to only allow read access to endpoints.
|
||||
|
||||
For `@Endpoint`, `@JmxEndpoint`, and `@WebEndpoint`, read access equates to the endpoint methods annotated with `@ReadOperation`. For `@ControllerEndpoint` and `@RestControllerEndpoint`, read access equates to HTTP GET requests.
|
||||
|
||||
## Exposing Endpoints
|
||||
|
||||
By default, only the `health` endpoint is exposed over HTTP and JMX. To configure which endpoints are exposed, use the `include` and `exclude` properties:
|
||||
|
||||
```yaml
|
||||
management:
|
||||
endpoints:
|
||||
web:
|
||||
exposure:
|
||||
include: "health,info,metrics"
|
||||
exclude: "beans"
|
||||
```
|
||||
|
||||
The `include` property lists the IDs of the endpoints that are exposed. The `exclude` property lists the IDs of the endpoints that should not be exposed. The `exclude` property takes precedence over the `include` property.
|
||||
|
||||
To expose all endpoints over HTTP:
|
||||
|
||||
```yaml
|
||||
management:
|
||||
endpoints:
|
||||
web:
|
||||
exposure:
|
||||
include: "*"
|
||||
```
|
||||
|
||||
## Security
|
||||
|
||||
For security purposes, only the `/health` endpoint is exposed over HTTP by default. You can use the `management.endpoints.web.exposure.include` property to configure the endpoints that are exposed.
|
||||
|
||||
If Spring Security is on the classpath and no other `WebSecurityConfigurer` bean is present, all actuators other than `/health` are secured by Spring Boot auto-configuration. If you define a custom `WebSecurityConfigurer` bean, Spring Boot auto-configuration backs off and lets you fully control the actuator access rules.
|
||||
|
||||
## Custom Endpoints
|
||||
|
||||
You can add additional endpoints by using `@Endpoint` and `@Component` annotations:
|
||||
|
||||
```java
|
||||
@Component
|
||||
@Endpoint(id = "custom")
|
||||
public class CustomEndpoint {
|
||||
|
||||
@ReadOperation
|
||||
public String customEndpoint() {
|
||||
return "Custom endpoint response";
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Web Endpoints
|
||||
|
||||
For web-specific endpoints, use `@WebEndpoint`:
|
||||
|
||||
```java
|
||||
@Component
|
||||
@WebEndpoint(id = "web-custom")
|
||||
public class WebCustomEndpoint {
|
||||
|
||||
@ReadOperation
|
||||
public String webCustomEndpoint() {
|
||||
return "Web custom endpoint response";
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### JMX Endpoints
|
||||
|
||||
For JMX-specific endpoints, use `@JmxEndpoint`:
|
||||
|
||||
```java
|
||||
@Component
|
||||
@JmxEndpoint(id = "jmx-custom")
|
||||
public class JmxCustomEndpoint {
|
||||
|
||||
@ReadOperation
|
||||
public String jmxCustomEndpoint() {
|
||||
return "JMX custom endpoint response";
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Health Endpoint
|
||||
|
||||
The `health` endpoint provides detailed information about the health of the application. By default, only health status is shown to unauthenticated users:
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "UP"
|
||||
}
|
||||
```
|
||||
|
||||
To show detailed health information:
|
||||
|
||||
```yaml
|
||||
management:
|
||||
endpoint:
|
||||
health:
|
||||
show-details: always
|
||||
```
|
||||
|
||||
### Custom Health Indicators
|
||||
|
||||
You can provide custom health information by registering Spring beans that implement the `HealthIndicator` interface:
|
||||
|
||||
```java
|
||||
@Component
|
||||
public class CustomHealthIndicator implements HealthIndicator {
|
||||
|
||||
@Override
|
||||
public Health health() {
|
||||
// Perform custom health check
|
||||
boolean isHealthy = checkHealth();
|
||||
|
||||
if (isHealthy) {
|
||||
return Health.up()
|
||||
.withDetail("custom", "Service is running")
|
||||
.build();
|
||||
} else {
|
||||
return Health.down()
|
||||
.withDetail("custom", "Service is down")
|
||||
.build();
|
||||
}
|
||||
}
|
||||
|
||||
private boolean checkHealth() {
|
||||
// Custom health check logic
|
||||
return true;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Info Endpoint
|
||||
|
||||
The `info` endpoint publishes information about your application. You can customize this information by implementing `InfoContributor`:
|
||||
|
||||
```java
|
||||
@Component
|
||||
public class CustomInfoContributor implements InfoContributor {
|
||||
|
||||
@Override
|
||||
public void contribute(Info.Builder builder) {
|
||||
builder.withDetail("custom", "Custom application info");
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Git Information
|
||||
|
||||
To expose git information in the `info` endpoint, add the following to your build:
|
||||
|
||||
**Maven:**
|
||||
```xml
|
||||
<plugin>
|
||||
<groupId>pl.project13.maven</groupId>
|
||||
<artifactId>git-commit-id-plugin</artifactId>
|
||||
</plugin>
|
||||
```
|
||||
|
||||
**Gradle:**
|
||||
```groovy
|
||||
plugins {
|
||||
id "com.gorylenko.gradle-git-properties" version "2.4.1"
|
||||
}
|
||||
```
|
||||
|
||||
### Build Information
|
||||
|
||||
Build information can be added to the `info` endpoint by configuring the build plugins:
|
||||
|
||||
**Maven:**
|
||||
```xml
|
||||
<plugin>
|
||||
<groupId>org.springframework.boot</groupId>
|
||||
<artifactId>spring-boot-maven-plugin</artifactId>
|
||||
<executions>
|
||||
<execution>
|
||||
<goals>
|
||||
<goal>build-info</goal>
|
||||
</goals>
|
||||
</execution>
|
||||
</executions>
|
||||
</plugin>
|
||||
```
|
||||
|
||||
**Gradle:**
|
||||
```groovy
|
||||
springBoot {
|
||||
buildInfo()
|
||||
}
|
||||
```
|
||||
|
||||
## Metrics Endpoint
|
||||
|
||||
The `metrics` endpoint provides access to application metrics collected by Micrometer. You can view all available metrics:
|
||||
|
||||
```
|
||||
GET /actuator/metrics
|
||||
```
|
||||
|
||||
Or view a specific metric:
|
||||
|
||||
```
|
||||
GET /actuator/metrics/jvm.memory.used
|
||||
```
|
||||
|
||||
### Custom Metrics
|
||||
|
||||
You can add custom metrics using Micrometer:
|
||||
|
||||
```java
|
||||
@Component
|
||||
public class CustomMetrics {
|
||||
|
||||
private final Counter customCounter;
|
||||
private final Timer customTimer;
|
||||
|
||||
public CustomMetrics(MeterRegistry meterRegistry) {
|
||||
this.customCounter = Counter.builder("custom.requests")
|
||||
.description("Custom request counter")
|
||||
.register(meterRegistry);
|
||||
|
||||
this.customTimer = Timer.builder("custom.processing.time")
|
||||
.description("Custom processing time")
|
||||
.register(meterRegistry);
|
||||
}
|
||||
|
||||
public void incrementCounter() {
|
||||
customCounter.increment();
|
||||
}
|
||||
|
||||
public void recordTime(Duration duration) {
|
||||
customTimer.record(duration);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Environment Endpoint
|
||||
|
||||
The `env` endpoint exposes properties from the Spring `Environment`. This includes configuration properties, system properties, environment variables, and more.
|
||||
|
||||
To view a specific property:
|
||||
|
||||
```
|
||||
GET /actuator/env/server.port
|
||||
```
|
||||
|
||||
## Loggers Endpoint
|
||||
|
||||
The `loggers` endpoint shows and allows modification of logger levels in your application.
|
||||
|
||||
To view all loggers:
|
||||
|
||||
```
|
||||
GET /actuator/loggers
|
||||
```
|
||||
|
||||
To view a specific logger:
|
||||
|
||||
```
|
||||
GET /actuator/loggers/com.example.MyClass
|
||||
```
|
||||
|
||||
To change a logger level:
|
||||
|
||||
```
|
||||
POST /actuator/loggers/com.example.MyClass
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"configuredLevel": "DEBUG"
|
||||
}
|
||||
```
|
||||
|
||||
## Configuration Properties Endpoint
|
||||
|
||||
The `configprops` endpoint displays all `@ConfigurationProperties` in your application:
|
||||
|
||||
```
|
||||
GET /actuator/configprops
|
||||
```
|
||||
|
||||
Properties that may contain sensitive information are masked by default.
|
||||
|
||||
## Thread Dump Endpoint
|
||||
|
||||
The `threaddump` endpoint provides a thread dump of the application:
|
||||
|
||||
```
|
||||
GET /actuator/threaddump
|
||||
```
|
||||
|
||||
This is useful for diagnosing performance issues and detecting deadlocks.
|
||||
|
||||
## Shutdown Endpoint
|
||||
|
||||
The `shutdown` endpoint allows you to gracefully shut down the application. It's disabled by default for security reasons:
|
||||
|
||||
```yaml
|
||||
management:
|
||||
endpoint:
|
||||
shutdown:
|
||||
enabled: true
|
||||
```
|
||||
|
||||
To trigger shutdown:
|
||||
|
||||
```
|
||||
POST /actuator/shutdown
|
||||
```
|
||||
|
||||
> **WARNING**
|
||||
>
|
||||
> The shutdown endpoint should be secured in production environments as it can terminate the application.
|
||||
1000
skills/spring-boot-actuator/references/examples.md
Normal file
1000
skills/spring-boot-actuator/references/examples.md
Normal file
File diff suppressed because it is too large
Load Diff
504
skills/spring-boot-actuator/references/http-exchanges.md
Normal file
504
skills/spring-boot-actuator/references/http-exchanges.md
Normal file
@@ -0,0 +1,504 @@
|
||||
# HTTP Exchanges
|
||||
|
||||
You can enable recording of HTTP exchanges by providing a bean of type `HttpExchangeRepository` in your application's configuration. For convenience, Spring Boot offers `InMemoryHttpExchangeRepository`, which, by default, stores the last 100 request-response exchanges. `InMemoryHttpExchangeRepository` is limited compared to tracing solutions, and we recommend using it only for development environments. For production environments, we recommend using a production-ready tracing or observability solution, such as Zipkin or OpenTelemetry. Alternatively, you can create your own `HttpExchangeRepository`.
|
||||
|
||||
You can use the `httpexchanges` endpoint to obtain information about the request-response exchanges that are stored in the `HttpExchangeRepository`.
|
||||
|
||||
## Basic Configuration
|
||||
|
||||
### In-Memory Repository (Development)
|
||||
|
||||
```java
|
||||
@Configuration
|
||||
public class HttpExchangesConfiguration {
|
||||
|
||||
@Bean
|
||||
public InMemoryHttpExchangeRepository httpExchangeRepository() {
|
||||
return new InMemoryHttpExchangeRepository();
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Custom Repository Size
|
||||
|
||||
```java
|
||||
@Configuration
|
||||
public class HttpExchangesConfiguration {
|
||||
|
||||
@Bean
|
||||
public InMemoryHttpExchangeRepository httpExchangeRepository() {
|
||||
return new InMemoryHttpExchangeRepository(1000); // Store last 1000 exchanges
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Custom HTTP Exchange Recording
|
||||
|
||||
To customize the items that are included in each recorded exchange, use the `management.httpexchanges.recording.include` configuration property:
|
||||
|
||||
```yaml
|
||||
management:
|
||||
httpexchanges:
|
||||
recording:
|
||||
include:
|
||||
- request-headers
|
||||
- response-headers
|
||||
- cookie-headers
|
||||
- authorization-header
|
||||
- principal
|
||||
- remote-address
|
||||
- session-id
|
||||
- time-taken
|
||||
```
|
||||
|
||||
Available options:
|
||||
- `request-headers`: Include request headers
|
||||
- `response-headers`: Include response headers
|
||||
- `cookie-headers`: Include cookie headers
|
||||
- `authorization-header`: Include authorization header
|
||||
- `principal`: Include principal information
|
||||
- `remote-address`: Include remote address
|
||||
- `session-id`: Include session ID
|
||||
- `time-taken`: Include request processing time
|
||||
|
||||
## Custom HTTP Exchange Repository
|
||||
|
||||
### Database-backed Repository
|
||||
|
||||
```java
|
||||
@Entity
|
||||
@Table(name = "http_exchanges")
|
||||
public class HttpExchangeEntity {
|
||||
|
||||
@Id
|
||||
@GeneratedValue(strategy = GenerationType.IDENTITY)
|
||||
private Long id;
|
||||
|
||||
@Column(name = "timestamp")
|
||||
private Instant timestamp;
|
||||
|
||||
@Column(name = "method")
|
||||
private String method;
|
||||
|
||||
@Column(name = "uri", length = 2000)
|
||||
private String uri;
|
||||
|
||||
@Column(name = "status")
|
||||
private Integer status;
|
||||
|
||||
@Column(name = "time_taken")
|
||||
private Long timeTaken;
|
||||
|
||||
@Column(name = "principal")
|
||||
private String principal;
|
||||
|
||||
@Column(name = "remote_address")
|
||||
private String remoteAddress;
|
||||
|
||||
@Column(name = "session_id")
|
||||
private String sessionId;
|
||||
|
||||
@Lob
|
||||
@Column(name = "request_headers")
|
||||
private String requestHeaders;
|
||||
|
||||
@Lob
|
||||
@Column(name = "response_headers")
|
||||
private String responseHeaders;
|
||||
|
||||
// Constructors, getters, setters
|
||||
}
|
||||
|
||||
@Repository
|
||||
public interface HttpExchangeEntityRepository extends JpaRepository<HttpExchangeEntity, Long> {
|
||||
|
||||
List<HttpExchangeEntity> findTop100ByOrderByTimestampDesc();
|
||||
|
||||
@Modifying
|
||||
@Query("DELETE FROM HttpExchangeEntity h WHERE h.timestamp < :cutoff")
|
||||
void deleteOlderThan(@Param("cutoff") Instant cutoff);
|
||||
}
|
||||
|
||||
@Component
|
||||
public class DatabaseHttpExchangeRepository implements HttpExchangeRepository {
|
||||
|
||||
private final HttpExchangeEntityRepository repository;
|
||||
private final ObjectMapper objectMapper;
|
||||
|
||||
public DatabaseHttpExchangeRepository(HttpExchangeEntityRepository repository) {
|
||||
this.repository = repository;
|
||||
this.objectMapper = new ObjectMapper();
|
||||
}
|
||||
|
||||
@Override
|
||||
public List<HttpExchange> findAll() {
|
||||
return repository.findTop100ByOrderByTimestampDesc()
|
||||
.stream()
|
||||
.map(this::toHttpExchange)
|
||||
.collect(Collectors.toList());
|
||||
}
|
||||
|
||||
@Override
|
||||
public void add(HttpExchange httpExchange) {
|
||||
HttpExchangeEntity entity = toEntity(httpExchange);
|
||||
repository.save(entity);
|
||||
}
|
||||
|
||||
private HttpExchangeEntity toEntity(HttpExchange exchange) {
|
||||
HttpExchangeEntity entity = new HttpExchangeEntity();
|
||||
entity.setTimestamp(exchange.getTimestamp());
|
||||
|
||||
HttpExchange.Request request = exchange.getRequest();
|
||||
entity.setMethod(request.getMethod());
|
||||
entity.setUri(request.getUri().toString());
|
||||
entity.setPrincipal(exchange.getPrincipal() != null ?
|
||||
exchange.getPrincipal().getName() : null);
|
||||
entity.setRemoteAddress(request.getRemoteAddress());
|
||||
|
||||
if (exchange.getResponse() != null) {
|
||||
entity.setStatus(exchange.getResponse().getStatus());
|
||||
}
|
||||
|
||||
entity.setTimeTaken(exchange.getTimeTaken() != null ?
|
||||
exchange.getTimeTaken().toMillis() : null);
|
||||
|
||||
try {
|
||||
entity.setRequestHeaders(objectMapper.writeValueAsString(request.getHeaders()));
|
||||
if (exchange.getResponse() != null) {
|
||||
entity.setResponseHeaders(objectMapper.writeValueAsString(
|
||||
exchange.getResponse().getHeaders()));
|
||||
}
|
||||
} catch (Exception e) {
|
||||
// Handle serialization error
|
||||
}
|
||||
|
||||
return entity;
|
||||
}
|
||||
|
||||
private HttpExchange toHttpExchange(HttpExchangeEntity entity) {
|
||||
// Implement conversion from entity to HttpExchange
|
||||
// This is complex due to HttpExchange being immutable
|
||||
// Consider using a builder pattern or reflection
|
||||
return null; // Simplified for brevity
|
||||
}
|
||||
|
||||
@Scheduled(fixedRate = 3600000) // Clean up every hour
|
||||
public void cleanup() {
|
||||
Instant cutoff = Instant.now().minus(Duration.ofDays(7));
|
||||
repository.deleteOlderThan(cutoff);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Filtered HTTP Exchange Repository
|
||||
|
||||
```java
|
||||
@Component
|
||||
public class FilteredHttpExchangeRepository implements HttpExchangeRepository {
|
||||
|
||||
private final HttpExchangeRepository delegate;
|
||||
private final Set<String> excludePaths;
|
||||
private final Set<String> excludeUserAgents;
|
||||
|
||||
public FilteredHttpExchangeRepository(HttpExchangeRepository delegate) {
|
||||
this.delegate = delegate;
|
||||
this.excludePaths = Set.of("/actuator/health", "/actuator/metrics", "/favicon.ico");
|
||||
this.excludeUserAgents = Set.of("kube-probe", "ELB-HealthChecker");
|
||||
}
|
||||
|
||||
@Override
|
||||
public List<HttpExchange> findAll() {
|
||||
return delegate.findAll();
|
||||
}
|
||||
|
||||
@Override
|
||||
public void add(HttpExchange httpExchange) {
|
||||
if (shouldRecord(httpExchange)) {
|
||||
delegate.add(httpExchange);
|
||||
}
|
||||
}
|
||||
|
||||
private boolean shouldRecord(HttpExchange exchange) {
|
||||
String path = exchange.getRequest().getUri().getPath();
|
||||
|
||||
// Skip health check and monitoring endpoints
|
||||
if (excludePaths.contains(path)) {
|
||||
return false;
|
||||
}
|
||||
|
||||
// Skip requests from monitoring tools
|
||||
String userAgent = exchange.getRequest().getHeaders().getFirst("User-Agent");
|
||||
if (userAgent != null && excludeUserAgents.stream().anyMatch(userAgent::contains)) {
|
||||
return false;
|
||||
}
|
||||
|
||||
// Skip successful static resource requests
|
||||
if (path.startsWith("/static/") || path.startsWith("/css/") || path.startsWith("/js/")) {
|
||||
return exchange.getResponse() == null || exchange.getResponse().getStatus() >= 400;
|
||||
}
|
||||
|
||||
return true;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Async HTTP Exchange Recording
|
||||
|
||||
### Async Repository Wrapper
|
||||
|
||||
```java
|
||||
@Component
|
||||
public class AsyncHttpExchangeRepository implements HttpExchangeRepository {
|
||||
|
||||
private final HttpExchangeRepository delegate;
|
||||
private final TaskExecutor taskExecutor;
|
||||
|
||||
public AsyncHttpExchangeRepository(HttpExchangeRepository delegate,
|
||||
@Qualifier("httpExchangeTaskExecutor") TaskExecutor taskExecutor) {
|
||||
this.delegate = delegate;
|
||||
this.taskExecutor = taskExecutor;
|
||||
}
|
||||
|
||||
@Override
|
||||
public List<HttpExchange> findAll() {
|
||||
return delegate.findAll();
|
||||
}
|
||||
|
||||
@Override
|
||||
public void add(HttpExchange httpExchange) {
|
||||
taskExecutor.execute(() -> {
|
||||
try {
|
||||
delegate.add(httpExchange);
|
||||
} catch (Exception e) {
|
||||
// Log error but don't let it affect the main request
|
||||
log.error("Failed to record HTTP exchange", e);
|
||||
}
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
@Configuration
|
||||
public class HttpExchangeTaskExecutorConfiguration {
|
||||
|
||||
@Bean("httpExchangeTaskExecutor")
|
||||
public TaskExecutor httpExchangeTaskExecutor() {
|
||||
ThreadPoolTaskExecutor executor = new ThreadPoolTaskExecutor();
|
||||
executor.setCorePoolSize(1);
|
||||
executor.setMaxPoolSize(2);
|
||||
executor.setQueueCapacity(1000);
|
||||
executor.setThreadNamePrefix("http-exchange-");
|
||||
executor.setRejectedExecutionHandler(new ThreadPoolExecutor.DiscardOldestPolicy());
|
||||
executor.initialize();
|
||||
return executor;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## HTTP Exchanges Endpoint
|
||||
|
||||
### Accessing HTTP Exchanges
|
||||
|
||||
```
|
||||
GET /actuator/httpexchanges
|
||||
```
|
||||
|
||||
Response format:
|
||||
|
||||
```json
|
||||
{
|
||||
"exchanges": [
|
||||
{
|
||||
"timestamp": "2023-12-01T10:30:00.123Z",
|
||||
"request": {
|
||||
"method": "GET",
|
||||
"uri": "http://localhost:8080/api/users/123",
|
||||
"headers": {
|
||||
"accept": ["application/json"],
|
||||
"user-agent": ["Mozilla/5.0..."]
|
||||
},
|
||||
"remoteAddress": "192.168.1.100"
|
||||
},
|
||||
"response": {
|
||||
"status": 200,
|
||||
"headers": {
|
||||
"content-type": ["application/json"],
|
||||
"content-length": ["256"]
|
||||
}
|
||||
},
|
||||
"principal": {
|
||||
"name": "john.doe"
|
||||
},
|
||||
"session": {
|
||||
"id": "JSESSIONID123"
|
||||
},
|
||||
"timeTaken": "PT0.025S"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Securing the Endpoint
|
||||
|
||||
```java
|
||||
@Configuration
|
||||
public class HttpExchangesSecurityConfig {
|
||||
|
||||
@Bean
|
||||
@Order(1)
|
||||
public SecurityFilterChain httpExchangesSecurityFilterChain(HttpSecurity http) throws Exception {
|
||||
return http
|
||||
.requestMatcher(EndpointRequest.to("httpexchanges"))
|
||||
.authorizeHttpRequests(requests ->
|
||||
requests.anyRequest().hasRole("ADMIN"))
|
||||
.httpBasic(withDefaults())
|
||||
.build();
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Custom HTTP Exchange Information
|
||||
|
||||
### Including Custom Data
|
||||
|
||||
```java
|
||||
@Component
|
||||
public class CustomHttpExchangeRepository implements HttpExchangeRepository {
|
||||
|
||||
private final InMemoryHttpExchangeRepository delegate;
|
||||
|
||||
public CustomHttpExchangeRepository() {
|
||||
this.delegate = new InMemoryHttpExchangeRepository();
|
||||
}
|
||||
|
||||
@Override
|
||||
public List<HttpExchange> findAll() {
|
||||
return delegate.findAll();
|
||||
}
|
||||
|
||||
@Override
|
||||
public void add(HttpExchange httpExchange) {
|
||||
HttpExchange enrichedExchange = enrichExchange(httpExchange);
|
||||
delegate.add(enrichedExchange);
|
||||
}
|
||||
|
||||
private HttpExchange enrichExchange(HttpExchange original) {
|
||||
// Add custom information to the exchange
|
||||
// Note: HttpExchange is immutable, so we need to create a wrapper
|
||||
// or use reflection to modify internal state
|
||||
|
||||
// For demonstration, we'll just add it normally
|
||||
// In practice, you might need to create a custom implementation
|
||||
return original;
|
||||
}
|
||||
}
|
||||
|
||||
@Component
|
||||
public class HttpExchangeEnricher {
|
||||
|
||||
public void enrich(HttpServletRequest request, HttpServletResponse response) {
|
||||
// Add custom attributes that can be picked up by the repository
|
||||
request.setAttribute("custom.trace.id", getTraceId());
|
||||
request.setAttribute("custom.user.role", getUserRole());
|
||||
request.setAttribute("custom.api.version", getApiVersion(request));
|
||||
}
|
||||
|
||||
private String getTraceId() {
|
||||
// Get from tracing context
|
||||
return "trace-123";
|
||||
}
|
||||
|
||||
private String getUserRole() {
|
||||
Authentication auth = SecurityContextHolder.getContext().getAuthentication();
|
||||
return auth != null ? auth.getAuthorities().toString() : "anonymous";
|
||||
}
|
||||
|
||||
private String getApiVersion(HttpServletRequest request) {
|
||||
return request.getHeader("API-Version");
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Performance Considerations
|
||||
|
||||
### Configuration for Production
|
||||
|
||||
```yaml
|
||||
management:
|
||||
httpexchanges:
|
||||
recording:
|
||||
include:
|
||||
- time-taken
|
||||
- principal
|
||||
- remote-address
|
||||
# Exclude detailed headers to reduce memory usage
|
||||
exclude:
|
||||
- request-headers
|
||||
- response-headers
|
||||
endpoint:
|
||||
httpexchanges:
|
||||
enabled: false # Disable in production for security
|
||||
```
|
||||
|
||||
### Custom Sampling
|
||||
|
||||
```java
|
||||
@Component
|
||||
public class SamplingHttpExchangeRepository implements HttpExchangeRepository {
|
||||
|
||||
private final HttpExchangeRepository delegate;
|
||||
private final Random random = new Random();
|
||||
private final double samplingRate;
|
||||
|
||||
public SamplingHttpExchangeRepository(HttpExchangeRepository delegate,
|
||||
@Value("${app.http-exchanges.sampling-rate:0.1}") double samplingRate) {
|
||||
this.delegate = delegate;
|
||||
this.samplingRate = samplingRate;
|
||||
}
|
||||
|
||||
@Override
|
||||
public List<HttpExchange> findAll() {
|
||||
return delegate.findAll();
|
||||
}
|
||||
|
||||
@Override
|
||||
public void add(HttpExchange httpExchange) {
|
||||
if (random.nextDouble() < samplingRate) {
|
||||
delegate.add(httpExchange);
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Production Use**: Disable HTTP exchanges endpoint in production or secure it properly
|
||||
2. **Memory Management**: Use limited-size repositories to prevent memory leaks
|
||||
3. **Sensitive Data**: Be careful not to log sensitive information in headers
|
||||
4. **Performance**: Consider async recording for high-throughput applications
|
||||
5. **Sampling**: Use sampling in production to reduce overhead
|
||||
6. **Retention**: Implement cleanup policies for stored exchanges
|
||||
7. **Security**: Ensure recorded data doesn't contain credentials or tokens
|
||||
|
||||
### Production Configuration Example
|
||||
|
||||
```yaml
|
||||
management:
|
||||
endpoint:
|
||||
httpexchanges:
|
||||
enabled: false # Disabled in production
|
||||
httpexchanges:
|
||||
recording:
|
||||
include:
|
||||
- time-taken
|
||||
- principal
|
||||
- remote-address
|
||||
exclude:
|
||||
- authorization-header
|
||||
- cookie-headers
|
||||
- request-headers
|
||||
- response-headers
|
||||
|
||||
logging:
|
||||
level:
|
||||
org.springframework.boot.actuate.web.exchanges: WARN
|
||||
```
|
||||
582
skills/spring-boot-actuator/references/jmx.md
Normal file
582
skills/spring-boot-actuator/references/jmx.md
Normal file
@@ -0,0 +1,582 @@
|
||||
# JMX with Spring Boot Actuator
|
||||
|
||||
Java Management Extensions (JMX) provide a standard mechanism to monitor and manage applications. By default, this feature is not enabled. You can turn it on by setting the `spring.jmx.enabled` configuration property to `true`. Spring Boot exposes the most suitable `MBeanServer` as a bean with an ID of `mbeanServer`. Any of your beans that are annotated with Spring JMX annotations (`@ManagedResource`, `@ManagedAttribute`, or `@ManagedOperation`) are exposed to it.
|
||||
|
||||
If your platform provides a standard `MBeanServer`, Spring Boot uses that and defaults to the VM `MBeanServer`, if necessary. If all that fails, a new `MBeanServer` is created.
|
||||
|
||||
> **NOTE**
|
||||
>
|
||||
> `spring.jmx.enabled` affects only the management beans provided by Spring. Enabling management beans provided by other libraries (for example Log4j2 or Quartz) is independent.
|
||||
|
||||
## Basic JMX Configuration
|
||||
|
||||
### Enabling JMX
|
||||
|
||||
```yaml
|
||||
spring:
|
||||
jmx:
|
||||
enabled: true
|
||||
default-domain: com.example.myapp
|
||||
|
||||
management:
|
||||
endpoints:
|
||||
jmx:
|
||||
exposure:
|
||||
include: "*"
|
||||
endpoint:
|
||||
jmx:
|
||||
enabled: true
|
||||
```
|
||||
|
||||
### Custom MBean Server Configuration
|
||||
|
||||
```java
|
||||
@Configuration
|
||||
public class JmxConfiguration {
|
||||
|
||||
@Bean
|
||||
@Primary
|
||||
public MBeanServer mbeanServer() {
|
||||
MBeanServer server = ManagementFactory.getPlatformMBeanServer();
|
||||
return server;
|
||||
}
|
||||
|
||||
@Bean
|
||||
public JmxMetricsExporter jmxMetricsExporter(MeterRegistry meterRegistry) {
|
||||
return new JmxMetricsExporter(meterRegistry);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Creating Custom MBeans
|
||||
|
||||
### Using @ManagedResource Annotation
|
||||
|
||||
```java
|
||||
@Component
|
||||
@ManagedResource(
|
||||
objectName = "com.example:type=ApplicationMetrics,name=UserService",
|
||||
description = "User Service Management Bean"
|
||||
)
|
||||
public class UserServiceMBean {
|
||||
|
||||
private final UserService userService;
|
||||
private long totalUsers = 0;
|
||||
private long activeUsers = 0;
|
||||
|
||||
public UserServiceMBean(UserService userService) {
|
||||
this.userService = userService;
|
||||
}
|
||||
|
||||
@ManagedAttribute(description = "Total number of users")
|
||||
public long getTotalUsers() {
|
||||
return userService.getTotalUserCount();
|
||||
}
|
||||
|
||||
@ManagedAttribute(description = "Number of active users")
|
||||
public long getActiveUsers() {
|
||||
return userService.getActiveUserCount();
|
||||
}
|
||||
|
||||
@ManagedAttribute(description = "Cache hit ratio")
|
||||
public double getCacheHitRatio() {
|
||||
return userService.getCacheHitRatio();
|
||||
}
|
||||
|
||||
@ManagedOperation(description = "Clear user cache")
|
||||
public void clearCache() {
|
||||
userService.clearCache();
|
||||
}
|
||||
|
||||
@ManagedOperation(description = "Refresh user statistics")
|
||||
public String refreshStatistics() {
|
||||
userService.refreshStatistics();
|
||||
return "Statistics refreshed at " + Instant.now();
|
||||
}
|
||||
|
||||
@ManagedOperation(description = "Get user by ID")
|
||||
@ManagedOperationParameters({
|
||||
@ManagedOperationParameter(name = "userId", description = "User ID")
|
||||
})
|
||||
public String getUserInfo(Long userId) {
|
||||
User user = userService.findById(userId);
|
||||
return user != null ? user.toString() : "User not found";
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Implementing MBean Interface
|
||||
|
||||
```java
|
||||
public interface ApplicationConfigMBean {
|
||||
String getEnvironment();
|
||||
void setLogLevel(String loggerName, String level);
|
||||
boolean isMaintenanceMode();
|
||||
void setMaintenanceMode(boolean maintenanceMode);
|
||||
void reloadConfiguration();
|
||||
Map<String, String> getSystemProperties();
|
||||
}
|
||||
|
||||
@Component
|
||||
public class ApplicationConfig implements ApplicationConfigMBean {
|
||||
|
||||
private final Environment environment;
|
||||
private final LoggingSystem loggingSystem;
|
||||
private boolean maintenanceMode = false;
|
||||
|
||||
public ApplicationConfig(Environment environment, LoggingSystem loggingSystem) {
|
||||
this.environment = environment;
|
||||
this.loggingSystem = loggingSystem;
|
||||
}
|
||||
|
||||
@Override
|
||||
public String getEnvironment() {
|
||||
return String.join(",", environment.getActiveProfiles());
|
||||
}
|
||||
|
||||
@Override
|
||||
public void setLogLevel(String loggerName, String level) {
|
||||
LogLevel logLevel = level != null ? LogLevel.valueOf(level.toUpperCase()) : null;
|
||||
loggingSystem.setLogLevel(loggerName, logLevel);
|
||||
}
|
||||
|
||||
@Override
|
||||
public boolean isMaintenanceMode() {
|
||||
return maintenanceMode;
|
||||
}
|
||||
|
||||
@Override
|
||||
public void setMaintenanceMode(boolean maintenanceMode) {
|
||||
this.maintenanceMode = maintenanceMode;
|
||||
// Publish event or notify other components
|
||||
}
|
||||
|
||||
@Override
|
||||
public void reloadConfiguration() {
|
||||
// Implement configuration reload logic
|
||||
// This could refresh @ConfigurationProperties beans
|
||||
}
|
||||
|
||||
@Override
|
||||
public Map<String, String> getSystemProperties() {
|
||||
return System.getProperties().entrySet().stream()
|
||||
.collect(Collectors.toMap(
|
||||
e -> String.valueOf(e.getKey()),
|
||||
e -> String.valueOf(e.getValue())
|
||||
));
|
||||
}
|
||||
|
||||
@PostConstruct
|
||||
public void registerMBean() {
|
||||
try {
|
||||
MBeanServer server = ManagementFactory.getPlatformMBeanServer();
|
||||
ObjectName objectName = new ObjectName("com.example:type=ApplicationConfig");
|
||||
server.registerMBean(this, objectName);
|
||||
} catch (Exception e) {
|
||||
throw new RuntimeException("Failed to register MBean", e);
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Application Metrics via JMX
|
||||
|
||||
### Custom Metrics MBean
|
||||
|
||||
```java
|
||||
@Component
|
||||
@ManagedResource(
|
||||
objectName = "com.example:type=Performance,name=ApplicationMetrics",
|
||||
description = "Application Performance Metrics"
|
||||
)
|
||||
public class ApplicationMetricsMBean {
|
||||
|
||||
private final MeterRegistry meterRegistry;
|
||||
private final Counter requestCounter;
|
||||
private final Timer responseTimer;
|
||||
private final Gauge activeConnections;
|
||||
|
||||
public ApplicationMetricsMBean(MeterRegistry meterRegistry) {
|
||||
this.meterRegistry = meterRegistry;
|
||||
this.requestCounter = Counter.builder("application.requests.total")
|
||||
.description("Total number of requests")
|
||||
.register(meterRegistry);
|
||||
this.responseTimer = Timer.builder("application.response.time")
|
||||
.description("Response time")
|
||||
.register(meterRegistry);
|
||||
this.activeConnections = Gauge.builder("application.connections.active")
|
||||
.description("Active connections")
|
||||
.register(meterRegistry, this, ApplicationMetricsMBean::getActiveConnectionsCount);
|
||||
}
|
||||
|
||||
@ManagedAttribute(description = "Total requests processed")
|
||||
public long getTotalRequests() {
|
||||
return (long) requestCounter.count();
|
||||
}
|
||||
|
||||
@ManagedAttribute(description = "Average response time in milliseconds")
|
||||
public double getAverageResponseTime() {
|
||||
return responseTimer.mean(TimeUnit.MILLISECONDS);
|
||||
}
|
||||
|
||||
@ManagedAttribute(description = "95th percentile response time")
|
||||
public double getResponse95thPercentile() {
|
||||
return responseTimer.percentile(0.95, TimeUnit.MILLISECONDS);
|
||||
}
|
||||
|
||||
@ManagedAttribute(description = "Current active connections")
|
||||
public long getActiveConnections() {
|
||||
return getActiveConnectionsCount();
|
||||
}
|
||||
|
||||
@ManagedAttribute(description = "JVM memory usage percentage")
|
||||
public double getMemoryUsagePercentage() {
|
||||
MemoryMXBean memoryBean = ManagementFactory.getMemoryMXBean();
|
||||
MemoryUsage heapUsage = memoryBean.getHeapMemoryUsage();
|
||||
return (double) heapUsage.getUsed() / heapUsage.getMax() * 100;
|
||||
}
|
||||
|
||||
@ManagedOperation(description = "Reset request counter")
|
||||
public void resetRequestCounter() {
|
||||
// Note: Micrometer counters cannot be reset, this would require custom implementation
|
||||
// or using a different metric type
|
||||
}
|
||||
|
||||
private long getActiveConnectionsCount() {
|
||||
// Implementation to get actual active connections
|
||||
return 42; // Placeholder
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Database Connection Pool MBean
|
||||
|
||||
```java
|
||||
@Component
|
||||
@ManagedResource(
|
||||
objectName = "com.example:type=Database,name=ConnectionPool",
|
||||
description = "Database Connection Pool Metrics"
|
||||
)
|
||||
public class DatabaseConnectionPoolMBean {
|
||||
|
||||
private final DataSource dataSource;
|
||||
|
||||
public DatabaseConnectionPoolMBean(DataSource dataSource) {
|
||||
this.dataSource = dataSource;
|
||||
}
|
||||
|
||||
@ManagedAttribute(description = "Active connections")
|
||||
public int getActiveConnections() {
|
||||
if (dataSource instanceof HikariDataSource) {
|
||||
return ((HikariDataSource) dataSource).getHikariPoolMXBean().getActiveConnections();
|
||||
}
|
||||
return -1; // Not supported
|
||||
}
|
||||
|
||||
@ManagedAttribute(description = "Idle connections")
|
||||
public int getIdleConnections() {
|
||||
if (dataSource instanceof HikariDataSource) {
|
||||
return ((HikariDataSource) dataSource).getHikariPoolMXBean().getIdleConnections();
|
||||
}
|
||||
return -1; // Not supported
|
||||
}
|
||||
|
||||
@ManagedAttribute(description = "Total connections")
|
||||
public int getTotalConnections() {
|
||||
if (dataSource instanceof HikariDataSource) {
|
||||
return ((HikariDataSource) dataSource).getHikariPoolMXBean().getTotalConnections();
|
||||
}
|
||||
return -1; // Not supported
|
||||
}
|
||||
|
||||
@ManagedAttribute(description = "Threads awaiting connection")
|
||||
public int getThreadsAwaitingConnection() {
|
||||
if (dataSource instanceof HikariDataSource) {
|
||||
return ((HikariDataSource) dataSource).getHikariPoolMXBean().getThreadsAwaitingConnection();
|
||||
}
|
||||
return -1; // Not supported
|
||||
}
|
||||
|
||||
@ManagedOperation(description = "Suspend connection pool")
|
||||
public void suspendPool() {
|
||||
if (dataSource instanceof HikariDataSource) {
|
||||
((HikariDataSource) dataSource).getHikariPoolMXBean().suspendPool();
|
||||
}
|
||||
}
|
||||
|
||||
@ManagedOperation(description = "Resume connection pool")
|
||||
public void resumePool() {
|
||||
if (dataSource instanceof HikariDataSource) {
|
||||
((HikariDataSource) dataSource).getHikariPoolMXBean().resumePool();
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Security and JMX
|
||||
|
||||
### Securing JMX Access
|
||||
|
||||
```yaml
|
||||
spring:
|
||||
jmx:
|
||||
enabled: true
|
||||
|
||||
management:
|
||||
endpoints:
|
||||
jmx:
|
||||
exposure:
|
||||
include: "health,info,metrics"
|
||||
exclude: "env,configprops" # Exclude sensitive endpoints
|
||||
|
||||
# JMX-specific security
|
||||
com.sun.management.jmxremote.port: 9999
|
||||
com.sun.management.jmxremote.authenticate: true
|
||||
com.sun.management.jmxremote.ssl: false
|
||||
com.sun.management.jmxremote.access.file: /path/to/jmxremote.access
|
||||
com.sun.management.jmxremote.password.file: /path/to/jmxremote.password
|
||||
```
|
||||
|
||||
### Custom JMX Security
|
||||
|
||||
```java
|
||||
@Configuration
|
||||
public class JmxSecurityConfiguration {
|
||||
|
||||
@Bean
|
||||
public JMXConnectorServer jmxConnectorServer() throws Exception {
|
||||
JMXServiceURL url = new JMXServiceURL("service:jmx:rmi://localhost:9999");
|
||||
|
||||
Map<String, Object> environment = new HashMap<>();
|
||||
environment.put(JMXConnectorServer.AUTHENTICATOR, new CustomJMXAuthenticator());
|
||||
|
||||
JMXConnectorServer server = JMXConnectorServerFactory.newJMXConnectorServer(
|
||||
url, environment, ManagementFactory.getPlatformMBeanServer());
|
||||
|
||||
server.start();
|
||||
return server;
|
||||
}
|
||||
|
||||
private static class CustomJMXAuthenticator implements JMXAuthenticator {
|
||||
@Override
|
||||
public Subject authenticate(Object credentials) {
|
||||
if (!(credentials instanceof String[])) {
|
||||
throw new SecurityException("Credentials must be String[]");
|
||||
}
|
||||
|
||||
String[] creds = (String[]) credentials;
|
||||
if (creds.length != 2) {
|
||||
throw new SecurityException("Credentials must contain username and password");
|
||||
}
|
||||
|
||||
String username = creds[0];
|
||||
String password = creds[1];
|
||||
|
||||
// Implement your authentication logic
|
||||
if ("admin".equals(username) && "password".equals(password)) {
|
||||
return new Subject();
|
||||
}
|
||||
|
||||
throw new SecurityException("Authentication failed");
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Monitoring and Alerting with JMX
|
||||
|
||||
### Health Check MBean
|
||||
|
||||
```java
|
||||
@Component
|
||||
@ManagedResource(
|
||||
objectName = "com.example:type=Health,name=ApplicationHealth",
|
||||
description = "Application Health Monitoring"
|
||||
)
|
||||
public class ApplicationHealthMBean {
|
||||
|
||||
private final HealthEndpoint healthEndpoint;
|
||||
private final List<String> healthIssues = new ArrayList<>();
|
||||
|
||||
public ApplicationHealthMBean(HealthEndpoint healthEndpoint) {
|
||||
this.healthEndpoint = healthEndpoint;
|
||||
}
|
||||
|
||||
@ManagedAttribute(description = "Overall application health status")
|
||||
public String getHealthStatus() {
|
||||
HealthComponent health = healthEndpoint.health();
|
||||
return health.getStatus().getCode();
|
||||
}
|
||||
|
||||
@ManagedAttribute(description = "Detailed health information")
|
||||
public String getHealthDetails() {
|
||||
HealthComponent health = healthEndpoint.health();
|
||||
return health.toString();
|
||||
}
|
||||
|
||||
@ManagedAttribute(description = "Database health status")
|
||||
public String getDatabaseHealth() {
|
||||
HealthComponent health = healthEndpoint.healthForPath("db");
|
||||
return health != null ? health.getStatus().getCode() : "UNKNOWN";
|
||||
}
|
||||
|
||||
@ManagedAttribute(description = "Current health issues")
|
||||
public String[] getHealthIssues() {
|
||||
return healthIssues.toArray(new String[0]);
|
||||
}
|
||||
|
||||
@ManagedOperation(description = "Refresh health status")
|
||||
public void refreshHealth() {
|
||||
HealthComponent health = healthEndpoint.health();
|
||||
healthIssues.clear();
|
||||
|
||||
if (health instanceof CompositeHealthComponent) {
|
||||
CompositeHealthComponent composite = (CompositeHealthComponent) health;
|
||||
composite.getComponents().forEach((name, component) -> {
|
||||
if (!Status.UP.equals(component.getStatus())) {
|
||||
healthIssues.add(name + ": " + component.getStatus().getCode());
|
||||
}
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
@PostConstruct
|
||||
public void init() {
|
||||
refreshHealth();
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Notification MBean
|
||||
|
||||
```java
|
||||
@Component
|
||||
@ManagedResource(
|
||||
objectName = "com.example:type=Notifications,name=AlertManager",
|
||||
description = "Application Alert Management"
|
||||
)
|
||||
public class AlertManagerMBean extends NotificationBroadcasterSupport {
|
||||
|
||||
private final AtomicLong sequenceNumber = new AtomicLong(0);
|
||||
private boolean alertsEnabled = true;
|
||||
|
||||
@ManagedAttribute(description = "Are alerts enabled")
|
||||
public boolean isAlertsEnabled() {
|
||||
return alertsEnabled;
|
||||
}
|
||||
|
||||
@ManagedAttribute(description = "Enable or disable alerts")
|
||||
public void setAlertsEnabled(boolean alertsEnabled) {
|
||||
this.alertsEnabled = alertsEnabled;
|
||||
}
|
||||
|
||||
@ManagedOperation(description = "Send test alert")
|
||||
public void sendTestAlert() {
|
||||
sendAlert("TEST", "Test alert from JMX", "INFO");
|
||||
}
|
||||
|
||||
public void sendAlert(String type, String message, String severity) {
|
||||
if (!alertsEnabled) {
|
||||
return;
|
||||
}
|
||||
|
||||
Notification notification = new Notification(
|
||||
type,
|
||||
this,
|
||||
sequenceNumber.incrementAndGet(),
|
||||
System.currentTimeMillis(),
|
||||
message
|
||||
);
|
||||
|
||||
notification.setUserData(Map.of(
|
||||
"severity", severity,
|
||||
"timestamp", Instant.now().toString()
|
||||
));
|
||||
|
||||
sendNotification(notification);
|
||||
}
|
||||
|
||||
@Override
|
||||
public MBeanNotificationInfo[] getNotificationInfo() {
|
||||
return new MBeanNotificationInfo[]{
|
||||
new MBeanNotificationInfo(
|
||||
new String[]{"HEALTH", "PERFORMANCE", "SECURITY", "TEST"},
|
||||
Notification.class.getName(),
|
||||
"Application alerts and notifications"
|
||||
)
|
||||
};
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Naming Convention**: Use consistent ObjectName patterns
|
||||
2. **Security**: Always secure JMX access in production
|
||||
3. **Performance**: Be mindful of expensive operations in MBean methods
|
||||
4. **Documentation**: Provide clear descriptions for attributes and operations
|
||||
5. **Error Handling**: Handle exceptions gracefully in MBean operations
|
||||
6. **Resource Management**: Properly manage resources in MBean operations
|
||||
7. **Monitoring**: Monitor JMX itself for availability and performance
|
||||
|
||||
### Production JMX Configuration
|
||||
|
||||
```yaml
|
||||
# Production JMX configuration
|
||||
spring:
|
||||
jmx:
|
||||
enabled: true
|
||||
default-domain: "com.mycompany.myapp"
|
||||
|
||||
management:
|
||||
endpoints:
|
||||
jmx:
|
||||
exposure:
|
||||
include: "health,info,metrics"
|
||||
exclude: "env,configprops,beans"
|
||||
endpoint:
|
||||
jmx:
|
||||
enabled: true
|
||||
|
||||
# JVM JMX settings (set as JVM arguments)
|
||||
# -Dcom.sun.management.jmxremote=true
|
||||
# -Dcom.sun.management.jmxremote.port=9999
|
||||
# -Dcom.sun.management.jmxremote.authenticate=true
|
||||
# -Dcom.sun.management.jmxremote.ssl=true
|
||||
# -Dcom.sun.management.jmxremote.access.file=/etc/jmx/jmxremote.access
|
||||
# -Dcom.sun.management.jmxremote.password.file=/etc/jmx/jmxremote.password
|
||||
```
|
||||
|
||||
### JMX Client Example
|
||||
|
||||
```java
|
||||
public class JmxClient {
|
||||
|
||||
public static void main(String[] args) throws Exception {
|
||||
String url = "service:jmx:rmi:///jndi/rmi://localhost:9999/jmxrmi";
|
||||
JMXServiceURL serviceURL = new JMXServiceURL(url);
|
||||
|
||||
Map<String, Object> environment = new HashMap<>();
|
||||
environment.put(JMXConnector.CREDENTIALS, new String[]{"admin", "password"});
|
||||
|
||||
try (JMXConnector connector = JMXConnectorFactory.connect(serviceURL, environment)) {
|
||||
MBeanServerConnection connection = connector.getMBeanServerConnection();
|
||||
|
||||
// Get application health
|
||||
ObjectName healthName = new ObjectName("com.example:type=Health,name=ApplicationHealth");
|
||||
String healthStatus = (String) connection.getAttribute(healthName, "HealthStatus");
|
||||
System.out.println("Health Status: " + healthStatus);
|
||||
|
||||
// Invoke operation
|
||||
connection.invoke(healthName, "refreshHealth", null, null);
|
||||
|
||||
// Listen for notifications
|
||||
ObjectName alertName = new ObjectName("com.example:type=Notifications,name=AlertManager");
|
||||
connection.addNotificationListener(alertName,
|
||||
(notification, handback) -> {
|
||||
System.out.println("Alert: " + notification.getMessage());
|
||||
}, null, null);
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
385
skills/spring-boot-actuator/references/loggers.md
Normal file
385
skills/spring-boot-actuator/references/loggers.md
Normal file
@@ -0,0 +1,385 @@
|
||||
# Loggers Endpoint
|
||||
|
||||
Spring Boot Actuator includes the ability to view and configure the log levels of your application at runtime. You can view either the entire list or an individual logger's configuration, which is made up of both the explicitly configured logging level as well as the effective logging level given to it by the logging framework. These levels can be one of:
|
||||
|
||||
- `TRACE`
|
||||
- `DEBUG`
|
||||
- `INFO`
|
||||
- `WARN`
|
||||
- `ERROR`
|
||||
- `FATAL`
|
||||
- `OFF`
|
||||
- `null`
|
||||
|
||||
`null` indicates that there is no explicit configuration.
|
||||
|
||||
## Viewing Logger Configuration
|
||||
|
||||
### View All Loggers
|
||||
|
||||
To view the configuration of all loggers:
|
||||
|
||||
```
|
||||
GET /actuator/loggers
|
||||
```
|
||||
|
||||
Response example:
|
||||
|
||||
```json
|
||||
{
|
||||
"levels": ["OFF", "ERROR", "WARN", "INFO", "DEBUG", "TRACE"],
|
||||
"loggers": {
|
||||
"ROOT": {
|
||||
"configuredLevel": "INFO",
|
||||
"effectiveLevel": "INFO"
|
||||
},
|
||||
"com.example": {
|
||||
"configuredLevel": null,
|
||||
"effectiveLevel": "INFO"
|
||||
},
|
||||
"com.example.MyClass": {
|
||||
"configuredLevel": "DEBUG",
|
||||
"effectiveLevel": "DEBUG"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### View Specific Logger
|
||||
|
||||
To view the configuration of a specific logger:
|
||||
|
||||
```
|
||||
GET /actuator/loggers/com.example.MyClass
|
||||
```
|
||||
|
||||
Response example:
|
||||
|
||||
```json
|
||||
{
|
||||
"configuredLevel": "DEBUG",
|
||||
"effectiveLevel": "DEBUG"
|
||||
}
|
||||
```
|
||||
|
||||
## Configuring a Logger
|
||||
|
||||
To configure a given logger, `POST` a partial entity to the resource's URI, as the following example shows:
|
||||
|
||||
```
|
||||
POST /actuator/loggers/com.example.MyClass
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"configuredLevel": "DEBUG"
|
||||
}
|
||||
```
|
||||
|
||||
> **TIP**
|
||||
>
|
||||
> To "reset" the specific level of the logger (and use the default configuration instead), you can pass a value of `null` as the `configuredLevel`.
|
||||
|
||||
### Reset Logger Level
|
||||
|
||||
To reset a logger to its default level:
|
||||
|
||||
```
|
||||
POST /actuator/loggers/com.example.MyClass
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"configuredLevel": null
|
||||
}
|
||||
```
|
||||
|
||||
## Configuration Examples
|
||||
|
||||
### Enable Debug Logging for Specific Package
|
||||
|
||||
```bash
|
||||
curl -X POST http://localhost:8080/actuator/loggers/com.example.service \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"configuredLevel": "DEBUG"}'
|
||||
```
|
||||
|
||||
### Enable Trace Logging for Spring Security
|
||||
|
||||
```bash
|
||||
curl -X POST http://localhost:8080/actuator/loggers/org.springframework.security \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"configuredLevel": "TRACE"}'
|
||||
```
|
||||
|
||||
### Set Root Logger Level
|
||||
|
||||
```bash
|
||||
curl -X POST http://localhost:8080/actuator/loggers/ROOT \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"configuredLevel": "WARN"}'
|
||||
```
|
||||
|
||||
## Programmatic Logger Management
|
||||
|
||||
You can also manage loggers programmatically in your application:
|
||||
|
||||
```java
|
||||
@RestController
|
||||
public class LoggerController {
|
||||
|
||||
private final LoggingSystem loggingSystem;
|
||||
|
||||
public LoggerController(LoggingSystem loggingSystem) {
|
||||
this.loggingSystem = loggingSystem;
|
||||
}
|
||||
|
||||
@PostMapping("/admin/logger/{name}")
|
||||
public void setLogLevel(@PathVariable String name, @RequestBody LogLevelRequest request) {
|
||||
LogLevel level = request.getLevel() != null ?
|
||||
LogLevel.valueOf(request.getLevel().toUpperCase()) : null;
|
||||
loggingSystem.setLogLevel(name, level);
|
||||
}
|
||||
|
||||
public static class LogLevelRequest {
|
||||
private String level;
|
||||
|
||||
public String getLevel() { return level; }
|
||||
public void setLevel(String level) { this.level = level; }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Conditional Logging
|
||||
|
||||
### Environment-based Configuration
|
||||
|
||||
```yaml
|
||||
logging:
|
||||
level:
|
||||
com.example: ${LOGGING_LEVEL_EXAMPLE:INFO}
|
||||
org.springframework.web: ${LOGGING_LEVEL_WEB:WARN}
|
||||
org.hibernate.SQL: ${LOGGING_LEVEL_SQL:WARN}
|
||||
org.hibernate.type.descriptor.sql: ${LOGGING_LEVEL_SQL_PARAMS:WARN}
|
||||
|
||||
---
|
||||
spring:
|
||||
config:
|
||||
activate:
|
||||
on-profile: development
|
||||
logging:
|
||||
level:
|
||||
com.example: DEBUG
|
||||
org.hibernate.SQL: DEBUG
|
||||
org.hibernate.type.descriptor.sql: TRACE
|
||||
|
||||
---
|
||||
spring:
|
||||
config:
|
||||
activate:
|
||||
on-profile: production
|
||||
logging:
|
||||
level:
|
||||
root: WARN
|
||||
com.example: INFO
|
||||
```
|
||||
|
||||
### Feature Toggle Logging
|
||||
|
||||
```java
|
||||
@Component
|
||||
public class FeatureLoggingController {
|
||||
|
||||
private final LoggingSystem loggingSystem;
|
||||
private final Environment environment;
|
||||
|
||||
public FeatureLoggingController(LoggingSystem loggingSystem, Environment environment) {
|
||||
this.loggingSystem = loggingSystem;
|
||||
this.environment = environment;
|
||||
}
|
||||
|
||||
@EventListener
|
||||
public void handleFeatureToggleChange(FeatureToggleEvent event) {
|
||||
if ("debug-logging".equals(event.getFeatureName())) {
|
||||
if (event.isEnabled()) {
|
||||
enableDebugLogging();
|
||||
} else {
|
||||
disableDebugLogging();
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
private void enableDebugLogging() {
|
||||
loggingSystem.setLogLevel("com.example.service", LogLevel.DEBUG);
|
||||
loggingSystem.setLogLevel("com.example.repository", LogLevel.DEBUG);
|
||||
}
|
||||
|
||||
private void disableDebugLogging() {
|
||||
loggingSystem.setLogLevel("com.example.service", null);
|
||||
loggingSystem.setLogLevel("com.example.repository", null);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Security Considerations
|
||||
|
||||
### Securing the Loggers Endpoint
|
||||
|
||||
```java
|
||||
@Configuration
|
||||
public class LoggersSecurityConfig {
|
||||
|
||||
@Bean
|
||||
@Order(1)
|
||||
public SecurityFilterChain loggersSecurityFilterChain(HttpSecurity http) throws Exception {
|
||||
return http
|
||||
.requestMatcher(EndpointRequest.to("loggers"))
|
||||
.authorizeHttpRequests(requests ->
|
||||
requests.anyRequest().hasRole("ADMIN"))
|
||||
.httpBasic(withDefaults())
|
||||
.build();
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Read-only Access
|
||||
|
||||
To provide read-only access to the loggers endpoint:
|
||||
|
||||
```yaml
|
||||
management:
|
||||
endpoint:
|
||||
loggers:
|
||||
access: read-only
|
||||
```
|
||||
|
||||
Or configure programmatically:
|
||||
|
||||
```java
|
||||
@Configuration
|
||||
public class LoggersAccessConfig {
|
||||
|
||||
@Bean
|
||||
@Order(1)
|
||||
public SecurityFilterChain loggersSecurityFilterChain(HttpSecurity http) throws Exception {
|
||||
return http
|
||||
.requestMatcher(EndpointRequest.to("loggers"))
|
||||
.authorizeHttpRequests(requests ->
|
||||
requests
|
||||
.requestMatchers(HttpMethod.GET).hasRole("LOGGER_READER")
|
||||
.requestMatchers(HttpMethod.POST).hasRole("LOGGER_ADMIN")
|
||||
.anyRequest().denyAll())
|
||||
.httpBasic(withDefaults())
|
||||
.build();
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## OpenTelemetry Integration
|
||||
|
||||
By default, logging via OpenTelemetry is not configured. You have to provide the location of the OpenTelemetry logs endpoint to configure it:
|
||||
|
||||
```yaml
|
||||
management:
|
||||
otlp:
|
||||
logging:
|
||||
endpoint: "https://otlp.example.com:4318/v1/logs"
|
||||
```
|
||||
|
||||
> **NOTE**
|
||||
>
|
||||
> The OpenTelemetry Logback appender and Log4j appender are not part of Spring Boot. For more details, see the [OpenTelemetry Logback appender](https://github.com/open-telemetry/opentelemetry-java-instrumentation/tree/main/instrumentation/logback/logback-appender-1.0/library) or the [OpenTelemetry Log4j2 appender](https://github.com/open-telemetry/opentelemetry-java-instrumentation/tree/main/instrumentation/log4j/log4j-appender-2.17/library) in the [OpenTelemetry Java instrumentation GitHub repository](https://github.com/open-telemetry/opentelemetry-java-instrumentation).
|
||||
|
||||
> **TIP**
|
||||
>
|
||||
> You have to configure the appender in your `logback-spring.xml` or `log4j2-spring.xml` configuration to get OpenTelemetry logging working.
|
||||
|
||||
The `OpenTelemetryAppender` for both Logback and Log4j requires access to an `OpenTelemetry` instance to function properly. This instance must be set programmatically during application startup:
|
||||
|
||||
```java
|
||||
@Component
|
||||
public class OpenTelemetryAppenderInitializer {
|
||||
|
||||
public OpenTelemetryAppenderInitializer(OpenTelemetry openTelemetry) {
|
||||
// Configure Logback appender
|
||||
if (LoggerFactory.getILoggerFactory() instanceof LoggerContext) {
|
||||
LoggerContext context = (LoggerContext) LoggerFactory.getILoggerFactory();
|
||||
context.getStatusManager().add(new OnConsoleStatusListener());
|
||||
|
||||
OpenTelemetryAppender appender = new OpenTelemetryAppender();
|
||||
appender.setContext(context);
|
||||
appender.setOpenTelemetry(openTelemetry);
|
||||
appender.start();
|
||||
|
||||
ch.qos.logback.classic.Logger rootLogger = context.getLogger(Logger.ROOT_LOGGER_NAME);
|
||||
rootLogger.addAppender(appender);
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Monitor Performance**: Changing log levels at runtime can impact application performance
|
||||
2. **Security**: Always secure the loggers endpoint in production environments
|
||||
3. **Audit Changes**: Log when log levels are changed and by whom
|
||||
4. **Temporary Changes**: Consider making runtime log level changes temporary
|
||||
5. **Documentation**: Document the purpose of different log levels in your application
|
||||
6. **Testing**: Test your application with different log levels to ensure it performs well
|
||||
7. **Correlation IDs**: Use correlation IDs to track requests across log entries
|
||||
|
||||
### Audit Log Level Changes
|
||||
|
||||
```java
|
||||
@Component
|
||||
public class LoggerAuditListener {
|
||||
|
||||
private static final Logger logger = LoggerFactory.getLogger(LoggerAuditListener.class);
|
||||
|
||||
@EventListener
|
||||
public void handleLoggerConfigurationChange(LoggerConfigurationChangeEvent event) {
|
||||
String username = getCurrentUsername();
|
||||
logger.info("Logger level changed: logger={}, oldLevel={}, newLevel={}, user={}",
|
||||
event.getLoggerName(),
|
||||
event.getOldLevel(),
|
||||
event.getNewLevel(),
|
||||
username);
|
||||
}
|
||||
|
||||
private String getCurrentUsername() {
|
||||
Authentication auth = SecurityContextHolder.getContext().getAuthentication();
|
||||
return auth != null ? auth.getName() : "system";
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Temporary Log Level Changes
|
||||
|
||||
```java
|
||||
@Component
|
||||
public class TemporaryLogLevelManager {
|
||||
|
||||
private final LoggingSystem loggingSystem;
|
||||
private final ScheduledExecutorService scheduler = Executors.newScheduledThreadPool(1);
|
||||
private final Map<String, LogLevel> originalLevels = new ConcurrentHashMap<>();
|
||||
|
||||
public TemporaryLogLevelManager(LoggingSystem loggingSystem) {
|
||||
this.loggingSystem = loggingSystem;
|
||||
}
|
||||
|
||||
public void setTemporaryLogLevel(String loggerName, LogLevel level, Duration duration) {
|
||||
// Store original level
|
||||
LoggerConfiguration config = loggingSystem.getLoggerConfiguration(loggerName);
|
||||
originalLevels.put(loggerName, config.getConfiguredLevel());
|
||||
|
||||
// Set new level
|
||||
loggingSystem.setLogLevel(loggerName, level);
|
||||
|
||||
// Schedule reset
|
||||
scheduler.schedule(() -> resetLogLevel(loggerName), duration.toMillis(), TimeUnit.MILLISECONDS);
|
||||
}
|
||||
|
||||
private void resetLogLevel(String loggerName) {
|
||||
LogLevel originalLevel = originalLevels.remove(loggerName);
|
||||
loggingSystem.setLogLevel(loggerName, originalLevel);
|
||||
}
|
||||
}
|
||||
```
|
||||
578
skills/spring-boot-actuator/references/metrics.md
Normal file
578
skills/spring-boot-actuator/references/metrics.md
Normal file
@@ -0,0 +1,578 @@
|
||||
# Metrics with Spring Boot Actuator
|
||||
|
||||
Spring Boot Actuator provides dependency management and auto-configuration for [Micrometer](https://micrometer.io/), an application metrics facade that supports numerous monitoring systems, including:
|
||||
|
||||
- AppOptics
|
||||
- Atlas
|
||||
- Datadog
|
||||
- Dynatrace
|
||||
- Elastic
|
||||
- Ganglia
|
||||
- Graphite
|
||||
- Humio
|
||||
- InfluxDB
|
||||
- JMX
|
||||
- KairosDB
|
||||
- New Relic
|
||||
- OpenTelemetry Protocol (OTLP)
|
||||
- Prometheus
|
||||
- Simple (in-memory)
|
||||
- Google Cloud Monitoring (Stackdriver)
|
||||
- StatsD
|
||||
- Wavefront
|
||||
|
||||
> **TIP**
|
||||
>
|
||||
> To learn more about Micrometer's capabilities, see its [reference documentation](https://micrometer.io/docs), in particular the [concepts section](https://micrometer.io/docs/concepts).
|
||||
|
||||
## Getting Started
|
||||
|
||||
Spring Boot auto-configures a composite `MeterRegistry` and adds a registry to the composite for each of the supported implementations that it finds on the classpath. Having a dependency on `micrometer-registry-{system}` in your runtime classpath is enough for Spring Boot to configure the registry.
|
||||
|
||||
Most registries share common features. For instance, you can disable a particular registry even if the Micrometer registry implementation is on the classpath. The following example disables Datadog:
|
||||
|
||||
```yaml
|
||||
management:
|
||||
datadog:
|
||||
metrics:
|
||||
export:
|
||||
enabled: false
|
||||
```
|
||||
|
||||
You can also disable all registries unless stated otherwise by the registry-specific property, as the following example shows:
|
||||
|
||||
```yaml
|
||||
management:
|
||||
defaults:
|
||||
metrics:
|
||||
export:
|
||||
enabled: false
|
||||
```
|
||||
|
||||
Spring Boot also adds any auto-configured registries to the global static composite registry on the `Metrics` class, unless you explicitly tell it not to:
|
||||
|
||||
```yaml
|
||||
management:
|
||||
metrics:
|
||||
use-global-registry: false
|
||||
```
|
||||
|
||||
You can register any number of `MeterRegistryCustomizer` beans to further configure the registry, such as applying common tags, before any meters are registered with the registry:
|
||||
|
||||
```java
|
||||
@Component
|
||||
public class MyMeterRegistryConfiguration {
|
||||
|
||||
@Bean
|
||||
public MeterRegistryCustomizer<MeterRegistry> metricsCommonTags() {
|
||||
return registry -> registry.config().commonTags("region", "us-east-1");
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
You can apply customizations to particular registry implementations by being more specific about the generic type:
|
||||
|
||||
```java
|
||||
@Component
|
||||
public class MyMeterRegistryConfiguration {
|
||||
|
||||
@Bean
|
||||
public MeterRegistryCustomizer<GraphiteMeterRegistry> graphiteMetricsNamingConvention() {
|
||||
return registry -> registry.config().namingConvention(this::toGraphiteConvention);
|
||||
}
|
||||
|
||||
private String toGraphiteConvention(String name, Meter.Type type, String baseUnit) {
|
||||
return name.toLowerCase().replace(".", "_");
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Spring Boot also configures built-in instrumentation that you can control through configuration or dedicated annotation markers.
|
||||
|
||||
## Supported Metrics
|
||||
|
||||
Spring Boot provides automatic meter registration for a wide variety of technologies. In most situations, the defaults provide sensible metrics that can be published to any of the supported monitoring systems.
|
||||
|
||||
### JVM Metrics
|
||||
|
||||
JVM metrics are published under the `jvm.` meter name. The following JVM metrics are provided:
|
||||
|
||||
- Memory and buffer pools
|
||||
- Statistics related to garbage collection
|
||||
- Thread utilization
|
||||
- Number of classes loaded/unloaded
|
||||
|
||||
### System Metrics
|
||||
|
||||
System metrics are published under the `system.`, `process.`, and `disk.` meter names. The following system metrics are provided:
|
||||
|
||||
- CPU metrics
|
||||
- File descriptor metrics
|
||||
- Uptime metrics
|
||||
- Disk space metrics
|
||||
|
||||
### Application Startup Metrics
|
||||
|
||||
Application startup metrics are published under the `application.started.time` meter name. The following startup metrics are provided:
|
||||
|
||||
- Application startup time
|
||||
- Application ready time
|
||||
|
||||
### HTTP Request Metrics
|
||||
|
||||
HTTP request metrics are automatically recorded for all HTTP requests. Metrics are published under the `http.server.requests` meter name.
|
||||
|
||||
Tags added to HTTP server request metrics:
|
||||
|
||||
- `method`: The request's HTTP method (e.g., `GET` or `POST`)
|
||||
- `uri`: The request's URI template prior to variable substitution (e.g., `/api/person/{id}`)
|
||||
- `status`: The response's HTTP status code (e.g., `200` or `500`)
|
||||
- `outcome`: The request's outcome based on the status code (`SUCCESS`, `REDIRECTION`, `CLIENT_ERROR`, `SERVER_ERROR`, or `UNKNOWN`)
|
||||
|
||||
To customize the tags, provide a `@Bean` that implements `WebMvcTagsContributor`:
|
||||
|
||||
```java
|
||||
@Component
|
||||
public class MyWebMvcTagsContributor implements WebMvcTagsContributor {
|
||||
|
||||
@Override
|
||||
public Iterable<Tag> getTags(HttpServletRequest request,
|
||||
HttpServletResponse response,
|
||||
Object handler,
|
||||
Throwable exception) {
|
||||
return Tags.of("custom.tag", "custom-value");
|
||||
}
|
||||
|
||||
@Override
|
||||
public Iterable<Tag> getLongRequestTags(HttpServletRequest request,
|
||||
Object handler) {
|
||||
return Tags.of("custom.tag", "custom-value");
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### WebFlux Metrics
|
||||
|
||||
WebFlux metrics are automatically recorded for all WebFlux requests. Metrics are published under the `http.server.requests` meter name.
|
||||
|
||||
Tags added to WebFlux request metrics:
|
||||
|
||||
- `method`: The request's HTTP method
|
||||
- `uri`: The request's URI template
|
||||
- `status`: The response's HTTP status code
|
||||
- `outcome`: The request's outcome
|
||||
|
||||
### Data Source Metrics
|
||||
|
||||
Auto-configuration enables the instrumentation of all available DataSource objects with metrics prefixed with `hikaricp.`, `tomcat.datasource.`, or `dbcp2.`.
|
||||
|
||||
Connection pool metrics are published under the following meter names:
|
||||
|
||||
- `hikaricp.connections` (HikariCP)
|
||||
- `tomcat.datasource.connections` (Tomcat)
|
||||
- `dbcp2.connections` (Apache DBCP2)
|
||||
|
||||
### Cache Metrics
|
||||
|
||||
Auto-configuration enables the instrumentation of all available Cache managers on startup with metrics prefixed with `cache.`. The cache instrumentation is standardized for a basic set of metrics.
|
||||
|
||||
Cache metrics include:
|
||||
|
||||
- Size
|
||||
- Hit ratio
|
||||
- Evictions
|
||||
- Puts and misses
|
||||
|
||||
### Task Execution and Scheduling Metrics
|
||||
|
||||
Auto-configuration enables the instrumentation of all available `ThreadPoolTaskExecutor` and `ThreadPoolTaskScheduler` beans with metrics prefixed with `executor.` and `scheduler.` respectively.
|
||||
|
||||
Executor metrics include:
|
||||
|
||||
- Active threads
|
||||
- Pool size
|
||||
- Queue size
|
||||
- Task completion
|
||||
|
||||
## Custom Metrics
|
||||
|
||||
To record your own metrics, inject `MeterRegistry` into your component:
|
||||
|
||||
```java
|
||||
@Component
|
||||
public class MyService {
|
||||
private final Counter counter;
|
||||
private final Timer timer;
|
||||
private final Gauge gauge;
|
||||
|
||||
public MyService(MeterRegistry meterRegistry) {
|
||||
this.counter = Counter.builder("my.counter")
|
||||
.description("A simple counter")
|
||||
.register(meterRegistry);
|
||||
|
||||
this.timer = Timer.builder("my.timer")
|
||||
.description("A simple timer")
|
||||
.register(meterRegistry);
|
||||
|
||||
this.gauge = Gauge.builder("my.gauge")
|
||||
.description("A simple gauge")
|
||||
.register(meterRegistry, this, MyService::calculateGaugeValue);
|
||||
}
|
||||
|
||||
public void doSomething() {
|
||||
counter.increment();
|
||||
|
||||
Timer.Sample sample = Timer.start(meterRegistry);
|
||||
// ... do work
|
||||
sample.stop(timer);
|
||||
}
|
||||
|
||||
private double calculateGaugeValue(MyService self) {
|
||||
return Math.random();
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Using @Timed Annotation
|
||||
|
||||
You can use the `@Timed` annotation to time method executions:
|
||||
|
||||
```java
|
||||
@Component
|
||||
public class MyService {
|
||||
|
||||
@Timed(name = "my.method.time", description = "Time taken to execute my method")
|
||||
public void timedMethod() {
|
||||
// method body
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
For the `@Timed` annotation to work, you need to enable timing support:
|
||||
|
||||
```java
|
||||
@Configuration
|
||||
@EnableConfigurationProperties
|
||||
public class TimedConfiguration {
|
||||
|
||||
@Bean
|
||||
public TimedAspect timedAspect(MeterRegistry registry) {
|
||||
return new TimedAspect(registry);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Using @Counted Annotation
|
||||
|
||||
You can use the `@Counted` annotation to count method invocations:
|
||||
|
||||
```java
|
||||
@Component
|
||||
public class MyService {
|
||||
|
||||
@Counted(name = "my.method.count", description = "Number of times my method is called")
|
||||
public void countedMethod() {
|
||||
// method body
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
For the `@Counted` annotation to work, you need to enable counting support:
|
||||
|
||||
```java
|
||||
@Configuration
|
||||
public class CountedConfiguration {
|
||||
|
||||
@Bean
|
||||
public CountedAspect countedAspect(MeterRegistry registry) {
|
||||
return new CountedAspect(registry);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Meter Filters
|
||||
|
||||
You can register any number of `MeterFilter` beans to control how meters are registered:
|
||||
|
||||
```java
|
||||
@Configuration
|
||||
public class MetricsConfiguration {
|
||||
|
||||
@Bean
|
||||
public MeterFilter renameFilter() {
|
||||
return MeterFilter.rename("old.metric.name", "new.metric.name");
|
||||
}
|
||||
|
||||
@Bean
|
||||
public MeterFilter denyFilter() {
|
||||
return MeterFilter.deny(id -> id.getName().contains("unwanted"));
|
||||
}
|
||||
|
||||
@Bean
|
||||
public MeterFilter tagFilter() {
|
||||
return MeterFilter.commonTags("application", "my-app");
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Metrics Endpoint
|
||||
|
||||
The `metrics` endpoint provides access to all the metrics collected by the application. You can view the names of all available meters by visiting `/actuator/metrics`.
|
||||
|
||||
To view the value of a particular meter, specify its name as a path parameter:
|
||||
|
||||
```
|
||||
GET /actuator/metrics/jvm.memory.used
|
||||
```
|
||||
|
||||
The response contains the meter's measurements:
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "jvm.memory.used",
|
||||
"description": "The amount of used memory",
|
||||
"baseUnit": "bytes",
|
||||
"measurements": [
|
||||
{
|
||||
"statistic": "VALUE",
|
||||
"value": 8.73E8
|
||||
}
|
||||
],
|
||||
"availableTags": [
|
||||
{
|
||||
"tag": "area",
|
||||
"values": ["heap", "nonheap"]
|
||||
},
|
||||
{
|
||||
"tag": "id",
|
||||
"values": ["Compressed Class Space", "PS Eden Space", "PS Survivor Space"]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
You can drill down to a particular meter by adding query parameters:
|
||||
|
||||
```
|
||||
GET /actuator/metrics/jvm.memory.used?tag=area:heap&tag=id:PS%20Eden%20Space
|
||||
```
|
||||
|
||||
## Monitoring System Integration
|
||||
|
||||
### Prometheus
|
||||
|
||||
To export metrics to Prometheus, add the following dependency:
|
||||
|
||||
```xml
|
||||
<dependency>
|
||||
<groupId>io.micrometer</groupId>
|
||||
<artifactId>micrometer-registry-prometheus</artifactId>
|
||||
</dependency>
|
||||
```
|
||||
|
||||
This exposes a `/actuator/prometheus` endpoint that presents metrics in the format expected by a Prometheus server.
|
||||
|
||||
Configuration example:
|
||||
|
||||
```yaml
|
||||
management:
|
||||
endpoints:
|
||||
web:
|
||||
exposure:
|
||||
include: "prometheus"
|
||||
metrics:
|
||||
export:
|
||||
prometheus:
|
||||
enabled: true
|
||||
step: 1m
|
||||
descriptions: true
|
||||
```
|
||||
|
||||
### Datadog
|
||||
|
||||
To export metrics to Datadog, add the following dependency:
|
||||
|
||||
```xml
|
||||
<dependency>
|
||||
<groupId>io.micrometer</groupId>
|
||||
<artifactId>micrometer-registry-datadog</artifactId>
|
||||
</dependency>
|
||||
```
|
||||
|
||||
Configuration:
|
||||
|
||||
```yaml
|
||||
management:
|
||||
metrics:
|
||||
export:
|
||||
datadog:
|
||||
api-key: ${DATADOG_API_KEY}
|
||||
application-key: ${DATADOG_APP_KEY}
|
||||
uri: https://api.datadoghq.com
|
||||
step: 1m
|
||||
```
|
||||
|
||||
### InfluxDB
|
||||
|
||||
To export metrics to InfluxDB, add the following dependency:
|
||||
|
||||
```xml
|
||||
<dependency>
|
||||
<groupId>io.micrometer</groupId>
|
||||
<artifactId>micrometer-registry-influx</artifactId>
|
||||
</dependency>
|
||||
```
|
||||
|
||||
Configuration:
|
||||
|
||||
```yaml
|
||||
management:
|
||||
metrics:
|
||||
export:
|
||||
influx:
|
||||
uri: http://localhost:8086
|
||||
db: mydb
|
||||
username: ${INFLUX_USERNAME}
|
||||
password: ${INFLUX_PASSWORD}
|
||||
step: 1m
|
||||
```
|
||||
|
||||
### New Relic
|
||||
|
||||
To export metrics to New Relic, add the following dependency:
|
||||
|
||||
```xml
|
||||
<dependency>
|
||||
<groupId>io.micrometer</groupId>
|
||||
<artifactId>micrometer-registry-newrelic</artifactId>
|
||||
</dependency>
|
||||
```
|
||||
|
||||
Configuration:
|
||||
|
||||
```yaml
|
||||
management:
|
||||
metrics:
|
||||
export:
|
||||
newrelic:
|
||||
api-key: ${NEW_RELIC_API_KEY}
|
||||
account-id: ${NEW_RELIC_ACCOUNT_ID}
|
||||
step: 1m
|
||||
```
|
||||
|
||||
### Simple Registry (In-Memory)
|
||||
|
||||
The simple registry is automatically configured if no other registry is found on the classpath. It stores metrics in memory and is useful for development and testing:
|
||||
|
||||
```yaml
|
||||
management:
|
||||
metrics:
|
||||
export:
|
||||
simple:
|
||||
enabled: true
|
||||
step: 1m
|
||||
```
|
||||
|
||||
## Performance Considerations
|
||||
|
||||
### Meter Cardinality
|
||||
|
||||
Be mindful of meter cardinality when adding tags. High-cardinality tags (like user IDs) can lead to performance issues:
|
||||
|
||||
```java
|
||||
// Bad - high cardinality
|
||||
Timer.builder("user.request.time")
|
||||
.tag("user.id", userId) // Could be millions of different values
|
||||
.register(registry);
|
||||
|
||||
// Good - low cardinality
|
||||
Timer.builder("user.request.time")
|
||||
.tag("user.type", userType) // Limited number of values
|
||||
.register(registry);
|
||||
```
|
||||
|
||||
### Sampling
|
||||
|
||||
For high-throughput applications, consider using sampling to reduce overhead:
|
||||
|
||||
```java
|
||||
@Bean
|
||||
public MeterFilter samplingFilter() {
|
||||
return MeterFilter.maximumExpectedValue("http.server.requests",
|
||||
Duration.ofMillis(500));
|
||||
}
|
||||
```
|
||||
|
||||
### Meter Registry Configuration
|
||||
|
||||
Configure appropriate publishing intervals to balance between timeliness and performance:
|
||||
|
||||
```yaml
|
||||
management:
|
||||
metrics:
|
||||
export:
|
||||
prometheus:
|
||||
step: 30s # Adjust based on your needs
|
||||
```
|
||||
|
||||
## Security Considerations
|
||||
|
||||
### Sensitive Data
|
||||
|
||||
Be careful not to include sensitive information in metric tags or names:
|
||||
|
||||
```java
|
||||
// Bad - exposes sensitive data
|
||||
Counter.builder("login.attempts")
|
||||
.tag("username", username) // Could expose usernames
|
||||
.register(registry);
|
||||
|
||||
// Good - uses hashed or anonymized data
|
||||
Counter.builder("login.attempts")
|
||||
.tag("outcome", successful ? "success" : "failure")
|
||||
.register(registry);
|
||||
```
|
||||
|
||||
### Endpoint Security
|
||||
|
||||
Secure the metrics endpoint in production:
|
||||
|
||||
```yaml
|
||||
management:
|
||||
endpoints:
|
||||
web:
|
||||
exposure:
|
||||
include: "metrics"
|
||||
endpoint:
|
||||
metrics:
|
||||
access: restricted
|
||||
```
|
||||
|
||||
Or using Spring Security:
|
||||
|
||||
```java
|
||||
@Configuration
|
||||
public class ActuatorSecurity {
|
||||
|
||||
@Bean
|
||||
public SecurityFilterChain actuatorSecurityFilterChain(HttpSecurity http) throws Exception {
|
||||
return http
|
||||
.requestMatcher(EndpointRequest.toAnyEndpoint())
|
||||
.authorizeHttpRequests(requests ->
|
||||
requests.anyRequest().hasRole("ACTUATOR"))
|
||||
.httpBasic(withDefaults())
|
||||
.build();
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Use meaningful meter names**: Follow naming conventions specific to your monitoring system
|
||||
2. **Add appropriate tags**: Use tags to add dimensions but avoid high cardinality
|
||||
3. **Monitor meter cardinality**: High cardinality can impact performance
|
||||
4. **Use meter filters**: Filter out unwanted metrics or rename meters
|
||||
5. **Configure appropriate publishing intervals**: Balance between timeliness and performance
|
||||
6. **Secure sensitive endpoints**: Protect metrics endpoints in production
|
||||
7. **Test metrics in development**: Verify metrics are collected correctly before deploying
|
||||
8. **Document custom metrics**: Maintain documentation for custom metrics and their purposes
|
||||
318
skills/spring-boot-actuator/references/monitoring.md
Normal file
318
skills/spring-boot-actuator/references/monitoring.md
Normal file
@@ -0,0 +1,318 @@
|
||||
# HTTP Monitoring and Management
|
||||
|
||||
If you are developing a web application, Spring Boot Actuator auto-configures all enabled endpoints to be exposed over HTTP. The default convention is to use the `id` of the endpoint with a prefix of `/actuator` as the URL path. For example, `health` is exposed as `/actuator/health`.
|
||||
|
||||
> **TIP**
|
||||
>
|
||||
> Actuator is supported natively with Spring MVC, Spring WebFlux, and Jersey. If both Jersey and Spring MVC are available, Spring MVC is used.
|
||||
|
||||
> **NOTE**
|
||||
>
|
||||
> Jackson is a required dependency in order to get the correct JSON responses as documented in the [API documentation](https://docs.spring.io/spring-boot/docs/current/actuator-api/htmlsingle/).
|
||||
|
||||
## Customizing the Management Endpoint Paths
|
||||
|
||||
Sometimes, it is useful to customize the prefix for the management endpoints. For example, your application might already use `/actuator` for another purpose. You can use the `management.endpoints.web.base-path` property to change the prefix for your management endpoint, as the following example shows:
|
||||
|
||||
```yaml
|
||||
management:
|
||||
endpoints:
|
||||
web:
|
||||
base-path: "/manage"
|
||||
```
|
||||
|
||||
The preceding example changes the endpoint from `/actuator/{id}` to `/manage/{id}` (for example, `/manage/info`).
|
||||
|
||||
> **NOTE**
|
||||
>
|
||||
> Unless the management port has been configured to expose endpoints by using a different HTTP port, `management.endpoints.web.base-path` is relative to `server.servlet.context-path` (for servlet web applications) or `spring.webflux.base-path` (for reactive web applications). If `management.server.port` is configured, `management.endpoints.web.base-path` is relative to `management.server.base-path`.
|
||||
|
||||
If you want to map endpoints to a different path, you can use the `management.endpoints.web.path-mapping` property.
|
||||
|
||||
The following example remaps `/actuator/health` to `/healthcheck`:
|
||||
|
||||
```yaml
|
||||
management:
|
||||
endpoints:
|
||||
web:
|
||||
base-path: "/"
|
||||
path-mapping:
|
||||
health: "healthcheck"
|
||||
```
|
||||
|
||||
## Customizing the Management Server Port
|
||||
|
||||
Exposing management endpoints by using the default HTTP port is a sensible choice for cloud-based deployments. If, however, your application runs inside your own data center, you may prefer to expose endpoints by using a different HTTP port.
|
||||
|
||||
You can set the `management.server.port` property to change the HTTP port, as the following example shows:
|
||||
|
||||
```yaml
|
||||
management:
|
||||
server:
|
||||
port: 8081
|
||||
```
|
||||
|
||||
> **NOTE**
|
||||
>
|
||||
> On Cloud Foundry, by default, applications receive requests only on port 8080 for both HTTP and TCP routing. If you want to use a custom management port on Cloud Foundry, you need to explicitly set up the application's routes to forward traffic to the custom port.
|
||||
|
||||
## Configuring Management-specific SSL
|
||||
|
||||
When configured to use a custom port, you can also configure the management server with its own SSL by using the various `management.server.ssl.*` properties. For example, doing so lets a management server be available over HTTP while the main application uses HTTPS, as the following property settings show:
|
||||
|
||||
```yaml
|
||||
server:
|
||||
port: 8443
|
||||
ssl:
|
||||
enabled: true
|
||||
key-store: "classpath:store.jks"
|
||||
key-password: "secret"
|
||||
management:
|
||||
server:
|
||||
port: 8080
|
||||
ssl:
|
||||
enabled: false
|
||||
```
|
||||
|
||||
Alternatively, both the main server and the management server can use SSL but with different key stores, as follows:
|
||||
|
||||
```yaml
|
||||
server:
|
||||
port: 8443
|
||||
ssl:
|
||||
enabled: true
|
||||
key-store: "classpath:main.jks"
|
||||
key-password: "secret"
|
||||
management:
|
||||
server:
|
||||
port: 8080
|
||||
ssl:
|
||||
enabled: true
|
||||
key-store: "classpath:management.jks"
|
||||
key-password: "secret"
|
||||
```
|
||||
|
||||
## Customizing the Management Server Address
|
||||
|
||||
You can customize the address on which the management endpoints are available by setting the `management.server.address` property. Doing so can be useful if you want to listen only on an internal or ops-facing network or to listen only for connections from `localhost`.
|
||||
|
||||
> **NOTE**
|
||||
>
|
||||
> You can listen on a different address only when the port differs from the main server port.
|
||||
|
||||
The following example does not allow remote management connections:
|
||||
|
||||
```yaml
|
||||
management:
|
||||
server:
|
||||
port: 8081
|
||||
address: "127.0.0.1"
|
||||
```
|
||||
|
||||
## Disabling HTTP Endpoints
|
||||
|
||||
If you do not want to expose endpoints over HTTP, you can set the management port to `-1`, as the following example shows:
|
||||
|
||||
```yaml
|
||||
management:
|
||||
server:
|
||||
port: -1
|
||||
```
|
||||
|
||||
You can also achieve this by using the `management.endpoints.web.exposure.exclude` property, as the following example shows:
|
||||
|
||||
```yaml
|
||||
management:
|
||||
endpoints:
|
||||
web:
|
||||
exposure:
|
||||
exclude: "*"
|
||||
```
|
||||
|
||||
## Security Configuration for Management Endpoints
|
||||
|
||||
### Basic Authentication
|
||||
|
||||
To secure management endpoints with basic authentication:
|
||||
|
||||
```yaml
|
||||
spring:
|
||||
security:
|
||||
user:
|
||||
name: admin
|
||||
password: secret
|
||||
roles: ACTUATOR
|
||||
|
||||
management:
|
||||
endpoints:
|
||||
web:
|
||||
exposure:
|
||||
include: "*"
|
||||
endpoint:
|
||||
health:
|
||||
show-details: when-authorized
|
||||
```
|
||||
|
||||
### Custom Security Configuration
|
||||
|
||||
For more granular control, create a custom security configuration:
|
||||
|
||||
```java
|
||||
@Configuration
|
||||
public class ManagementSecurityConfig {
|
||||
|
||||
@Bean
|
||||
@Order(1)
|
||||
public SecurityFilterChain actuatorSecurityFilterChain(HttpSecurity http) throws Exception {
|
||||
return http
|
||||
.requestMatcher(EndpointRequest.toAnyEndpoint())
|
||||
.authorizeHttpRequests(requests ->
|
||||
requests
|
||||
.requestMatchers(EndpointRequest.to("health", "info")).permitAll()
|
||||
.anyRequest().hasRole("ACTUATOR")
|
||||
)
|
||||
.httpBasic(withDefaults())
|
||||
.build();
|
||||
}
|
||||
|
||||
@Bean
|
||||
public SecurityFilterChain defaultSecurityFilterChain(HttpSecurity http) throws Exception {
|
||||
return http
|
||||
.authorizeHttpRequests(requests ->
|
||||
requests.anyRequest().authenticated())
|
||||
.formLogin(withDefaults())
|
||||
.build();
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Role-based Access Control
|
||||
|
||||
Different endpoints can require different roles:
|
||||
|
||||
```java
|
||||
@Configuration
|
||||
public class ActuatorSecurityConfig {
|
||||
|
||||
@Bean
|
||||
@Order(1)
|
||||
public SecurityFilterChain actuatorSecurityFilterChain(HttpSecurity http) throws Exception {
|
||||
return http
|
||||
.requestMatcher(EndpointRequest.toAnyEndpoint())
|
||||
.authorizeHttpRequests(requests ->
|
||||
requests
|
||||
.requestMatchers(EndpointRequest.to("health", "info")).permitAll()
|
||||
.requestMatchers(EndpointRequest.to("metrics", "prometheus")).hasRole("METRICS_READER")
|
||||
.requestMatchers(EndpointRequest.to("env", "configprops")).hasRole("CONFIG_READER")
|
||||
.requestMatchers(EndpointRequest.to("shutdown")).hasRole("ADMIN")
|
||||
.anyRequest().hasRole("ACTUATOR")
|
||||
)
|
||||
.httpBasic(withDefaults())
|
||||
.build();
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## CORS Configuration
|
||||
|
||||
To enable Cross-Origin Resource Sharing (CORS) for management endpoints:
|
||||
|
||||
```yaml
|
||||
management:
|
||||
endpoints:
|
||||
web:
|
||||
cors:
|
||||
allowed-origins: "https://example.com"
|
||||
allowed-methods: "GET,POST"
|
||||
allowed-headers: "*"
|
||||
allow-credentials: true
|
||||
```
|
||||
|
||||
## Custom Management Context Path
|
||||
|
||||
When using a separate management port, you can configure a custom context path:
|
||||
|
||||
```yaml
|
||||
management:
|
||||
server:
|
||||
port: 9090
|
||||
base-path: "/admin"
|
||||
endpoints:
|
||||
web:
|
||||
base-path: "/actuator"
|
||||
```
|
||||
|
||||
This configuration makes endpoints available at `http://localhost:9090/admin/actuator/*`.
|
||||
|
||||
## Load Balancer Configuration
|
||||
|
||||
When running behind a load balancer, configure the health endpoint appropriately:
|
||||
|
||||
```yaml
|
||||
management:
|
||||
endpoint:
|
||||
health:
|
||||
probes:
|
||||
enabled: true
|
||||
group:
|
||||
liveness:
|
||||
include: "livenessState"
|
||||
readiness:
|
||||
include: "readinessState,db"
|
||||
endpoints:
|
||||
web:
|
||||
exposure:
|
||||
include: "health,info,metrics"
|
||||
```
|
||||
|
||||
This allows the load balancer to check:
|
||||
- Liveness: `GET /actuator/health/liveness`
|
||||
- Readiness: `GET /actuator/health/readiness`
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Separate Management Port**: Use a different port for management endpoints in production
|
||||
2. **Secure Endpoints**: Always secure management endpoints in production environments
|
||||
3. **Limit Exposure**: Only expose necessary endpoints (`include` specific endpoints rather than using `*`)
|
||||
4. **Monitor Access**: Log and monitor access to management endpoints
|
||||
5. **Network Security**: Use firewalls to restrict access to management ports
|
||||
6. **SSL/TLS**: Use HTTPS for management endpoints in production
|
||||
7. **Health Checks**: Configure appropriate health indicators for your infrastructure
|
||||
8. **Graceful Shutdown**: Consider enabling graceful shutdown for production deployments
|
||||
|
||||
```yaml
|
||||
# Production-ready configuration example
|
||||
server:
|
||||
port: 8080
|
||||
shutdown: graceful
|
||||
|
||||
management:
|
||||
server:
|
||||
port: 8081
|
||||
address: "127.0.0.1" # Only local access
|
||||
ssl:
|
||||
enabled: true
|
||||
key-store: "classpath:management.p12"
|
||||
key-store-password: "${KEYSTORE_PASSWORD}"
|
||||
endpoints:
|
||||
web:
|
||||
exposure:
|
||||
include: "health,info,metrics,prometheus"
|
||||
enabled-by-default: false
|
||||
endpoint:
|
||||
health:
|
||||
enabled: true
|
||||
show-details: when-authorized
|
||||
probes:
|
||||
enabled: true
|
||||
info:
|
||||
enabled: true
|
||||
metrics:
|
||||
enabled: true
|
||||
prometheus:
|
||||
enabled: true
|
||||
|
||||
spring:
|
||||
lifecycle:
|
||||
timeout-per-shutdown-phase: 30s
|
||||
```
|
||||
543
skills/spring-boot-actuator/references/observability.md
Normal file
543
skills/spring-boot-actuator/references/observability.md
Normal file
@@ -0,0 +1,543 @@
|
||||
# Observability with Spring Boot Actuator
|
||||
|
||||
Spring Boot Actuator provides comprehensive observability features through integration with Micrometer, including metrics, tracing, and structured logging. This enables monitoring, alerting, and debugging of Spring Boot applications in production.
|
||||
|
||||
## Three Pillars of Observability
|
||||
|
||||
### 1. Metrics
|
||||
Quantitative measurements of application behavior:
|
||||
- Application metrics (requests/second, response times)
|
||||
- JVM metrics (memory usage, garbage collection)
|
||||
- System metrics (CPU, disk usage)
|
||||
- Custom business metrics
|
||||
|
||||
### 2. Tracing
|
||||
Request flow tracking across distributed systems:
|
||||
- Distributed tracing with OpenTelemetry or Zipkin
|
||||
- Span creation and propagation
|
||||
- Request correlation across services
|
||||
- Performance bottleneck identification
|
||||
|
||||
### 3. Logging
|
||||
Structured application event recording:
|
||||
- Centralized logging with correlation IDs
|
||||
- Log level management
|
||||
- Structured logging formats (JSON)
|
||||
- Integration with tracing context
|
||||
|
||||
## Observability Configuration
|
||||
|
||||
### Basic Setup
|
||||
|
||||
```yaml
|
||||
management:
|
||||
endpoints:
|
||||
web:
|
||||
exposure:
|
||||
include: "health,info,metrics,prometheus,loggers"
|
||||
|
||||
metrics:
|
||||
export:
|
||||
prometheus:
|
||||
enabled: true
|
||||
distribution:
|
||||
percentiles-histogram:
|
||||
http.server.requests: true
|
||||
http.client.requests: true
|
||||
|
||||
tracing:
|
||||
sampling:
|
||||
probability: 0.1 # 10% sampling in production
|
||||
|
||||
zipkin:
|
||||
tracing:
|
||||
endpoint: "http://zipkin:9411/api/v2/spans"
|
||||
|
||||
logging:
|
||||
pattern:
|
||||
level: "%5p [%X{traceId:-},%X{spanId:-}]"
|
||||
level:
|
||||
org.springframework.web: DEBUG
|
||||
```
|
||||
|
||||
### Micrometer Integration
|
||||
|
||||
```java
|
||||
@Configuration
|
||||
public class ObservabilityConfiguration {
|
||||
|
||||
@Bean
|
||||
public MeterRegistryCustomizer<MeterRegistry> metricsCommonTags() {
|
||||
return registry -> registry.config()
|
||||
.commonTags("application", "my-app")
|
||||
.commonTags("environment", getEnvironment());
|
||||
}
|
||||
|
||||
@Bean
|
||||
public ObservationRegistryCustomizer<ObservationRegistry> observationRegistryCustomizer() {
|
||||
return registry -> registry.observationConfig()
|
||||
.observationHandler(new LoggingObservationHandler())
|
||||
.observationHandler(new MetricsObservationHandler(meterRegistry()))
|
||||
.observationHandler(new TracingObservationHandler(tracer()));
|
||||
}
|
||||
|
||||
private String getEnvironment() {
|
||||
return System.getProperty("spring.profiles.active", "development");
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Custom Observability Components
|
||||
|
||||
### Custom Health Indicators
|
||||
|
||||
```java
|
||||
@Component
|
||||
public class DatabaseHealthIndicator implements HealthIndicator {
|
||||
|
||||
private final DataSource dataSource;
|
||||
|
||||
public DatabaseHealthIndicator(DataSource dataSource) {
|
||||
this.dataSource = dataSource;
|
||||
}
|
||||
|
||||
@Override
|
||||
public Health health() {
|
||||
try (Connection connection = dataSource.getConnection()) {
|
||||
boolean isValid = connection.isValid(5);
|
||||
|
||||
if (isValid) {
|
||||
return Health.up()
|
||||
.withDetail("database", "PostgreSQL")
|
||||
.withDetail("connection_pool", getConnectionPoolInfo())
|
||||
.build();
|
||||
} else {
|
||||
return Health.down()
|
||||
.withDetail("database", "Connection validation failed")
|
||||
.build();
|
||||
}
|
||||
} catch (Exception ex) {
|
||||
return Health.down(ex)
|
||||
.withDetail("database", "Connection failed")
|
||||
.build();
|
||||
}
|
||||
}
|
||||
|
||||
private Map<String, Object> getConnectionPoolInfo() {
|
||||
// Return connection pool metrics
|
||||
return Map.of(
|
||||
"active", 5,
|
||||
"idle", 3,
|
||||
"max", 10
|
||||
);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Custom Metrics
|
||||
|
||||
```java
|
||||
@Component
|
||||
public class BusinessMetrics {
|
||||
|
||||
private final Counter orderCounter;
|
||||
private final Timer orderProcessingTime;
|
||||
private final Gauge activeUsers;
|
||||
|
||||
public BusinessMetrics(MeterRegistry meterRegistry) {
|
||||
this.orderCounter = Counter.builder("orders.total")
|
||||
.description("Total number of orders")
|
||||
.tag("type", "all")
|
||||
.register(meterRegistry);
|
||||
|
||||
this.orderProcessingTime = Timer.builder("orders.processing.time")
|
||||
.description("Order processing time")
|
||||
.register(meterRegistry);
|
||||
|
||||
this.activeUsers = Gauge.builder("users.active")
|
||||
.description("Number of active users")
|
||||
.register(meterRegistry, this, BusinessMetrics::getActiveUserCount);
|
||||
}
|
||||
|
||||
public void recordOrder(String orderType) {
|
||||
orderCounter.increment(Tags.of("type", orderType));
|
||||
}
|
||||
|
||||
public void recordOrderProcessingTime(Duration duration) {
|
||||
orderProcessingTime.record(duration);
|
||||
}
|
||||
|
||||
private double getActiveUserCount() {
|
||||
// Implement logic to get active user count
|
||||
return 150.0;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Observation Aspects
|
||||
|
||||
```java
|
||||
@Aspect
|
||||
@Component
|
||||
public class ObservationAspect {
|
||||
|
||||
private final ObservationRegistry observationRegistry;
|
||||
|
||||
public ObservationAspect(ObservationRegistry observationRegistry) {
|
||||
this.observationRegistry = observationRegistry;
|
||||
}
|
||||
|
||||
@Around("@annotation(observed)")
|
||||
public Object observe(ProceedingJoinPoint joinPoint, Observed observed) throws Throwable {
|
||||
String operationName = observed.name().isEmpty() ?
|
||||
joinPoint.getSignature().getName() : observed.name();
|
||||
|
||||
return Observation.createNotStarted(operationName, observationRegistry)
|
||||
.lowCardinalityKeyValues(observed.lowCardinalityKeyValues())
|
||||
.observe(() -> {
|
||||
try {
|
||||
return joinPoint.proceed();
|
||||
} catch (RuntimeException ex) {
|
||||
throw ex;
|
||||
} catch (Throwable ex) {
|
||||
throw new RuntimeException(ex);
|
||||
}
|
||||
});
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Distributed Observability
|
||||
|
||||
### Service Correlation
|
||||
|
||||
```java
|
||||
@RestController
|
||||
public class OrderController {
|
||||
|
||||
private final OrderService orderService;
|
||||
private final ObservationRegistry observationRegistry;
|
||||
|
||||
public OrderController(OrderService orderService, ObservationRegistry observationRegistry) {
|
||||
this.orderService = orderService;
|
||||
this.observationRegistry = observationRegistry;
|
||||
}
|
||||
|
||||
@PostMapping("/orders")
|
||||
public ResponseEntity<Order> createOrder(@RequestBody CreateOrderRequest request) {
|
||||
return Observation.createNotStarted("order.create", observationRegistry)
|
||||
.lowCardinalityKeyValue("operation", "create")
|
||||
.lowCardinalityKeyValue("service", "order-service")
|
||||
.observe(() -> {
|
||||
Order order = orderService.createOrder(request);
|
||||
return ResponseEntity.ok(order);
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
@Service
|
||||
public class OrderService {
|
||||
|
||||
private final PaymentServiceClient paymentClient;
|
||||
|
||||
@Observed(name = "order.processing")
|
||||
public Order createOrder(CreateOrderRequest request) {
|
||||
// Business logic with automatic observation
|
||||
PaymentResult payment = paymentClient.processPayment(request.getPayment());
|
||||
|
||||
if (payment.isSuccessful()) {
|
||||
return saveOrder(request);
|
||||
} else {
|
||||
throw new PaymentFailedException("Payment failed");
|
||||
}
|
||||
}
|
||||
|
||||
private Order saveOrder(CreateOrderRequest request) {
|
||||
// Save order logic
|
||||
return new Order();
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Cross-Service Tracing
|
||||
|
||||
```java
|
||||
@Component
|
||||
public class PaymentServiceClient {
|
||||
|
||||
private final WebClient webClient;
|
||||
private final ObservationRegistry observationRegistry;
|
||||
|
||||
public PaymentServiceClient(WebClient.Builder webClientBuilder,
|
||||
ObservationRegistry observationRegistry) {
|
||||
this.webClient = webClientBuilder
|
||||
.baseUrl("http://payment-service")
|
||||
.build();
|
||||
this.observationRegistry = observationRegistry;
|
||||
}
|
||||
|
||||
public PaymentResult processPayment(PaymentRequest request) {
|
||||
return Observation.createNotStarted("payment.process", observationRegistry)
|
||||
.lowCardinalityKeyValue("service", "payment-service")
|
||||
.lowCardinalityKeyValue("method", "POST")
|
||||
.observe(() -> {
|
||||
return webClient
|
||||
.post()
|
||||
.uri("/payments")
|
||||
.bodyValue(request)
|
||||
.retrieve()
|
||||
.bodyToMono(PaymentResult.class)
|
||||
.block();
|
||||
});
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Alerting and Monitoring
|
||||
|
||||
### Health-based Alerting
|
||||
|
||||
```java
|
||||
@Component
|
||||
public class HealthAlertManager {
|
||||
|
||||
private final HealthEndpoint healthEndpoint;
|
||||
private final NotificationService notificationService;
|
||||
|
||||
@Scheduled(fixedRate = 30000) // Check every 30 seconds
|
||||
public void checkHealth() {
|
||||
HealthComponent health = healthEndpoint.health();
|
||||
|
||||
if (!Status.UP.equals(health.getStatus())) {
|
||||
Alert alert = Alert.builder()
|
||||
.severity(Alert.Severity.HIGH)
|
||||
.title("Application Health Check Failed")
|
||||
.description("Application health status: " + health.getStatus())
|
||||
.details(health.getDetails())
|
||||
.build();
|
||||
|
||||
notificationService.sendAlert(alert);
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Metric-based Alerting
|
||||
|
||||
```java
|
||||
@Component
|
||||
public class MetricAlertManager {
|
||||
|
||||
private final MeterRegistry meterRegistry;
|
||||
private final NotificationService notificationService;
|
||||
|
||||
@Scheduled(fixedRate = 60000) // Check every minute
|
||||
public void checkMetrics() {
|
||||
// Check error rate
|
||||
double errorRate = getErrorRate();
|
||||
if (errorRate > 0.05) { // 5% error rate threshold
|
||||
sendAlert("High Error Rate",
|
||||
String.format("Error rate: %.2f%%", errorRate * 100));
|
||||
}
|
||||
|
||||
// Check response time
|
||||
double avgResponseTime = getAverageResponseTime();
|
||||
if (avgResponseTime > 1000) { // 1 second threshold
|
||||
sendAlert("High Response Time",
|
||||
String.format("Average response time: %.2f ms", avgResponseTime));
|
||||
}
|
||||
|
||||
// Check memory usage
|
||||
double memoryUsage = getMemoryUsage();
|
||||
if (memoryUsage > 0.9) { // 90% memory usage
|
||||
sendAlert("High Memory Usage",
|
||||
String.format("Memory usage: %.2f%%", memoryUsage * 100));
|
||||
}
|
||||
}
|
||||
|
||||
private double getErrorRate() {
|
||||
Timer successTimer = meterRegistry.find("http.server.requests")
|
||||
.tag("status", "200")
|
||||
.timer();
|
||||
Timer errorTimer = meterRegistry.find("http.server.requests")
|
||||
.tag("status", "500")
|
||||
.timer();
|
||||
|
||||
if (successTimer != null && errorTimer != null) {
|
||||
double total = successTimer.count() + errorTimer.count();
|
||||
return total > 0 ? errorTimer.count() / total : 0.0;
|
||||
}
|
||||
return 0.0;
|
||||
}
|
||||
|
||||
private double getAverageResponseTime() {
|
||||
Timer timer = meterRegistry.find("http.server.requests").timer();
|
||||
return timer != null ? timer.mean(TimeUnit.MILLISECONDS) : 0.0;
|
||||
}
|
||||
|
||||
private double getMemoryUsage() {
|
||||
Gauge memoryUsed = meterRegistry.find("jvm.memory.used").gauge();
|
||||
Gauge memoryMax = meterRegistry.find("jvm.memory.max").gauge();
|
||||
|
||||
if (memoryUsed != null && memoryMax != null) {
|
||||
return memoryUsed.value() / memoryMax.value();
|
||||
}
|
||||
return 0.0;
|
||||
}
|
||||
|
||||
private void sendAlert(String title, String message) {
|
||||
Alert alert = Alert.builder()
|
||||
.severity(Alert.Severity.MEDIUM)
|
||||
.title(title)
|
||||
.description(message)
|
||||
.timestamp(Instant.now())
|
||||
.build();
|
||||
|
||||
notificationService.sendAlert(alert);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Production Observability Setup
|
||||
|
||||
### Prometheus Configuration
|
||||
|
||||
```yaml
|
||||
management:
|
||||
endpoints:
|
||||
web:
|
||||
exposure:
|
||||
include: "health,info,metrics,prometheus"
|
||||
|
||||
metrics:
|
||||
export:
|
||||
prometheus:
|
||||
enabled: true
|
||||
step: 30s
|
||||
descriptions: true
|
||||
distribution:
|
||||
percentiles-histogram:
|
||||
"[http.server.requests]": true
|
||||
percentiles:
|
||||
"[http.server.requests]": 0.5, 0.95, 0.99
|
||||
slo:
|
||||
"[http.server.requests]": 100ms, 500ms, 1s
|
||||
|
||||
prometheus:
|
||||
metrics:
|
||||
export:
|
||||
enabled: true
|
||||
```
|
||||
|
||||
### Grafana Dashboard Configuration
|
||||
|
||||
```json
|
||||
{
|
||||
"dashboard": {
|
||||
"title": "Spring Boot Application Dashboard",
|
||||
"panels": [
|
||||
{
|
||||
"title": "Request Rate",
|
||||
"type": "graph",
|
||||
"targets": [
|
||||
{
|
||||
"expr": "rate(http_server_requests_seconds_count[5m])",
|
||||
"legendFormat": "{{method}} {{uri}}"
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"title": "Response Time",
|
||||
"type": "graph",
|
||||
"targets": [
|
||||
{
|
||||
"expr": "histogram_quantile(0.95, rate(http_server_requests_seconds_bucket[5m]))",
|
||||
"legendFormat": "95th percentile"
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"title": "JVM Memory",
|
||||
"type": "graph",
|
||||
"targets": [
|
||||
{
|
||||
"expr": "jvm_memory_used_bytes / jvm_memory_max_bytes * 100",
|
||||
"legendFormat": "Memory Usage %"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Observability Strategy**: Define clear observability goals and SLIs/SLOs
|
||||
2. **Metric Cardinality**: Keep metric labels low-cardinality to avoid performance issues
|
||||
3. **Sampling**: Use appropriate sampling rates for tracing in high-throughput applications
|
||||
4. **Security**: Secure observability endpoints and ensure no sensitive data is exposed
|
||||
5. **Performance**: Monitor the performance impact of observability instrumentation
|
||||
6. **Alerting**: Set up meaningful alerts based on business metrics, not just technical metrics
|
||||
7. **Documentation**: Document your observability setup and runbooks for incident response
|
||||
|
||||
### Complete Production Configuration
|
||||
|
||||
```yaml
|
||||
# Production observability configuration
|
||||
management:
|
||||
endpoints:
|
||||
web:
|
||||
exposure:
|
||||
include: "health,info,metrics,prometheus"
|
||||
base-path: "/actuator"
|
||||
|
||||
endpoint:
|
||||
health:
|
||||
show-details: when-authorized
|
||||
probes:
|
||||
enabled: true
|
||||
metrics:
|
||||
enabled: true
|
||||
prometheus:
|
||||
enabled: true
|
||||
|
||||
metrics:
|
||||
export:
|
||||
prometheus:
|
||||
enabled: true
|
||||
step: 30s
|
||||
distribution:
|
||||
percentiles-histogram:
|
||||
http.server.requests: true
|
||||
percentiles:
|
||||
http.server.requests: 0.5, 0.95, 0.99
|
||||
|
||||
tracing:
|
||||
sampling:
|
||||
probability: 0.01 # 1% sampling in production
|
||||
|
||||
zipkin:
|
||||
tracing:
|
||||
endpoint: "${ZIPKIN_URL:http://localhost:9411/api/v2/spans}"
|
||||
|
||||
logging:
|
||||
pattern:
|
||||
level: "%5p [%X{traceId:-},%X{spanId:-}]"
|
||||
level:
|
||||
root: INFO
|
||||
com.example: DEBUG
|
||||
org.springframework.web: WARN
|
||||
|
||||
# Custom application properties
|
||||
app:
|
||||
observability:
|
||||
alerts:
|
||||
error-rate-threshold: 0.05
|
||||
response-time-threshold: 1000
|
||||
memory-threshold: 0.9
|
||||
retention:
|
||||
metrics: 30d
|
||||
traces: 7d
|
||||
logs: 30d
|
||||
```
|
||||
138
skills/spring-boot-actuator/references/process-monitoring.md
Normal file
138
skills/spring-boot-actuator/references/process-monitoring.md
Normal file
@@ -0,0 +1,138 @@
|
||||
# Process Monitoring
|
||||
|
||||
Spring Boot Actuator provides several features for monitoring the application process, including process information, thread dumps, and heap dumps.
|
||||
|
||||
## Process Information
|
||||
|
||||
The `info` endpoint can provide process-specific information:
|
||||
|
||||
```java
|
||||
@Component
|
||||
public class ProcessInfoContributor implements InfoContributor {
|
||||
|
||||
@Override
|
||||
public void contribute(Info.Builder builder) {
|
||||
RuntimeMXBean runtime = ManagementFactory.getRuntimeMXBean();
|
||||
|
||||
builder.withDetail("process", Map.of(
|
||||
"pid", ProcessHandle.current().pid(),
|
||||
"uptime", Duration.ofMillis(runtime.getUptime()),
|
||||
"start-time", Instant.ofEpochMilli(runtime.getStartTime()),
|
||||
"jvm-name", runtime.getVmName(),
|
||||
"jvm-version", runtime.getVmVersion()
|
||||
));
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Thread Monitoring
|
||||
|
||||
### Thread Dump Endpoint
|
||||
|
||||
Access thread dumps via:
|
||||
```
|
||||
GET /actuator/threaddump
|
||||
```
|
||||
|
||||
### Custom Thread Monitoring
|
||||
|
||||
```java
|
||||
@Component
|
||||
@ManagedResource(objectName = "com.example:type=ThreadMonitor")
|
||||
public class ThreadMonitorMBean {
|
||||
|
||||
@ManagedAttribute
|
||||
public int getActiveThreadCount() {
|
||||
return Thread.activeCount();
|
||||
}
|
||||
|
||||
@ManagedAttribute
|
||||
public long getTotalStartedThreadCount() {
|
||||
return ManagementFactory.getThreadMXBean().getTotalStartedThreadCount();
|
||||
}
|
||||
|
||||
@ManagedOperation
|
||||
public String getThreadDump() {
|
||||
ThreadMXBean threadBean = ManagementFactory.getThreadMXBean();
|
||||
ThreadInfo[] threadInfos = threadBean.dumpAllThreads(true, true);
|
||||
|
||||
StringBuilder dump = new StringBuilder();
|
||||
for (ThreadInfo threadInfo : threadInfos) {
|
||||
dump.append(threadInfo.toString()).append("\n");
|
||||
}
|
||||
return dump.toString();
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Memory Monitoring
|
||||
|
||||
### Heap Dump Endpoint
|
||||
|
||||
Access heap dumps via:
|
||||
```
|
||||
GET /actuator/heapdump
|
||||
```
|
||||
|
||||
### Memory Metrics
|
||||
|
||||
```java
|
||||
@Component
|
||||
public class MemoryMetrics {
|
||||
|
||||
private final MeterRegistry meterRegistry;
|
||||
|
||||
public MemoryMetrics(MeterRegistry meterRegistry) {
|
||||
this.meterRegistry = meterRegistry;
|
||||
|
||||
Gauge.builder("memory.heap.usage")
|
||||
.description("Heap memory usage percentage")
|
||||
.register(meterRegistry, this, MemoryMetrics::getHeapUsagePercentage);
|
||||
}
|
||||
|
||||
private double getHeapUsagePercentage() {
|
||||
MemoryMXBean memoryBean = ManagementFactory.getMemoryMXBean();
|
||||
MemoryUsage heapUsage = memoryBean.getHeapMemoryUsage();
|
||||
return (double) heapUsage.getUsed() / heapUsage.getMax() * 100;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Process Health Monitoring
|
||||
|
||||
```java
|
||||
@Component
|
||||
public class ProcessHealthIndicator implements HealthIndicator {
|
||||
|
||||
@Override
|
||||
public Health health() {
|
||||
try {
|
||||
// Check process health
|
||||
long pid = ProcessHandle.current().pid();
|
||||
ProcessHandle process = ProcessHandle.of(pid).orElseThrow();
|
||||
|
||||
if (process.isAlive()) {
|
||||
return Health.up()
|
||||
.withDetail("pid", pid)
|
||||
.withDetail("cpu-time", process.info().totalCpuDuration())
|
||||
.withDetail("start-time", process.info().startInstant())
|
||||
.build();
|
||||
} else {
|
||||
return Health.down()
|
||||
.withDetail("reason", "Process not alive")
|
||||
.build();
|
||||
}
|
||||
} catch (Exception ex) {
|
||||
return Health.down(ex).build();
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Security**: Secure heap dump and thread dump endpoints in production
|
||||
2. **Performance**: Monitor the performance impact of process monitoring
|
||||
3. **Storage**: Be aware that heap dumps can be very large files
|
||||
4. **Automation**: Set up automated collection of thread dumps during incidents
|
||||
5. **Analysis**: Use appropriate tools for analyzing heap and thread dumps
|
||||
557
skills/spring-boot-actuator/references/tracing.md
Normal file
557
skills/spring-boot-actuator/references/tracing.md
Normal file
@@ -0,0 +1,557 @@
|
||||
# Distributed Tracing with Spring Boot Actuator
|
||||
|
||||
Spring Boot Actuator provides dependency management and auto-configuration for [Micrometer Tracing](https://micrometer.io/docs/tracing), a facade for popular tracer libraries.
|
||||
|
||||
> **TIP**
|
||||
>
|
||||
> To learn more about Micrometer Tracing capabilities, see its [reference documentation](https://micrometer.io/docs/tracing).
|
||||
|
||||
## Supported Tracers
|
||||
|
||||
Spring Boot ships auto-configuration for the following tracers:
|
||||
|
||||
- [OpenTelemetry](https://opentelemetry.io/) with [Zipkin](https://zipkin.io/), [Wavefront](https://docs.wavefront.com/), or [OTLP](https://opentelemetry.io/docs/reference/specification/protocol/)
|
||||
- [OpenZipkin Brave](https://github.com/openzipkin/brave) with [Zipkin](https://zipkin.io/) or [Wavefront](https://docs.wavefront.com/)
|
||||
|
||||
## Getting Started with OpenTelemetry and Zipkin
|
||||
|
||||
### Dependencies
|
||||
|
||||
Add the following dependencies to your project:
|
||||
|
||||
**Maven:**
|
||||
```xml
|
||||
<dependencies>
|
||||
<dependency>
|
||||
<groupId>org.springframework.boot</groupId>
|
||||
<artifactId>spring-boot-starter-actuator</artifactId>
|
||||
</dependency>
|
||||
<dependency>
|
||||
<groupId>io.micrometer</groupId>
|
||||
<artifactId>micrometer-tracing-bridge-otel</artifactId>
|
||||
</dependency>
|
||||
<dependency>
|
||||
<groupId>io.opentelemetry</groupId>
|
||||
<artifactId>opentelemetry-exporter-zipkin</artifactId>
|
||||
</dependency>
|
||||
</dependencies>
|
||||
```
|
||||
|
||||
**Gradle:**
|
||||
```groovy
|
||||
dependencies {
|
||||
implementation 'org.springframework.boot:spring-boot-starter-actuator'
|
||||
implementation 'io.micrometer:micrometer-tracing-bridge-otel'
|
||||
implementation 'io.opentelemetry:opentelemetry-exporter-zipkin'
|
||||
}
|
||||
```
|
||||
|
||||
### Configuration
|
||||
|
||||
Add the following application properties:
|
||||
|
||||
```yaml
|
||||
management:
|
||||
tracing:
|
||||
sampling:
|
||||
probability: 1.0 # Sample 100% of requests in development
|
||||
zipkin:
|
||||
tracing:
|
||||
endpoint: "http://localhost:9411/api/v2/spans"
|
||||
|
||||
logging:
|
||||
pattern:
|
||||
level: "%5p [%X{traceId:-},%X{spanId:-}]"
|
||||
```
|
||||
|
||||
### Basic Application Example
|
||||
|
||||
```java
|
||||
@SpringBootApplication
|
||||
@RestController
|
||||
public class MyApplication {
|
||||
|
||||
private static final Logger logger = LoggerFactory.getLogger(MyApplication.class);
|
||||
|
||||
@GetMapping("/")
|
||||
public String home() {
|
||||
logger.info("Handling home request");
|
||||
return "Hello World!";
|
||||
}
|
||||
|
||||
public static void main(String[] args) {
|
||||
SpringApplication.run(MyApplication.class, args);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Configuration Options
|
||||
|
||||
### Sampling Configuration
|
||||
|
||||
Control which traces are collected:
|
||||
|
||||
```yaml
|
||||
management:
|
||||
tracing:
|
||||
sampling:
|
||||
probability: 0.1 # Sample 10% of requests in production
|
||||
rate: 100 # Maximum 100 traces per second
|
||||
```
|
||||
|
||||
### Zipkin Configuration
|
||||
|
||||
```yaml
|
||||
management:
|
||||
zipkin:
|
||||
tracing:
|
||||
endpoint: "http://zipkin:9411/api/v2/spans"
|
||||
timeout: 1s
|
||||
connect-timeout: 1s
|
||||
read-timeout: 10s
|
||||
```
|
||||
|
||||
### OpenTelemetry OTLP Configuration
|
||||
|
||||
```yaml
|
||||
management:
|
||||
otlp:
|
||||
tracing:
|
||||
endpoint: "http://otlp-collector:4318/v1/traces"
|
||||
timeout: 1s
|
||||
compression: gzip
|
||||
headers:
|
||||
Authorization: "Bearer your-token"
|
||||
```
|
||||
|
||||
### Wavefront Configuration
|
||||
|
||||
```yaml
|
||||
management:
|
||||
wavefront:
|
||||
tracing:
|
||||
application-name: "my-application"
|
||||
service-name: "my-service"
|
||||
api-token: "${WAVEFRONT_API_TOKEN}"
|
||||
uri: "https://your-instance.wavefront.com"
|
||||
```
|
||||
|
||||
## Custom Spans
|
||||
|
||||
### Using @Observed Annotation
|
||||
|
||||
```java
|
||||
@Service
|
||||
public class UserService {
|
||||
|
||||
@Observed(name = "user.service.find-by-id")
|
||||
public User findById(Long id) {
|
||||
// Service logic
|
||||
return userRepository.findById(id);
|
||||
}
|
||||
|
||||
@Observed(
|
||||
name = "user.service.create",
|
||||
contextualName = "creating-user",
|
||||
lowCardinalityKeyValues = {"operation", "create"}
|
||||
)
|
||||
public User createUser(CreateUserRequest request) {
|
||||
// Creation logic
|
||||
return save(request.toUser());
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Programmatic Span Creation
|
||||
|
||||
```java
|
||||
@Service
|
||||
public class OrderService {
|
||||
|
||||
private final ObservationRegistry observationRegistry;
|
||||
|
||||
public OrderService(ObservationRegistry observationRegistry) {
|
||||
this.observationRegistry = observationRegistry;
|
||||
}
|
||||
|
||||
public Order processOrder(OrderRequest request) {
|
||||
return Observation.createNotStarted("order.processing", observationRegistry)
|
||||
.lowCardinalityKeyValue("order.type", request.getType())
|
||||
.observe(() -> {
|
||||
// Add custom tags
|
||||
Observation.Scope scope = Observation.start("order.validation", observationRegistry);
|
||||
try {
|
||||
validateOrder(request);
|
||||
} finally {
|
||||
scope.close();
|
||||
}
|
||||
|
||||
// Process order
|
||||
return saveOrder(request);
|
||||
});
|
||||
}
|
||||
|
||||
private void validateOrder(OrderRequest request) {
|
||||
// Validation logic
|
||||
}
|
||||
|
||||
private Order saveOrder(OrderRequest request) {
|
||||
// Save logic
|
||||
return new Order();
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Using Micrometer's Tracer API
|
||||
|
||||
```java
|
||||
@Service
|
||||
public class PaymentService {
|
||||
|
||||
private final Tracer tracer;
|
||||
|
||||
public PaymentService(Tracer tracer) {
|
||||
this.tracer = tracer;
|
||||
}
|
||||
|
||||
public PaymentResult processPayment(PaymentRequest request) {
|
||||
Span span = tracer.nextSpan()
|
||||
.name("payment.processing")
|
||||
.tag("payment.method", request.getMethod())
|
||||
.tag("payment.amount", String.valueOf(request.getAmount()))
|
||||
.start();
|
||||
|
||||
try (Tracer.SpanInScope ws = tracer.withSpanInScope(span)) {
|
||||
// Add events
|
||||
span.event("payment.validation.started");
|
||||
validatePayment(request);
|
||||
span.event("payment.validation.completed");
|
||||
|
||||
span.event("payment.processing.started");
|
||||
PaymentResult result = processPaymentInternal(request);
|
||||
span.event("payment.processing.completed");
|
||||
|
||||
// Add result information
|
||||
span.tag("payment.status", result.getStatus());
|
||||
return result;
|
||||
} catch (Exception ex) {
|
||||
span.tag("error", ex.getMessage());
|
||||
throw ex;
|
||||
} finally {
|
||||
span.end();
|
||||
}
|
||||
}
|
||||
|
||||
private void validatePayment(PaymentRequest request) {
|
||||
// Validation logic
|
||||
}
|
||||
|
||||
private PaymentResult processPaymentInternal(PaymentRequest request) {
|
||||
// Processing logic
|
||||
return new PaymentResult();
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Baggage
|
||||
|
||||
Baggage allows you to pass context information across service boundaries:
|
||||
|
||||
```java
|
||||
@Service
|
||||
public class UserService {
|
||||
|
||||
private final BaggageManager baggageManager;
|
||||
|
||||
public UserService(BaggageManager baggageManager) {
|
||||
this.baggageManager = baggageManager;
|
||||
}
|
||||
|
||||
public User getCurrentUser(String userId) {
|
||||
// Set baggage that will be propagated to downstream services
|
||||
try (BaggageInScope baggageInScope =
|
||||
baggageManager.createBaggage("user.id", userId).makeCurrent()) {
|
||||
|
||||
return fetchUserFromDatabase(userId);
|
||||
}
|
||||
}
|
||||
|
||||
private User fetchUserFromDatabase(String userId) {
|
||||
// This method and any downstream calls will have access to the baggage
|
||||
String currentUserId = baggageManager.getBaggage("user.id").get();
|
||||
// Use the user ID for security context, logging, etc.
|
||||
return userRepository.findById(userId);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## HTTP Client Tracing
|
||||
|
||||
### WebClient Tracing
|
||||
|
||||
Spring Boot automatically configures tracing for WebClient:
|
||||
|
||||
```java
|
||||
@Service
|
||||
public class ExternalApiService {
|
||||
|
||||
private final WebClient webClient;
|
||||
|
||||
public ExternalApiService(WebClient.Builder webClientBuilder) {
|
||||
this.webClient = webClientBuilder
|
||||
.baseUrl("https://api.example.com")
|
||||
.build();
|
||||
}
|
||||
|
||||
public ApiResponse callExternalApi(String data) {
|
||||
return webClient
|
||||
.post()
|
||||
.uri("/process")
|
||||
.bodyValue(data)
|
||||
.retrieve()
|
||||
.bodyToMono(ApiResponse.class)
|
||||
.block();
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### RestTemplate Tracing
|
||||
|
||||
For RestTemplate, add the interceptor manually:
|
||||
|
||||
```java
|
||||
@Configuration
|
||||
public class RestTemplateConfig {
|
||||
|
||||
@Bean
|
||||
public RestTemplate restTemplate(RestTemplateBuilder builder) {
|
||||
return builder
|
||||
.interceptors(new TraceRestTemplateInterceptor())
|
||||
.build();
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Database Tracing
|
||||
|
||||
### JPA/Hibernate Tracing
|
||||
|
||||
Enable SQL tracing with additional configuration:
|
||||
|
||||
```yaml
|
||||
spring:
|
||||
jpa:
|
||||
properties:
|
||||
hibernate:
|
||||
generate_statistics: true
|
||||
session:
|
||||
events:
|
||||
log:
|
||||
LOG_QUERIES_SLOWER_THAN_MS: 25
|
||||
|
||||
management:
|
||||
tracing:
|
||||
enabled: true
|
||||
metrics:
|
||||
distribution:
|
||||
percentiles-histogram:
|
||||
http.server.requests: true
|
||||
```
|
||||
|
||||
### Custom Database Observation
|
||||
|
||||
```java
|
||||
@Repository
|
||||
public class UserRepository {
|
||||
|
||||
private final JdbcTemplate jdbcTemplate;
|
||||
private final ObservationRegistry observationRegistry;
|
||||
|
||||
public UserRepository(JdbcTemplate jdbcTemplate,
|
||||
ObservationRegistry observationRegistry) {
|
||||
this.jdbcTemplate = jdbcTemplate;
|
||||
this.observationRegistry = observationRegistry;
|
||||
}
|
||||
|
||||
public User findById(Long id) {
|
||||
return Observation.createNotStarted("db.user.find-by-id", observationRegistry)
|
||||
.lowCardinalityKeyValue("db.operation", "select")
|
||||
.lowCardinalityKeyValue("db.table", "users")
|
||||
.observe(() -> {
|
||||
String sql = "SELECT * FROM users WHERE id = ?";
|
||||
return jdbcTemplate.queryForObject(sql,
|
||||
new UserRowMapper(), id);
|
||||
});
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Async Processing Tracing
|
||||
|
||||
### @Async Methods
|
||||
|
||||
```java
|
||||
@Service
|
||||
public class NotificationService {
|
||||
|
||||
@Async
|
||||
@Observed(name = "notification.send")
|
||||
public CompletableFuture<Void> sendNotificationAsync(String recipient, String message) {
|
||||
// Async notification logic
|
||||
return CompletableFuture.completedFuture(null);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Manual Trace Propagation
|
||||
|
||||
```java
|
||||
@Service
|
||||
public class EmailService {
|
||||
|
||||
private final Tracer tracer;
|
||||
private final ExecutorService executorService;
|
||||
|
||||
public EmailService(Tracer tracer) {
|
||||
this.tracer = tracer;
|
||||
this.executorService = Executors.newFixedThreadPool(5);
|
||||
}
|
||||
|
||||
public void sendEmailAsync(String recipient, String subject, String body) {
|
||||
TraceContext traceContext = tracer.currentSpan().context();
|
||||
|
||||
executorService.submit(() -> {
|
||||
try (Tracer.SpanInScope ws = tracer.withSpanInScope(
|
||||
tracer.toSpan(traceContext))) {
|
||||
Span span = tracer.nextSpan()
|
||||
.name("email.send")
|
||||
.tag("email.recipient", recipient)
|
||||
.start();
|
||||
|
||||
try (Tracer.SpanInScope emailScope = tracer.withSpanInScope(span)) {
|
||||
// Send email logic
|
||||
sendEmailInternal(recipient, subject, body);
|
||||
} finally {
|
||||
span.end();
|
||||
}
|
||||
}
|
||||
});
|
||||
}
|
||||
|
||||
private void sendEmailInternal(String recipient, String subject, String body) {
|
||||
// Email sending implementation
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Production Configuration
|
||||
|
||||
### Performance Optimizations
|
||||
|
||||
```yaml
|
||||
management:
|
||||
tracing:
|
||||
sampling:
|
||||
probability: 0.01 # Sample 1% in production
|
||||
rate: 1000 # Max 1000 traces per second
|
||||
baggage:
|
||||
enabled: false # Disable if not needed
|
||||
remote-fields: []
|
||||
zipkin:
|
||||
tracing:
|
||||
endpoint: "${ZIPKIN_ENDPOINT:http://zipkin:9411/api/v2/spans}"
|
||||
timeout: 1s
|
||||
connect-timeout: 1s
|
||||
|
||||
# Optimize logging for performance
|
||||
logging:
|
||||
pattern:
|
||||
level: "%5p [%X{traceId:-},%X{spanId:-}]"
|
||||
level:
|
||||
io.micrometer.tracing: WARN
|
||||
org.springframework.web.servlet.mvc.method.annotation: WARN
|
||||
```
|
||||
|
||||
### Security Considerations
|
||||
|
||||
```yaml
|
||||
management:
|
||||
endpoints:
|
||||
web:
|
||||
exposure:
|
||||
include: "health,info,metrics"
|
||||
exclude: "trace" # Don't expose trace endpoint
|
||||
endpoint:
|
||||
trace:
|
||||
enabled: false
|
||||
tracing:
|
||||
baggage:
|
||||
correlation:
|
||||
enabled: false # Disable MDC correlation if sensitive data
|
||||
remote-fields: [] # Don't propagate sensitive fields
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
1. **No traces appearing**: Check sampling probability and endpoint configuration
|
||||
2. **High overhead**: Reduce sampling probability or disable baggage
|
||||
3. **Missing spans**: Ensure proper dependency injection of ObservationRegistry
|
||||
4. **Broken trace context**: Check async processing and thread boundaries
|
||||
|
||||
### Debug Configuration
|
||||
|
||||
```yaml
|
||||
logging:
|
||||
level:
|
||||
io.micrometer.tracing: DEBUG
|
||||
io.opentelemetry: DEBUG
|
||||
brave: DEBUG
|
||||
zipkin2: DEBUG
|
||||
|
||||
management:
|
||||
tracing:
|
||||
sampling:
|
||||
probability: 1.0 # Sample everything for debugging
|
||||
```
|
||||
|
||||
### Health Check for Tracing
|
||||
|
||||
```java
|
||||
@Component
|
||||
public class TracingHealthIndicator implements HealthIndicator {
|
||||
|
||||
private final Tracer tracer;
|
||||
|
||||
public TracingHealthIndicator(Tracer tracer) {
|
||||
this.tracer = tracer;
|
||||
}
|
||||
|
||||
@Override
|
||||
public Health health() {
|
||||
try {
|
||||
Span span = tracer.nextSpan().name("health.check.tracing").start();
|
||||
span.end();
|
||||
return Health.up()
|
||||
.withDetail("tracer", tracer.getClass().getSimpleName())
|
||||
.build();
|
||||
} catch (Exception ex) {
|
||||
return Health.down()
|
||||
.withDetail("error", ex.getMessage())
|
||||
.build();
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Sampling Strategy**: Use lower sampling rates in production (1-10%)
|
||||
2. **Span Naming**: Use consistent, meaningful span names with low cardinality
|
||||
3. **Tag Strategy**: Add meaningful tags but avoid high-cardinality values
|
||||
4. **Error Handling**: Always properly handle and tag errors in spans
|
||||
5. **Performance**: Monitor the overhead of tracing in production
|
||||
6. **Security**: Be careful not to include sensitive data in span tags or baggage
|
||||
7. **Correlation**: Use correlation IDs to link traces across service boundaries
|
||||
8. **Testing**: Include tracing in your testing strategy with TestObservationRegistry
|
||||
Reference in New Issue
Block a user