QuarkusのObservability入門｜メトリクスエンドポイントを初心者向けに徹底解説

1. QuarkusのObservabilityとは何か

1. QuarkusのObservabilityとは何か

QuarkusのObservabilityとは、アプリケーションの状態を外から観測できるようにする考え方です。CPU使用率やメモリ量だけでなく、HTTPリクエストの回数やエラーの発生数など、アプリ内部の振る舞いを数値として確認できます。これにより、本番環境でも異常に早く気づけるようになります。QuarkusではObservabilityの仕組みが最初から統合されており、初心者でも設定しやすい点が特徴です。

2. メトリクスエンドポイントの基本的な役割

2. メトリクスエンドポイントの基本的な役割

メトリクスエンドポイントとは、アプリケーションが収集した数値情報をHTTP経由で公開する窓口です。Quarkusではこのエンドポイントにアクセスすることで、現在の状態をテキスト形式で取得できます。監視ツールやPrometheusのような仕組みは、このエンドポイントから定期的に情報を取得し、グラフ化やアラートに利用します。

3. Quarkusで利用されるMetricsの仕組み

3. Quarkusで利用されるMetricsの仕組み

Quarkusのメトリクスは、MicroProfile Metricsという仕様をベースにしています。これはJava向けの標準的なメトリクス定義で、カウンターやタイマーなどの概念が用意されています。Quarkusはこれを内部で扱いやすい形に統合しており、特別な実装をしなくても基本的なHTTPメトリクスが自動で収集されます。

4. メトリクスエンドポイントのURLと確認方法

4. メトリクスエンドポイントのURLと確認方法

開発モードでQuarkusを起動すると、メトリクスエンドポイントは特定のパスで公開されます。ブラウザやコマンドラインからアクセスするだけで内容を確認できます。ローカル環境で試すことで、どのような情報が取得できるのかを感覚的に理解できます。

<!-- ブラウザでアクセスする例 -->
http://localhost:8080/q/metrics

<!-- curlで確認する例 -->
curl http://localhost:8080/q/metrics

5. application.propertiesでの基本設定

5. application.propertiesでの基本設定

Quarkusでは設定ファイルを使ってObservability関連の挙動を制御できます。メトリクスを有効にする設定はシンプルで、初心者でも迷いにくい構成になっています。設定内容はテキストで管理できるため、環境ごとに切り替えるのも容易です。

# メトリクス機能を有効化
quarkus.micrometer.enabled=true
quarkus.micrometer.export.prometheus.enabled=true

6. Javaコードで独自メトリクスを追加する

6. Javaコードで独自メトリクスを追加する

自動で収集される情報だけでなく、自分で定義したメトリクスを追加することも可能です。例えば、特定の処理が何回実行されたかを数えたい場合に役立ちます。Javaコードに少し手を加えるだけで、Observabilityの幅が大きく広がります。

import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;
import org.eclipse.microprofile.metrics.annotation.Counted;

@Path("/hello")
public class HelloResource {

    @GET
    @Counted(name = "hello_count", description = "Hello APIの呼び出し回数")
    public String hello() {
        return "Hello Quarkus";
    }
}

7. タイマー系メトリクスで処理時間を知る

7. タイマー系メトリクスで処理時間を知る

処理時間を測定することは、パフォーマンス問題を見つけるうえで非常に重要です。Quarkusではタイマー系のメトリクスを使うことで、APIの応答時間を簡単に記録できます。数値として可視化されるため、改善前後の比較もしやすくなります。

import org.eclipse.microprofile.metrics.annotation.Timed;

@Path("/process")
public class ProcessResource {

    @GET
    @Timed(name = "process_time", description = "処理時間の計測")
    public String process() throws InterruptedException {
        Thread.sleep(100);
        return "done";
    }
}

8. Prometheusと連携する際の考え方

8. Prometheusと連携する際の考え方

Quarkusのメトリクスエンドポイントは、そのままPrometheusと連携できます。Prometheusは定期的にエンドポイントへアクセスし、数値を収集します。Quarkus側では特別な実装をせずとも、正しい形式でデータが公開されるため、監視基盤の構築がスムーズに進みます。

9. 初心者がつまずきやすいポイント

9. 初心者がつまずきやすいポイント

初めてQuarkusのメトリクスを触ると、エンドポイントにアクセスできない、設定が反映されないといった問題に出会いがちです。多くの場合は起動モードの違いや設定ファイルの記述漏れが原因です。まずはローカル環境でメトリクスが表示されることを確認し、段階的に理解を深めることが大切です。