系统监控 (Monitoring)
你当前正在浏览历史版本 Vert.x 4.1.8 的文档。 访问本页面的 最新版本。

Vert.x Micrometer Metrics 度量指标

本项目是 Vert.x 度量指标服务提供者接口(SPI)的一种实现。 它使用 Micrometer 来管理度量指标并上报给多种后端。

特性

  • Vert.x 核心工具监控:TCP/HTTP 客户端与服务端、DatagramSocket 、EventBus 以及各类池(Pool)

  • 通过 Micrometer 支持用户自定义度量指标

  • 上报至 Micrometer 支持的任意后端

  • 内置针对 InfluxDB、https://prometheus.io/[Prometheus] 和 JMX 上报的配置选项。

InfluxDB

快速入门

类路径(Classpath)中必须包含 vertx-micrometer-metrics 和 micrometer-registry-influx 模块。

Maven 用户应在项目的 POM 文件中添加以下依赖:

<dependency>
  <groupId>io.vertx</groupId>
  <artifactId>vertx-micrometer-metrics</artifactId>
  <version>5.0.12</version>
</dependency>
<dependency>
  <groupId>io.micrometer</groupId>
  <artifactId>micrometer-registry-influx</artifactId>
  <version>${micrometer.version}</version>
</dependency>

Gradle 用户则在构建文件中添加:

compile 'io.vertx:vertx-micrometer-metrics:5.0.12'
compile 'io.micrometer:micrometer-registry-influx:${micrometer.version}'

配置示例

Vert.x 默认不会启用 SPI 实现。 你必须在 Vert.x 配置选项中启用度量指标收集。

Vertx vertx = Vertx.vertx(new VertxOptions().setMetricsOptions(
  new MicrometerMetricsOptions()
    .setInfluxDbOptions(new VertxInfluxDbOptions().setEnabled(true))
    .setEnabled(true)));

使用指定的 URI

Vertx vertx = Vertx.vertx(new VertxOptions().setMetricsOptions(
  new MicrometerMetricsOptions()
    .setInfluxDbOptions(new VertxInfluxDbOptions().setEnabled(true)
      .setUri("http://influxdb.example.com:8888"))
    .setEnabled(true)));

连接到 InfluxDB V2

连接到 InfluxDB V2 需要至少设置 org 属性。

Vertx vertx = Vertx.vertx(new VertxOptions().setMetricsOptions(
  new MicrometerMetricsOptions()
    .setInfluxDbOptions(new VertxInfluxDbOptions().setEnabled(true)
      .setOrg("my-org"))
    .setEnabled(true)));

使用指定的数据库名称或存储桶(Bucket)

要配置指定的数据库名称:

Vertx vertx = Vertx.vertx(new VertxOptions().setMetricsOptions(
  new MicrometerMetricsOptions()
    .setInfluxDbOptions(new VertxInfluxDbOptions().setEnabled(true)
      .setDb("sales-department"))
    .setEnabled(true)));

对于 InfluxDB V2,你也可以使用 setBucket。

配置身份认证

可以通过用户名和密码配置身份认证:

Vertx vertx = Vertx.vertx(new VertxOptions().setMetricsOptions(
  new MicrometerMetricsOptions()
    .setInfluxDbOptions(new VertxInfluxDbOptions().setEnabled(true)
      .setUserName("username")
      .setPassword("password"))
    .setEnabled(true)));

或者也可以通过 Token 进行配置:

Vertx vertx = Vertx.vertx(new VertxOptions().setMetricsOptions(
  new MicrometerMetricsOptions()
    .setInfluxDbOptions(new VertxInfluxDbOptions().setEnabled(true)
      .setToken(authToken))
    .setEnabled(true)));

Prometheus

快速入门

类路径中必须包含 vertx-micrometer-metrics 和 micrometer-registry-prometheus 模块。 为了暴露度量指标,你大概率还需要引入 vertx-web。

Maven 用户应在项目的 POM 文件中添加以下依赖:

<dependency>
  <groupId>io.vertx</groupId>
  <artifactId>vertx-micrometer-metrics</artifactId>
  <version>5.0.12</version>
</dependency>
<dependency>
  <groupId>io.micrometer</groupId>
  <artifactId>micrometer-registry-prometheus</artifactId>
  <version>${micrometer.version}</version>
</dependency>

Gradle 用户则在构建文件中添加:

compile 'io.vertx:vertx-micrometer-metrics:5.0.12'
compile 'io.micrometer:micrometer-registry-prometheus:${micrometer.version}'

配置示例

Vert.x 默认不会启用 SPI 实现。你必须在 Vert.x 配置选项中启用度量指标收集。

Vertx vertx = Vertx.vertx(new VertxOptions().setMetricsOptions(
  new MicrometerMetricsOptions()
    .setPrometheusOptions(new VertxPrometheusOptions().setEnabled(true))
    .setEnabled(true)));

使用带有自定义端点的嵌入式 HTTP 服务端

Vertx vertx = Vertx.vertx(new VertxOptions().setMetricsOptions(
  new MicrometerMetricsOptions()
    .setPrometheusOptions(new VertxPrometheusOptions().setEnabled(true)
      .setStartEmbeddedServer(true)
      .setEmbeddedServerOptions(new HttpServerOptions().setPort(8080))
      .setEmbeddedServerEndpoint("/metrics/vertx"))
    .setEnabled(true)));

若未指定嵌入式服务端端点,则默认为 /metrics。

使用自定义 HTTP 服务端

PrometheusRequestHandler 为抓取和提供 Prometheus 度量指标提供了灵活性。

vertx.createHttpServer()
  .requestHandler(PrometheusRequestHandler.create(prometheusMeterRegistry, "/metrics/prometheus"))
  .listen(8888);

将度量指标绑定到现有的 Vert.x Web 路由器

Vertx vertx = Vertx.vertx(new VertxOptions().setMetricsOptions(
  new MicrometerMetricsOptions()
    .setPrometheusOptions(new VertxPrometheusOptions().setEnabled(true))
    .setEnabled(true)));

// 稍后创建路由器
Router router = Router.router(vertx);
router.route("/metrics").handler(PrometheusScrapingHandler.create());
vertx.createHttpServer().requestHandler(router).listen(8080);

JMX

快速入门

类路径中必须包含 vertx-micrometer-metrics 和 micrometer-registry-jmx 模块。

Maven 用户应在项目的 POM 文件中添加以下依赖:

<dependency>
  <groupId>io.vertx</groupId>
  <artifactId>vertx-micrometer-metrics</artifactId>
  <version>5.0.12</version>
</dependency>
<dependency>
  <groupId>io.micrometer</groupId>
  <artifactId>micrometer-registry-jmx</artifactId>
  <version>${micrometer.version}</version>
</dependency>

Gradle 用户则在构建文件中添加:

compile 'io.vertx:vertx-micrometer-metrics:5.0.12'
compile 'io.micrometer:micrometer-registry-jmx:${micrometer.version}'

配置示例

Vert.x 默认不会启用 SPI 实现。你必须在 Vert.x 配置选项中启用度量指标收集。

Vertx vertx = Vertx.vertx(new VertxOptions().setMetricsOptions(
  new MicrometerMetricsOptions()
    .setJmxMetricsOptions(new VertxJmxMetricsOptions().setEnabled(true))
    .setEnabled(true)));

配置 step 与 domain

在 Micrometer 中,step 指的是上报周期(以秒为单位)。domain 则是注册 MBean 所使用的 JMX 域。

Vertx vertx = Vertx.vertx(new VertxOptions().setMetricsOptions(
  new MicrometerMetricsOptions()
    .setJmxMetricsOptions(new VertxJmxMetricsOptions().setEnabled(true)
      .setStep(5)
      .setDomain("my.metrics.domain"))
    .setEnabled(true)));

其他后端或组合

即使 Vert.x 选项中未实现 Micrometer 支持的所有后端,你仍然可以创建任何 Micrometer Registry 并将其传递给 Vert.x。

可用后端列表包括 Graphite、Ganglia、Atlas 等。 它还支持使用 Micrometer Composite Registry,以便将相同的度量指标上报到多个后端。

在此示例中,度量指标同时上报给 JMX 和 Graphite:

CompositeMeterRegistry myRegistry = new CompositeMeterRegistry();
myRegistry.add(new JmxMeterRegistry(s -> null, Clock.SYSTEM));
myRegistry.add(new GraphiteMeterRegistry(s -> null, Clock.SYSTEM));

Vertx vertx = Vertx.builder()
  .with(new VertxOptions()
    .setMetricsOptions(new MicrometerMetricsOptions()
      .setEnabled(true)))
  .withMetrics(new MicrometerMetricsFactory(myRegistry))
  .build();

高级用法

有关选项的详尽列表,请参阅 MicrometerMetricsOptions。

Prometheus 中的平均值与分位数

默认情况下,使用 Prometheus Registry 时,直方图(Histogram)类型的度量指标不会包含平均值或分位数统计数据。

平均值并不是开箱即用的,但通常可以在查询时使用 promql 进行计算。例如,过去 5 分钟内 HTTP 客户端响应时间的平均值:

  rate(vertx_http_client_response_time_seconds_sum[5m])
/
  rate(vertx_http_client_response_time_seconds_count[5m])

要计算分位数,有两种可选方案。第一种是全局激活分位数统计,以便用于 Prometheus 的 histogram_quantile 函数:

Vertx vertx = Vertx.vertx(new VertxOptions().setMetricsOptions(
  new MicrometerMetricsOptions()
    .setPrometheusOptions(new VertxPrometheusOptions().setEnabled(true)
      .setPublishQuantiles(true))
    .setEnabled(true)));

然后,例如查询过去 5 分钟内 HTTP 客户端响应时间的第 99 百分位数的 promql 如下:

  histogram_quantile(0.99, sum(rate(vertx_http_client_response_time_seconds_bucket[5m])) by (le))

该方案的优势在于可以在 promql 中利用它跨维度进行聚合。 其缺点是在底层会为统计信息创建大量的时序数据(Time-series)。

第二种方案是创建有限的统计数据,且不能跨维度聚合。 这需要直接访问 Micrometer / Prometheus Registry:

PrometheusMeterRegistry registry = (PrometheusMeterRegistry) BackendRegistries.getDefaultNow();
registry.config().meterFilter(
  new MeterFilter() {
    @Override
    public DistributionStatisticConfig configure(Meter.Id id, DistributionStatisticConfig config) {
      return DistributionStatisticConfig.builder()
        .percentiles(0.95, 0.99)
        .build()
        .merge(config);
    }
  });

另请参阅更多关于直方图与百分位数的内容:

此外,你还可以查看一些 完整可运行的示例。 它们附带了关于配置 Prometheus 并在 Grafana 中查看仪表板的简要说明。

禁用部分度量指标域

限制受监控的 Vert.x 模块可以通过 disabledMetricsCategories 来完成。

有关度量域的完整列表,请参阅 MetricsDomain。

用户自定义度量指标

Micrometer Registry 是可访问的,以便创建新的度量指标或获取现有的度量指标。 默认情况下会使用唯一的 Registry,并在 JVM 的各个 Vert.x 实例之间共享:

MeterRegistry registry = BackendRegistries.getDefaultNow();

也可以通过在度量选项中指定 Registry 名称,为每个 Vert.x 实例使用独立的 Registry。 随后可以专门检索它:

Vertx vertx = Vertx.vertx(new VertxOptions().setMetricsOptions(
  new MicrometerMetricsOptions()
    .setInfluxDbOptions(new VertxInfluxDbOptions().setEnabled(true)) // 或 VertxPrometheusOptions
    .setRegistryName("my registry")
    .setEnabled(true)));

// 稍后:
MeterRegistry registry = BackendRegistries.getNow("my registry");

例如,以下是一个自定义 Timer,用于跟踪定期调用的某段代码的执行时间:

MeterRegistry registry = BackendRegistries.getDefaultNow();
Timer timer = Timer
  .builder("my.timer")
  .description("a description of what this timer does")
  .register(registry);

vertx.setPeriodic(1000, l -> {
  timer.record(() -> {
    // 在此处运行需要监控的操作
  });
});

有关 Micrometer Registry 以及如何创建度量指标的更多示例和文档,请查阅 Micrometer 文档。

复用现有的 Registry

可以复用现有的 Micrometer Registry(或 Prometheus Java 客户端的 CollectorRegistry), 并通过 VertxBuilder 将其注入到 Vert.x 实例中:

PrometheusMeterRegistry registry = new PrometheusMeterRegistry(PrometheusConfig.DEFAULT);

// 你也可以复用来自 Prometheus Java 客户端的现有 registry:
PrometheusRegistry prometheusClientRegistry = new PrometheusRegistry();
registry = new PrometheusMeterRegistry(PrometheusConfig.DEFAULT, prometheusClientRegistry, Clock.SYSTEM);

// 在 MicrometerMetricsOptions 中复用。
// 此处配置的 Prometheus 选项(如 "setPublishQuantiles(true)")将影响整个 registry。
Vertx.builder()
  .with(new VertxOptions().setMetricsOptions(
    new MicrometerMetricsOptions()
      .setPrometheusOptions(new VertxPrometheusOptions().setEnabled(true)
        .setPublishQuantiles(true))
      .setEnabled(true)))
  .withMetrics(new MicrometerMetricsFactory(registry))
  .build();

Vert.x Micrometer Metrics 为标签匹配注册了 Meter Filter。 自 Micrometer 1.13 起,如果在注册 Meter 之后才配置 MeterFilter,https://github.com/micrometer-metrics/micrometer/pull/4917[会记录一条警告日志]。

为避免出现该警告,请确保仅在 Vert.x Micrometer Metrics 初始化之后再注册你自己的 Meter。

JVM 与系统度量指标

Vert.x Micrometer Metrics 可以配置为收集 JVM 和系统度量指标:

metricsOptions.setJvmMetricsEnabled(true);

Netty 度量指标

Vert.x 依赖 Netty 作为网络层。

Vert.x Micrometer Metrics 可以配置为收集 Netty 度量指标:

metricsOptions.setNettyMetricsEnabled(true);

收集的度量数据与 Vert.x 特定的字节缓冲区分配器(Byte buffer allocator)和 Event Loop 线程组相关。

其他插桩度量

由于提供了对 Micrometer Registry 的直接访问,因此可以充分利用 Micrometer API:

MeterRegistry registry = BackendRegistries.getDefaultNow();
DiskSpaceMetrics metrics = new DiskSpaceMetrics(new File("/opt/myapp/data"));
metrics.bindTo(registry);

度量指标名称

Vert.x 提供的每个度量指标都可以通过度量选项进行重命名,使用 MetricsNaming 和 setMetricsNaming。

标签与匹配器

Vert.x Micrometer Metrics 定义了一组标签(Label,亦称为 Tag 或字段),用于为度量指标提供维度支持。例如,与 Event Bus 消息相关的度量指标具有 address 标签,这样就可以查询特定 Event Bus 地址的时序数据、按地址比较时序数据,或执行查询 API 允许的任何聚合操作。

在设置度量选项时,你可以指定要启用或禁用的标签:

Vertx vertx = Vertx.vertx(new VertxOptions().setMetricsOptions(
  new MicrometerMetricsOptions()
    .setPrometheusOptions(new VertxPrometheusOptions().setEnabled(true))
    .setLabels(EnumSet.of(Label.REMOTE, Label.LOCAL, Label.HTTP_CODE, Label.HTTP_PATH))
    .setEnabled(true)));

标签的完整列表详见:Label。

启用标签可能会导致值的高基数(High cardinality),这可能会给度量指标后端带来麻烦并影响性能。 因此必须谨慎使用。 通常情况下,当可能取值的集合是有界的时,启用标签是没问题的。

出于这个原因,默认启用的标签仅限于已知取值有界的那些。

除了单纯启用/禁用之外,还可以对标签进行更深入的交互。主要有两种方式:

使用匹配器(Matcher)

可以使用 Match 对象,通过与精确字符串或正则表达式进行匹配(前者更高效),来过滤或重命名某些标签值。

以下是一个将 HTTP 服务端度量指标限制为仅包含标签 local=localhost:8080 的示例:

Vertx vertx = Vertx.vertx(new VertxOptions().setMetricsOptions(
  new MicrometerMetricsOptions()
    .setPrometheusOptions(new VertxPrometheusOptions().setEnabled(true))
    .addLabelMatch(new Match()
      // 仅将 HTTP 服务端度量指标限制为带有标签 "local=localhost:8080" 的指标
      .setDomain(MetricsDomain.HTTP_SERVER)
      .setLabel("local")
      .setValue("localhost:8080"))
    .setEnabled(true)));

在 Match 中指定 alias 时,将使用别名重命名标签值而不是进行过滤。

匹配器在通过配置控制标签时特别有用,因为它们是通过 MicrometerMetricsOptions 进行设置的。

使用 Micrometer 的 MeterFilter

可以直接访问 Micrometer 的 MeterFilter API 来定义标签规则。 与 Matcher 相比,它在操作标签方面提供了更多特性,但无法直接从配置中定义。 因此两者各有利弊。

以下是一个使用正则表达式将 HTTP 请求的实际 path 标签替换为通用形式的示例:

MeterRegistry registry = BackendRegistries.getDefaultNow();
Pattern pattern = Pattern.compile("/foo/bar/.*");

registry.config().meterFilter(
  MeterFilter.replaceTagValues(Label.HTTP_PATH.toString(), actualPath -> {
    Matcher m = pattern.matcher(actualPath);
    if (m.matches()) {
      return "/foo/bar/:id";
    }
    return actualPath;
  }, ""));
Matcher 在底层使用了 MeterFilter。

自定义 Tag 提供者

你可以定义一个函数,为 HTTP 服务端或客户端度量指标生成额外的 Tag(或标签)。 该函数接收一个 HttpRequest 对象作为参数,并返回 一个包含 Tag 的 Iterable。

例如,以下演示了如何在服务端和客户端度量指标中将 x-user 请求头映射为自定义标签 user:

Vertx vertx = Vertx.vertx(new VertxOptions().setMetricsOptions(
  new MicrometerMetricsOptions()
    .setPrometheusOptions(new VertxPrometheusOptions().setEnabled(true))
    .setServerRequestTagsProvider(req -> {
      String user = req.headers().get("x-user");
      return Collections.singletonList(Tag.of("user", user));
    })
    .setClientRequestTagsProvider(req -> {
      String user = req.headers().get("x-user");
      return Collections.singletonList(Tag.of("user", user));
    })
    .setEnabled(true)));

快照(Snapshot)

可以通过 Measured 对象创建 MetricsService,以获取其相关度量指标和测量值的快照。 快照以 JsonObject 形式返回。

一个众所周知的 Measured 对象就是 Vertx:

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

其他组件,例如 EventBus 或 HttpServer,也是可测量的(Measurable):

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

最后,还可以根据度量指标的基础名称来过滤返回的指标:

MetricsService metricsService = MetricsService.create(vertx);
// 客户端 + 服务端
JsonObject metrics = metricsService.getMetricsSnapshot("vertx.http");
System.out.println(metrics);

Vert.x Core 度量指标

本节列出了监控 Vert.x 核心工具所生成的所有度量指标。

不同的度量指标后端在命名指标时可能遵循不同的规范或规则。 下面描述的名称是 Vert.x 4 中使用的默认名称,采用下划线分隔符。 实际名称可能会因度量指标后端而异。

TCP 客户端

度量指标名称 标签(Labels) 类型 描述

vertx_net_client_bytes_read

local, remote

Counter

从远端主机接收的字节数。

vertx_net_client_bytes_written

local, remote

Counter

发送到远端主机的字节数。

vertx_net_client_active_connections

local, remote

Gauge

当前已打开的与远端主机的连接数。

vertx_net_client_errors

local, remote, class

Counter

错误数。

HTTP 客户端

度量指标名称 标签(Labels) 类型 描述

vertx_http_client_bytes_read

local, remote

Counter

从远端主机接收的字节数。

vertx_http_client_bytes_written

local, remote

Counter

发送到远端主机的字节数。

vertx_http_client_active_connections

local, remote

Gauge

当前已打开的与远端主机的连接数。

vertx_http_client_errors

local, remote, class

Counter

错误数。

vertx_http_client_active_requests

local, remote, path, method

Gauge

正在处理并等待响应的请求数。

vertx_http_client_requests_total

local, remote, path, method

Counter

已发送的请求数。

vertx_http_client_request_bytes

local, remote, path, method

Summary

请求的字节大小。

vertx_http_client_response_time_seconds

local, remote, path, method, code

Timer

响应时间(以秒为单位)。

vertx_http_client_responses_total

local, remote, path, method, code

Counter

接收到的响应数。

vertx_http_client_response_bytes

local, remote, path, method, code

Summary

响应的字节大小。

vertx_http_client_active_ws_connections

local, remote

Gauge

当前已打开的 WebSocket 数量。

TCP 服务端

度量指标名称 标签(Labels) 类型 描述

vertx_net_server_bytes_read

local, remote

Counter

Net 服务端接收的字节数。

vertx_net_server_bytes_written

local, remote

Counter

Net 服务端发送的字节数。

vertx_net_server_active_connections

local, remote

Gauge

与 Net 服务端建立的打开连接数。

vertx_net_server_errors

local, remote, class

Counter

错误数。

HTTP 服务端

度量指标名称 标签(Labels) 类型 描述

vertx_http_server_bytes_read

local, remote

Counter

HTTP 服务端接收的字节数。

vertx_http_server_bytes_written

local, remote

Counter

HTTP 服务端发送的字节数。

vertx_http_server_active_connections

local, remote

Gauge

与 HTTP 服务端建立的打开连接数。

vertx_http_server_errors

local, remote, class

Counter

错误数。

vertx_http_server_active_requests

local, remote, path, method

Gauge

正在处理的请求数。

vertx_http_server_requests_total

local, remote, path, method, code, route

Counter

已处理的请求数。

vertx_http_server_request_resets_total

local, remote, path, method

Counter

请求重置(Reset)的次数。

vertx_http_server_request_bytes

local, remote, path, method

Summary

请求的字节大小。

vertx_http_server_response_time_seconds

local, remote, path, method, code, route

Timer

请求处理时间(以秒为单位)。

vertx_http_server_response_bytes

local, remote, path, method, code, route

Summary

响应的字节大小。

vertx_http_server_active_ws_connections

local, remote

Gauge

当前已打开的 WebSocket 数量。

数据报套接字(Datagram Socket)

度量指标名称 标签(Labels) 类型 描述

vertx_datagram_bytes_read

local

Summary

在 <host>:<port> 监听地址上接收的总字节数。

vertx_datagram_bytes_written

(无)

Summary

发送到远端主机的总字节数。

vertx_datagram_errors

class

Counter

错误总数。

Event Bus

度量指标名称 标签(Labels) 类型 描述

vertx_eventbus_bytes_read

address

Summary

从 Event Bus 集群对等节点读取消息时接收的总字节数。

vertx_eventbus_bytes_written

address

Summary

向 Event Bus 集群对等节点发送消息时发送的总字节数。

vertx_eventbus_handlers

address

Gauge

正在使用的 Event Bus Handler(处理器)数量。

vertx_eventbus_pending

address,side (local/remote)

Gauge

尚未处理的消息数。如果相应地址上注册了 N 个 Handler,发布一条消息将计为 N 个待处理消息。

vertx_eventbus_processed

address,side (local/remote)

Counter

已处理的消息数。

vertx_eventbus_published

address,side (local/remote)

Counter

发布的消息数(发布/订阅模式)。

vertx_eventbus_discarded

address,side (local/remote)

Counter

被丢弃的消息数(例如 Handler 注销时仍待处理的消息,或溢出的消息)。

vertx_eventbus_sent

address,side (local/remote)

Counter

发送的消息数(点对点模式)。

vertx_eventbus_received

address,side (local/remote)

Counter

接收到的消息数。

vertx_eventbus_delivered

address,side (local/remote)

Counter

已交付给 Handler 的消息数。

vertx_eventbus_reply_failures

address,failure

Counter

消息回复失败的次数。

Worker 池度量指标

Vert.x Worker 池公开的度量指标如池度量指标中所定义。

池类型(pool_type)为 worker。

Vert.x 预先创建了两个 Worker 池:worker-thread 和 internal-blocking。

通用度量指标

池度量指标

除核心 HTTP 客户端之外的 Vert.x 客户端可能会公开池度量指标。

度量指标名称 标签(Labels) 类型 描述

vertx_pool_queue_time_seconds

pool_type,pool_name

Timer

在队列中等待处理所花费的时间(以秒为单位)。

vertx_pool_queue_pending

pool_type,pool_name

Gauge

队列中待处理的元素数量。

vertx_pool_usage

pool_type,pool_name

Timer

使用资源的时间(即 Worker 池的处理时间)。

vertx_pool_in_use

pool_type,pool_name

Gauge

已使用的资源数量。

vertx_pool_completed

pool_type,pool_name

Counter

使用该资源已完成的元素数量(即 Worker 池执行的任务总数)。

vertx_pool_ratio

pool_type,pool_name

Gauge

池使用比率,仅在能够确定最大池大小时提供。

客户端度量指标

除核心 HTTP / Net 客户端之外的 Vert.x 客户端可以实现一套标准的客户端度量指标。

此类客户端度量指标以“客户端类型(Client type)”标识符命名,在下表中显示为 $TYPE。

namespace 标签的具体含义由客户端实现自行决定。

度量指标名称 标签(Labels) 类型 描述

vertx_$TYPE_queue_pending

remote, namespace

Gauge

队列中待处理的元素数量。

vertx_$TYPE_queue_time_seconds

remote, namespace

Timer

在队列中等待处理所花费的时间(以秒为单位)。

vertx_$TYPE_processing_pending

remote, namespace

Gauge

正在处理的元素数量。

vertx_$TYPE_processing_time_seconds

remote, namespace

Timer

从请求开始到响应结束的处理时间(以秒为单位)。

vertx_$TYPE_resets_total

remote, namespace

Counter

重置(Reset)总次数。

数据库客户端度量指标

以下客户端公开了客户端度量指标以及可选的池度量指标。

  • Vert.x SQL 客户端

  • Vert.x Redis 客户端

  • …​

池度量指标带有一个 pool_type,例如 SQL 客户端使用 sql 类型

  • vertx.pool.queue.pending,其 pool_type=sql

  • vertx.pool.queue.time,其 pool_type=sql

  • vertx.pool.usage,其 pool_type=sql

  • vertx.pool.ratio,其 pool_type=sql

  • vertx.pool.completed,其 pool_type=sql

  • vertx.pool.in.use,其 pool_type=sql

客户端度量指标类型出现在度量指标名称中

  • vertx.sql.processing.pending

  • vertx.sql.processing.time

为了区分各个池,你可以在 PoolOptions 上设置一个池名称,它将作为标签公开

  • vertx.pool.queue.pending,其 pool_type=sql 且 pool_name=the-pool-name

  • vertx.pool.queue.time,其 pool_type=sql 且 pool_name=the-pool-name

  • vertx.pool.usage,其 pool_type=sql 且 pool_name=the-pool-name

  • vertx.pool.ratio,其 pool_type=sql 且 pool_name=the-pool-name

  • vertx.pool.completed,其 pool_type=sql 且 pool_name=the-pool-name

  • vertx.pool.in.use,其 pool_type=sql 且 pool_name=the-pool-name

同样地,客户端度量指标使用命名空间(Namespace)来区分彼此

  • vertx.sql.processing.pending,其 client_namespace=the-client-name

  • vertx.sql.processing.time,其 client_namespace=the-client-name

必须配置 Micrometer 以公开这些标签

micrometerMetricsOptions.addLabels(Label.POOL_NAME);
micrometerMetricsOptions.addLabels(Label.NAMESPACE);

Vert.x SQL 客户端

Vert.x SQL 客户端使用 sql 类型。

使用 PoolOptions#setName(String) 命名该池

poolOptions.setName("the-pool-name");

同样,使用 SqlConnectOptions#setMetricsName(String) 来限定客户端度量指标的作用域

connectOptions.setMetricsName("the-client-name");

Vert.x Redis 客户端

Vert.x Redis 客户端使用 redis 类型。

使用 RedisOptions#setPoolName(String) 命名该池

redisOptions.setPoolName("the-pool-name");

同样,使用 RedisOptions#setMetricsName(String) 来限定客户端度量指标的作用域

redisOptions.setMetricsName("the-client-name");

其他杂项

关于 Gauge 已被注册的警告

在日志中,你可能会发现类似如下的消息:

[vert.x-eventloop-thread-0] WARN io.micrometer.core.instrument.MeterRegistry - This Gauge has been already registered (MeterId{name='vertx.pool.queue.pending', tags=[tag(pool_name=localhost:37917),tag(pool_type=ws)]}), the registration will be ignored. Note that subsequent logs will be logged at debug level.

这是一个已知的 issue,但无需担心,它不会影响 Vert.x 上报数据的准确性。

简而言之,发生这种情况是因为 Micrometer 的 Gauge 限制,而 Vert.x Micrometer Metrics 对此进行了规避处理。