spring actuator - 启用 Production-ready Features
依赖方式：
<dependencies>
<dependency>
<groupid>org.springframework.boot</groupid>
<artifactid>spring-boot-starter-actuator</artifactid>
</dependency>
</dependencies>
Endpoint
Actuator endpoints 让您监控 application 并与之交互。 Spring Boot 包含许多 built-in endpoints 并允许您添加自己的。例如，health端点提供基本的 application 健康信息。
每个端点都可以是启用或禁用。它控制是否在 application context 中创建端点并且其 bean 是否存在。要远程访问，端点也必须是通过 JMX 或 HTTP 公开。大多数 applications 选择 HTTP，其中端点的 ID 以及/actuator的前缀映射到 URL。对于 example，默认情况下，health端点映射到/actuator/health。
以下 technology-agnostic endpoints 可用：
| ID | 描述 | 默认情况下启用 |
|---|---|---|
auditevents |
公开当前 application 的 audit events 信息。 | 是 |
beans |
显示 application 中所有 Spring beans 的完整列表。 | 是 |
caches |
暴露可用的缓存。 | 是 |
conditions |
显示在 configuration 和 auto-configuration classes 上评估的条件以及它们执行或不执行 match 的原因。 | 是 |
configprops |
显示所有@ConfigurationProperties的整理列表。 |
是 |
env |
从 Spring 的ConfigurableEnvironment公开 properties。 |
是 |
flyway |
显示已应用的任何 Flyway 数据库迁移。 | 是 |
health |
显示 application 健康信息。 | 是 |
httptrace |
显示 HTTP 跟踪信息(默认情况下，最后 100 个 HTTP request-response 交换)。 | 是 |
info |
显示任意 application 信息。 | 是 |
integrationgraph |
显示 Spring Integration 图。 | 是 |
loggers |
显示并修改 application 中 loggers 的 configuration。 | 是 |
liquibase |
显示已应用的任何 Liquibase 数据库迁移。 | 是 |
metrics |
显示当前 application 的'metrics'信息。 | 是 |
mappings |
显示所有@RequestMapping paths 的整理列表。 |
是 |
scheduledtasks |
显示 application 中的计划任务。 | 是 |
sessions |
允许从 Spring Session-backed session store 中检索和删除用户会话。使用 Spring Session 支持 reactive web applications 时不可用。 | 是 |
shutdown |
让 application 正常关闭。 | 没有 |
threaddump |
执行线程转储。 | 是 |
如果 application 是 web application(Spring MVC，Spring WebFlux 或 Jersey)，则可以使用以下附加 endpoints：
| ID | 描述 | 默认情况下启用 |
|---|---|---|
heapdump |
返回hprof堆转储文件。 |
是 |
jolokia |
通过 HTTP 公开 JMX beans(当 Jolokia 在 classpath 上时，不适用于 WebFlux)。 | 是 |
logfile |
返回日志文件的内容(如果已设置logging.file或logging.path properties)。支持使用 HTTP Range标头来检索 log 文件内容的一部分。 |
是 |
prometheus |
以 Prometheus 服务器可以抓取的格式公开 metrics。 | 是 |
要了解有关 Actuator 的 endpoints 及其请求和响应格式的更多信息，请参阅单独的 API 文档(HTML或PDF)。
启用 Endpoints
默认情况下，启用除shutdown之外的所有 endpoints。要配置端点的启用，请使用其management.endpoint.<id>.enabled property。以下 example 启用shutdown端点：
management.endpoint.shutdown.enabled=true
如果您希望端点启用为 opt-in 而不是 opt-out，请将management.endpoints.enabled-by-default property 设置为false并使用单个端点enabled properties 重新加入。以下 example 启用info端点并禁用所有其他 endpoints：
management.endpoints.enabled-by-default=false
management.endpoint.info.enabled=true
> 已禁用 endpoints 完全从 application context 中删除。如果只想更改端点所暴露的技术，请改用包含和排除 properties。
暴露 Endpoints
由于 Endpoints 可能包含敏感信息，因此应仔细考虑何时公开它们。以下 table 显示 built-in endpoints 的默认曝光：
| ID | JMX | Web |
|---|---|---|
auditevents |
是 | 没有 |
beans |
是 | 没有 |
caches |
是 | 没有 |
conditions |
是 | 没有 |
configprops |
是 | 没有 |
env |
是 | 没有 |
flyway |
是 | 没有 |
health |
是 | 是 |
heapdump |
N/A | 没有 |
httptrace |
是 | 没有 |
info |
是 | 是 |
integrationgraph |
是 | 没有 |
jolokia |
N/A | 没有 |
logfile |
N/A | 没有 |
loggers |
是 | 没有 |
liquibase |
是 | 没有 |
metrics |
是 | 没有 |
mappings |
是 | 没有 |
prometheus |
N/A | 没有 |
scheduledtasks |
是 | 没有 |
sessions |
是 | 没有 |
shutdown |
是 | 没有 |
threaddump |
是 | 没有 |
要更改公开的 endpoints，请使用以下 technology-specific include和exclude properties：
| 属性 | 默认 |
|---|---|
management.endpoints.jmx.exposure.exclude |
|
management.endpoints.jmx.exposure.include |
* |
management.endpoints.web.exposure.exclude |
|
management.endpoints.web.exposure.include |
info, health |
include property 列出公开的 endpoints 的 ID。 exclude property 列出不应公开的 endpoints 的 ID。 exclude property 优先于include property。 include和exclude properties 都可以配置端点 ID 列表。
对于 example，要停止通过 JMX 公开所有 endpoints 并仅显示health和info endpoints，请使用以下 property：
management.endpoints.jmx.exposure.include=health,info
*可用于选择所有 endpoints。对于 example，要通过 HTTP 公开除env和beans endpoints 之外的所有内容，请使用以下 properties：
management.endpoints.web.exposure.include=*
management.endpoints.web.exposure.exclude=env,beans
> *在 YAML 中有特殊含义，因此如果要包含(或排除)所有 endpoints，请务必添加引号，如下面的示例所示：
management:
endpoints:
web:
exposure:
include: "*"
> 如果您的 application 公开曝光，我们强烈建议您也保护你的 endpoints。
> 如果要在公开 endpoints 时实现自己的策略，可以注册EndpointFilter bean。
保护 HTTP Endpoints
应该像处理任何其他敏感 URL 一样注意保护 HTTP endpoints。如果存在 Spring Security，则默认使用 Spring Security 的 content-negotiation 策略保护 endpoints。如果您希望为 HTTP endpoints 配置自定义安全性，对于 example，只允许具有特定角色的用户访问它们，Spring Boot 提供了一些方便的RequestMatcher objects，可以与 Spring Security 结合使用。
典型的 Spring Security configuration 可能类似于以下 example：
@Configuration
public class ActuatorSecurity extends WebSecurityConfigurerAdapter {
@Override
protected void configure(HttpSecurity http) throws Exception {
http.requestMatcher(EndpointRequest.toAnyEndpoint()).authorizeRequests()
.anyRequest().hasRole("ENDPOINT_ADMIN")
.and()
.httpBasic();
}
}
前面的 example 使用EndpointRequest.toAnyEndpoint()来匹配任何端点的请求，然后确保所有端点都具有ENDPOINT_ADMIN角色。其他几种匹配方法也可以在EndpointRequest上找到。有关详细信息，请参阅 API 文档(HTML或PDF)。
如果在防火墙后部署 applications，您可能希望无需身份验证即可访问所有 actuator endpoints。您可以通过更改management.endpoints.web.exposure.include property 来执行此操作，如下所示：
application.properties.
management.endpoints.web.exposure.include=*
此外，如果存在 Spring Security，则需要添加自定义安全性 configuration，以允许对 endpoints 进行未经身份验证的访问，如下面的示例所示：
@Configuration
public class ActuatorSecurity extends WebSecurityConfigurerAdapter {
@Override
protected void configure(HttpSecurity http) throws Exception {
http.requestMatcher(EndpointRequest.toAnyEndpoint()).authorizeRequests()
.anyRequest().permitAll();
}
}
配置 Endpoints
Endpoints 自动缓存对不带任何参数的读取操作的响应。要配置端点将缓存响应的 time 数量，请使用其cache.time-to-live property。以下 example 将beans端点缓存的 time-to-live 设置为 10 秒：
application.properties.
management.endpoint.beans.cache.time-to-live=10s
> 前缀management.endpoint.<name>用于唯一标识正在配置的端点。
> 在进行经过身份验证的 HTTP 请求时，Principal被视为端点的输入，因此不会缓存响应。
CORS 支持
Cross-origin 资源共享(CORS)是一个W3C 规范，它允许您以灵活的方式指定哪种 cross-domain 请求被授权。如果您使用 Spring MVC 或 Spring WebFlux，则可以配置 Actuator 的 web endpoints 以支持此类方案。
默认情况下禁用 CORS 支持，仅在设置了management.endpoints.web.cors.allowed-origins property 后才启用 CORS 支持。以下 configuration 允许来自example.com域的GET和POST calls：
management.endpoints.web.cors.allowed-origins=http://example.com
management.endpoints.web.cors.allowed-methods=GET,POST
> 有关选项的完整列表，请参见CorsEndpointProperties。
健康信息
可以使用运行状况信息来检查 running application 的状态。当生产系统出现故障时，监控软件通常会使用它来提醒某人。 health端点公开的信息取决于management.endpoint.health.show-details property，可以使用以下值之一配置：
| 名称 | 描述 |
|---|---|
never |
细节永远不会显示。 |
when-authorized |
详细信息仅向授权用户显示。可以使用management.endpoint.health.roles配置授权角色。 |
always |
向所有用户显示详细信息。 |
默认的 value 是never。
健康信息是从HealthIndicatorRegistry的内容中收集的(默认情况下ApplicationContext中定义的所有HealthIndicator个实例.Spring Boot 包含一些 auto-configured HealthIndicators，您也可以编写自己的。默认情况下，最终系统 state 是由HealthAggregator派生的根据状态的有序列表对每个HealthIndicator的状态进行排序。排序列表中的第一个状态用作整体健康状态。如果没有HealthIndicator返回HealthAggregator已知的状态，则使用UNKNOWN状态。
> HealthIndicatorRegistry可用于在运行时注册和取消注册健康指示器。
编写自定义 HealthIndicators
要提供自定义运行状况信息，可以注册实现HealthIndicator接口的 Spring beans。您需要提供health()方法的 implementation 并_return Health响应。 Health响应应包含状态，并可选择包含要显示的其他详细信息。以下 code 显示 sample HealthIndicator implementation：
import org.springframework.boot.actuate.health.Health;
import org.springframework.boot.actuate.health.HealthIndicator;
import org.springframework.stereotype.Component;
@Component
public class MyHealthIndicator implements HealthIndicator {
@Override
public Health health() {
int errorCode = check(); // perform some specific health check
if (errorCode != 0) {
return Health.down().withDetail("Error Code", errorCode).build();
}
return Health.up().build();
}
}
除了 Spring Boot 的预定义状态类型之外，Health还可以 return 表示新系统 state 的自定义Status。在这种情况下，还需要提供HealthAggregator接口的自定义 implementation，或者必须使用management.health.status.order configuration property 配置默认 implementation。
对于 example，假设在HealthIndicator implementations 之一中使用了带 code FATAL的新Status。要配置 severity order，请将以下 property 添加到 application properties：
management.health.status.order=FATAL, DOWN, OUT_OF_SERVICE, UNKNOWN, UP
响应中的 HTTP 状态 code 反映了整体运行状况(对于 example，UP maps 为 200，而OUT_OF_SERVICE和DOWN map 为 503)。如果通过 HTTP 访问运行状况端点，则可能还需要注册自定义状态映射。对于 example，以下 property maps FATAL到 503(服务不可用)：
management.health.status.http-mapping.FATAL=503
> 如果需要更多控制，可以定义自己的HealthStatusHttpMapper bean。
以下 table 显示 built-in 状态的默认状态映射：
| 状态 | 制图 |
|---|---|
| 下 | SERVICE_UNAVAILABLE(503) |
| OUT_OF_SERVICE | SERVICE_UNAVAILABLE(503) |
| UP | 默认情况下没有映射，因此 http 状态为 200 |
| 未知 | 默认情况下没有映射，因此 http 状态为 200 |
Application 信息
Application 信息公开从ApplicationContext中定义的所有InfoContributor beans 收集的各种信息。 Spring Boot 包含了许多 auto-configured InfoContributor beans，你可以编写自己的。
Auto-configured InfoContributors
在适当的情况下，Spring Boot 下面的InfoContributor beans 是 auto-configured：
| 名称 | 描述 |
|---|---|
| EnvironmentInfoContributor | 在info key 下公开Environment中的任何 key。 |
| GitInfoContributor | 如果git.properties文件可用，则公开 git 信息。 |
| BuildInfoContributor | 如果META-INF/build-info.properties文件可用，则公开 build 信息。 |
> 可以通过设置management.info.defaults.enabled property 来禁用它们。
自定义应用程序信息
您可以通过设置info.* Spring properties 来自定义info端点公开的数据。 info key 下的所有Environment properties 都会自动公开。例如，您可以将以下设置添加到application.properties文件中：
info.app.encoding=UTF-8
info.app.java.source=1.8
info.app.java.target=1.8
> 也可以在 build time 展开 info properties而不是硬编码这些值。
编写自定义 InfoContributors
要提供自定义 application 信息，可以注册实现InfoContributor接口的 Spring beans。
以下 example 使用单个 value 提供example条目：
import java.util.Collections;
import org.springframework.boot.actuate.info.Info;
import org.springframework.boot.actuate.info.InfoContributor;
import org.springframework.stereotype.Component;
@Component
public class ExampleInfoContributor implements InfoContributor {
@Override
public void contribute(Info.Builder builder) {
builder.withDetail("example",
Collections.singletonMap("key", "value"));
}
}
如果到达info端点，您应该看到包含以下附加条目的响应：
{
"example": {
"key" : "value"
}
}
Loggers
Spring Boot Actuator 包括在运行时查看和配置 application 的 log 级别的功能。您可以查看整个列表或单个 logger 的 configuration，它由显式配置的 logging level 以及 logging framework 给它的有效 logging level 组成。这些级别可以是以下之一：
TRACEDEBUGINFOWARNERRORFATALOFFnull
null表示没有明确的 configuration。
配置 Logger
要配置给定的 logger，POST是资源 URI 的部分实体，如下面的示例所示：
{
"configuredLevel": "DEBUG"
}
> 要**“重置”**logger 的特定 level(并使用默认的 configuration)，您可以传递的_val作为configuredLevel。
Metrics
Spring Boot Actuator 为micrometer提供了依赖管理 和自动配置，micrometer是一个支持众多监控系统的 application metrics 门面，包括：
- AppOptics
- Atlas
- Datadog
- Dynatrace
- Elastic
- Ganglia
- 石墨
- Humio
- Influx
- JMX
- KairosDB
- New Relic
- Prometheus
- SignalFx
- 简单(in-memory)
- StatsD
- Wavefront
> 要了解有关 Micrometer 功能的更多信息，请参阅其reference 文档，特别是概念部分。
支持的Metrics
Spring Boot 在适用时注册以下核心 metrics：
- JVM metrics，报告利用率：
- 各种 memory 和缓冲池
- 与垃圾收集有关的统计
- 线程利用率
- classes 数量 loaded/unloaded
- CPU metrics
- 文件描述符 metrics
- Kafka consumer metrics
- Log4j2 metrics：记录每个 level 记录到 Log4j2 的 events 的数量
- Logback metrics：记录每个 level 记录到 Logback 的 events 的数量
- 正常运行时间 metrics：报告正常运行时间的量表和表示 application 的绝对开始 time 的固定量表
- Tomcat metrics
- Spring Integration metrics
spring mvc metrics
通过自动配置，可以检测由spring mvc 处理的请求。当management.metrics.web.server.request.autotime.enabled为true时，所有请求都会检测，如果设置为false，那么需要在Controller的处理方法上，添加@Timed注解。
例如：
@Timed
@RequestMapping(value = "/keys",
produces = { "application/json" },
method = RequestMethod.GET)
ResponseEntity<list<prop>> keysGet(
@NotNull
@ApiParam(value = "namespace的唯一名字", required = true)
@Valid
@RequestParam(value = "namespace", required = true)
String namespace) throws ApiException{
}
默认情况下，所有的请求的metrics名均为http.server.requests。也可以通过设置management.metrics.web.server.request.metric-name自定义metrics 名称。
默认情况下，Spring MVC-related metrics tag如下：
| 标签 | 描述 |
|---|---|
exception |
处理请求时抛出的任何 exception 的简单 class name。 |
method |
请求的方法(对于 example，GET或POST) |
outcome |
根据响应的状态 code 请求结果。 1xx 是INFORMATIONAL，2xx 是SUCCESS，3xx 是REDIRECTION，4xx CLIENT_ERROR，5xx 是SERVER_ERROR |
status |
响应的 HTTP 状态 code(对于 example，200或500) |
uri |
如果可能，在变量替换之前请求 URI 模板(对于 example，/api/person/{id}) |
要自定义tag，请实现WebMvcTagsProvider并添加@Bean注解。
那么默认情况下，例子中的metrics请求（/actuator/metrics/http.server.requests）结果如下：
{
"name": "http.server.requests",
"description": null,
"baseUnit": "seconds",
"measurements": [
{
"statistic": "COUNT",
"value": 58
},
{
"statistic": "TOTAL_TIME",
"value": 1.7464228859999997
},
{
"statistic": "MAX",
"value": 0
}
],
"availableTags": [
{
"tag": "exception",
"values": [
"None"
]
},
{
"tag": "method",
"values": [
"GET"
]
},
{
"tag": "uri",
"values": [
"/actuator/metrics/{requiredMetricName}",
"/**/favicon.ico",
"/webjars/**",
"/keys",
"/actuator/mappings",
"/actuator/metrics"
]
},
{
"tag": "outcome",
"values": [
"CLIENT_ERROR",
"SUCCESS"
]
},
{
"tag": "status",
"values": [
"404",
"200"
]
}
]
}
> ⚠️可能需要访问/keys HTTP endpoint， 在 name=http.server.requests的metrics中 tag=uri的values列表中无/keys 。
请求actuator/metrics/http.server.requests?tag=uri:/keys 获取/keys endpoint的 实际情况：
{
"name": "http.server.requests",
"description": null,
"baseUnit": "seconds",
"measurements": [
{
"statistic": "COUNT",
"value": 23
},
{
"statistic": "TOTAL_TIME",
"value": 1.085364246
},
{
"statistic": "MAX",
"value": 0
}
],
"availableTags": [
{
"tag": "exception",
"values": [
"None"
]
},
{
"tag": "method",
"values": [
"GET"
]
},
{
"tag": "outcome",
"values": [
"SUCCESS"
]
},
{
"tag": "status",
"values": [
"200"
]
}
]
}
注册自定义metrics
要注册自定义 metrics，自动注入MeterRegistry到 component 中，例如：
class Dictionary {
private final List<string> words = new CopyOnWriteArrayList<>();
Dictionary(MeterRegistry registry) {
registry.gaugeCollectionSize("dictionary.size", Tags.empty(), this.words);
}
// …
}
> MeterRegistry 会自动配置bean。
需要跨组件或 applications 重复检测 metrics，则可以将metrics suit 封装在MeterBinder的实现类中。默认情况下，所有MeterBinder beans 中的 metrics 将自动绑定（由spring 管理的）到MeterRegistry。
如果需要自定义某个Meter，可以使用io.micrometer.core.instrument.config.MeterFilter接口。默认情况下，所有MeterFilter 接口的beans都会自动应用到micrometer 的MeterRegistry.Config中。
例如，如果要将所有以com.example开头的Meter 重命名mytag.region Tag为mytag.areaTag，则可以执行以下操作：
@Bean
public MeterFilter renameRegionTagMeterFilter() {
return MeterFilter.renameTag("com.example", "mytag.region", "mytag.area");
}
通用tags
通用tag通常用于在操作环境（例如主机，实例，区域，堆栈等）维度上进行深入分析。通用tag会作用到所有的metrics中，可以类似如下配置：
management.metrics.tags.region=us-east-1
management.metrics.tags.stack=prod
上面的示例将region tag和stask tag添加到所有meter，其值分别为us-east-1和prod。
per-meter属性
除了MeterFilter，还可以通过属性配置来实现自定义metrics。 pre-meter属性的个性化会影响所有以给定meter name开头的meter ID，例如：
management.metrics.enable.example.remote=false
会使所有以example.remote开始的meter全部失效。
| Property | Description |
|---|---|
management.metrics.enable |
是否开启所有metrics |
management.metrics.distribution.percentiles-histogram |
是否发布适合于计算可聚合(跨维度)百分位近似的直方图。 |
management.metrics.distribution.minimum-expected-value, management.metrics.distribution.maximum-expected-value |
通过限制预期值的范围来发布较少的直方图桶。 |
management.metrics.distribution.percentiles |
发布在 application 中计算的百分位数值 |
management.metrics.distribution.sla |
使用 SLA 定义的存储桶发布累积直方图。 |
For more details on concepts behind percentiles-histogram, percentiles and sla refer to the "Histograms and percentiles" section of the micrometer documentation.
审计
一旦 Spring Security 在运行，Spring Boot Actuator 有一个灵活的审计 framework 发布 events(默认情况下，“authentication success”, “failure” and “access denied”)。此 feature 对于报告和基于身份验证失败实现 lock-out policy 非常有用。
要自定义已发布的安全性 events，您可以提供自己的AbstractAuthenticationAuditListener和AbstractAuthorizationAuditListener的 实现类。
您还可以将审计服务用于您自己的业务 events。要执行此操作，请将现有AuditEventRepository注入您自己的组件并直接使用它或使用 Spring ApplicationEventPublisher发布AuditApplicationEvent(通过实现ApplicationEventPublisherAware)。
HTTP 请求跟踪
将自动为所有 HTTP 请求启用跟踪。您可以查看httptrace端点并获取有关**最近 100 **个 request-response 交换的基本信息。
自定义 HTTP 跟踪
要自定义每个跟踪中包含的项目，请使用management.trace.http.include 配置属性。对于高级自定义，请考虑注册自己的HttpExchangeTracer实现类。
默认情况下，使用InMemoryHttpTraceRepository为最后 100 个 request-response 交换的 stores 跟踪。如果需要扩展容量，可以定义自己的InMemoryHttpTraceRepository bean 实例。您还可以创建自己的备选方案HttpTraceRepository 的实现类。
进程监控
spring boot中对进程监控有用的两个类：
ApplicationPidFileWriter：创建一个包含 application PID 的文件(默认情况下，在 application 目录中，文件 name 为application.pid)。WebServerPortFileWriter：创建一个包含 running web 服务器端口的文件(或 files)(默认情况下，在 application 目录中，文件 name 为application.port)。
⚠️默认情况下，这些writers 未激活。
激活进程监控文件
-
扩展 Configuration：
META-INF/spring.factories文件中，您可以激活写入 PID 文件的 listener：org.springframework.context.ApplicationListener=\ org.springframework.boot.context.ApplicationPidFileWriter,\ org.springframework.boot.web.context.WebServerPortFileWriter -
以编程方式：调用
SpringApplication.addListeners(…)方法并传递相应的Writer object 来激活 listener。此方法还允许您自定义Writer构造函数中的文件 name 和路径。
</string></list<prop></name></id>
