监控

指标

本项目实现了 Vert.x 指标服务提供者接口（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 核心定义了用于报告指标的 SPI（例如本项目中实现），但它没有定义用于检索指标的 API（因为某些指标收集器只进行报告，没有其他功能）。

MetricsService 在 Dropwizard Registry 之前提供了一个 API，用于获取指标数据快照。

命名

下面列出的每个被测量组件（Vertx 除外）都将有一个关联的基名称。每个指标都可以通过提供完整的限定名称 <fqn> baseName + . + metricName 从 Vertx 中检索。

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();
// set up server
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 // any json value
}

Counter（计数器）

{
  "type"  : "counter",
  "count" : 1 // number
}

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" // string representing rate
}

ThroughputMeter（吞吐量计量器）

扩展 Meter（计量器）以提供即时吞吐量。

{
  "type"              : "meter",
  "count"             : 40 // long
  "meanRate"          : 2.0 // double
  "oneSecondRate"     : 3 // long - number of occurence for the last second
  "oneMinuteRate"     : 1.0 // double
  "fiveMinuteRate"    : 1.0 // double
  "fifteenMinuteRate" : 1.0 // double
  "rate"              : "events/second" // string representing rate
}

Timer（计时器）

计时器基本上是 Histogram（直方图） + Meter（计量器）的组合。

{
  "type": "timer",

  // histogram data
  "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 data
  "meanRate"          : 1.0 // double
  "oneMinuteRate"     : 1.0 // double
  "fiveMinuteRate"    : 1.0 // double
  "fifteenMinuteRate" : 1.0 // double
  "rate"              : "events/second" // string representing rate
}

Throughput Timer（吞吐量计时器）

扩展 Timer（计时器）以提供即时吞吐量指标。

{
  "type": "timer",

  // histogram data
  "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 data
  "meanRate"          : 1.0 // double
  "oneSecondRate"     : 3 // long - number of occurence for the last second
  "oneMinuteRate"     : 1.0 // double
  "fiveMinuteRate"    : 1.0 // double
  "fifteenMinuteRate" : 1.0 // double
  "rate"              : "events/second" // string representing rate
}

指标

目前提供以下指标。

Vert.x 指标

提供以下指标

vertx.event-loop-size - 事件循环池中线程数量的 Gauge（度量计）
vertx.worker-pool-size - 工作池中线程数量的 Gauge（度量计）
vertx.cluster-host - cluster-host 设置的 Gauge（度量计）
vertx.cluster-port - cluster-port 设置的 Gauge（度量计）

HTTP 服务器指标

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

HTTP 服务器包括 Net 服务器的所有指标以及以下指标

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 等）在注册表中设置单独的条目可能没有意义，而是需要一个汇总的条目。为此，您可以为匹配实例设置一个别名，在这种情况下，别名将用作注册表名称的一部分，而不是 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 本身不报告任何路由信息。与 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，字节表示请求/响应的主体，因此会忽略头部等。

HTTP 客户端指标

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

HTTP 客户端包括 HTTP 服务器的所有指标以及以下指标

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 - 请求结束和响应开始之间等待时间的 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 服务器的所有指标

客户端指标

基名称：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 - 请求结束和响应开始之间等待时间的 Timer（计时器）

数据报套接字指标

基名称：vertx.datagram

sockets - 数据报套接字数量的 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_ 类型的池是阻塞工作池。Vert.x 将其工作池暴露为 _vert.x-worker-thread_ 和 _vert.x-internal-blocking_。使用 WorkerExecutor 创建的命名工作执行器也会被暴露。

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

使用 Vert.x SQL 客户端创建的数据源暴露为 _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 的域

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

在命令行中，只需将以下系统属性附加到您的应用程序（适用于 vertx CLI 和胖 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

配置指标服务时，可以指定一个可选的注册表名称，用于在 Dropwizard 共享注册表中注册底层 Dropwizard Registry，以便您可以检索此注册表并根据您的需要使用。

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

使用已存在的 Dropwizard Registry

可选地，可以使用已存在的 Dropwizard Registry。为此，请将 MetricRegistry 实例作为参数传递给 VertxOptions 对象中的 setMetricRegistry 函数。

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 连接器的替代方案。它是一种基于代理的方法，支持多种平台。除了基本的 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 可以检索它们。

然后，您需要 _插入_ Jolokia 以暴露数据。有多种方法可以 _插入_ Jolokia。请参阅以获取更多详细信息。在这里，我们解释如何使用默认配置的 Jolokia 代理。请参阅 Jolokia 文档以配置它。

代理可以在启动应用程序时附加，也可以在运行中的 JVM 上附加（您需要特殊权限才能访问该进程）。在第一种情况下，使用以下方式启动您的应用程序

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

-javaagent 指定 Jolokia 代理 JAR 文件的路径。您可以从命令行配置端口和主机。这里它在 https://:7777 上注册 REST 端点。

您也可以通过以下方式将代理附加到运行中的 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 代理。有多种方法可以附加 Jolokia。请参阅以获取更多详细信息。在这里，我们解释如何使用默认配置的 Jolokia 代理。请参阅 Jolokia 文档以配置它。