Part V. Spring Boot Actuator: Production-ready features

Spring boot actuator准生产环境特点

Spring Boot includes a number of additional features to help you monitor and manage your application when you push it to production. You can choose to manage and monitor your application by using HTTP endpoints or with JMX. Auditing, health, and metrics gathering can also be automatically applied to your application.

spring boot 包含一些额外的特点来帮助你监控和管理你的应用，当你将它放到生产环境中。你能够选择管理和监控你的应用通过Http 端点或者使用JMX。审计，健康和指标收集也可以自动应用于您的应用程序。

49. Enabling Production-ready Features

启用生产环境特点

The spring-boot-actuator module provides all of Spring Boot’s production-ready features. The simplest way to enable the features is to add a dependency to thespring-boot-starter-actuator ‘Starter’.

Spring-boot-actuator模块提供了所有的Spring boot的准生产特点。简单的使用方式是添加一个依赖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.

Actuator的定义

致动器是制造术语，是指用于移动或控制某物的机械装置。执行器可以从一个小的变化中产生大量的运动。(来自于谷歌，未能翻译通顺)

To add the actuator to a Maven based project, add the following ‘Starter’ dependency:

添加actuator到Maven基本项目，添加以下starter依赖：


	
		org.springframework.boot
		spring-boot-starter-actuator

50. 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, thehealth endpoint provides basic application health information.

Actuator端点允许您监控应用程序并与其进行交互。Spring boot 包括一系列的内嵌端点并且允许你添加自己的端点。例如，heath端点提供了基本的应用健康信息。

Each individual endpoint can be enabled or disabled. This controls whether or not the endpoint is created and its bean exists in the application context. To be remotely accessible an endpoint also has to be exposed via JMX or HTTP. Most applications choose HTTP, where the ID of the endpoint along with a prefix of /actuator is mapped to a URL. For example, by default, the health endpoint is mapped to /actuator/health.

每一个独立的端点能够被启用和不启用。这控制端点是否被创建，通过它的bean是否存在于应用程序上下文中。要远程访问端点，还必须通过JMX或HTTP进行暴露。大多数程序选择HTTP方式，其中ID和前缀/actuator组合匹配一个URL。例如，默认health端点匹配到/actuator/health。

The following technology-agnostic endpoints are available:

下面是 technology-agnostic（不知如何翻译）端点可以使用：

ID（id）	Description（描述）	Enabled by default（默认启用）
auditevents	Exposes audit events information for the current application.（公开当前应用程序的审计事件信息。）	可用
beans	Displays a complete list of all the Spring beans in your application.（显示应用程序中所有Spring bean的完整列表。）	可用
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`.（显示所有@ConfigurationProperties的整理列表。）	可用
env	Exposes properties from Spring’s `ConfigurableEnvironment`. （公开来自Spring的ConfigurableEnvironment的属性。）	可用
flyway	Shows any Flyway database migrations that have been applied.（显示已应用的所有Flyway数据库迁移。）	可用
health	Shows application health information.（显示应用健康信息）	可用
httptrace	Displays HTTP trace information (by default, the last 100 HTTP request-response exchanges).显示HTTP跟踪信息（默认情况下为最后100个HTTP请求 - 响应交换）。	可用
info	Displays arbitrary application info.（显示任意的应用信息。）	可用
loggers	Shows and modifies the configuration of loggers in the application.（显示和修改应用程序中日志记录器的配置。）	可用
liquibase	Shows any Liquibase database migrations that have been applied.（显示已应用的任何Liquibase数据库迁移。）	可用
metrics	Shows ‘metrics’ information for the current application.（显示“etrics"信息为当前应用）	可用
mappings	Displays a collated list of all `@RequestMapping` paths.（显示所有@RequestMapping路径的整理列表。）	可用
scheduledtasks	Displays the scheduled tasks in your application.（显示你应用的定时任务）	可用
sessions	Allows retrieval and deletion of user sessions from a Spring Session-backed session store. Not available when using Spring Session’s support for reactive web applications.（暂无翻译）	可用
shutdown	Lets the application be gracefully shutdown.（让应用程序正常关闭。）	不可用
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:

如果您的应用程序是一个Web应用程序（Spring MVC，Spring WebFlux或Jersey），则可以使用以下附加端点：

ID	描述	默认可用
heapdump	Returns a GZip compressed hprof heap dump file.（返回一个GZip压缩的hprof堆转储文件。）	可用
jolokia	Exposes JMX beans over HTTP (when Jolokia is on the classpath, not available for WebFlux).通过HTTP公开JMX bean（当Jolokia在类路径上时，不可用于WebFlux）。	可用
logfile	Returns the contents of the logfile (if logging.file or logging.path properties have been set). Supports the use of the HTTPRange header to retrieve part of the log file’s content.返回日志文件的内容（如果logging.file或logging.path属性已设置）。支持使用HTTP范围头来检索部分日志文件的内容。	可用
prometheus	Exposes metrics in a format that can be scraped by a Prometheus server.（以可以被Prometheus服务器抓取的格式显示指标。）	可用

To learn more about the Actuator’s endpoints and their request and response formats, please refer to the separate API documentation (HTML or PDF).

要详细了解Actuator的端点及其请求和响应格式，请参阅单独的API文档(HTML or PDF)。

50.1 Enabling Endpoints

启用端点

By default, all endpoints except for shutdown are enabled. To configure the enablement of an endpoint, use its management.endpoint..enabled property. The following example enables the shutdown endpoint:

默认情况下，除 shutdown 以外的所有端点均已启用。要配置端点的启用，请使用其management.endpoint. .enabled属性。以下示例启用关闭端点：

management.endpoint.shutdown.enabled=true

If you prefer endpoint enablement to be opt-in rather than opt-out,set the management.endpoints.enabled-by-default property to false and use individual endpoint enabled properties to opt back in. The following example enables the info endpoint and disables all other endpoints:

如果您希望端点启用选择加入而不是选择退出，请将management.endpoints.enabled-by-default属性设置为false，并使用单个启用端点的属性重新启用。以下示例启用info端点并禁用所有其他终点：

management.endpoints.enabled-by-default=false
management.endpoint.info.enabled=true

Disabled 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.

禁用的端点将从应用程序上下文中完全删除。如果您只想更改端点公开的技术，请改为使用包含和排除属性。

50.2 Exposing Endpoints

暴露端点

Since Endpoints may contain sensitive information, careful consideration should be given about when to expose them. The following table shows the default exposure for the built-in endpoints:

由于端点可能包含敏感信息，因此应仔细考虑何时公开它们。下表显示了内置端点的默认暴露：

ID	JMX	WEB
auditevents	yes	no
beans		no
conditions		no
configprops		no
env		no
flyway		no
health		yes
heapdump		no
httptrace		no
info		yes
jolokia		no
logfile		no
loggers		no
liquibase		no
metrics		no
mappings		no
prometheus		no
scheduledtasks		no
sessions		no
shutdown		no
threaddump		no

To change which endpoints are exposed, use the following technology-specific include and exclude properties:

要更改公开哪些端点，请使用以下技术特定的包含和排除属性：

property	default
management.endpoints.web.exposure.exclude
management.endpoints.web.exposure.include	info,health
management.endpoints.jmx.exposure.include(exclude)

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 excludeproperty takes precedence over the include property. Both include and exclude properties can be configured with a list of endpoint IDs.

include属性列出了暴露的IDS。exclude属性列出的IDS端点不应被暴露。exclude属性优先于include属性。包含和排除属性都可以使用端点ID列表进行配置。

For example, to stop exposing all endpoints over JMX and only expose the health and info endpoints, use the following property:

例如，要停止通过JMX公开所有端点并仅公开健康和信息端点，请使用以下属性：

management.endpoints.jmx.exposure.include=health,info

* can be used to select all endpoints. For example, to expose everything over HTTP except the env and beans endpoints, use the following properties:

可以用来选择所有端点。例如，要通过HTTP公开除env和beans端点之外的所有内容，请使用以下属性：

management.endpoints.web.exposure.include=*
management.endpoints.web.exposure.exclude=env,beans

has a special meaning in YAML, so be sure to add quotes if you want to include (or exclude) all endpoints, as shown in the following example:

management:
	endpoints:
		web:
			exposure:
				include: "*"

If your application is exposed publicly, we strongly recommend that you also secure your endpoints.

如果您的应用程序公开公开，我们强烈建议您也保护您的端点。

If you want to implement your own strategy for when endpoints are exposed, you can register an EndpointFilter bean.

如果您希望在暴露端点时实施您自己的策略，您可以注册一个EndpointFilter bean。

50.3 Securing HTTP Endpoints

保护HTTP端点

You should take care to secure HTTP endpoints in the same way that you would any other sensitive URL. If Spring Security is present, endpoints are secured by default using Spring Security’s content-negotiation strategy. If you wish to configure custom security for HTTP endpoints, for example, only allow users with a certain role to access them, Spring Boot provides some convenient RequestMatcher objects that can be used in combination with Spring Security.

您应该注意保护HTTP端点的方式与使用其他任何敏感网址的方式相同。如果存在Spring Security，则使用Spring Security的内容协商策略默认保护端点。例如，如果您希望为HTTP端点配置自定义安全性，则只允许具有特定角色的用户访问它们，Spring Boot提供了一些便捷的RequestMatcher对象，可以与Spring Security结合使用。

A typical Spring Security configuration might look something like the following example:

一个典型的Spring Security配置可能看起来像下面的例子：

@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();
	}

}

The preceding example uses EndpointRequest.toAnyEndpoint() to match a request to any endpoint and then ensures that all have the ENDPOINT_ADMIN role. Several other matcher methods are also available on EndpointRequest. See the API documentation (HTML or PDF) for details.

上例使用EndpointRequest.toAnyEndpoint（）将请求与任何端点进行匹配，然后确保所有端点都具有ENDPOINT_ADMIN角色。 EndpointRequest上还有其他几种匹配器方法。有关详细信息，请参阅API文档（HTML或PDF）。

If you deploy applications behind a firewall, you may prefer that all your actuator endpoints can be accessed without requiring authentication. You can do so by changing the management.endpoints.web.exposure.include property, as follows:

如果您在防火墙后面部署应用程序，您可能更喜欢所有的执行器端点都可以在无需验证的情况下进行访问。您可以通过更改management.endpoints.web.exposure.include属性来完成此操作，如下所示：

application.properties.

management.endpoints.web.exposure.include=*

Additionally, if Spring Security is present, you would need to add custom security configuration that allows unauthenticated access to the endpoints as shown in the following example:

此外，如果存在Spring Security，则需要添加自定义安全配置，以允许对端点进行未经身份验证的访问，如以下示例所示：

@Configuration
public class ActuatorSecurity extends WebSecurityConfigurerAdapter {

	@Override
	protected void configure(HttpSecurity http) throws Exception {
		http.requestMatcher(EndpointRequest.toAnyEndpoint()).authorizeRequests()
			.anyRequest().permitAll()
	}

}

50.4 Configuring Endpoints

配置端点

Endpoints automatically cache responses to read operations that do not take any parameters. To configure the amount of time for which an endpoint will cache a response, use its cache.time-to-live property. The following example sets the time-to-live of the beans endpoint’s cache to 10 seconds:

端点自动缓存响应以读取不带任何参数的操作。要配置端点缓存响应的时间量，请使用其cache.time-to-live属性。以下示例将beans端点缓存的生存时间设置为10秒：

management.endpoint.beans.cache.time-to-live=10s

The prefix management.endpoint. is used to uniquely identify the endpoint that is being configured.

前缀management.endpoint.用于唯一标识正在配置的端点。

50.5 Hypermedia for Actuator Web Endpoints

Actuator web端点超媒体

A “discovery page” is added with links to all the endpoints. The “discovery page” is available on /actuator by default.

“发现页面”添加了指向所有端点的链接。默认情况下，“发现页面”在/actuator上可用。

When a custom management context path is configured, the “discovery page” automatically moves from /actuator to the root of the management context. For example, if the management context path is /management, then the discovery page is available from /management. When the management context path is set to /, the discovery page is disabled to prevent the possibility of a clash with other mappings.

当定制管理上下文路径被配置时，“发现页面”自动从/执行器移动到管理上下文的根。例如，如果管理上下文路径是/管理，则发现页面可从/ management获得。当管理上下文路径设置为/时，禁用发现页面以防止与其他映射发生冲突的可能性。

50.6 Actuator Web Endpoint Paths

Actuator的web端点paths路径

By default, endpoints are exposed over HTTP under the /actuator path by using the ID of the endpoint. For example, the beans endpoint is exposed under/actuator/beans. If you want to map endpoints to a different path, you can use the management.endpoints.web.path-mapping property. Also, if you want change the base path, you can use management.endpoints.web.base-path.

默认情况下，端点通过使用端点的ID在/ actuator路径下的HTTP上公开。例如：beans端点暴露在/actuator/beans路径。如果要将端点映射到不同的路径，可以使用management.endpoints.web.path-mapping 属性。另外，如果您想更改基本路径，则可以使用management.endpoints.web.base-path。

The following example remaps /actuator/health to /healthcheck:

下面的例子是将/actuator/health路径映射到/healthcheck路径

application.properties.

management.endpoints.web.base-path=/
management.endpoints.web.path-mapping.health=healthcheck

50.7 CORS Support

Cross支持

Cross-origin resource sharing (CORS) is a W3C specification that lets you specify in a flexible way what kind of cross-domain requests are authorized. If you use Spring MVC or Spring WebFlux, Actuator’s web endpoints can be configured to support such scenarios.

跨源资源共享（CORS）是W3C规范，允许您以灵活的方式指定授权哪种跨域请求。如果您使用Spring MVC或Spring WebFlux，则可以配置Actuator的Web端点来支持这些场景。

CORS support is disabled by default and is only enabled once the management.endpoints.web.cors.allowed-origins property has been set. The following configuration permits GET and POST calls from the example.com domain:

默认情况下，CORS支持处于禁用状态，只有在设置了management.endpoints.web.cors.allowed-origins属性后才能启用。以下配置允许来自example.com域的GET和POST调用：

management.endpoints.web.cors.allowed-origins=http://example.com
management.endpoints.web.cors.allowed-methods=GET,POST

50.8 Implementing Custom Endpoints

实现自定义端点

If you add a @Bean annotated with @Endpoint, any methods annotated with @ReadOperation, @WriteOperation, or @DeleteOperation are automatically exposed over JMX and, in a web application, over HTTP as well. Endpoints can be exposed over HTTP using Jersey, Spring MVC, or Spring WebFlux.

如果添加用@Endpoint注释的@Bean，则任何使用@ReadOperation，@WriteOperation或@DeleteOperation注释的方法都会自动通过JMX公开，并且也可以通过HTTP在Web应用程序中通过HTTP公开。可以使用Jersey，Spring MVC或Spring WebFlux通过HTTP公开端点。

You can also write technology-specific endpoints by using @JmxEndpoint or @WebEndpoint. These endpoints are restricted to their respective technologies. For example, @WebEndpoint is exposed only over HTTP and not over JMX.

Spring boot actuator 官方文档翻译（本文基于Spring-boot-2.X）