SmallRye Metrics

以下指南演示了 Quarkus 应用程序如何使用 SmallRye Metrics，这是 MicroProfile Metrics规范的实现。 SmallRye Metrics 允许应用程序收集指标和统计数据，这些数据提供了有关应用程序内部发生的事情的见解。可以远程使用 JSON 或 OpenMetrics 格式读取指标信息，供 Prometheus 等其他工具处理并存储以进行分析和可视化。 除了本指南中描述的特定于应用程序的指标外，你还可以使用各种 Quarkus 扩展公开的内置指标。这些内容在支持内置指标的每个特定扩展指南中进行了描述。

Micrometer是针对 Quarkus 指标的推荐方法。在需要保留 MicroProfile 规范兼容性时，请使用 SmallRye Metrics 扩展。 当 Quarkus 升级到 Eclipse MicroProfile 6 时，SmallRye Metrics 支持将终止。

该技术被认为是 {extension-status}。 有关可能状态的完整列表，请查看我们的 FAQ entry.

Prerequisites

如要完成本指南，您需要：

  • Roughly 15 minutes

  • An IDE

  • 安装了 JDK 17+，已正确配置 JAVA_HOME

  • Apache Maven ${proposed-maven-version}

  • 如果你想使用 Quarkus CLI, 则可以选择使用

  • 如果你想构建一个本机可执行文件（或如果你使用本机容器构建，则使用 Docker），则可以选择安装 Mandrel 或 GraalVM 以及 configured appropriately

Architecture

在此示例中，我们构建了一个非常简单的微服务，提供了一个 REST 端点。该端点用于确定一个数是否是素数。实现类带有一些特定的度量注解，以便在响应用户的请求时收集特定的度量信息。稍后解释每个度量指标的含义。

Solution

我们建议你按照下一节中的说明一步一步创建应用程序。但是，你可以跳到已完成的示例。

  1. Clone the Git repository:[source, bash]

git clone {quickstarts-clone-url}

  • 或者，下载一个 $${quickstarts-base-url}/archive/main.zip[Quickstarts 存档]。解决方案位于 microprofile-metrics-quickstart directory，然后按照 Running and using the application部分进行操作。

Creating a Maven project

若要创建一个新项目：

CLI
quarkus create app {create-app-group-id}:{create-app-artifact-id} \
    --no-code
cd {create-app-artifact-id}

要创建一个 Gradle 项目，添加 --gradle 或 --gradle-kotlin-dsl 选项。 有关如何安装和使用 Quarkus CLI 的详细信息，请参见 Quarkus CLI 指南。

Maven
mvn {quarkus-platform-groupid}:quarkus-maven-plugin:{quarkus-version}:create \
    -DprojectGroupId={create-app-group-id} \
    -DprojectArtifactId={create-app-artifact-id} \
    -DnoCode
cd {create-app-artifact-id}

要创建一个 Gradle 项目，添加 -DbuildTool=gradle 或 -DbuildTool=gradle-kotlin-dsl 选项。

适用于 Windows 用户：

  • 如果使用 cmd，（不要使用反斜杠 \ ，并将所有内容放在同一行上）

  • 如果使用 Powershell，将 -D 参数用双引号引起来，例如 "-DprojectArtifactId={create-app-artifact-id}"

此命令生成一个使用 `smallrye-metrics`扩展的 Quarkus 项目。

如果你已配置好 Quarkus 项目，则可以通过在项目基本目录中运行以下命令，将 `smallrye-metrics`扩展添加到项目中：

CLI
quarkus extension add {add-extension-extensions}
Maven
./mvnw quarkus:add-extension -Dextensions='{add-extension-extensions}'
Gradle
./gradlew addExtension --extensions='{add-extension-extensions}'

这将把以下内容添加到您的构建文件中：

pom.xml
<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-smallrye-metrics</artifactId>
</dependency>
build.gradle
implementation("io.quarkus:quarkus-smallrye-metrics")

Writing an application

以下过程创建一个 Quarkus 应用程序，该程序包含一个实现用于检查数字是否为素数的算法的类。该算法通过一个 REST 接口公开。此外，需要有特定注解来确保在一段时间内计算出所需的度量信息，并且可以导出该信息以进行手动分析或通过其他工具进行处理。

该应用程序将收集以下指标：

  • performedChecks：一个计数器，它在用户询问一个数字时增加 1。

  • highestPrimeNumberSoFar：一个量规，它存储用户询问的最高数字（如果确定该数字为素数）。

  • checksTimer：一个复合指标，它对素数测试需要多长时间进行基准测试。稍后提供其他详细信息。

整个源代码如下所示：

package org.acme.microprofile.metrics;

import org.eclipse.microprofile.metrics.MetricUnits;
import org.eclipse.microprofile.metrics.annotation.Counted;
import org.eclipse.microprofile.metrics.annotation.Gauge;
import org.eclipse.microprofile.metrics.annotation.Timed;

import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.Produces;
import jakarta.ws.rs.core.MediaType;

@Path("/")
public class PrimeNumberChecker {

    private long highestPrimeNumberSoFar = 2;

    @GET
    @Path("/{number}")
    @Produces(MediaType.TEXT_PLAIN)
    @Counted(name = "performedChecks", description = "How many primality checks have been performed.")
    @Timed(name = "checksTimer", description = "A measure of how long it takes to perform the primality test.", unit = MetricUnits.MILLISECONDS)
    public String checkIfPrime(long number) {
        if (number < 1) {
            return "Only natural numbers can be prime numbers.";
        }
        if (number == 1) {
            return "1 is not prime.";
        }
        if (number == 2) {
            return "2 is prime.";
        }
        if (number % 2 == 0) {
            return number + " is not prime, it is divisible by 2.";
        }
        for (int i = 3; i < Math.floor(Math.sqrt(number)) + 1; i = i + 2) {
            if (number % i == 0) {
                return number + " is not prime, is divisible by " + i + ".";
            }
        }
        if (number > highestPrimeNumberSoFar) {
            highestPrimeNumberSoFar = number;
        }
        return number + " is prime.";
    }

    @Gauge(name = "highestPrimeNumberSoFar", unit = MetricUnits.NONE, description = "Highest prime number so far.")
    public Long highestPrimeNumberSoFar() {
        return highestPrimeNumberSoFar;
    }

}

Running and using the application

要执行在 Writing an application 中创建的应用程序，请执行以下操作：

  1. 在开发模式下运行微服务：include::./_includes/devtools/dev.adoc[]:!devtools-wrapped:

  2. 生成度量的值。[style="loweralpha"]

    1. 查询端点以确定某些数字是否为质数：[source, bash]

curl localhost:8080/350

应用程序会响应说 350 不是质数，因为它可以被 2 整除。

  • 对于较大的质数，测试需要更长的时间。[source, bash]

curl localhost:8080/629521085409773

应用程序会响应说 629521085409773 是质数。

  1. 使用您选择的数字执行其他调用。

    1. Review the generated metrics:[source, bash]

curl -H"Accept: application/json" localhost:8080/q/metrics/application

您会收到如下响应：

{
  "org.acme.microprofile.metrics.PrimeNumberChecker.checksTimer" : {			                    1
    "p50": 217.231273,										                                        2
    "p75": 217.231273,
    "p95": 217.231273,
    "p98": 217.231273,
    "p99": 217.231273,
    "p999": 217.231273,
    "min": 0.58961,										                                            3
    "mean": 112.15909190834819,								                                        4
    "max": 217.231273,									                                            5
    "stddev": 108.2721053982776,							    	                                6
    "count": 2,											                                            7
    "meanRate": 0.04943519091742238,							                                    8
    "oneMinRate": 0.2232140583080189,
    "fiveMinRate": 0.3559527083952095,
    "fifteenMinRate": 0.38474303050928976
  },
  "org.acme.microprofile.metrics.PrimeNumberChecker.performedChecks" : 2,		                    9
  "org.acme.microprofile.metrics.PrimeNumberChecker.highestPrimeNumberSoFar" : 629521085409773		10
}
1 checksTimer：基准对比质数测试需要多少时间的复合度量。所有持续时间均以毫秒为单位进行测量。它包含以下值。
2 p50, p75, p95, p99, p999：持续时间的百分比。例如，p95 中的值表示 95% 的测量值比此持续时间快。
3 min：执行质数测试所需的最短持续时间可能是针对一个小数执行的。
4 mean：测量持续时间的平均值。
5 max：最长的持续时间，可能是针对一个大质数。
6 stddev: The standard deviation.
7 count：观测次数，其值与 performedChecks 相同。
8 meanRate, oneMinRate, fiveMinRate, fifteenMinRate：平均吞吐量以及一分钟、五分钟和十五分钟的指数加权移动平均吞吐量。
9 performedChecks：每次用户询问一个数字时都会增加 1 的计数器。
10 highestPrimeNumberSoFar：计量器，用于存储由用户要求且确定为素数的最高数目。

如果您更喜欢 OpenMetrics 导出而不是 JSON 格式，请从命令行中删除 `-H"Accept: application/json"`参数。
Management interface

默认情况下，系统在主 HTTP 服务器上公开规则。您可以通过使用 `quarkus.management.enabled=true`属性启用管理界面在单独的网络接口和端口上公开这些规则。有关详细信息，请参阅 management interface reference。
Configuration Reference

Unresolved include directive in modules/ROOT/pages/smallrye-metrics.adoc - include::../../../target/quarkus-generated-doc/config/quarkus-smallrye-metrics.adoc[]