The English version of quarkus.io is the official project site. Translated sites are community supported on a best-effort basis.

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.6

  • 使用したい場合は、 Quarkus CLI

  • ネイティブ実行可能ファイルをビルドしたい場合、MandrelまたはGraalVM(あるいはネイティブなコンテナビルドを使用する場合はDocker)をインストールし、 適切に設定していること

アーキテクチャ

この例では、1つのRESTエンドポイントを提供する非常にシンプルなマイクロサービスを作成します。このエンドポイントは、ある数字が素数かどうかを判断するためのものです。この実装クラスには、ユーザーのリクエストに応答する際に特定のメトリクスを収集するように、特定のメトリクスのアノテーションが付けられています。各メトリックの意味については後述します。

ソリューション

次のセクションの指示に従って、段階的にアプリケーションを作成していくことをお勧めします。ただし、完成した例までスキップすることもできます。

  1. 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プロジェクトを作成するには:

コマンドラインインタフェース
quarkus create app org.acme:microprofile-metrics-quickstart \
    --extension='resteasy-reactive,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.8.3:create \
    -DprojectGroupId=org.acme \
    -DprojectArtifactId=microprofile-metrics-quickstart \
    -Dextensions='resteasy-reactive,smallrye-metrics' \
    -DnoCode
cd microprofile-metrics-quickstart

Gradleプロジェクトを作成するには、 -DbuildTool=gradle または -DbuildTool=gradle-kotlin-dsl オプションを追加します。

Windowsユーザーの場合:

  • cmdを使用する場合、(バックスラッシュ \ を使用せず、すべてを同じ行に書かないでください)。

  • Powershellを使用する場合は、 -D パラメータを二重引用符で囲んでください。例: "-DprojectArtifactId=microprofile-metrics-quickstart"

このコマンドは、 smallrye-metrics エクステンションを使用するMavenベースのQuarkusプロジェクトを生成します。

すでにQuarkusプロジェクトが設定されている場合は、プロジェクトのベースディレクトリーで以下のコマンドを実行することで、プロジェクトに smallrye-metrics エクステンションを追加することができます:

コマンドラインインタフェース
quarkus extension add smallrye-metrics
Maven
./mvnw quarkus:add-extension -Dextensions='smallrye-metrics'
Gradle
./gradlew addExtension --extensions='smallrye-metrics'

これにより、 pom.xml ファイルに以下が追加されます:

pom.xml
<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-smallrye-metrics</artifactId>
</dependency>
build.gradle
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;
    }

}

アプリケーションの実行と使用

アプリケーションの作成 で作成したアプリケーションを実行するには、次のようにします:

  1. マイクロサービスを開発モードで実行します:

    コマンドラインインタフェース
    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 : 平均スループットと 1、5、および 15 分間の指数関数的に重み付けした移動平均のスループット。
9 performedChecks : ユーザーが数字を問い合わせるたびに1つ増えるカウンター。
10 highestPrimeNumberSoFar: ユーザーが問い合わせし、素数であると判断された最高値を格納するゲージ。
JSON形式ではなくOpenMetricsのエクスポートが良い場合は、コマンドラインから -H"Accept: application/json" 引数を削除してください。
マネジメントインターフェース

デフォルトでは、メトリクスはメインの HTTP サーバーで公開されます。 quarkus.management.enabled=true プロパティでマネジメントインターフェイスを有効にすると、別のネットワーク・インターフェイスおよびポートで公開することができます。詳細については、 マネジメントインターフェイスのリファレンス を参照してください。

ビルド時に固定される構成プロパティ - 他のすべての構成プロパティは実行時にオーバーライド可能

Configuration property

デフォルト

The path to the metrics handler. By default, this value will be resolved as a path relative to ${quarkus.http.non-application-root-path}. If the management interface is enabled, the value will be resolved as a path relative to ${quarkus.management.root-path}.

Environment variable: QUARKUS_SMALLRYE_METRICS_PATH

Show more

string

metrics

Whether metrics published by Quarkus extensions should be enabled.

Environment variable: QUARKUS_SMALLRYE_METRICS_EXTENSIONS_ENABLED

Show more

boolean

true

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: QUARKUS_SMALLRYE_METRICS_MICROMETER_COMPATIBILITY

Show more

boolean

false

Whether detailed JAX-RS metrics should be enabled.

Environment variable: QUARKUS_SMALLRYE_METRICS_JAXRS_ENABLED

Show more

boolean

false

関連コンテンツ