编辑此页面

SmallRye Metrics

以下指南演示了 Quarkus 应用程序如何使用 SmallRye Metrics,它是 MicroProfile Metrics 规范的实现。

SmallRye Metrics 允许应用程序收集指标和统计信息,从而深入了解应用程序内部正在发生的事情。 可以使用 JSON 或 OpenMetrics 格式远程读取指标,以便由其他工具(例如 Prometheus)处理,并存储以进行分析和可视化。

除了本指南中描述的特定于应用程序的指标外,您还可以使用各种 Quarkus 扩展公开的内置指标。 这些在每个支持内置指标的特定扩展的指南中描述。

Micrometer 是 Quarkus 指标的推荐方法。 当需要保留 MicroProfile 规范兼容性时,请使用 SmallRye Metrics 扩展。

当 Quarkus 升级到 Eclipse MicroProfile 6 时,将停止支持 SmallRye Metrics。

此技术被认为是已弃用的。

已弃用意味着此扩展可能会在 Quarkus 的未来版本中被替换或删除。

有关可能的完整状态列表,请查看我们的常见问题解答条目

先决条件

要完成本指南,您需要

  • 大约 15 分钟

  • 一个 IDE

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

  • Apache Maven 3.9.9

  • 如果您想使用它,可以选择 Quarkus CLI

  • 如果您想构建本机可执行文件(或者如果您使用本机容器构建,则为 Docker),可以选择安装 Mandrel 或 GraalVM 并进行适当的配置

架构

在本示例中,我们构建一个非常简单的微服务,它提供一个 REST 端点。 此端点用于确定数字是否为素数。 实现类使用某些指标注释进行注释,以便在响应用户的请求时收集某些指标。 每个指标的含义将在稍后解释。

解决方案

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

  1. 克隆 Git 存储库

    git clone https://github.com/quarkusio/quarkus-quickstarts.git

创建 Maven 项目

要创建新项目

CLI
quarkus create app org.acme:microprofile-metrics-quickstart \
    --extension='rest,smallrye-metrics' \
    --no-code
cd microprofile-metrics-quickstart

要创建 Gradle 项目,请添加 --gradle--gradle-kotlin-dsl 选项。

有关如何安装和使用 Quarkus CLI 的更多信息,请参阅 Quarkus CLI 指南。

Maven
mvn io.quarkus.platform:quarkus-maven-plugin:3.24.4:create \
    -DprojectGroupId=org.acme \
    -DprojectArtifactId=microprofile-metrics-quickstart \
    -Dextensions='rest,smallrye-metrics' \
    -DnoCode
cd microprofile-metrics-quickstart

要创建 Gradle 项目,请添加 -DbuildTool=gradle-DbuildTool=gradle-kotlin-dsl 选项。

对于 Windows 用户

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

  • 如果使用 Powershell,请将 -D 参数括在双引号中,例如 "-DprojectArtifactId=microprofile-metrics-quickstart"

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

如果您已经配置了 Quarkus 项目,则可以通过在项目基本目录中运行以下命令将 smallrye-metrics 扩展添加到项目中

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

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

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

编写应用程序

以下过程创建一个 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;
    }

}

运行和使用应用程序

要执行在 编写应用程序 中创建的应用程序,请执行以下操作

  1. 以开发模式运行微服务

    CLI
    quarkus dev
    Maven
    ./mvnw quarkus:dev
    Gradle
    ./gradlew --console=plain quarkusDev
  2. 生成指标的值。

    1. 查询端点以确定某些数字是否为素数

      curl localhost:8080/350

      应用程序将响应 350 不是素数,因为它可被 2 整除。

      • 对于较大的素数,测试需要更多时间。

        curl localhost:8080/629521085409773

        应用程序将响应 629521085409773 是素数。

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

  3. 查看生成的指标

    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:标准差。
7 count:观察次数,其值与 performedChecks 相同。
8 meanRate, oneMinRate, fiveMinRate, fifteenMinRate:平均吞吐量和一分钟、五分钟和十五分钟的指数加权移动平均吞吐量。
9 performedChecks:计数器,每次用户询问一个数字时,计数器都会增加 1。
10 highestPrimeNumberSoFar:仪表,用于存储用户询问的最高数字,并且该数字被确定为素数。
如果您更喜欢 OpenMetrics 导出而不是 JSON 格式,请从命令行中删除 -H"Accept: application/json" 参数。
管理界面

默认情况下,指标在主 HTTP 服务器上公开。 您可以通过使用 quarkus.management.enabled=true 属性启用管理界面,从而在单独的网络接口和端口上公开它们。 有关更多信息,请参阅管理界面参考

构建时固定的配置属性 - 所有其他配置属性都可以在运行时覆盖

配置属性

类型

默认

指标处理程序的路径。 默认情况下,此值将解析为相对于 ${quarkus.http.non-application-root-path} 的路径。 如果启用了管理界面,则该值将解析为相对于 ${quarkus.management.root-path} 的路径。

环境变量:QUARKUS_SMALLRYE_METRICS_PATH

显示更多

字符串

metrics

是否应启用 Quarkus 扩展发布的指标。

环境变量:QUARKUS_SMALLRYE_METRICS_EXTENSIONS_ENABLED

显示更多

布尔值

true

应用 Micrometer 兼容模式,在此模式下,Quarkus 不会公开常规的“基本”和“供应商”指标,而是公开 Micrometer 公开的相同的“jvm”指标。 应用程序指标不受此模式的影响。 用例是为了方便从基于 Micrometer 的指标进行迁移,因为 JVM 指标的原始仪表板将继续工作,而无需重写它们。

环境变量:QUARKUS_SMALLRYE_METRICS_MICROMETER_COMPATIBILITY

显示更多

布尔值

false

是否应启用详细的 JAX-RS 指标。

环境变量:QUARKUS_SMALLRYE_METRICS_JAXRS_ENABLED

显示更多

布尔值

false

相关内容