SpringBoot（六）Actuator

发表于 更新于 分类于 本文字数： 1.5k 阅读时长 ≈ 5 分钟

Actuator 介绍

Actuator（执行器）是Spring Boot项目中提供的对应用系统进行监控和管理的功能模块。

Actuator 的核心是端点（Endpoint），Endpoint是指具体的监控目标，Actuator通过它来监视应用程序及交互，spring-boot-actuator 中已经内置了非常多的 Endpoint（health、info、beans、metrics、httptrace、shutdown等等），同时也允许我们自己扩展自己的 Endpoints。每个 Endpoint 都可以启用和禁用。要远程访问 Endpoint，还必须通过 JMX 或 HTTP 进行暴露，大多数情况使用 HTTP 的方式。Endpoint 的ID默认映射到一个带 /actuator 前缀的URL。例如，health 端点默认映射到 /actuator/health。

Actuator 使用

启用 Actuator 最简单方式是在项目中添加 spring-boot-starter-actuator依赖。 

1
2
3
4
5
6
7
8
9
<dependency>
	<groupId>org.springframework.boot</groupId>
	<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<!-- Actuator插件 -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-actuator</artifactId>
</dependency>

启动项目之后，在浏览器中访问 http://127.0.0.1:8080/actuator 就能看到系统的端点信息，在 Spring Boot 2.X 中，Actuator 默认只开放 health 和 info 两个端点，只能查看 http://127.0.0.1:8080/actuator/health 和 http://127.0.0.1:8080/actuator/info 两个url中的数据。

如果想要查看 Actuator 的所有端点，在配置文件中添加management.endpoints.web.exposure.include='*'后启动应用，访问 http://127.0.0.1:8080/actuator 就可以了。

1
2
3
4
5
#启动所有端点
management.endpoints.web.exposure.include='*'

#自定义管理端点路径，将 /actuator 路径重定义为 /manage
#management.endpoints.web.base-path=/manage

如果想要选择性的开启某个端点，可以将所有端点都禁止，打开想要开启的端点即可：

1
2
3
4
5
# 禁止所有端点
management.endpoints.enabled-by-default=false

# 开启info端点
management.endpoint.info.enabled=true

常用端点详解

health

主要用来检测应用的运行健康状况，是使用最多的一个endpoint。默认情况下 health 端点就是开放的，访问 http://127.0.0.1:8080/actuator/health 即可看到应用运行状态。

1
{"status":"UP"}

UP表示应用的状态是健康的。
health 端点只展示了简单的UP和DOWN状态。为了获得运行的系统更详细的健康指标，可以在配置文件中加如下内容：

1
management.endpoint.health.show-details=always

这样就能在/health中可以看到如下详细内容：

1
2
3
4
5
6
7
8
9
10
11
12
13
{
    "details": {
        "diskSpace": {
            "details": {
                "free": 27172782080,
                "threshold": 10485760,
                "total": 250790436864
            },
            "status": "UP"
        }
    },
    "status": "UP"
}

health端点现在包含了Disk Space Health Indicator。

如果你的应用包含database(比如MySQL)，health 端点将显示如下内容：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{
   "status":"UP",
   "details":{
      "db":{
         "status":"UP",
         "details":{
            "database":"MySQL",
            "hello":1
         }
      },
      "diskSpace":{
         "status":"UP",
         "details":{
            "total":250790436864,
            "free":100330897408,
            "threshold":10485760
         }
      }
   }
}

如果你的MySQL server没有启起来，状态将会变成DOWN：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
{
   "status":"DOWN",
   "details":{
      "db":{
         "status":"DOWN",
         "details":{
            "error":"org.springframework.jdbc.CannotGetJdbcConnectionException: Failed to obtain JDBC Connection; nested exception is java.sql.SQLTransientConnectionException: HikariPool-1 - Connection is not available, request timed out after 30006ms."
         }
      },
      "diskSpace":{
         "status":"UP",
         "details":{
            "total":250790436864,
            "free":100324585472,
            "threshold":10485760
         }
      }
   }
}

info

info端点是用来获取应用的基本信息。它通过META-INF/build-info.properties来获得编译信息，通过git.properties来获得Git信息。它同时可以展示任何其他信息，只要这个环境property中含有infokey。比如我们在项目中配置是：

1
2
3
info.app.name=Spring Boot Actuator Demo
info.app.version=v1.0.0
info.app.description=Spring Boot Actuator Demo

启动项目，访问 http://127.0.0.1:8080/actuator/info 返回信息如下：

1
2
3
4
5
6
7
{
    "app": {
        "description": "Spring Boot Actuator Demo",
        "name": "Spring Boot Actuator Demo",
        "version": "v1.0.0"
    }
}

env

通过 env 可以获取到所有关于当前 Spring Boot 应用程序的运行环境信息，如：操作系统信息（systemProperties）、环境变量信息、JDK 版本及 ClassPath 信息、当前启用的配置文件（activeProfiles）、propertySources、应用程序配置信息（applicationConfig）等。

可以通过 http://127.0.0.1:8080/actuator/env/{name} ，name表示想要查看的信息，可以独立显示。

metrics

访问 http://127.0.0.1:8080/actuator/metrics 展示了可以获取的系统度量指标信息项：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
{
    "names": [
        "jvm.memory.max",
        "jvm.threads.states",
        "jvm.gc.pause",
        "http.server.requests",
        "process.files.max",
        "jvm.gc.memory.promoted",
        "system.load.average.1m",
        "jvm.memory.used",
        "jvm.gc.max.data.size",
        "jvm.memory.committed",
        "system.cpu.count",
        "logback.events",
        "tomcat.global.sent",
        "jvm.buffer.memory.used",
        "tomcat.sessions.created",
        "jvm.threads.daemon",
        "system.cpu.usage",
        "jvm.gc.memory.allocated",
        "tomcat.global.request.max",
        "tomcat.global.request",
        "tomcat.sessions.expired",
        "jvm.threads.live",
        "jvm.threads.peak",
        "tomcat.global.received",
        "process.uptime",
        "tomcat.sessions.rejected",
        "process.cpu.usage",
        "tomcat.threads.config.max",
        "jvm.classes.loaded",
        "jvm.classes.unloaded",
        "tomcat.global.error",
        "tomcat.sessions.active.current",
        "tomcat.sessions.alive.max",
        "jvm.gc.live.data.size",
        "tomcat.threads.current",
        "process.files.open",
        "jvm.buffer.count",
        "jvm.buffer.total.capacity",
        "tomcat.sessions.active.max",
        "tomcat.threads.busy",
        "process.start.time"
    ]
}

想要获得每个度量的详细信息，你需要传递度量的名称到URL中，像
http://localhost:8080/actuator/metrics/{MetricName}
举个例子，获得systems.cpu.usage的详细信息，使用以下URLhttp://localhost:8080/actuator/metrics/system.cpu.usage。它将显示如下内容:

1
2
3
4
5
6
7
8
9
10
{
    "name": "system.cpu.usage",
    "measurements": [
    {
        "statistic": "VALUE",
        "value": 0
    }
    ],
"availableTags": []
}

loggers

通过访问 http://localhost:8080/actuator/loggers ,可以展示了应用中可配置的loggers的列表和相关的日志等级。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
{
    "levels": [
        "OFF",
        "ERROR",
        "WARN",
        "INFO",
        "DEBUG",
        "TRACE"
    ],
    "loggers": {
        "ROOT": {
            "configuredLevel": "INFO",
            "effectiveLevel": "INFO"
        },
        "com.lzumetal": {
            "configuredLevel": null,
            "effectiveLevel": "INFO"
        },
        "cn.lzumetal.springboot": {
            "configuredLevel": null,
            "effectiveLevel": "WARN"
        },
        ...
    }
}

你同样能够使用 http://localhost:8080/actuator/loggers/{name} 来展示特定logger的细节。
举个例子，为了获得root logger的细节，你可以使用http://localhost:8080/actuator/loggers/root：

1
2
3
4
{
   "configuredLevel":"INFO",
   "effectiveLevel":"INFO"
}
在运行时改变日志等级

loggers endpoint也允许你在运行时改变应用的日志等级。

举个例子，为了改变root logger的等级为DEBUG ，发送一个POST请求到http://localhost:8080/actuator/loggers/root ，加入如下参数:

1
2
3
{
   "configuredLevel": "DEBUG"
}

这个功能对于线上问题的排查非常有用。

同时，你可以通过传递null值给configuredLevel来重置日志等级。

使用Spring Security来保证Actuator Endpoints安全

Actuator endpoints是敏感的，必须保障进入是被授权的。如果Spring Security是包含在你的应用中，那么endpoint是通过HTTP认证被保护起来的。
如果没有， 你可以增加以下以来到你的应用中去：

1
2
3
4
<dependency>
   <groupId>org.springframework.boot</groupId>
   <artifactId>spring-boot-starter-security</artifactId>
</dependency>

接下去让我们看一下如何覆写spring security配置，并且定义你自己的进入规则。
下面的例子展示了一个简单的spring securiy配置。它使用叫做EndPointRequest的ReqeustMatcher工厂模式来配置Actuator endpoints进入规则。

1
2
3
4
5
6
7
8
9
10
11
12
@Configuration
public class ActuatorSecurity extends WebSecurityConfigurerAdapter {

	@Override
	protected void configure(HttpSecurity http) throws Exception {
		http.requestMatcher(EndpointRequest.toAnyEndpoint()).authorizeRequests()
				.anyRequest().hasRole("ACTUATOR_ADMIN")
				.and()
			.httpBasic();
	}

}

为了能够测试以上的配置，你可以在application.yaml中增加spring security用户。

1
2
3
4
5
6
7
# Spring Security Default user name and password
spring:
  security:
    user:
      name: actuator
      password: actuator
      roles: ACTUATOR_ADMIN
------ 本文完 ------