SmallRye Metrics
このガイドでは、Quarkusアプリケーションが MicroProfile Metrics 仕様の実装である SmallRye Metrics を使用する方法を説明しています。
SmallRye Metricsを使用すると、アプリケーション内部で何が起こっているかを把握するための指標や統計情報を収集できます。メトリクスは、JSONまたはOpenMetrics形式を使用してリモートで読み取り、Prometheusなどの追加ツールで処理し、分析および可視化のために保存することができます。
このガイドで説明しているアプリケーション固有のメトリクスとは別に、Quarkusの様々なエクステンションで公開されているビルトインメトリクスを使用することもできます。これらについては、ビルトインメトリクスをサポートする各エクステンションのガイドに記載されています。
Quarkusでは、 Micrometer を使用したメトリクスを推奨しています。MicroProfile仕様との互換性を保つために必要な場合は、SmallRye Metricsエクステンションを使用してください。 QuarkusがEclipse MicroProfile 6にアップグレードされると、SmallRye Metricsのサポートは打ち切られます。 |
この技術は、deprecatedと考えられています。 deprecated は、このエクステンションが Quarkus の将来のバージョンで置き換えられるか削除される可能性が高いことを意味します。 とりうるステータスの完全なリストについては、 FAQの項目 を参照してください。 |
前提条件
このガイドを完成させるには、以下が必要です:
-
約15分
-
IDE
-
JDK 17+がインストールされ、
JAVA_HOME
が適切に設定されていること -
Apache Maven 3.9.9
-
使用したい場合は、 Quarkus CLI
-
ネイティブ実行可能ファイルをビルドしたい場合、MandrelまたはGraalVM(あるいはネイティブなコンテナビルドを使用する場合はDocker)をインストールし、 適切に設定していること
アーキテクチャ
この例では、1つのRESTエンドポイントを提供する非常にシンプルなマイクロサービスを作成します。このエンドポイントは、ある数字が素数かどうかを判断するためのものです。この実装クラスには、ユーザーのリクエストに応答する際に特定のメトリクスを収集するように、特定のメトリクスのアノテーションが付けられています。各メトリックの意味については後述します。
ソリューション
次のセクションの指示に従って、段階的にアプリケーションを作成していくことをお勧めします。ただし、完成した例までスキップすることもできます。
-
Gitリポジトリのクローンを作成します:
git clone https://github.com/quarkusio/quarkus-quickstarts.git
-
または、https://github.com/quarkusio/quarkus-quickstarts/archive/main.zip[Quickstartsアーカイブ]をダウンロードしてください。ソリューションは
microprofile-metrics-quickstart
ディレクトリ に存在し、 アプリケーションの実行と使用 セクションを実施して下さい。
-
Mavenプロジェクトの作成
新しいMavenプロジェクトを作成するには:
Windowsユーザーの場合:
-
cmdを使用する場合、(バックスラッシュ
\
を使用せず、すべてを同じ行に書かないでください)。 -
Powershellを使用する場合は、
-D
パラメータを二重引用符で囲んでください。例:"-DprojectArtifactId=microprofile-metrics-quickstart"
このコマンドは、 smallrye-metrics
エクステンションを使用するMavenベースのQuarkusプロジェクトを生成します。
すでにQuarkusプロジェクトが設定されている場合は、プロジェクトのベースディレクトリーで以下のコマンドを実行することで、プロジェクトに smallrye-metrics
エクステンションを追加することができます:
quarkus extension add smallrye-metrics
./mvnw quarkus:add-extension -Dextensions='smallrye-metrics'
./gradlew addExtension --extensions='smallrye-metrics'
これにより、 pom.xml
ファイルに以下が追加されます:
<dependency>
<groupId>io.quarkus</groupId>
<artifactId>quarkus-smallrye-metrics</artifactId>
</dependency>
implementation("io.quarkus:quarkus-smallrye-metrics")
アプリケーションの作成
次の手順では、MavenベースのQuarkusアプリケーションを作成します。このアプリケーションは、数が素数であるかどうかをチェックするアルゴリズムを実装する1つのクラスで構成されています。このアルゴリズムは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;
}
}
アプリケーションの実行と使用
アプリケーションの作成 で作成したアプリケーションを実行するには、次のようにします:
-
マイクロサービスを開発モードで実行します:
コマンドラインインタフェースquarkus 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 : 平均スループットと 1、5、および 15 分間の指数関数的に重み付けした移動平均のスループット。 |
9 | performedChecks : ユーザーが数字を問い合わせるたびに1つ増えるカウンター。 |
10 | highestPrimeNumberSoFar : ユーザーが問い合わせし、素数であると判断された最高値を格納するゲージ。 |
JSON形式ではなくOpenMetricsのエクスポートが良い場合は、コマンドラインから -H"Accept: application/json" 引数を削除してください。
|
マネジメントインターフェース
デフォルトでは、メトリクスはメインの HTTP サーバーで公開されます。 |
ビルド時に固定される構成プロパティ - 他のすべての構成プロパティは実行時にオーバーライド可能
Configuration property |
型 |
デフォルト |
---|---|---|
The path to the metrics handler. By default, this value will be resolved as a path relative to Environment variable: Show more |
string |
|
Whether metrics published by Quarkus extensions should be enabled. Environment variable: Show more |
boolean |
|
Apply Micrometer compatibility mode, where instead of regular 'base' and 'vendor' metrics, Quarkus exposes the same 'jvm' metrics that Micrometer does. Application metrics are unaffected by this mode. The use case is to facilitate migration from Micrometer-based metrics, because original dashboards for JVM metrics will continue working without having to rewrite them. Environment variable: Show more |
boolean |
|
Whether detailed JAX-RS metrics should be enabled. Environment variable: Show more |
boolean |
|