springboot总结-actuator

简介

spring-boot-starter-actuator 是 Spring Boot 的一个启动器，它提供了一系列生产级别的特性，使得监控和管理 Spring Boot 应用变得更加简单。这些特性主要是通过 Actuator 的多个端点（endpoints）实现的，可以用来暴露各种信息，例如应用的健康状况、度量、环境信息等。

备注：

生产级别的特性：说明这个模块提供的特性和工具是为生产环境运行的应用所设计，旨在更好地监控、维护、诊断和管理在生产环境中的 Spring Boot 应用。

当你在应用中加入相关的 Spring Boot Starter（例如，JPA Starter 为数据库），相应的健康检查组件也会自动启用。

主要功能

  • 应用健康检查：提供应用的健康状态，例如数据库、缓存、消息队列等的健康情况。

  • 应用度量信息：提供应用和系统的各种度量信息，例如 JVM、垃圾收集、HTTP 请求等。

  • 应用环境信息：展示所有的 Spring 环境属性和配置信息。

  • 查看应用中的 Spring Beans。

  • 查看应用的线程信息。

  • 动态更改应用的日志级别。

...等等。

端点

端点代表应用中的一个特定的访问点，它暴露特定的数据或功能，供开发者或者运维人员查看或操作。

端点就像应用的一个小窗口，通过这个窗口，你可以获得应用的某个方面的信息或进行某些管理操作。

关键端点：

  • /actuator/health：展示应用的健康信息。这个端点通常用于生产环境中的健康检查。

  • /actuator/info：展示应用的任意应用特定信息。这些信息通常是从 application.properties 文件中的 info 配置属性中获取的。

  • /actuator/metrics：提供了丰富的应用度量信息。

  • /actuator/env：展示应用的环境属性。

  • /actuator/beans：展示应用中的所有 Spring Beans。

  • /actuator/loggers：查看和修改应用的日志配置。

...等等。这只是 Actuator 提供的一部分端点，实际上有更多的端点可用。

其他端点

httptrace：显示最近 100 次 HTTP 请求的跟踪信息。

threaddump：显示当前线程的堆栈跟踪信息。

auditevents：显示应用的审计事件信息。

conditions：显示 Spring Boot 的自动配置报告，包括哪些自动配置被应用和未被应用的原因。

configprops：显示所有 @ConfigurationProperties 的属性信息。

flyway：显示 Flyway 数据库迁移的信息。

liquibase：显示 Liquibase 数据库迁移的信息。

caches：显示可用的缓存信息。

sessions：显示当前会话的信息（需要 Spring Session 支持）。

shutdown：关闭应用。

jolokia：通过 Jolokia 访问 JVM MBeans（需要 Jolokia 支持）。

prometheus：以 Prometheus 格式显示度量信息（需要 Prometheus 支持）。

使用

添加依赖

<!-- Maven -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-actuator</artifactId>
</dependency>

默认情况下，Spring Boot Starter Actuator 会启用一组常用的端点，但你可以根据需要进行自定义配置。你可以在 application.properties 或 application.yml 中使用 management.endpoints.web.exposure.include 属性来指定要暴露的端点

management:
  endpoints:
    web:
      exposure:
        include: health,info,metrics,env

加入了依赖并配置了端点就可以通过http访问端点了

不指定端点

访问http://localhost:8080/actuator路径，而不指定具体的端点时，通常会返回包含所有已暴露端点的信息的JSON响应。这个响应列出了可用的Actuator端点及其路径。

示例响应：

{
    "_links": {
        "self": {
            "href": "http://localhost:8080/actuator",
            "templated": false
        },
        "beans": {
            "href": "http://localhost:8080/actuator/beans",
            "templated": false
        },
        "health": {
            "href": "http://localhost:8080/actuator/health",
            "templated": false
        },
        "info": {
            "href": "http://localhost:8080/actuator/info",
            "templated": false
        },
        "metrics": {
            "href": "http://localhost:8080/actuator/metrics",
            "templated": false
        },
        // 更多端点...
    }
}

响应中的_links字段包含了每个已暴露端点的名称和路径。

health端点

用于展示应用的健康信息

属性说明

默认情况下，访问该端点只会返回一个简单的响应，例如：{"status":"UP"} 或 {"status":"DOWN"}。

status: 这是最基础的属性，表示应用的总体健康状态。常见的值有：

    • UP：应用是健康的。
    • DOWN：应用存在问题。
    • OUT_OF_SERVICE：应用处于维护或不可用状态。
    • UNKNOWN：无法确定应用的健康状态。

details:当开启详细的健康检查时（通常是通过设置 management.endpoint.health.show-details 属性），你会得到更详细的响应

groups: 如果你配置了健康检查分组，该属性将列出所有的分组名。例如，你可能有一个专门检查数据库的分组和一个专门检查缓存的分组。

components: 这个属性列出了所有参与健康检查的组件的名字和状态。

description (可选): 对某个特定健康检查指标的描述。

 

details属性

开启details属性显示，配置文件配置：

management.endpoint.health.show-details=always

这意味着健康端点的详细信息将始终可见。除了 always，还有其他的值可以设置：

  • never: 从不显示详细信息。
  • when-authorized: 只有经过授权的用户可以看到详细信息。这需要与 Spring Security 一起使用。

响应示例：

"details": {
   "diskSpace": {
      "status": "UP",
      "details": {
         "total": 499963170816,
         "free": 422411247616,
         "threshold": 10485760
      }
   },
   "db": {
      "status": "DOWN",
      "details": {
         "error": "Cannot connect to the database"
      }
   }
}

groups属性

groups 属性允许你创建并使用健康检查分组。这些分组可以将多个健康指标组合在一起，使得你能够为不同的目的或观众定制健康检查的输出。

使用健康检查分组，你可以：

  1. 创建有针对性的健康检查，例如，一个专门针对数据库连接的分组，一个专门针对消息队列的分组等。
  2. 限制某些敏感或高开销的健康检查，只在需要时触发。
  3. 根据需要为不同的用户或系统提供不同级别的健康信息。

定义健康检查分组:

你可以在 application.properties 或 application.yml 文件中定义分组。例如，定义一个名为 database 的分组，该分组包括 db 和 redis 健康指标：

management.endpoint.health.group.database.include=db,redis

访问特定的健康检查分组:

一旦你定义了一个健康检查分组，你可以通过 /actuator/health/{group} 访问它。继续上面的例子，你可以访问 /actuator/health/database 来只获取 db 和 redis 的健康状态。

排除某些健康指标:

你还可以从分组中排除特定的健康指标。例如，从 database 分组中排除 redis：

management.endpoint.health.group.database.exclude=redis

为分组设置不同的详细信息级别:

如果你想为特定的分组设置一个与全局设置不同的详细信息级别，可以这样做：

management.endpoint.health.group.database.show-details=always

使用预定义的分组:

Spring Boot Actuator 也提供了一些预定义的健康检查分组，如 liveness 和 readiness。这些分组特别在 Kubernetes 等容器编排环境中有用，因为它们分别表示应用是否正在运行以及是否准备好处理请求。

components属性

Components属性展示所有的参与健康监测的模块

{
    "status": "UP",
    "components": {
        "db": {
            "status": "UP",
            "details": {
                "database": "MySQL",
                "validationQuery": "SELECT 1",
                "result": 1
            }
        },
        "diskSpace": {
            "status": "UP",
            "details": {
                "total": 76340641792,
                "free": 14252302336,
                "threshold": 10485760,
                "exists": true
            }
        
        "nacosConfig": {
            "status": "UP"
        },
        "nacosDiscovery": {
            "status": "UP"
        },
        "redis": {
            "status": "UP",
            "details": {
                "version": "6.0.9"
            }
        },
        "refreshScope": {
            "status": "UP"
        }
    },
    "groups": [
        "liveness",
        "readiness"
    ]
}

 

健康指标

Spring Boot Actuator 提供了多种内置的健康指标，用于检查应用及其相关的服务和基础设施是否健康。以下是一些常见的健康指标：

  1. db：检查数据库连接是否健康。它使用 DataSource Bean，通常与 JPA、JDBC 等整合。

  2. diskSpace：检查磁盘空间是否足够。默认情况下，当可用磁盘空间低于 10 MB 时，状态将变为 DOWN。

  3. mongo：检查 MongoDB 数据库的连接健康状况。

  4. redis：检查 Redis 数据存储的连接健康状况。

  5. rabbit：检查 RabbitMQ 服务器的连接健康状况。

  6. cassandra：检查 Apache Cassandra 数据库的连接健康状况。

  7. mail：验证 Java Mail 发送者是否被正确配置，并且可以建立连接。

  8. elasticsearch：检查 Elasticsearch 集群的健康状况。

  9. ldap：检查 LDAP 服务器的连接健康状况。

  10. solr：检查 Apache Solr 服务器的连接健康状况。

  11. jms：检查 JMS 代理（如 ActiveMQ）的连接健康状况。

  12. neo4j：检查 Neo4j 数据库的连接健康状况。

  13. kafka：检查 Apache Kafka 服务的连接健康状况。

  14. couchbase：检查 Couchbase 数据库的连接健康状况。

  15. influxdb：检查 InfluxDB 数据库的连接健康状况。

  16. reactive：对响应式数据源、响应式 MongoDB、响应式 Redis 等进行健康检查。

  17. liveness 和 readiness：在 Kubernetes 环境中特别有用，分别表示应用是否正在运行以及是否准备好处理请求。

这些健康指标大多数都是自动配置的，意味着当你在应用中添加相应的依赖时，相应的健康指标就会自动启用。例如，当你添加了 spring-boot-starter-data-jpa 和相应的数据库驱动时，db 健康指标就会自动启用。

除了上述内置的健康指标外，你还可以创建自定义的健康指标来满足特定的需求。只需实现 HealthIndicator 接口并注册为一个 Spring Bean 即可。

启用或禁用特定健康指标:

默认情况下，当你的应用中有相关的依赖时，大多数健康指标会自动启用。如果你想明确启用或禁用某个健康指标，可以使用以下配置：

management.health.<indicator-name>.enabled=true|false

例如，要禁用 db 指标，可以这样设置：

management.health.db.enabled=false

 

info端点

用于显示任意的应用信息。它通常用于显示应用的元数据，如版本号、描述、自定义信息等。这些信息可以通过配置文件设定（也可以实现 InfoContributor 接口来动态地生成信息。），并在请求 /actuator/info 时返回。

在 application.properties 中：

info.app.name=My Awesome App
info.app.version=1.0.0
info.app.description=This is a description of my application.

当你请求 /actuator/info 端点，基于上述配置，你会得到以下的 JSON 响应：

{
    "app": {
        "name": "My Awesome App",
        "version": "1.0.0",
        "description": "This is a description of my application."
    }
}

 

metrics端点

用于获取应用的各种度量信息，如内存使用、垃圾回收、活动线程、HTTP请求统计等。该端点依赖于 Micrometer 库，一个应用指标收集的外部库，它为各种监控系统提供了适配器。

在默认情况下，一旦你添加了 spring-boot-starter-actuator 和 micrometer-core 依赖，多数的基础度量指标都会自动启用。但你也可以进行更细粒度的配置：

启用/禁用指标: 你可以通过配置启用或禁用特定的指标。例如：

management.metrics.enable.jvm.memory=true

度量的绑定属性配置: 对于某些度量，Micrometer 提供了绑定属性来配置其行为，例如设置百分位：

management.metrics.distribution.percentiles-histogram.http.server.requests=true

响应返回

当你访问 /actuator/metrics，你会得到一个包含所有可用度量指标名称的列表。例如：

{
    "names": [
        "jvm.memory.max",
        "jvm.gc.memory.promoted",
        "http.server.requests",
        ...
    ]
}

要获取特定指标的详细信息，你可以通过指定该指标的名称来访问，如 /actuator/metrics/jvm.memory.max，响应可能如下：

{
    "name": "jvm.memory.max",
    "description": "The maximum amount of memory in bytes that can be used for memory management",
    "baseUnit": "bytes",
    "measurements": [
        {
            "statistic": "VALUE",
            "value": 1.073741824E9
        }
    ],
    "availableTags": [...]
}

此响应提供了关于该度量的详细信息：

  • name: 度量的名称
  • description: 对度量的描述
  • baseUnit: 度量的单位
  • measurements: 度量的实际统计数据
  • availableTags: 可用的标签列表，用于进一步细化或分组该度量。

 

env端点

提供了对当前应用环境属性的访问，包括配置属性、系统属性、环境变量等。它允许你查看当前环境中所有的属性和它们的值，这对于诊断配置问题或查看应用在不同环境中的配置是很有用的。

默认情况下，/actuator/env 端点是启用的。但你可以使用以下配置来修改它的行为：

启用/禁用端点:

management.endpoints.web.exposure.include=env
management.endpoints.web.exposure.exclude=env

端点敏感信息:

由于 /actuator/env 可能暴露敏感信息（例如，数据库密码），默认情况下，敏感属性的值会被红acted（隐藏）。但你可以通过设置 management.endpoint.env.keys-to-sanitize 属性来定制这个行为。

当你访问 /actuator/env，你会得到当前环境的属性来源及其相关属性。例如：

{
    "activeProfiles": ["default"],
    "propertySources": [
        {
            "name": "systemProperties",
            "properties": {
                "java.runtime.name": {
                    "value": "Java(TM) SE Runtime Environment"
                },
                ...
            }
        },
        {
            "name": "systemEnvironment",
            "properties": {
                "PATH": {
                    "value": "/usr/bin:/bin:/usr/sbin:/sbin"
                },
                ...
            }
        },
        ...
    ]
}

在此响应中：

  • activeProfiles: 当前激活的 Spring 配置文件。
  • propertySources: 应用环境中可用的属性来源列表。每个来源包含其属性及其值。

你还可以直接访问一个特定的属性来查看其值，如 /actuator/env/{propertyName}，例如 /actuator/env/java.home。

考虑到可能的敏感信息暴露，应谨慎配置它的访问权限，确保不会泄露重要的或敏感的数据。

beans端点

提供了一个查看应用上下文中所有 Spring Beans 及其元数据的方法。这对于验证和审查 Spring 应用的配置、Bean 的作用域、Bean 之间的依赖关系等方面是非常有用的。

默认情况下，/actuator/beans 端点是启用的。但你可以使用以下配置来修改它的行为：

启用/禁用端点:

management.endpoints.web.exposure.include=beans
management.endpoints.web.exposure.exclude=beans

响应返回

当你访问 /actuator/beans，你会得到一个包含应用上下文中所有 Spring Beans 的 JSON 响应。例如：

{
    "contexts": {
        "application": {
            "beans": {
                "exampleBean": {
                    "resource": "com.example.ExampleClass",
                    "scope": "singleton",
                    "type": "com.example.ExampleClass",
                    "dependencies": ["anotherBean"]
                },
                "anotherBean": {
                    "resource": "com.example.AnotherClass",
                    "scope": "singleton",
                    "type": "com.example.AnotherClass",
                    "dependencies": []
                },
                ...
            }
        }
    }
}

在此响应中：

  • contexts: 表示应用上下文及其 Beans。对于标准的 Spring Boot 应用，这里通常只有一个上下文（例如 "application"），但如果你使用了子上下文（如在 Spring MVC 中），它们也会被列出。

  • beans: 包含 Bean 名称作为键，以及相关的 Bean 信息作为值。Bean 信息包括：

    • resource: Bean 定义的来源（通常是 Java 类的全名）。
    • scope: Bean 的作用域（例如 "singleton" 或 "prototype"）。
    • type: Bean 的实际类型。
    • dependencies: 此 Bean 依赖的其他 Bean 的名称列表。

loggers端点

提供了一个接口来查看和修改应用的日志级别。这对于动态地调整日志级别来诊断运行中的问题而不需要重启应用是非常有用的。

默认情况下，/actuator/loggers 端点是启用的。但你可以使用以下配置来修改它的行为：

management.endpoints.web.exposure.include=loggers
management.endpoints.web.exposure.exclude=loggers

获取所有的日志配置:

当你访问 /actuator/loggers，你会得到一个包含当前应用中所有已配置的日志名称和它们的日志级别的 JSON 响应。

{
    "levels": ["OFF", "ERROR", "WARN", "INFO", "DEBUG", "TRACE"],
    "loggers": {
        "ROOT": {
            "configuredLevel": "INFO",
            "effectiveLevel": "INFO"
        },
        "com.example": {
            "configuredLevel": null,
            "effectiveLevel": "INFO"
        },
        ...
    }
}

在此响应中：

  • levels: 是所有可用的日志级别。
  • loggers: 是所有日志名称及其配置和有效日志级别。

获取特定日志器的配置:

你可以通过访问 /actuator/loggers/{name} 来获取特定日志器的配置。例如，访问 /actuator/loggers/com.example 可能会返回：

{
    "configuredLevel": null,
    "effectiveLevel": "INFO"
}

修改日志级别

除了查看日志级别，/actuator/loggers 端点还允许你动态地修改日志级别。为此，你需要发出一个 POST 请求，并提供所需的日志级别。例如，要将 com.example 的日志级别设置为 DEBUG，你可以执行以下命令（使用 curl）：

curl -i -X POST -H 'Content-Type: application/json' -d '{"configuredLevel": "DEBUG"}' http://localhost:8080/actuator/loggers/com.example

这将修改 com.example 日志器的日志级别为 DEBUG。

这个特性主要是为了允许在运行时临时调整日志级别来诊断问题，重启服务会恢复为原来的日志级别。

httptrace端点

用于跟踪HTTP请求和响应的详细信息。

httptrace端点默认是关闭的，这是出于安全和隐私方面的考虑。因为它可以包含有关应用程序的敏感信息，例如HTTP请求和响应的详细信息。

开启：这将启用"httptrace"端点，并允许通过HTTP访问它。

management.endpoints.web.exposure.include: httptrace

如果不想对外暴露只开启

management.endpoint.httptrace.enabled = true

响应：

{
  "traces": [
    {
      "timestamp": "2023-09-21T10:30:45.123456Z",
      "principal": null,
      "session": null,
      "request": {
        "method": "GET",
        "uri": "http://localhost:8080/api/resource",
        "headers": {
          "accept": "application/json",
          "user-agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36"
        }
      },
      "response": {
        "status": 200,
        "headers": {
          "Content-Type": "application/json"
        }
      },
      "timeTaken": 123
    },
    {
      "timestamp": "2023-09-21T10:31:15.789012Z",
      "principal": "user@example.com",
      "session": "ABC123",
      "request": {
        "method": "POST",
        "uri": "http://localhost:8080/api/update",
        "headers": {
          "accept": "application/json",
          "user-agent": "curl/7.68.0",
          "content-type": "application/json"
        }
      },
      "response": {
        "status": 201,
        "headers": {
          "Content-Type": "application/json"
        }
      },
      "timeTaken": 345
    }
  ]
}

这个示例响应包含了两个HTTP请求的信息。每个trace对象表示一个HTTP请求和响应的跟踪。以下是示例响应的一些关键字段说明：

  • timestamp：请求发生的时间戳。
  • principal：请求的身份信息，通常是用户的标识。
  • session：与请求关联的会话标识。
  • request：HTTP请求的详细信息，包括HTTP方法、URI和请求头。
  • response：HTTP响应的详细信息，包括状态码和响应头。
  • timeTaken：请求处理所花费的时间（以毫秒为单位）。

请注意，实际的响应内容可能更复杂，具体取决于你的应用程序和请求的性质。

 threaddump端点

用于获取应用程序的线程转储，可以用于分析应用程序中的线程状态和问题。

默认是关闭的，开放http访问和开启端点功能

management:
  endpoints:
    web:
      exposure:
        include: threaddump

 访问/actuator/threaddump

{
  "threads": [
    {
      "threadName": "http-nio-8080-exec-1",
      "threadId": 34,
      "threadState": "RUNNABLE",
      "blockedTime": null,
      "blockedCount": 0,
      "waitedTime": null,
      "waitedCount": 0,
      "lockInfo": null,
      "stackTrace": [
        {
          "className": "com.example.MyController",
          "methodName": "handleRequest",
          "fileName": "MyController.java",
          "lineNumber": 42,
          "nativeMethod": false
        },
        // Additional stack trace elements...
      ]
    },
    {
      "threadName": "http-nio-8080-exec-2",
      "threadId": 35,
      "threadState": "WAITING",
      // Additional thread details...
    },
    // Additional threads...
  ]
}

这个示例响应包含了应用程序中各个线程的信息，包括线程名称、线程ID、线程状态等。每个线程还包含与之相关的堆栈跟踪信息，以帮助你识别线程的执行路径和潜在问题。

caches端点

用于查看缓存的统计信息，例如缓存的命中率、缓存项的数量等。

默认是关闭的，开放http访问和开启端点

management:
  endpoints:
    web:
      exposure:
        include: caches

访问：/actuator/caches

{
  "cacheManager": "caffeine",
  "cacheNames": [
    "users",
    "products"
  ],
  "caches": {
    "users": {
      "target": "com.github.benmanes.caffeine.cache.BoundedLocalCache",
      "size": 100,
      "entries": 42,
      "hits": 123,
      "misses": 56,
      "evictions": 0
    },
    "products": {
      "target": "com.github.benmanes.caffeine.cache.BoundedLocalCache",
      "size": 50,
      "entries": 20,
      "hits": 60,
      "misses": 30,
      "evictions": 2
    }
  }
}

这个示例响应包含以下信息：

  • cacheManager：缓存管理器的名称。
  • cacheNames：已配置的缓存名称列表。
  • caches：每个缓存的统计信息，包括缓存的实现类、大小、条目数量、命中次数、未命中次数和驱逐次数。

shutdown端点

用于关闭应用程序。

开放http访问和开启端点：

management:
  endpoints:
    web:
      exposure:
        include: shutdown

curl -X POST http://localhost:8080/actuator/shutdown

应用程序成功关闭，通常会返回一个空的响应或简单的成功消息。响应的具体内容取决于应用程序的关闭逻辑和Actuator的配置。

shutdown端点的使用需要谨慎，因为它允许远程关闭应用程序。确保在生产环境中使用时进行适当的安全配置，以防止不必要的关闭请求。默认情况下，Spring Boot要求提供一个有效的安全凭证（例如，使用HTTP基本身份验证）来访问shutdown端点。

监控数据的来源

/metrics 端点的数据主要使用依赖的Micrometer 进行收集，其他端点大多使用 Spring Boot 的内部机制来提供数据。

安全性：

由于 Actuator 端点可能暴露敏感信息，因此在生产环境中使用时应确保进行适当的安全配置。当与 Spring Security 一同使用时，可以轻松地为 Actuator 端点添加安全访问控制。

自定义：

Actuator 提供了丰富的配置选项，允许你根据需要启用、禁用或自定义端点。这些配置可以在 application.properties 或 application.yml 文件中完成。

posted @ 2023-09-21 16:13  星光闪闪  阅读(1113)  评论(0)  编辑  收藏  举报