Red Hat Summit 红帽全球峰会支持控制台（Console）开发人员开始试用联系人

在 Quarkus 应用程序中收集指标

Red Hat build of Quarkus 2.2

指南

摘要

了解如何使用 Micrometer 和 Prometheus 在 Quarkus 中收集指标。

前言
复制链接

作为应用程序开发人员，您可以使用 Micrometer 来收集指标，以提高 Quarkus 应用程序的性能。

先决条件

  • 已安装了 OpenJDK(JDK)11，以及 JAVA_HOME 环境变量指定的 Java SDK 的位置。

    • 登录红帽客户门户网站，从 Software Downloads 页面下载 Open JDK 的 Red Hat build。
  • 已安装 Apache Maven 3.6.2 或更高版本。Maven 可以从 Apache Maven Project 网站获得。

对红帽文档提供反馈
复制链接

我们非常感谢您对我们的技术内容提供反馈，并鼓励您告诉我们您的想法。如果您想添加评论，提供见解、纠正拼写错误甚至询问问题，您可以在文档中直接这样做。

注意

您必须有一个红帽帐户并登录到客户门户网站。

要从客户门户网站提交文档反馈，请执行以下操作：

  1. 选择 Multi-page HTML 格式。
  2. 点文档右上角的 反馈 按钮。
  3. 突出显示您要提供反馈的文本部分。
  4. 点高亮文本旁的添加反馈对话框。
  5. 在页面右侧的文本框中输入您的反馈，然后单击 Submit。

每次提交反馈时，我们都会自动创建跟踪问题。打开在点 Submit 后显示的链接，并开始监视问题或添加更多注释。

感谢您的宝贵反馈。

使开源包含更多
复制链接

红帽致力于替换我们的代码、文档和 Web 属性中存在问题的语言。我们从这四个术语开始：master、slave、黑名单和白名单。由于此项工作十分艰巨，这些更改将在即将推出的几个发行版本中逐步实施。有关更多详情，请参阅我们的首席技术官 Chris Wright 提供的消息。

第 1 章 Quarkus 应用程序的指标集合
复制链接

指标是应用程序的特定方面的定量测量，用于观察趋势和行为。单个测量以固定间隔收集，每个由字符串键和附加（可选）标签或标签标识的每个数值。

这些键值对随后附加到一个时间序列：随时间索引的一系列数据点。捕获和分析指标，可帮助您在问题升级前找出潜在的问题并造成更严重的问题。

注意

指标无法用于诊断或问题确定问题。视觉化工具聚合单个测量，以提供趋势的视觉化呈现。特定于事件的上下文需要在聚合的指标数据中发现观察问题的原因；您需要更详细的跟踪或日志数据以便确定问题确定或根本原因分析。

您可以使用 Micrometer 库或 SmallRye Metrics 规格来收集运行时和应用程序指标：

  • Micrometer 为众所周知的监控系统提供了简单的常见问题解答。带有 Prometheus 的 Quarkus 对 Micrometer 对，以帮助您监控和管理应用程序。
  • SmallRye Metrics 是 MicroProfile 指标规范的实现，提供与 Prometheus 兼容的指标端点。

Micrometer 扩展是推荐在 Quarkus 中收集应用程序和运行时指标的方法，并提供以下功能：

  • 维度指标 - 定时器、测量、计数器、配送和长任务计时器的厂商中立接口，以及长任务计时器，当与维度监控系统相连接时，允许有效地访问特定指定指标，并能够在其维度分析方面深入到一定程度上。
  • 预先配置的绑定 - 开箱即用检测缓存、类加载程序、垃圾回收、处理器利用率、线程池和 HTTP 流量。其他扩展（如 hibernate-orm 和 mongodb-client ）在启用时自动提供额外的绑定。

第 2 章 在 Quarkus 应用程序中公开指标
复制链接

使用 micrometer 扩展在 Quarkus 1.11 中启用指标。启用它后，会使用 /q/metrics 端点查看 micrometer 扩展收集的所有指标的实时值。默认情况下，此端点仅以纯文本形式响应。

流程

  1. 将 quarkus-micrometer-registry-prometheus 扩展作为依赖项添加到应用程序中： 

    ./mvnw quarkus:add-extension -Dextensions="io.quarkus:quarkus-micrometer-registry-prometheus"
    Copy to Clipboard Toggle word wrap

    这个命令将以下依赖项添加到您的 pom.xml 中：

    pom.xml

    <dependency>
      <groupId>io.quarkus</groupId>
    <artifactId>quarkus-micrometer-registry-prometheus</artifactId>
</dependency>
    Copy to Clipboard Toggle word wrap

  2. 输入以下命令在您的终端中显示收集的指标： 

    curl http://localhost:8080/q/metrics
    Copy to Clipboard Toggle word wrap

  3. （可选）要使用 Micrometer 扩展启用 JSON 格式的指标集合，请将以下行添加到 src/main/resources/application.properties 文件中： 

    quarkus.micrometer.export.json.enabled=true
    Copy to Clipboard Toggle word wrap
  4. 保存对 application.properties 文件的更改。

  5. 使用以下命令以 JSON 格式查看指标： 

    curl -i -H "Accept: application/json" -H "Content-Type: application/json"
http://localhost:8080/q/metrics
    Copy to Clipboard Toggle word wrap

第 3 章 Quarkus 应用程序的自定义指标
复制链接

Micrometer 提供了一个 API，供您自行构建自定义指标。监控系统支持的最常见量表类型是量表、计数器和摘要。以下小节构建示例端点，并使用这些基本计量类型观察端点行为。

要注册计量，您需要对 MeterRegistry 的引用，该 registry 由 Micrometer 扩展进行配置和维护。MeterRegistry 可以注入应用程序，如下所示： 

package org.acme.micrometer;

import io.micrometer.core.instrument.MeterRegistry;

import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.PathParam;
import javax.ws.rs.Produces;

@Path("/")
@Produces("text/plain")
public class ExampleResource {

    private final MeterRegistry registry;

    ExampleResource(MeterRegistry registry) {
        this.registry = registry;
    }
}
Copy to Clipboard Toggle word wrap

Micrometer 有惯例，必须创建计量，并使用点来分隔网段（如 a.name. like. this ）。然后 Micrometer 会将该名称转换为所选 registry 首选格式。Prometheus 使用下划线，这意味着前面的名称将显示为 a_name_like_ this，在 Prometheus 格式的指标输出中。

Micrometer 在唯一标识符和标记组合和特定计量实例之间维护内部映射。使用 注册、计数器 或其他方法来递增计数器或记录值不会创建新的计量实例，除非之前未看到标识符和标签值的组合。

量表

测量值可以随时间增加或减少，如回车的速度。在监控缓存或集合的统计信息时，量表很有用。请考虑以下一个简单的示例，它可观察列表的大小： 

    LinkedList<Long> list = new LinkedList<>();

    // Update the constructor to create the gauge
    ExampleResource(MeterRegistry registry) {
        this.registry = registry;
        registry.gaugeCollectionSize("example.list.size", Tags.empty(), list);
    }

    @GET
    @Path("gauge/{number}")
    public Long checkListSize(@PathParam("number") long number) {
        if (number == 2 || number % 2 == 0) {
            // add even numbers to the list
            list.add(number);
        } else {
            // remove items from the list for odd numbers
            try {
                number = list.removeFirst();
            } catch (NoSuchElementException nse) {
                number = 0;
            }
        }
        return number;
    }
Copy to Clipboard Toggle word wrap

使用 Prometheus 时，当访问 Prometheus 端点时，观察创建量表的值以及列表的大小。务必要注意，量表会被抽样，而不是设置 ; 与量表关联的值在测量之间可能会如何改变。

Micrometer 为创建量表提供了一些额外的机制。请注意，Micrometer 不会创建对它默认观察对象的强大引用。根据 registry，Micrometer 会省略量表，可观察已垃圾回收的对象或者将 NaN （而非数字）用作观察到的值。

永不计算可以计算的内容。量表的直接使用方式可能比计数器小。如果您测量什么值可以被计算（因为值始终递增），则改为使用计数器。

计数器

计数器用于测量仅增加的值。在以下示例中，您将计算测试次数以确定其是否为 prime 的次数： 

    @GET
    @Path("prime/{number}")
    public String checkIfPrime(@PathParam("number") long number) {
        if (number < 1) {
            return "Only natural numbers can be prime numbers.";
        }
        if (number == 1 || number == 2 || number % 2 == 0) {
            return number + " is not prime.";
        }

        if ( testPrimeNumber(number) ) {
            return number + " is prime.";
        } else {
            return number + " is not prime.";
        }
    }

    protected boolean testPrimeNumber(long number) {
        // Count the number of times we test for a prime number
        registry.counter("example.prime.number").increment();
        for (int i = 3; i < Math.floor(Math.sqrt(number)) + 1; i = i + 2) {
            if (number % i == 0) {
                return false;
            }
        }
        return true;
    }
Copy to Clipboard Toggle word wrap

可能会在指示检查值的计数器中添加标签或标签到计数器中。请记住，每个指标名称(testPrimeNumber)和标签值组合都会生成唯一的时间序列。使用未绑定的一组数据作为标签值可导致"通配符性增长"，在新时间序列创建时呈指数增加。

然而，可以添加一个标签来传达一些的更多信息。在以下示例中，进行了调整，计数器被移动来添加一个标签。 

    @GET
    @Path("prime/{number}")
    public String checkIfPrime(@PathParam("number") long number) {
        if (number < 1) {
            registry.counter("example.prime.number", "type", "not-natural").increment();
            return "Only natural numbers can be prime numbers.";
        }
        if (number == 1 ) {
            registry.counter("example.prime.number", "type", "one").increment();
            return number + " is not prime.";
        }
        if (number == 2 || number % 2 == 0) {
            registry.counter("example.prime.number", "type", "even").increment();
            return number + " is not prime.";
        }

        if ( testPrimeNumber(number) ) {
            registry.counter("example.prime.number", "type", "prime").increment();
            return number + " is prime.";
        } else {
            registry.counter("example.prime.number", "type", "not-prime").increment();
            return number + " is not prime.";
        }
    }

    protected boolean testPrimeNumber(long number) {
        for (int i = 3; i < Math.floor(Math.sqrt(number)) + 1; i = i + 2) {
            if (number % i == 0) {
                return false;
            }
        }
        return true;
    }
Copy to Clipboard Toggle word wrap

查看由此计数器生成的数据，您可以确定检查负数字的频率，或者数字一或一个数字，等等。尝试以下序列，并在纯文本输出中查找 example_prime_number_total。请注意，当 Micrometer 将 Prometheus 命名规则应用到 example.prime.number 时，会添加 _total 后缀。 

# If you did not leave quarkus running in dev mode, start it again:
./mvnw compile quarkus:dev

curl http://localhost:8080/example/prime/-1
curl http://localhost:8080/example/prime/0
curl http://localhost:8080/example/prime/1
curl http://localhost:8080/example/prime/2
curl http://localhost:8080/example/prime/3
curl http://localhost:8080/example/prime/15
curl http://localhost:8080/q/metrics
Copy to Clipboard Toggle word wrap

不得计算您可以时间或总结的内容。计数器仅记录一个计数，这可能是必需的。但是，如果您更好地了解值的改变方式，一个计时器（当基本测量单位是时），或者发布摘要可能更为合适。

概述和计时器

Micrometer 中的计时器和配送摘要非常相似。两者都允许您记录观察到的值，这将与其他记录值进行聚合，并作为总和存储。Micrometer 还递增计数器，以指示已记录的测量数，并在指定的时间间隔内跟踪观察到的值。

发行版摘要是通过调用 记录 方法以记录记录值的方式进行填充，而计时器则提供特定于时间和测量持续时间的额外功能。例如，我们可以使用一个计时器来测量使用 记录 方法之一总结调用供应商功能需要花费的时间长度： 

    protected boolean testPrimeNumber(long number) {
        Timer timer = registry.timer("example.prime.number.test");
        return timer.record(() -> {
            for (int i = 3; i < Math.floor(Math.sqrt(number)) + 1; i = i + 2) {
                if (number % i == 0) {
                    return false;
                }
            }
            return true;
        });
    }
Copy to Clipboard Toggle word wrap

Micrometer 将在为这个计时器发送指标时应用 Prometheus 约定。Prometheus 以秒为单位测量时间。Micrometer 将测量的时间转换为秒，并在指标名称中包含单位（按约定）。访问 prime 端点几次后，查看以下三个条目的纯文本输出： example_prime_number_seconds_count、example_ prime_number_seconds_sum、example_prime_number_test_seconds_ sum. 

# If you did not leave quarkus running in dev mode, start it again:
./mvnw compile quarkus:dev

curl http://localhost:8080/example/prime/256
curl http://localhost:8080/q/metrics
curl http://localhost:8080/example/prime/7919
curl http://localhost:8080/q/metrics
Copy to Clipboard Toggle word wrap

可以将计时器和配送摘要配置为发送其他统计信息，如直方数据、预计算百分比或服务级别目标(SLO)界限。请注意，计算、校验和以及直方数据可在度量（或在一系列实例之间或一系列实例之间）重新分配，而预先计算百分比的值。

第 4 章 HTTP 指标
复制链接

Micrometer 扩展自动为 HTTP 服务器请求。遵循 timers 的 Prometheus 命名约定，查找 http_server_requests_seconds_count、http_server_requests_seconds_sum 和 http_server_requests_seconds_max。为请求的 uri、HTTP 方法（GET、POST 等）、状态代码（200、302、404 等）和更常规的结果字段添加了标头标签。 

# HELP http_server_requests_seconds
# TYPE http_server_requests_seconds summary
http_server_requests_seconds_count{env="test",method="GET",outcome="SUCCESS",registry="prometheus",status="200",uri="/example/prime/{number}",} 6.0
http_server_requests_seconds_sum{env="test",method="GET",outcome="SUCCESS",registry="prometheus",status="200",uri="/example/prime/{number}",} 0.007355093
http_server_requests_seconds_count{env="test",method="GET",outcome="SUCCESS",registry="prometheus",status="200",uri="/example/gauge/{number}",} 4.0
http_server_requests_seconds_sum{env="test",method="GET",outcome="SUCCESS",registry="prometheus",status="200",uri="/example/gauge/{number}",} 0.005035393
# HELP http_server_requests_seconds_max
# TYPE http_server_requests_seconds_max gauge
http_server_requests_seconds_max{env="test",method="GET",outcome="SUCCESS",registry="prometheus",status="200",uri="/example/prime/{number}",} 0.002110405
http_server_requests_seconds_max{env="test",method="GET",outcome="SUCCESS",registry="prometheus",status="200",uri="/example/gauge/{number}",} 0.00239441
Copy to Clipboard Toggle word wrap

忽略端点

您可以使用 quarkus.micrometer.binder.http-server.ignore-patterns 属性来禁用 HTTP 端点的测量。此属性接受以逗号分隔的简单正则表达式列表，用于识别应忽略的 URI 路径。例如，设置 quarkus.micrometer.binder.http-server.ignore-patterns=/example/prime/[0-9]+ 将忽略对 http://localhost:8080/example/prime/7919 的请求。仍然会测量对 http://localhost:8080/example/gauge/7919 的请求。

URI 模板

Micrometer 扩展将在代表以模板形式表示路径参数的 URI 时做出最佳努力。使用以上 http://localhost:8080/example/prime/7919 的示例，到 http://localhost:8080/example/prime/7919 的请求应该显示为 http_server_requests_seconds_* 指标的属性，其标签为 uri=/example/prime/{number}。

如果无法确定正确的 URL，请使用 quarkus.micrometer.binder.http-server.match-patterns 属性。此属性接受以逗号分隔列表，定义简单正则表达式匹配模式和替换字符串之间的关联。例如，设置 quarkus.micrometer.binder.http-server.match-patterns=/example/prime/[0-9]+=/example/{jellybeans} 的值将值 /example/{jellybeans} 用于 uri 与 /example/prime/[0-9]+ 匹配时。

第 5 章 可靠性指标
复制链接

可靠性指标用于通过定量措施来表达软件产品的可靠性。您使用的指标取决于可靠性指标应用以及应用程序域要求的系统类型。从网站可靠性工程角度看，有一些关键指标专注于 Java 应用程序。

平均故障时间

mean Time to Failure(MTTF)是两个连续失败间隔的时间间隔。您用于衡量 MTTF 的时间单元取决于系统，还可按照事务数量进行定义。对于具有大型事务的系统，MTTF 通常一致。

要修复的时间

平均时间修复(MTTR)是跟踪导致失败并修复错误的平均时间。

平均故障间隔时间

当您合并 MTTF 和 MTTR 指标时，结果等于问题间延迟(MTBF)。时间测量是实时的，而不是 MTTF 中包含的执行时间。

Occurrence 故障率

Occurrence 的失败率(ROCOF)是单元时间间隔中发生的故障数，并关注经常发生、意外事件的可能性。

已弃用故障的可能性

Demand(POFOD)上的故障概率是系统在发出服务请求时会失败的概率。POFOD 是安全关键系统及偶尔需要服务保护系统的重要措施。

Availabiity

可用性测量系统可在任何给定时间使用的概率。您必须考虑修复时间和系统的重启时间。

第 6 章 与 OpenShift 集成
复制链接

您可以启用 Quarkus 应用程序，以将 Micrometer 指标库用于运行时和应用程序指标。Micrometer 的行为如同 Prometheus 等应用程序和第三方（如 Prometheus）之间，它们被嵌入到 OpenShift 中。使用 Quarkus 与 OpenShift 集成，不仅可以公开自动启用的嵌入式指标，还可以作为应用程序的一部分注册的自定义指标。

有关配置各种指标的更多信息，请参阅 Quarkus Micrometer 社区指南。

先决条件

  • 您可以访问 OpenShift CLI、4.6 或更高版本。
  • 您有一个 OpenShift 实例

流程

完成以下说明，并在 OpenShift 中使用内嵌的 Prometheus 从 Quarkus 应用程序公开指标：

  1. 在 OpenShift 中为用户定义的项目启用监控
  2. 将 Quarkus 应用程序部署到 OpenShift
  3. 在 OpenShift 项目中创建服务监控器

6.1. 在 OpenShift 中为用户定义的项目启用监控
复制链接

在 Red Hat OpenShift Container Platform 4.6 或更高版本中，您可以为用户定义的项目以及默认平台监控启用监控。

先决条件

  • 可以访问 OpenShift CLI, 4.6 或更高版本
  • 具有 OpenShift 实例

流程

  1. 进入 为用户定义的项目启用监控，并根据具体说明如何启用用户定义的项目监控。总之，您将在命名空间 openshift-monitoring中创建 ConfigMap

cluster-monitoring-config.yaml: 

apiVersion: v1
kind: ConfigMap
metadata:
    name: cluster-monitoring-config
    namespace: openshift-monitoring
data:
    config.yaml: |
    enableUserWorkload: true
Copy to Clipboard Toggle word wrap
注意

如果使用 OpenShift 4.5 或更早版本，请使用： 

apiVersion: v1
kind: ConfigMap
metadata:
    name: cluster-monitoring-config
    namespace: openshift-monitoring
data:
    config.yaml: |
    techPreviewUserWorkload:
        enabled: true
Copy to Clipboard Toggle word wrap

完成为用户定义的项目启用监控的步骤后，OpenShift 会自动创建一个命名空间 openshift-user-workload-monitoring，您将在开始将 Quarkus 应用程序部署到 OpenShift 并在 OpenShift 项目中创建服务监控器。

6.2. 将 Quarkus 应用程序部署到 OpenShift
复制链接

设置所需的基础架构后，您必须使用 Prometheus 启用 Micrometer。

先决条件

流程

  1. 实施 REST API： 

    <dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-resteasy</artifactId>
</dependency>
<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-micrometer-registry-prometheus</artifactId>
</dependency>
    Copy to Clipboard Toggle word wrap

  2. 添加微主题 registry 常见问题： 

    import javax.inject.Inject;
import javax.ws.rs.GET;
import javax.ws.rs.Path;

import io.micrometer.core.instrument.MeterRegistry;

@Path("/hello")
public class GreetingsResource {

    @Inject
    MeterRegistry registry;

    @GET
    public String sayHello() {
        registry.counter("greeting_counter").increment();

        return "Hello!";
    }
}
    Copy to Clipboard Toggle word wrap

    这个 Micrometer facade 创建了一个计数器，每次调用服务时都会递增。registry 可帮助创建自定义指标或手动使用指标。您还可以将方法注解如下： 

    @GET
@Counted(value = "greeting_counter")
public String sayHello() {
    return "Hello!";
}
    Copy to Clipboard Toggle word wrap

  3. 运行应用程序： 

    mvn compile quarkus:dev
    Copy to Clipboard Toggle word wrap

  4. 致电您的服务： 

    curl http://localhost:8080/hello
    Copy to Clipboard Toggle word wrap

    该服务应通过 Hello!

  5. 浏览至 http://localhost:8080/q/metrics您应该看到值为 1.0 的 greeting_counter （您刚刚完成的实例）： 

    # HELP greeting_counter_total
#TYPE greeting_counter_total counter
greeting_counter_total 1.0
    Copy to Clipboard Toggle word wrap

  6. 通过在 pom.xml 中输入扩展 quarkus-openshift，将 Quarkus 应用程序部署到 OpenShift 中： 

    <dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-openshift</artifactId>
</dependency>
    Copy to Clipboard Toggle word wrap

  7. 将应用程序部署到 OpenShift 中新创建的名为 my-project 的项目： 

    oc new-project my-project

mvn clean package -Dquarkus.kubernetes.deploy=true -Dquarkus.openshift.expose=true -Dquarkus.openshift.labels.app-with-metrics=quarkus-app
    Copy to Clipboard Toggle word wrap

app-with-metrics 在 OpenShift 项目中创建服务监控器中所述。

注意

如果您使用带有非安全 SSL 的 OpenShift，则需要在 Maven 命令中附加 -Dquarkus.kubernetes-client.trust-certs=true。

6.3. 在 OpenShift 项目中创建服务监控器
复制链接

Prometheus 使用 pull 模型从应用程序获取指标，这意味着它会提取或监视端点来拉取指标。虽然前面的流程可帮助在 OpenShift 实例中公开您的服务，但您还没有将 Prometheus 中的任何内容配置为提取您的服务。这就是必要的服务监控器的原因。

服务监控器是一个自定义资源，您必须在运行该服务的同一项目或命名空间中创建资源： my-project。

流程

  1. 设置 service-monitor.yaml ： 

    apiVersion: monitoring.coreos.com/v1
kind: ServiceMonitor
metadata:
  labels:
    k8s-app: prometheus-app-monitor
  name: prometheus-app-monitor
  namespace: my-project
spec:
  endpoints:
  - interval: 30s
    targetPort: 8080
    scheme: http
  selector:
    matchLabels:
      app-with-metrics: 'quarkus-app'
    Copy to Clipboard Toggle word wrap

  2. 应用 service-monitor.yaml： 

    oc apply -f service-monitor.yaml
    Copy to Clipboard Toggle word wrap

    此命令创建一个名为 prometheus-app-monitor 的服务监控器，它将选择标签 app-with-metrics: quarkus-app 的应用程序。此标签在将 Quarkus 应用程序部署到 OpenShift 过程中被添加。OpenShift 为带有 app-with-metrics: quarkus-app 的所有服务调用端点 /metrics。

  3. 使用您的服务监控器：

    1. 致电您的问候服务： curl http://quarkus-micrometer-my-project.ocp.host/hello。这会增加 greeting_counter_total 计数器。
    2. 要查看指标，请浏览 OpenShift Console 并选择 Developer > Monitoring 视图。
    3. 选择 Metrics 选项卡。
    4. 在 Custom Query 字段中输入 greeting_counter_total。

指标显示在 Custom Query 字段的表中。

Red Hat logoGithubredditYoutubeTwitter

学习

尝试、购买和销售

社区

关于红帽文档

通过我们的产品和服务，以及可以信赖的内容，帮助红帽用户创新并实现他们的目标。 了解我们当前的更新.

让开源更具包容性

红帽致力于替换我们的代码、文档和 Web 属性中存在问题的语言。欲了解更多详情，请参阅红帽博客.

關於紅帽

我们提供强化的解决方案，使企业能够更轻松地跨平台和环境（从核心数据中心到网络边缘）工作。

Theme

© 2026 Red Hat返回顶部