Ứng dụng Spring Boot của bạn chạy trên production, health check trả 200, và bạn tin mọi thứ ổn — cho đến khi người dùng báo timeout. Một endpoint health chỉ nói tiến trình còn sống, không nói nó có làm được việc hay không. Spring Boot Actuator trên Boot 4.1.2 cung cấp phần còn lại: trạng thái theo nhóm, số liệu Micrometer, và cấu hình runtime có kiểm soát.
Bài này đi từ một dependency duy nhất đến health group cho Kubernetes, metric tự viết và lớp bảo vệ endpoint. Code dùng Boot 4.1.2, Framework 7.0.10, Java 25 LTS.
Mục lục
Cập nhật 2026
- Boot 4.1.2, Actuator module hóa. Starter giữ nguyên tên, nhưng kéo thêm module
spring-boot-healthvàspring-boot-micrometer-metrics. Endpoint ID và property không đổi; không có endpoint mới. - Package của API đổi chỗ.
HealthIndicatorvàHealthgiờ ởorg.springframework.boot.health.contributor;EndpointRequestởorg.springframework.boot.security.autoconfigure.actuate.web.servlet. Code copy từ Boot 3 sẽ không biên dịch. - Mặc định chỉ
healthđược expose qua HTTP. Bản cũ nói health và info; thực tế chỉ health, bạn phải tự thêminfo,metrics,prometheus. - Đo lường và tracing không đổi hướng. Micrometer 1.17.2 do Boot quản lý; Prometheus vẫn qua
micrometer-registry-prometheus. Micrometer Tracing 1.7.2 thay Sleuth.
Actuator: endpoint, exposure và access là ba thứ khác nhau
Actuator là tập endpoint quản trị được auto-configure khi starter có trên classpath. Mỗi endpoint có một ID (health, metrics, env, …) và có thể được phơi ra qua HTTP, JMX, hoặc cả hai. Endpoint không phải controller nghiệp vụ: nó là adapter mỏng trên một đối tượng đọc trạng thái ứng dụng.
Ba lớp cấu hình dễ bị nhầm. Enable quyết định endpoint có tồn tại trong ứng dụng. Exposure quyết định nó có xuất hiện trên giao thức nào. Access quyết định người gọi được đọc, ghi hay không. Mặc định, phần lớn endpoint có access unrestricted, nhưng chỉ health được expose qua HTTP; shutdown và heapdump bị hạn chế chặt hơn. Vì vậy expose không đồng nghĩa công khai; endpoint bị ẩn vẫn gọi được qua JMX nếu JMX còn bật.
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-actuator</artifactId>
</dependency>
Chạy ứng dụng rồi gọi GET /actuator/health, bạn nhận về {"status":"UP"}. Chi tiết từng thành phần bị ẩn mặc định; bật bằng management.endpoint.health.show-details. Nếu endpoint trả 404, kiểm tra: starter có trong runtime classpath, ID có trong danh sách exposure, và base path có bị đổi không.
Endpoint nào trả lời câu hỏi nào
| Endpoint | Cho biết gì | Ghi chú dùng thực tế |
|---|---|---|
health |
Tổng hợp trạng thái các HealthContributor |
Mặc định chỉ trả status; probe Kubernetes dùng các nhóm con |
info |
Thông tin build, Git, metadata tự khai | Rỗng nếu bạn không cấu hình info.* hoặc build-info |
metrics |
Danh sách meter và giá trị hiện tại | Dùng để điều tra một metric cụ thể, không phải để scrape |
env |
Property source và giá trị cấu hình | Giá trị bị che mặc định; đây là dữ liệu nhạy cảm |
beans |
Toàn bộ bean trong context | Debug thiếu bean hoặc sai scope; output rất lớn |
conditions |
Điều kiện auto-config khớp hay không | Trả lời “vì sao auto-config không chạy” |
mappings |
Mapping URL của MVC và Actuator | Dùng khi request trả 404 hoặc 405 |
threaddump |
Stack của tất cả thread | Chụp vài lần để tìm deadlock |
heapdump |
File heap (HPROF trên HotSpot) | Nhị phân, có thể rất lớn; không bao giờ để công khai |
loggers |
Cấp log hiện tại của từng logger | GET để xem, POST để đổi mức log lúc runtime |
prometheus |
Định dạng scrape của Prometheus | Chỉ có khi registry Prometheus trên classpath |
conditions là endpoint đáng học nhất trong nhóm debug. Nó liệt kê positive và negative matches của từng auto-config, kèm lý do. Khi một bean không xuất hiện, nơi này trả lời nhanh hơn đọc lại cấu hình; cơ chế bên dưới nằm ở Spring Boot Autoconfiguration.
beans, mappings và env hữu ích khi phát triển, nhưng phơi cấu trúc nội bộ. env che giá trị mặc định (management.endpoint.env.show-values=never); đặt thành always biến endpoint này thành bản dump secret. threaddump lộ tên lớp và đôi khi tham số trong stack. heapdump chứa cả bộ nhớ, gồm token và mật khẩu trong object.
loggers là endpoint duy nhất trong bảng bạn có thể ghi khi ứng dụng đang chạy. Gọi GET /actuator/loggers/com.example.shop.service để xem mức hiện tại, rồi POST cùng path với body {"configuredLevel":"DEBUG"}. Đây là công cụ điều tra tạm thời, không phải cấu hình lâu dài.
Expose có chọn lọc, đổi base path, tách cổng quản trị
management:
endpoints:
web:
base-path: /actuator
exposure:
include: health,info,metrics,prometheus
exclude: env,beans
server:
port: 8081 # bỏ dòng này nếu management dùng chung cổng 8080
include là danh sách trắng, exclude thắng khi một ID xuất hiện ở cả hai. Dùng * để chọn tất cả rồi trừ đi những gì nguy hiểm; đừng dùng * một mình trên production. Danh sách trên đủ cho dịch vụ có Prometheus scrape: health cho probe, info cho version, metrics để điều tra, prometheus cho pipeline — không có env, beans, heapdump.
management.endpoints.web.base-path đổi tiền tố, mặc định /actuator. Đổi sang /manage chỉ làm URL khó đoán hơn, không phải biện pháp bảo mật. Nếu tách cổng bằng management.server.port, endpoint chạy trên management context riêng, không dùng chung Tomcat connector và thread pool với ứng dụng. Cách này cho firewall chỉ mở 8081 cho mạng monitoring, nhưng probe trên cổng quản trị có thể UP trong khi app chính hỏng — lý do để đặt probe ở cổng chính.
Health group, probe Kubernetes và chỉ báo tự viết
/actuator/health tổng hợp trạng thái từ các chỉ báo: disk space, datasource, Redis, Kafka, và các chỉ báo bạn tự viết. Mỗi chỉ báo trả UP, DOWN, OUT_OF_SERVICE hoặc UNKNOWN; trạng thái tổng hợp lấy mức nghiêm trọng nhất. Chi tiết chỉ hiện khi show-details cho phép, và when-authorized chỉ hiện cho người đã xác thực.
management:
endpoint:
health:
show-details: when-authorized
probes:
enabled: true
group:
readiness:
include: readinessState,db # thêm db vào readiness
liveness:
include: livenessState # không thêm db vào liveness
Với probe Kubernetes, Boot 4.1 bật sẵn hai nhóm liveness và readiness, ánh xạ qua LivenessStateHealthIndicator và ReadinessStateHealthIndicator. Đường dẫn là /actuator/health/liveness và /actuator/health/readiness. Bật thêm đường dẫn trên cổng chính bằng management.endpoint.health.probes.add-additional-paths=true; khi đó chúng có ở /livez và /readyz. Nếu management ở cổng riêng, trỏ probe đúng cổng đó.
Liveness không được kiểm tra database. Liveness trả lời “tiến trình còn sống và có thể tiến triển không”; nếu nó phụ thuộc DB, một lần DB chậm sẽ khiến Kubernetes restart toàn bộ pod, biến sự cố phụ thuộc thành vòng lặp khởi động. Readiness mới là nơi đặt phụ thuộc cần để phục vụ traffic, nhưng vẫn cần timeout ngắn và cache; đừng gọi DB mỗi lần probe.
Nhóm tùy chỉnh dùng cùng cơ chế: management.endpoint.health.group.custom.include=db tạo /actuator/health/custom. Tên chỉ báo sai làm ứng dụng fail lúc khởi động; để nguyên validate-group-membership=true. Nhóm cũng hỗ trợ exclude, show-details, roles và additional-path.
Một HealthIndicator tối thiểu
// File: src/main/java/com/example/shop/health/InventoryHealthIndicator.java
package com.example.shop.health;
import org.springframework.boot.health.contributor.Health;
import org.springframework.boot.health.contributor.HealthIndicator;
import org.springframework.stereotype.Component;
@Component("inventory")
public class InventoryHealthIndicator implements HealthIndicator {
private final InventoryClient client;
public InventoryHealthIndicator(InventoryClient client) {
this.client = client;
}
@Override
public Health health() {
try {
int backlog = client.backlog();
if (backlog < 500) {
return Health.up().withDetail("backlog", backlog).build();
}
return Health.down().withDetail("backlog", backlog).build();
} catch (Exception ex) {
return Health.down().withDetail("error", ex.getClass().getSimpleName()).build();
}
}
}
ID của chỉ báo là tên bean bỏ hậu tố HealthIndicator; đặt tên bean inventory để group tham chiếu không mơ hồ. Chỉ báo chạy đồng bộ trong request health: mọi lời gọi mạng phải có timeout ngắn, và cache kết quả nếu phép kiểm tra đắt.
Micrometer: metric do bạn định nghĩa
Boot auto-configure MeterRegistry tổng hợp và thêm registry cho từng implementation trên classpath. Inject nó để đăng ký counter, timer, gauge. Đặt tên theo miền nghiệp vụ và giữ bộ tag nhỏ.
// File: src/main/java/com/example/shop/metrics/CheckoutMetrics.java
package com.example.shop.metrics;
import java.util.concurrent.TimeUnit;
import io.micrometer.core.instrument.Counter;
import io.micrometer.core.instrument.MeterRegistry;
import io.micrometer.core.instrument.Timer;
import org.springframework.stereotype.Component;
@Component
public class CheckoutMetrics {
private final Counter paid;
private final Timer duration;
public CheckoutMetrics(MeterRegistry registry) {
this.paid = Counter.builder("checkout.paid")
.description("Số lần thanh toán thành công")
.tag("channel", "web")
.register(registry);
this.duration = Timer.builder("checkout.duration")
.description("Thời gian xử lý checkout")
.tag("channel", "web")
.publishPercentileHistogram()
.register(registry);
}
public void recordSuccess(long nanos) {
paid.increment();
duration.record(nanos, TimeUnit.NANOSECONDS);
}
}
Timer có sẵn count, total time, max; publishPercentileHistogram() thêm bucket để Prometheus tính percentile. Chỉ bật cho timer thật sự cần, vì mỗi bucket là một series. Với Prometheus, thêm registry vào runtime classpath:
<dependency>
<groupId>io.micrometer</groupId>
<artifactId>micrometer-registry-prometheus</artifactId>
<scope>runtime</scope>
</dependency>
Version do Boot BOM quản lý. Endpoint /actuator/prometheus chỉ có khi registry trên classpath và prometheus nằm trong exposure. Prometheus scrape /actuator/prometheus; Grafana chỉ hiển thị.
Tag chung khai báo một lần cho mọi meter:
management:
metrics:
tags:
application: shop-api
env: prod
management.metrics.tags.* áp cho toàn bộ meter, kể cả http.server.requests do Boot tự tạo. Chỉ dùng giá trị hữu hạn, ổn định. Dùng management.metrics.enable.* để lọc meter theo tiền tố.
Bảo mật Actuator: mặc định chỉ là điểm khởi đầu
Nếu Spring Security có trên classpath và bạn chưa khai báo SecurityFilterChain nào, auto-config của Boot bảo vệ mọi Actuator endpoint trừ health. Ngay khi bạn thêm một chain tùy chỉnh, auto-config lùi hoàn toàn và bạn phải tự viết quy tắc — kể cả quy tắc cho phần còn lại của ứng dụng. Đây là lý do phổ biến khiến Actuator vô tình mở công khai sau khi thêm cấu hình bảo mật.
// File: src/main/java/com/example/shop/config/ActuatorSecurityConfig.java
package com.example.shop.config;
import org.springframework.boot.security.autoconfigure.actuate.web.servlet.EndpointRequest;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.annotation.Order;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.web.SecurityFilterChain;
import static org.springframework.security.config.Customizer.withDefaults;
@Configuration(proxyBeanMethods = false)
public class ActuatorSecurityConfig {
@Bean
@Order(1)
SecurityFilterChain actuatorChain(HttpSecurity http) throws Exception {
http.securityMatcher(EndpointRequest.toAnyEndpoint())
.authorizeHttpRequests((requests) -> requests
.requestMatchers(EndpointRequest.to("health")).permitAll()
.anyRequest().hasRole("ACTUATOR"))
.httpBasic(withDefaults());
return http.build();
}
@Bean
@Order(2)
SecurityFilterChain appChain(HttpSecurity http) throws Exception {
http.authorizeHttpRequests((requests) -> requests.anyRequest().authenticated())
.formLogin(withDefaults());
return http.build();
}
}
EndpointRequest.to("health") khớp cả các nhóm con như liveness và readiness, nên probe vẫn gọi được mà không cần token. Các endpoint khác yêu cầu role ACTUATOR, tương ứng authority ROLE_ACTUATOR. Cổng quản trị riêng chỉ giảm bề mặt tấn công; firewall và network policy vẫn cần.
CSRF bật mặc định, nên POST /actuator/loggers từ script sẽ nhận 403. Chỉ tắt CSRF cho chain Actuator khi client không phải browser và đã có xác thực mạnh. Với env, đừng bật show-values=always; dùng management.endpoint.env.roles nếu cần.
Tracing: Sleuth đã dừng, Micrometer Tracing tiếp quản
Spring Cloud Sleuth đã archive; dòng cuối 3.1 không hỗ trợ Boot 3 trở lên và không có bản vá. Micrometer Tracing 1.7.2 là successor: facade trên Brave hoặc OpenTelemetry, tự lan truyền trace/span ID qua RestClient và WebClient do Boot dựng. Boot lấy mẫu 10% mặc định; đổi bằng management.tracing.sampling.probability, nhưng đừng đặt 1.0 trên production chỉ vì muốn thấy đủ trace. Actuator và tracing gặp nhau ở observation: cùng một lời gọi HTTP vừa tạo timer, vừa tạo span. Phần này được đào sâu ở bài tracing xuyên dịch vụ.
Bốn lỗi biến Actuator thành sự cố
Expose env hoặc heapdump ra ngoài. Đây là hai endpoint nguy hiểm nhất. env lộ cấu hình, heapdump lộ toàn bộ bộ nhớ gồm credential đang dùng. Kể cả đã có xác thực, chỉ mở trong mạng quản trị; đừng đặt sau reverse proxy công khai.
Để liveness kiểm tra database. Một dependency chậm làm mọi pod bị restart, rồi chính việc restart làm dependency quá tải. Liveness chỉ nên kiểm tra tiến trình và khả năng tiến triển; DB thuộc readiness, với timeout và cache. Với ứng dụng khởi động lâu, dùng startupProbe thay vì nới failureThreshold của liveness.
Tag có cardinality cao. Gắn userId, orderId hay raw URL vào counter tạo ra hàng triệu series, làm Prometheus chậm và tốn bộ nhớ. Chỉ dùng tag có tập giá trị hữu hạn; với URI, Boot chuẩn hóa theo path template và giới hạn 100 giá trị qua management.metrics.web.server.max-uri-tags. Cần phân tích theo user thì dùng log hoặc trace, không dùng metric.
Dùng Actuator như admin console. Đổi log level bằng tay, sửa cấu hình qua env, gọi shutdown, hay coi metrics là dashboard chỉ hợp trong môi trường phát triển. Trên production, cấu hình đi qua pipeline, log level qua config có version, tắt dịch vụ qua orchestrator. Actuator để quan sát, không để vận hành bằng tay.
Nhìn trước 2027
Boot 4.2 đang ở RC2; hướng đi là module hóa sâu hơn và OpenTelemetry là lựa chọn chính cho tracing, còn endpoint ID và property Actuator giữ ổn định. Không có API mới, nên đầu tư đúng là exposure, health group và metric có tên tốt.
Checklist trước khi lên production
- Exposure chỉ gồm
health,info,metrics,prometheus;env,beans,heapdump,shutdownbị loại. - Liveness chỉ dùng
livenessState; readiness có dependency cần thiết nhưng có timeout và cache. show-detailslàwhen-authorizedhoặcnever, không phảialways.- Metric mới có tên nghiệp vụ, tag hữu hạn; đã kiểm tra số series trên Prometheus.
- Actuator có chain bảo mật riêng, probe được phép, POST được bảo vệ CSRF hoặc chỉ gọi từ client tin cậy.
- Đã scrape
/actuator/prometheustừ đúng network và dashboard nhận dữ liệu.
Đọc tiếp trong series
Cách starter kéo dependency ở Spring Boot Starters. Toàn bộ thứ tự bài học ở Spring Boot Roadmap.



