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 端点。 此端点用于确定数字是否为素数。 实现类使用某些指标注释进行注释,以便在响应用户的请求时收集某些指标。 每个指标的含义将在稍后解释。
解决方案
我们建议您按照下一节中的说明逐步创建应用程序。 但是,您可以跳到完成的示例。
-
克隆 Git 存储库
git clone https://github.com/quarkusio/quarkus-quickstarts.git
-
或者,下载 Quickstarts 存档。 解决方案位于
microprofile-metrics-quickstart
目录中,并按照 运行和使用应用程序 部分进行操作。
-
创建 Maven 项目
要创建新项目
对于 Windows 用户
-
如果使用 cmd,(不要使用反斜杠
\
并将所有内容放在同一行上) -
如果使用 Powershell,请将
-D
参数括在双引号中,例如"-DprojectArtifactId=microprofile-metrics-quickstart"
此命令生成一个使用 smallrye-metrics
扩展的 Quarkus 项目。
如果您已经配置了 Quarkus 项目,则可以通过在项目基本目录中运行以下命令将 smallrye-metrics
扩展添加到项目中
quarkus extension add smallrye-metrics
./mvnw quarkus:add-extension -Dextensions='smallrye-metrics'
./gradlew addExtension --extensions='smallrye-metrics'
这会将以下内容添加到您的构建文件中
<dependency>
<groupId>io.quarkus</groupId>
<artifactId>quarkus-smallrye-metrics</artifactId>
</dependency>
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;
}
}
运行和使用应用程序
要执行在 编写应用程序 中创建的应用程序,请执行以下操作
-
以开发模式运行微服务
CLIquarkus dev
Maven./mvnw quarkus:dev
Gradle./gradlew --console=plain quarkusDev
-
生成指标的值。
-
查询端点以确定某些数字是否为素数
curl localhost:8080/350
应用程序将响应 350 不是素数,因为它可被 2 整除。
-
对于较大的素数,测试需要更多时间。
curl localhost:8080/629521085409773
应用程序将响应 629521085409773 是素数。
-
-
使用您选择的数字执行其他调用。
-
-
查看生成的指标
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 扩展发布的指标。 环境变量: 显示更多 |
布尔值 |
|
应用 Micrometer 兼容模式,在此模式下,Quarkus 不会公开常规的“基本”和“供应商”指标,而是公开 Micrometer 公开的相同的“jvm”指标。 应用程序指标不受此模式的影响。 用例是为了方便从基于 Micrometer 的指标进行迁移,因为 JVM 指标的原始仪表板将继续工作,而无需重写它们。 环境变量: 显示更多 |
布尔值 |
|
是否应启用详细的 JAX-RS 指标。 环境变量: 显示更多 |
布尔值 |
|