系统监控 (Monitoring)

度量指标（Metrics）

本项目实现了 Vert.x 度量指标服务提供者接口（Metrics SPI），用于将度量指标上报至 Dropwizard Metrics 库。

特性

提供一个相当简单的 API，通过 Measured 接口获取度量指标。该接口已被多个 Vert.x 组件实现，如 HttpServer、 NetServer，甚至 Vertx 本身。

基于 Dropwizard 实现的可配置 JMX 上报，将 Vert.x 暴露为 JMX MBean。

命令行启用

通过命令行界面运行 Vert.x 时，可以通过 JVM 系统属性启用度量指标。以 vertx.metrics.options. 开头的系统属性将传递给度量指标配置项。

vertx.metrics.options.enabled 是用于启用度量指标实现的 Vert.x Core 标准选项，此选项必须设置为 true：

java -jar your-fat-jar -Dvertx.metrics.options.enabled=true

vertx.metrics.options.registryName 用于配置所使用的 Dropwizard Registry：

java -jar your-fat-jar -Dvertx.metrics.options.enabled=true -Dvertx.metrics.options.registryName=my-registry

vertx.metrics.options.jmxEnabled 与 vertx.metrics.options.jmxDomain 用于配置 JMX 注册：

java -jar your-fat-jar -Dvertx.metrics.options.enabled=true -Dvertx.metrics.options.jmxEnabled=true ...

vertx.metrics.options.configPath 选项允许通过属性文件重新配置度量指标。

度量指标服务

虽然 Vert.x Core 定义了用于上报度量指标的 SPI（例如本项目即为其实现），但并未定义用于获取度量指标的 API（因为某些度量指标收集器仅负责上报）。

MetricsService 在 Dropwizard Registry 之上提供了一套 API，用于获取度量指标数据快照。

命名规范

下面列出的每个被测组件（Vertx 本身除外）都会关联一个基础名称（baseName）。你可以通过 Vertx 传入完全限定名（FQN）baseName + . + metricName 来获取各度量指标：

JsonObject metrics = metricsService.getMetricsSnapshot(vertx);
metrics.getJsonObject("vertx.eventbus.handlers");

或者直接从被测组件本身通过度量指标简短名称获取：

EventBus eventBus = vertx.eventBus();
JsonObject metrics = metricsService.getMetricsSnapshot(eventBus);
metrics.getJsonObject("handlers");

下文展示了更多关于如何获取和使用特定组件度量指标的示例。

也可以列出所有度量指标名称：

Set<String> metricsNames = metricsService.metricsNames();
for (String metricsName : metricsNames) {
  System.out.println("Known metrics name " + metricsName);
}

baseName 默认为 vertx，但可以自定义设置：

DropwizardMetricsOptions metricsOptions =
  new DropwizardMetricsOptions().setBaseName("foo");

获取度量指标

启用后，MetricsService 允许从任意实现了 Measured 的对象获取度量指标快照。该对象会提供一个映射表，将度量指标名称映射到由 JsonObject 表示的数据中。例如，若要打印某个特定 Vert.x 实例的所有度量指标：

MetricsService metricsService = MetricsService.create(vertx);
JsonObject metrics = metricsService.getMetricsSnapshot(vertx);
System.out.println(metrics);

有关 JsonObject 所表示的具体数据内容（实际指标）的详细信息，请参阅具体实现文档，例如 vertx-metrics。

通常你可能只想采集某个特定组件（如 HTTP 服务器）的特定度量指标，而无需知晓每个度量指标命名的具体细节（这部分交由 SPI 实现者负责）。

由于 HttpServer 实现了 Measured，你可以轻松获取该 HTTP 服务器专有的所有度量指标。

MetricsService metricsService = MetricsService.create(vertx);
HttpServer server = vertx.createHttpServer();
// 配置服务器
JsonObject metrics = metricsService.getMetricsSnapshot(server);

也可以使用基础名称获取度量指标：

MetricsService metricsService = MetricsService.create(vertx);
JsonObject metrics = metricsService.getMetricsSnapshot("vertx.eventbus.message");

数据表示

以下是各 Dropwizard 度量指标在 JSON 中的表示方式。有关每个度量指标的详细信息，请参阅 Dropwizard Metrics 文档。

Gauge

{
  "type"  : "gauge",
  "value" : value // 任意 JSON 值
}

Counter

{
  "type"  : "counter",
  "count" : 1 // 数字
}

Histogram

{
  "type"   : "histogram",
  "count"  : 1 // long 型整数
  "min"    : 1 // long 型整数
  "max"    : 1 // long 型整数
  "mean"   : 1.0 // double 型浮点数
  "stddev" : 1.0 // double 型浮点数
  "median" : 1.0 // double 型浮点数
  "75%"    : 1.0 // double 型浮点数
  "95%"    : 1.0 // double 型浮点数
  "98%"    : 1.0 // double 型浮点数
  "99%"    : 1.0 // double 型浮点数
  "99.9%"  : 1.0 // double 型浮点数
}

Meter

{
  "type"              : "meter",
  "count"             : 1 // long 型整数
  "meanRate"          : 1.0 // double 型浮点数
  "oneMinuteRate"     : 1.0 // double 型浮点数
  "fiveMinuteRate"    : 1.0 // double 型浮点数
  "fifteenMinuteRate" : 1.0 // double 型浮点数
  "rate"              : "events/second" // 表示速率的字符串
}

ThroughputMeter

继承自 Meter ，用于提供瞬时吞吐量指标。

{
  "type"              : "meter",
  "count"             : 40 // long 型整数
  "meanRate"          : 2.0 // double 型浮点数
  "oneSecondRate"     : 3 // long - 最近一秒内的发生次数
  "oneMinuteRate"     : 1.0 // double 型浮点数
  "fiveMinuteRate"    : 1.0 // double 型浮点数
  "fifteenMinuteRate" : 1.0 // double 型浮点数
  "rate"              : "events/second" // 表示速率的字符串
}

Timer

Timer 本质上是 Histogram 与 Meter 的组合。

{
  "type": "timer",

  // Histogram 数据
  "count"  : 1 // long 型整数
  "min"    : 1 // long 型整数
  "max"    : 1 // long 型整数
  "mean"   : 1.0 // double 型浮点数
  "stddev" : 1.0 // double 型浮点数
  "median" : 1.0 // double 型浮点数
  "75%"    : 1.0 // double 型浮点数
  "95%"    : 1.0 // double 型浮点数
  "98%"    : 1.0 // double 型浮点数
  "99%"    : 1.0 // double 型浮点数
  "99.9%"  : 1.0 // double 型浮点数

  // Meter 数据
  "meanRate"          : 1.0 // double 型浮点数
  "oneMinuteRate"     : 1.0 // double 型浮点数
  "fiveMinuteRate"    : 1.0 // double 型浮点数
  "fifteenMinuteRate" : 1.0 // double 型浮点数
  "rate"              : "events/second" // 表示速率的字符串
}

Throughput Timer

继承自 Timer ，用于提供瞬时吞吐量度量指标。

{
  "type": "timer",

  // Histogram 数据
  "count"      : 1 // long 型整数
  "min"        : 1 // long 型整数
  "max"        : 1 // long 型整数
  "mean"       : 1.0 // double 型浮点数
  "stddev"     : 1.0 // double 型浮点数
  "median"     : 1.0 // double 型浮点数
  "75%"        : 1.0 // double 型浮点数
  "95%"        : 1.0 // double 型浮点数
  "98%"        : 1.0 // double 型浮点数
  "99%"        : 1.0 // double 型浮点数
  "99.9%"      : 1.0 // double 型浮点数

  // Meter 数据
  "meanRate"          : 1.0 // double 型浮点数
  "oneSecondRate"     : 3 // long - 最近一秒内的发生次数
  "oneMinuteRate"     : 1.0 // double 型浮点数
  "fiveMinuteRate"    : 1.0 // double 型浮点数
  "fifteenMinuteRate" : 1.0 // double 型浮点数
  "rate"              : "events/second" // 表示速率的字符串
}

度量指标清单

当前提供以下度量指标。

Vert.x 度量指标

提供以下度量指标：

vertx.event-loop-size - Event Loop 线程池中线程数量的 Gauge
vertx.worker-pool-size - Worker 线程池中线程数量的 Gauge
vertx.cluster-host - cluster-host 配置项的 Gauge
vertx.cluster-port - cluster-port 配置项的 Gauge

HTTP 服务端度量指标

基础名称：vertx.http.servers.<host>:<port>

HTTP 服务端包含 Net Server 的所有度量指标，外加以下内容：

requests - 请求耗时及其发生速率的 Throughput Timer
<http-method>-requests - 特定 HTTP 方法请求耗时及其发生速率的 Throughput Timer
- 示例：get-requests、post-requests
<http-method>-requests./<uri> - 特定 HTTP 方法及 URI 请求耗时及其发生速率的 Throughput Timer
- 示例：get-requests./some/uri、post-requests./some/uri?foo=bar
<http-method>-requests./<route> - 特定 HTTP 方法及请求路由耗时及其发生速率的 Throughput Timer
- 示例：get-requests./route1、post-requests./resource/:id
responses-1xx - 1xx 响应状态码的 ThroughputMeter
responses-2xx - 2xx 响应状态码的 ThroughputMeter
responses-3xx - 3xx 响应状态码的 ThroughputMeter
responses-4xx - 4xx 响应状态码的 ThroughputMeter
responses-5xx - 5xx 响应状态码的 ThroughputMeter
open-websockets - 打开的 WebSocket 连接数的 Counter
open-websockets.<remote-host> - 特定远程主机的打开的 WebSocket 连接数的 Counter

HTTP URI 度量指标必须在选项中通过精确匹配或正则表达式匹配显式配置：

Vertx vertx = Vertx.vertx(new VertxOptions().setMetricsOptions(
    new DropwizardMetricsOptions().
        setEnabled(true).
        addMonitoredHttpServerUri(
            new Match().setValue("/")).
        addMonitoredHttpServerUri(
            new Match().setValue("/foo/.*").setType(MatchType.REGEX))
));

若 URI 包含某些路径参数（如 /users/:userId），为每个用户 ID 在注册表中单独保留条目（例如 get-requests./users/1、get-requests./users/2 等）通常没有意义，汇总统计更为合理。为此，你可以为匹配规则实例设置别名（alias），此时别名将代替 URI 作为注册表名称的一部分，形式如 <http-method>-requests.<alias>。此外，针对每个已定义的别名，每个响应状态码分组都会有独立的计数器，如 responses-<code>.<alias>。

Vertx vertx = Vertx.vertx(new VertxOptions().setMetricsOptions(
    new DropwizardMetricsOptions().
        setEnabled(true).
        addMonitoredHttpServerUri(new Match().setValue("/users/.*").setAlias("users").setType(MatchType.REGEX))
));

HTTP 请求路由可以由像 vertx-web 这样的框架在处理每次请求时上报，即 Vert.x Core 本身不会上报任何路由信息。与 URI 度量指标类似，路由度量指标也必须在选项中显式配置：

Vertx vertx = Vertx.vertx(new VertxOptions().setMetricsOptions(
  new DropwizardMetricsOptions().
    setEnabled(true).
    addMonitoredHttpServerRoute(new Match().setValue("/users/.*").setType(MatchType.REGEX))
));

与 URI 度量指标类似，路由度量指标也可以提供别名，但通常路由本身已经提供了充分且合理的 URI 语义分组。请注意，单个 HTTP 请求可能会被多次路由（例如由于 vertx-web 子路由器），每个请求上报的所有路由都将使用 > 连接在一起（例如 /internal_api>/resource/:id）。

对于 bytes-read 与 bytes-written，字节数表示请求/响应的正文（body），因此请求头（headers）等会被忽略。

HTTP 客户端度量指标

基础名称：vertx.http.clients（默认）或 vertx.http.clients.<id>，其中 <id> 是通过 setMetricsName 配置的非空字符串。

HTTP 客户端包含 Http Server 的所有度量指标，外加以下内容：

responses-1xx - 1xx 响应状态码的 Meter
responses-2xx - 2xx 响应状态码的 Meter
responses-3xx - 3xx 响应状态码的 Meter
responses-4xx - 4xx 响应状态码的 Meter
responses-5xx - 5xx 响应状态码的 Meter

HTTP 客户端为每个远程端点维护一个连接池，并带有一个待处理请求队列。

端点度量指标同样可用：

endpoint.<host:port>.open-netsockets - 到该端点的实际打开套接字数量的 Counter
endpoint.<host:port>.usage - 请求开始到响应结束之间时延的 Timer
endpoint.<host:port>.in-use - 实际进行中的请求/响应数量的 Counter
endpoint.<host:port>.ttfb - 请求结束到响应开始之间等待时间（TTFB）的 Timer

其中 <host> 是端点主机名（可能尚未解析），<port> 为 TCP 端口号。

受监控的端点可以通过对服务端的 $host:$port 进行匹配来配置。此设置的默认值为不监控任何端点。

受监控的端点可以在 DropwizardMetricsOptions 中通过指定主机名匹配或正则表达式匹配来进行配置：

Vertx vertx = Vertx.vertx(new VertxOptions().setMetricsOptions(
    new DropwizardMetricsOptions().
        setEnabled(true).
        addMonitoredHttpClientEndpoint(
            new Match().setValue("some-host:80")).
        addMonitoredHttpClientEndpoint(
            new Match().setValue("another-host:.*").setType(MatchType.REGEX))
));

HTTP 客户端连接池度量指标暴露为连接池度量指标。

Net 服务端度量指标

基础名称：vertx.net.servers.<host>:<port>

open-netsockets - 打开的 Net Socket 连接数的 Counter
open-netsockets.<remote-host> - 特定远程主机的打开的 Net Socket 连接数的 Counter
connections - 连接持续时长及其发生速率的 Timer
exceptions - 异常发生次数的 Counter
bytes-read - 读取字节数的 Counter
bytes-written - 写入字节数的 Counter

Net 客户端度量指标

基础名称：vertx.net.clients（默认）或 vertx.net.clients.<id>，其中 <id> 是通过 setMetricsName 配置的非空字符串。

Net 客户端包含 Net Server 的所有度量指标。

客户端度量指标

基础名称：vertx.<type>.clients（默认）或 vertx.<type>.clients.<id>，其中 <id> 是客户端度量指标的标识符，<type> 是度量指标的类型。

SQL 客户端的类型为 sql，标识符是客户端选项中定义的 metricsName。

客户端包含以下度量指标：

endpoint.<host:port>.requests - 请求时延的 Timer
endpoint.<host:port>.queue-delay - 队列中待处理请求等待时间的 Timer
endpoint.<host:port>.queue-size - 实际队列大小的 Counter
endpoint.<host:port>.in-use - 实际进行中的请求/响应数量的 Counter
endpoint.<host:port>.ttfb - 请求结束到响应开始之间等待时间（TTFB）的 Timer

数据报套接字（Datagram Socket）度量指标

基础名称：vertx.datagram

sockets - 数据报套接字（Datagram Socket）数量的 Counter
exceptions - 异常发生次数的 Counter
bytes-written - 写入字节数的 Counter
<host>:<port>.bytes-read - 读取字节数的 Counter
- 该指标仅在数据报套接字处于监听状态时可用

池度量指标

基础名称：vertx.pools.<type>.<name>，其中 type 是池的类型（例如 worker、http、datasource），而 name 是池的名称（例如 vert.x-worker-thread）。

worker 类型的池是阻塞型 Worker 线程池。Vert.x 会暴露其 Worker 为 vert.x-worker-thread 和 vert.x-internal-blocking。通过 WorkerExecutor 创建的具名 Worker 执行器也会暴露。

http 类型的池是 HTTP 客户端连接池。

通过 Vert.x SQL 客户端创建的数据源（Datasource）暴露为 sql。

queue-delay - 测量获取资源延迟（即队列中等待时间）的 Timer
queue-size - 队列中实际等待者数量的 Counter
usage - 测量资源使用时长的 Timer
in-use - 实际使用的资源数量的 Counter
pool-ratio - 在用资源 / 池大小比率的 Gauge
max-pool-size - 最大池大小的 Gauge

当被测池的最大容量无法确定时，pool-ratio 和 max_pool_size 将不存在。

JMX

JMX 默认处于禁用状态。

若要使用 JMX，你需要显式启用它：

Vertx vertx = Vertx.vertx(new VertxOptions().setMetricsOptions(
    new DropwizardMetricsOptions().setJmxEnabled(true)
));

若通过命令行运行 Vert.x，可以通过取消 vertx 或 vertx.bat 脚本中 JMX_OPTS 行的注释来启用度量指标和 JMX：

JMX_OPTS="-Dcom.sun.management.jmxremote -Dvertx.metrics.options.jmxEnabled=true"

你可以配置创建 MBean 时所使用的域（domain）：

Vertx vertx = Vertx.vertx(new VertxOptions().setMetricsOptions(
    new DropwizardMetricsOptions().
        setJmxEnabled(true).
        setJmxDomain("mydomain")
));

在命令行中，只需将以下系统属性追加到你的应用程序（适用于 vertx CLI 和 Fat Jar）：

-Dvertx.metrics.options.jmxEnabled=true -Dvertx.metrics.options.jmxDomain=vertx

启用远程 JMX

若希望通过 JMX 远程暴露度量指标，你至少需要设置以下系统属性：

com.sun.management.jmxremote

如果从命令行运行，可以通过编辑 vertx 或 vertx.bat 并取消 JMX_OPTS 行的注释来完成。

有关配置 JMX 的更多信息，请参阅 Oracle JMX 文档。

若在公网服务器上运行 Vert.x，暴露远程 JMX 访问时请务必谨慎。

访问 Dropwizard Registry

在配置度量指标服务时，可以指定一个可选的 Registry 名称，以便将底层的 Dropwizard Registry 注册到 Dropwizard Shared Registry 中，方便你按需获取并使用该 Registry。

VertxOptions options = new VertxOptions().setMetricsOptions(
    new DropwizardMetricsOptions().setEnabled(true).setRegistryName("my-registry")
);
Vertx vertx = Vertx.vertx(options);
// 获取 Registry
MetricRegistry registry = SharedMetricRegistries.getOrCreate("my-registry");}

使用已存在的 Dropwizard Registry

你也可以选择复用已有的 Dropwizard Registry。为此，只需将 MetricRegistry 实例作为参数传递给 DropwizardMetricsOptions 对象的 setMetricRegistry 方法（通过 VertxOptions 进行配置）。

MetricRegistry metricRegistry = new MetricRegistry();
VertxOptions options = new VertxOptions().setMetricsOptions(
    new DropwizardMetricsOptions().setEnabled(true).setMetricRegistry(metricRegistry)
);
Vertx vertx = Vertx.vertx(options);

结合使用 Jolokia 与 Hawtio

Jolokia 是一个 JMX-HTTP 桥接器，提供了替代 JSR-160 连接器的方案。它采用基于代理（Agent）的方式，支持多种平台。除了基础的 JMX 操作外，它还通过批量请求等特性增强了 JMX 远程访问能力。

Hawtio 是一个模块化的 Web 控制台，用于消费 Jolokia 暴露的数据。它可以让你创建仪表盘，并从 JMX 中获取内存、CPU 或任何 Vert.x 度量指标等数据。

本节介绍如何配置你的 Vert.x 应用程序以在 Hawtio 中获取度量指标。

首先，你需要使用以下选项配置你的 Vert.x 实例：

Vertx vertx = Vertx.vertx(new VertxOptions().setMetricsOptions(
    new DropwizardMetricsOptions()
        .setEnabled(true)
        .setJmxEnabled(true)
        .setJmxDomain("vertx-metrics")));

你可以将域更改为任何所需名称。该配置同样适用于集群化 Vert.x 实例。此配置指示 vertx-dropwizard-metrics 在本地 MBean 服务器中暴露度量指标，以便 Jolokia 获取它们。

接下来，你需要接入（plug）Jolokia 来暴露数据。接入 Jolokia 有多种方式，详见更多细节。在此，我们介绍如何使用默认配置的 Jolokia Agent。请参阅 Jolokia 文档了解如何进行配置。

Agent 既可以在启动应用程序时挂载，也可以附加到运行中的 JVM 上（这需要拥有访问该进程的特定权限）。对于第一种情况，启动应用程序时使用：

java -javaagent:/.../agents/jolokia-jvm.jar=port=7777,host=localhost -jar ...

-javaagent 指定 Jolokia Agent JAR 文件的路径。你可以通过命令行配置端口和主机。在此示例中，它在 http://localhost:7777 注册 REST 端点。

你也可以通过以下命令将 Agent 附加到正在运行的 JVM 上：

java -jar jolokia-jvm.jar start PID

将 PID 替换为该 JVM 的进程 ID。

在 Jolokia 配置并启动后，你就可以在 Hawtio 中消费这些数据了。

在 Hawtio 中，输入如下连接详细信息：

然后，你可以进入 JMX 选项卡，在其中应该能找到一个以你在 Vert.x 配置中输入的 JMX 域名命名的目录：

在此基础上，你可以配置自己的仪表盘，并获取 Vert.x 暴露的任何度量指标。

结合使用 Jolokia 与 JMX4Perl 将度量指标暴露给 Nagios

Check_jmx4perl 是一个 Nagios 插件，使用 jmx4perl 远程访问 JMX 数据。它可以让你将 Vert.x 度量指标暴露给 Nagios。

首先，你需要挂载 Jolokia JVM Agent 启动应用程序。接入 Jolokia 有多种方式，详见更多细节。在此，我们介绍如何使用默认配置的 Jolokia Agent。请参阅 Jolokia 文档了解如何进行配置。