Eclipse MicroProfile Metricsを試す

$ java --version
openjdk 11.0.11 2021-04-20
OpenJDK Runtime Environment (build 11.0.11+9-Ubuntu-0ubuntu2.20.04)
OpenJDK 64-Bit Server VM (build 11.0.11+9-Ubuntu-0ubuntu2.20.04, mixed mode, sharing)


$ mvn --version
Apache Maven 3.8.2 (ea98e05a04480131370aa0c110b8c54cf726c06f)
Maven home: $HOME/.sdkman/candidates/maven/current
Java version: 11.0.11, vendor: Ubuntu, runtime: /usr/lib/jvm/java-11-openjdk-amd64
Default locale: ja_JP, platform encoding: UTF-8
OS name: "linux", version: "5.4.0-81-generic", arch: "amd64", family: "unix"

WildFlyは、24.0.1.Finalを使います。

準備

Mavenでのプロジェクト定義は、こんな感じにしました。

pom.xml

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>org.littlewings</groupId>
    <artifactId>microprofile-metrics-example</artifactId>
    <version>0.0.1-SNAPSHOT</version>
    <packaging>war</packaging>

    <properties>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
        <maven.compiler.source>11</maven.compiler.source>
        <maven.compiler.target>11</maven.compiler.target>
        <failOnMissingWebXml>false</failOnMissingWebXml>
    </properties>

    <dependencies>
        <dependency>
            <groupId>jakarta.platform</groupId>
            <artifactId>jakarta.jakartaee-web-api</artifactId>
            <version>8.0.0</version>
            <scope>provided</scope>
        </dependency>

        <dependency>
            <groupId>org.eclipse.microprofile.metrics</groupId>
            <artifactId>microprofile-metrics-api</artifactId>
            <version>3.0</version>
            <scope>provided</scope>
        </dependency>
    </dependencies>

    <build>
        <finalName>${project.artifactId}</finalName>
    </build>
</project>

Eclipse MicroProfile MetricsのAPIを使うには、microprofile-metrics-apiを依存関係に追加します。

        <dependency>
            <groupId>org.eclipse.microprofile.metrics</groupId>
            <artifactId>microprofile-metrics-api</artifactId>
            <version>3.0</version>
            <scope>provided</scope>
        </dependency>

WARファイルの名前は、microprofile-metrics-example.warとします。

アプリケーションは、JAX-RSを使って書くことにしましょう。JAX-RS有効化のクラスを作成しておきます。

src/main/java/org/littlewings/microprofile/metrics/JaxrsActivator.java

package org.littlewings.microprofile.metrics;

import javax.ws.rs.ApplicationPath;
import javax.ws.rs.core.Application;

@ApplicationPath("")
public class JaxrsActivator extends Application {
}

WildFlyのダウンロード。

$ curl -OL https://download.jboss.org/wildfly/24.0.1.Final/wildfly-24.0.1.Final.zip
$ unzip wildfly-24.0.1.Final.zip
$ cd wildfly-24.0.1.Final

Eclipse MicroProfileを使うので、設定ファイルはstandalone-microprofile.xmlを指定して起動します。

$ bin/standalone.sh -c standalone-microprofile.xml -Dwildfly.statistics-enabled=true

WildFly自身のメトリクスも取得できるように、-Dwildfly.statistics-enabled=trueも指定しておきましょう。

管理CLIも起動しておきます。

$ bin/jboss-cli.sh -c
[standalone@localhost:9990 /]

RESTエンドポイントで、WildFlyのメトリクスを取得してみる

起動した状態のWildFlyのメトリクスを取得してみましょう。

Exposing metrics via REST API

WildFlyの場合、9990ポートでアクセスします。

/metricsで、全スコープのメトリクスを取得できます。

$ curl -s localhost:9990/metrics | grep -v '^#' | perl -wp -e 's!^(.+?_.+?)_.+!$1!' | sort | uniq -c 
      3 base_classloader
      4 base_cpu
      4 base_gc
      1 base_jvm
      6 base_memory
      3 base_thread
      2 vendor_BufferPool
     16 vendor_memoryPool
     60 wildfly_datasources
     14 wildfly_ee
      7 wildfly_io
     17 wildfly_jca
     12 wildfly_messaging
      1 wildfly_request
     11 wildfly_transactions
     12 wildfly_undertow

/metrics/baseとすることで、Base metricsに絞ることができます。

$ curl -s localhost:9990/metrics/base | grep -v '^#' | perl -wp -e 's!^(.+?_.+?)_.+!$1!' | sort | uniq -c 
      3 base_classloader
      4 base_cpu
      4 base_gc
      1 base_jvm
      6 base_memory
      3 base_thread

/metrics/vendorで、Vendor specific metricsです。

$ curl -s localhost:9990/metrics/vendor | grep -v '^#' | perl -wp -e 's!^(.+?_.+?)_.+!$1!' | sort | uniq -c 
      2 vendor_BufferPool
     16 vendor_memoryPool
     60 wildfly_datasources
     14 wildfly_ee
      7 wildfly_io
     17 wildfly_jca
     12 wildfly_messaging
      1 wildfly_request
     11 wildfly_transactions
     12 wildfly_undertow

Application metricsは、まだアプリケーションが登録されていないので存在しません。

$ curl -s localhost:9990/metrics/application | grep -v '^#' | perl -wp -e 's!^(.+?_.+?)_.+!$1!' | sort | uniq -c

こんな感じで、/metrics/[スコープ]で取得するメトリクスのスコープを絞ることができます。

さらに/metrics/[スコープ]/[メトリクス名]でメトリクスを絞って取得することもできます。

$ curl localhost:9990/metrics/vendor/wildfly_io_io_thread_count
# HELP wildfly_io_io_thread_count I/O thread count
# TYPE wildfly_io_io_thread_count gauge
wildfly_io_io_thread_count{worker="default",microprofile_scope="vendor"} 16.0

メトリクスの種類

プログラムを書く前に、先にメトリクスの種類を見ておいた方が良さそうです。

Metadata

というか、いきなり書き始めて進めてみたら、自分が困りました…。

Counter … 単調に増加する数値（long）
ConcurrentGause … 増減する数値（long）。現在のカウント、前に完了した1分の間の最大値、最小値の3つの値が公開される
Gauge … CPUの温度やディスク使用率など、サンプリングされるメトリクス
- Gaugeについては、メトリクス取得時にGauge#getValueの呼び出しが行われる
- Gauge JSON Format
Meter … 平均スループット、1分、5分、15分の指数加重移動平均スループットを追跡する
Histogram … 値（long）の分布を計算する
Timer … 時間を集計し、期間の統計とスループットの統計を提供する
- DurationやCallable、Runnable、Contextで記録
SimpleTimer … Timerの軽量版
- 経過時間、呼び出しカウント、前に完了した1分間の最大、最小を記録
- Prometheusで使う場合、Timerを使う方が良い

どんなメトリクスになるのかは、RESTエンドポイントの各メトリクスの記載を見た方がわかりやすいでしょうね。

Exposing metrics via REST API

また、Histgram以外のメトリクスは、アノテーションでの記録が可能です。

Annotations

アノテーションでメトリクスを記録する

では、まずはアノテーションを使ってメトリクスを記録してみましょう。

こちらを見ながら作成していきます。

Annotations

雛形となるJAX-RSリソースクラスを用意。

src/main/java/org/littlewings/microprofile/metrics/SimpleAnnotatedResource.java

package org.littlewings.microprofile.metrics;

import java.util.concurrent.TimeUnit;
import javax.inject.Inject;
import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.Produces;
import javax.ws.rs.core.MediaType;

import org.eclipse.microprofile.metrics.annotation.ConcurrentGauge;
import org.eclipse.microprofile.metrics.annotation.Counted;
import org.eclipse.microprofile.metrics.annotation.SimplyTimed;
import org.eclipse.microprofile.metrics.annotation.Timed;

@Path("annotated")
public class SimpleAnnotatedResource {

    // ここに、メトリクスを記録するコードを書く

}

こちらに、メトリクスを記録するコードを埋め込んでいきます。

Counter metricsを記録する、@Counted。属性はnameだけを指定してみました。

    @GET
    @Path("count-hello-world")
    @Produces(MediaType.TEXT_PLAIN)
    @Counted(name = "hello_world_call_count")
    public String countHelloWorld() {
        return "Hello World!!";
    }

こちらですね。

    @Counted(name = "hello_world_call_count")

これで、このリソースメソッドの呼び出し回数がメトリクスとして記録されるようになります。

パッケージングして

$ mvn package

デプロイ。

[standalone@localhost:9990 /] deploy /path/to/target/microprofile-metrics-example.war

以降は、この操作を省略します（記載したソースコードが含まれたWebアプリケーションがデプロイされたものとして
話を進めます）。

この時点で、実はメトリクスは見られるようになっています。

$ curl localhost:9990/metrics/application
# TYPE application_org_littlewings_microprofile_metrics_SimpleAnnotatedResource_hello_world_call_count_total counter
application_org_littlewings_microprofile_metrics_SimpleAnnotatedResource_hello_world_call_count_total 0.0

アクセスしてみましょう。

$ curl localhost:8080/microprofile-metrics-example/annotated/count-hello-world
Hello World!!


$ curl localhost:8080/microprofile-metrics-example/annotated/count-hello-world
Hello World!!

こんな感じでカウントアップされていきます。

$ curl -s localhost:9990/metrics/application
# TYPE application_org_littlewings_microprofile_metrics_SimpleAnnotatedResource_hello_world_call_count_total counter
application_org_littlewings_microprofile_metrics_SimpleAnnotatedResource_hello_world_call_count_total 2.0

次は、もう少し属性を指定してみましょう。属性を指定するということは、メタデータを指定することになります。

Metadata

    @GET
    @Path("count-yeah")
    @Produces(MediaType.TEXT_PLAIN)
    @Counted(name = "yeah_call_count", absolute = true, displayName = "yeah call count metrics", description = "yeah call count description")
    public String countYeah() {
        return "Yeah!!";
    }

アクセスしてみます。

$ curl localhost:8080/microprofile-metrics-example/annotated/count-yeah
Yeah!!


$ curl localhost:8080/microprofile-metrics-example/annotated/count-yeah
Yeah!!

メトリクスは、こんな感じになります。

# HELP application_yeah_call_count_total yeah call count description
# TYPE application_yeah_call_count_total counter
application_yeah_call_count_total 2.0

descriptionは、HELPに使われていることが確認できます。

先ほどと比べると、メトリクスの名前がやたら短いですね。これはabsoluteをtrueとしたからです。

absoluteをfalse（デフォルト）とすると、クラスのFQCNがメトリクスの名前に含まれるようになります。

アノテーションを使ってメトリクスを記録する場合の、メトリクス名に関する規則はこちらに記載されています。

Annotated Naming Convention

メトリクス名にはスコープおよびメトリクスによってはサフィックスが付与されるので、それぞれのメトリクスの
情報を参照しましょう。

ところで、displayNameの情報はどこにいったのでしょうか？これは、OPTIONSで確認できます。

$ curl -XOPTIONS -H 'Accept: application/json' localhost:9990/metrics/application

{
    "org.littlewings.microprofile.metrics.SimpleAnnotatedResource.hello_world_call_count": {
        "unit": "none",
        "type": "counter",
        "displayName": "org.littlewings.microprofile.metrics.SimpleAnnotatedResource.hello_world_call_count",
        "tags": [
            [
            ]
        ]
    },
    "yeah_call_count": {
        "unit": "none",
        "type": "counter",
        "description": "yeah call count description",
        "displayName": "yeah call count metrics",
        "tags": [
            [
            ]
        ]
    }
}

キーがメトリクス名になっていることに注意しましょう。

つまり、自分が作っている今回の例だと
application_org_littlewings_microprofile_metrics_SimpleAnnotatedResource_hello_world_call_count_totalという
見た目のメトリクスは、org.littlewings.microprofile.metrics.SimpleAnnotatedResource.hello_world_call_countという
名前でアクセスできることになります。

$ curl -s localhost:9990/metrics/application/org.littlewings.microprofile.metrics.SimpleAnnotatedResource.hello_world_call_count
# TYPE application_org_littlewings_microprofile_metrics_SimpleAnnotatedResource_hello_world_call_count_total counter
application_org_littlewings_microprofile_metrics_SimpleAnnotatedResource_hello_world_call_count_total 2.0

ちょっとわかりにくいので、困ったらOPTIONSでメトリクスのメタデータを見てみましょう。
メトリクス単位で取得したい場合などに、この情報は役立つでしょう。

話を戻して。

同じメトリクスを別のメソッドでも記録することができます。もうひとつ、JAX-RSリソースメソッドを追加。

    @GET
    @Path("count-yeah2")
    @Produces(MediaType.TEXT_PLAIN)
    @Counted(name = "yeah_call_count", absolute = true, displayName = "yeah call count metrics", description = "yeah call count description")
    public String countYeah2() {
        return "Yeah2!!";
    }

こちらに記載のあるように、メトリクスはメタデータさえ同じであれば複数のアノテーションで同じメトリクスを
参照することができます。

Reusing Metrics

同じ名前のメトリクスで、異なるメタデータのものを定義した場合は、IllegalArgumentExceptionがスローされますが。
あと、Gaugeはこのルールの対象外になります。

呼び出し。

$ curl localhost:8080/microprofile-metrics-example/annotated/count-yeah2
Yeah2!!


$ curl localhost:8080/microprofile-metrics-example/annotated/count-yeah2
Yeah2!!

これで、2つのJAX-RSリソースメソッドのどちらを呼び出しても、同じCounterメトリクスが更新されるようになりました。

$ curl localhost:9990/metrics/application/yeah_call_count
# HELP application_yeah_call_count_total yeah call count description
# TYPE application_yeah_call_count_total counter
application_yeah_call_count_total 4.0

次に、Concurrent Gaugeを使ってみましょう。

ランダムな秒数をスリープするように仕込んで、すぐには終了しないようにします。

    @GET
    @Path("concurrent-gause")
    @Produces(MediaType.TEXT_PLAIN)
    @ConcurrentGauge(name = "my_concurrent_gause")
    public String concurrentGause() throws InterruptedException {
        long sleepSeconds = randomService.randomInt(5);
        TimeUnit.SECONDS.sleep(sleepSeconds);

        return String.format("sleeped %d sec", sleepSeconds);
    }

この時、ランダムな整数を取得する処理はCDI管理Beanとし、こちらもCountメトリクスを取得するようにしましょう。

src/main/java/org/littlewings/microprofile/metrics/RandomService.java

package org.littlewings.microprofile.metrics;

import java.util.Random;
import javax.annotation.PostConstruct;
import javax.enterprise.context.ApplicationScoped;

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

@ApplicationScoped
public class RandomService {
    Random random;

    @PostConstruct
    public void init() {
        random = new Random();
        random.nextInt();
    }

    @Counted
    public int randomInt(int bound) {
        return random.nextInt(bound);
    }
}

こんな感じでアクセスしている間に

$ curl localhost:8080/microprofile-metrics-example/annotated/concurrent-gause &
$ curl localhost:8080/microprofile-metrics-example/annotated/concurrent-gause &
$ curl localhost:8080/microprofile-metrics-example/annotated/concurrent-gause &
$ curl localhost:8080/microprofile-metrics-example/annotated/concurrent-gause &
$ curl localhost:8080/microprofile-metrics-example/annotated/concurrent-gause &

メトリクスを見ると、現在メソッド処理中の数がわかったりします。

$ curl localhost:9990/metrics/application/org.littlewings.microprofile.metrics.SimpleAnnotatedResource.my_concurrent_gause
# TYPE application_org_littlewings_microprofile_metrics_SimpleAnnotatedResource_my_concurrent_gause_current gauge
application_org_littlewings_microprofile_metrics_SimpleAnnotatedResource_my_concurrent_gause_current 6.0
# TYPE application_org_littlewings_microprofile_metrics_SimpleAnnotatedResource_my_concurrent_gause_max gauge
application_org_littlewings_microprofile_metrics_SimpleAnnotatedResource_my_concurrent_gause_max 0.0
# TYPE application_org_littlewings_microprofile_metrics_SimpleAnnotatedResource_my_concurrent_gause_min gauge
application_org_littlewings_microprofile_metrics_SimpleAnnotatedResource_my_concurrent_gause_min 0.0

処理が全部終了すると、currentは0になります。

$ curl localhost:9990/metrics/application/org.littlewings.microprofile.metrics.SimpleAnnotatedResource.my_concurrent_gause
# TYPE application_org_littlewings_microprofile_metrics_SimpleAnnotatedResource_my_concurrent_gause_current gauge
application_org_littlewings_microprofile_metrics_SimpleAnnotatedResource_my_concurrent_gause_current 0.0
# TYPE application_org_littlewings_microprofile_metrics_SimpleAnnotatedResource_my_concurrent_gause_max gauge
application_org_littlewings_microprofile_metrics_SimpleAnnotatedResource_my_concurrent_gause_max 6.0
# TYPE application_org_littlewings_microprofile_metrics_SimpleAnnotatedResource_my_concurrent_gause_min gauge
application_org_littlewings_microprofile_metrics_SimpleAnnotatedResource_my_concurrent_gause_min 0.0

時間が経つと、maxなどに反映されていきます。

CDI管理Beanに付与したCounterも、こんな感じになりました。

$ curl localhost:9990/metrics/application/org.littlewings.microprofile.metrics.RandomService.randomInt
# TYPE application_org_littlewings_microprofile_metrics_RandomService_randomInt_total counter
application_org_littlewings_microprofile_metrics_RandomService_randomInt_total 5.0

TimerとSimple Timerも試してみましょう。こちらも、ランダムにスリープを入れます。

    @GET
    @Path("timer")
    @Produces(MediaType.TEXT_PLAIN)
    @Timed(name = "my_timer")
    public int timer() throws InterruptedException {
        long sleepSeconds = randomService.randomInt(5);
        TimeUnit.SECONDS.sleep(sleepSeconds);

        return (int) sleepSeconds;
    }

    @GET
    @Path("simply-timer")
    @Produces(MediaType.TEXT_PLAIN)
    @SimplyTimed(name = "my_simply_timer")
    public int simplyTimer() throws InterruptedException {
        long sleepSeconds = randomService.randomInt(5);
        TimeUnit.SECONDS.sleep(sleepSeconds);

        return (int) sleepSeconds;
    }

Timerで記録するメソッドにアクセスしてみます。5回ほど。

$ curl localhost:8080/microprofile-metrics-example/annotated/timer
4


$ curl localhost:8080/microprofile-metrics-example/annotated/timer
4


$ curl localhost:8080/microprofile-metrics-example/annotated/timer
3


$ curl localhost:8080/microprofile-metrics-example/annotated/timer
2


$ curl localhost:8080/microprofile-metrics-example/annotated/timer
3

Timerで記録したメトリクスです。

$ curl localhost:9990/metrics/application/org.littlewings.microprofile.metrics.SimpleAnnotatedResource.my_timer
# TYPE application_org_littlewings_microprofile_metrics_SimpleAnnotatedResource_my_timer_rate_per_second gauge
application_org_littlewings_microprofile_metrics_SimpleAnnotatedResource_my_timer_rate_per_second 0.04659992804288887
# TYPE application_org_littlewings_microprofile_metrics_SimpleAnnotatedResource_my_timer_one_min_rate_per_second gauge
application_org_littlewings_microprofile_metrics_SimpleAnnotatedResource_my_timer_one_min_rate_per_second 0.03803114091972095
# TYPE application_org_littlewings_microprofile_metrics_SimpleAnnotatedResource_my_timer_five_min_rate_per_second gauge
application_org_littlewings_microprofile_metrics_SimpleAnnotatedResource_my_timer_five_min_rate_per_second 0.014230203582008386
# TYPE application_org_littlewings_microprofile_metrics_SimpleAnnotatedResource_my_timer_fifteen_min_rate_per_second gauge
application_org_littlewings_microprofile_metrics_SimpleAnnotatedResource_my_timer_fifteen_min_rate_per_second 0.005270118248321379
# TYPE application_org_littlewings_microprofile_metrics_SimpleAnnotatedResource_my_timer_min_seconds gauge
application_org_littlewings_microprofile_metrics_SimpleAnnotatedResource_my_timer_min_seconds 2.000252859
# TYPE application_org_littlewings_microprofile_metrics_SimpleAnnotatedResource_my_timer_max_seconds gauge
application_org_littlewings_microprofile_metrics_SimpleAnnotatedResource_my_timer_max_seconds 4.000690081
# TYPE application_org_littlewings_microprofile_metrics_SimpleAnnotatedResource_my_timer_mean_seconds gauge
application_org_littlewings_microprofile_metrics_SimpleAnnotatedResource_my_timer_mean_seconds 3.1550887689637688
# TYPE application_org_littlewings_microprofile_metrics_SimpleAnnotatedResource_my_timer_stddev_seconds gauge
application_org_littlewings_microprofile_metrics_SimpleAnnotatedResource_my_timer_stddev_seconds 0.7427672463717483
# TYPE application_org_littlewings_microprofile_metrics_SimpleAnnotatedResource_my_timer_seconds summary
application_org_littlewings_microprofile_metrics_SimpleAnnotatedResource_my_timer_seconds_count 5.0
# TYPE application_org_littlewings_microprofile_metrics_SimpleAnnotatedResource_my_timer_seconds_sum gauge
application_org_littlewings_microprofile_metrics_SimpleAnnotatedResource_my_timer_seconds_sum 16.001751731
application_org_littlewings_microprofile_metrics_SimpleAnnotatedResource_my_timer_seconds{quantile="0.5"} 3.000265941
application_org_littlewings_microprofile_metrics_SimpleAnnotatedResource_my_timer_seconds{quantile="0.75"} 4.000317245
application_org_littlewings_microprofile_metrics_SimpleAnnotatedResource_my_timer_seconds{quantile="0.95"} 4.000690081
application_org_littlewings_microprofile_metrics_SimpleAnnotatedResource_my_timer_seconds{quantile="0.98"} 4.000690081
application_org_littlewings_microprofile_metrics_SimpleAnnotatedResource_my_timer_seconds{quantile="0.99"} 4.000690081
application_org_littlewings_microprofile_metrics_SimpleAnnotatedResource_my_timer_seconds{quantile="0.999"} 4.000690081

次に、Simple Timer。

$ curl localhost:8080/microprofile-metrics-example/annotated/simply-timer
4


$ curl localhost:8080/microprofile-metrics-example/annotated/simply-timer
1


$ curl localhost:8080/microprofile-metrics-example/annotated/simply-timer
0


$ curl localhost:8080/microprofile-metrics-example/annotated/simply-timer
3


$ curl localhost:8080/microprofile-metrics-example/annotated/simply-timer
0

Timerに比べると、記録されるメトリクスはぐっと減ります。

$ curl localhost:9990/metrics/application/org.littlewings.microprofile.metrics.SimpleAnnotatedResource.my_simply_timer
# TYPE application_org_littlewings_microprofile_metrics_SimpleAnnotatedResource_my_simply_timer_total counter
application_org_littlewings_microprofile_metrics_SimpleAnnotatedResource_my_simply_timer_total 5.0
# TYPE application_org_littlewings_microprofile_metrics_SimpleAnnotatedResource_my_simply_timer_elapsedTime_seconds gauge
application_org_littlewings_microprofile_metrics_SimpleAnnotatedResource_my_simply_timer_elapsedTime_seconds 8.000970078
# TYPE application_org_littlewings_microprofile_metrics_SimpleAnnotatedResource_my_simply_timer_minTimeDuration_seconds gauge
application_org_littlewings_microprofile_metrics_SimpleAnnotatedResource_my_simply_timer_minTimeDuration_seconds 6.6287E-5
# TYPE application_org_littlewings_microprofile_metrics_SimpleAnnotatedResource_my_simply_timer_maxTimeDuration_seconds gauge
application_org_littlewings_microprofile_metrics_SimpleAnnotatedResource_my_simply_timer_maxTimeDuration_seconds 4.000279805

Gause

アノテーションを使ったサンプルの最後に、Gaugeを試してみましょう。

Gaugeは特殊で、アノテーションを付与してもすぐにはメトリクスに登録されず、実際にアノテーションを付与した
CDI管理Beanがインスタンス化されるまで遅延します。

Responsibility of the MicroProfile Metrics implementation

また、Gaugeは複数のCDI管理Beanに紐付けられることを許可しません。

Metrics and CDI scopes

このあたりが注意点です。で、Gaugeを使用したサンプル。

src/main/java/org/littlewings/microprofile/metrics/ApplicationScopedAnnotatedResource.java

package org.littlewings.microprofile.metrics;

import javax.enterprise.context.ApplicationScoped;
import javax.inject.Inject;
import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.Produces;
import javax.ws.rs.core.MediaType;

import org.eclipse.microprofile.metrics.MetricUnits;
import org.eclipse.microprofile.metrics.annotation.Gauge;

@Path("application-scoped-annotated")
@ApplicationScoped
public class ApplicationScopedAnnotatedResource {
    @Inject
    RandomService randomService;

    @GET
    @Path("gauge")
    @Produces(MediaType.TEXT_PLAIN)
    @Gauge(name = "my_gauge", unit = MetricUnits.BYTES)
    public int gause() {
        Thread.dumpStack();

        return randomService.randomInt(1024);
    }
}

Gaugeは、他のメトリクスと違って単位を明示的に指定する必要があります。

    @Gauge(name = "my_gauge", unit = MetricUnits.BYTES)

Gaugeを使ったメソッドにアクセスしてみます。

$ curl localhost:8080/microprofile-metrics-example/application-scoped-annotated/gauge
360


$ curl localhost:8080/microprofile-metrics-example/application-scoped-annotated/gauge
999

これで、メトリクスが記録されるのですが…。

実際に記録されたメトリクスを確認してみます。

$ curl localhost:9990/metrics/application/org.littlewings.microprofile.metrics.ApplicationScopedAnnotatedResource.my_gauge
# TYPE application_org_littlewings_microprofile_metrics_ApplicationScopedAnnotatedResource_my_gauge_bytes gauge
application_org_littlewings_microprofile_metrics_ApplicationScopedAnnotatedResource_my_gauge_bytes 541.0

この時、裏では@Gaugeアノテーションを付与したメソッドが呼び出されています。

18:23:40,560 ERROR [stderr] (management I/O-1) java.lang.Exception: Stack trace
18:23:40,560 ERROR [stderr] (management I/O-1)  at java.base/java.lang.Thread.dumpStack(Thread.java:1383)
18:23:40,560 ERROR [stderr] (management I/O-1)  at deployment.microprofile-metrics-example.war//org.littlewings.microprofile.metrics.ApplicationScopedAnnotatedResource.gause(ApplicationScopedAnnotatedResource.java:24)
18:23:40,560 ERROR [stderr] (management I/O-1)  at java.base/jdk.internal.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
18:23:40,560 ERROR [stderr] (management I/O-1)  at java.base/jdk.internal.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:62)
18:23:40,560 ERROR [stderr] (management I/O-1)  at java.base/jdk.internal.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43)
18:23:40,560 ERROR [stderr] (management I/O-1)  at java.base/java.lang.reflect.Method.invoke(Method.java:566)
18:23:40,560 ERROR [stderr] (management I/O-1)  at io.smallrye.metrics//io.smallrye.metrics.interceptors.GaugeRegistrationInterceptor.invokeMethod(GaugeRegistrationInterceptor.java:88)
18:23:40,560 ERROR [stderr] (management I/O-1)  at io.smallrye.metrics//io.smallrye.metrics.interceptors.GaugeRegistrationInterceptor.access$100(GaugeRegistrationInterceptor.java:46)
18:23:40,560 ERROR [stderr] (management I/O-1)  at io.smallrye.metrics//io.smallrye.metrics.interceptors.GaugeRegistrationInterceptor$ForwardingGauge.getValue(GaugeRegistrationInterceptor.java:108)
18:23:40,560 ERROR [stderr] (management I/O-1)  at io.smallrye.metrics//io.smallrye.metrics.interceptors.GaugeRegistrationInterceptor$ForwardingGauge.getValue(GaugeRegistrationInterceptor.java:94)
18:23:40,560 ERROR [stderr] (management I/O-1)  at io.smallrye.metrics//io.smallrye.metrics.exporters.OpenMetricsExporter.createSimpleValueLine(OpenMetricsExporter.java:513)
18:23:40,560 ERROR [stderr] (management I/O-1)  at io.smallrye.metrics//io.smallrye.metrics.exporters.OpenMetricsExporter.exposeEntries(OpenMetricsExporter.java:200)
18:23:40,560 ERROR [stderr] (management I/O-1)  at io.smallrye.metrics//io.smallrye.metrics.exporters.OpenMetricsExporter.exportMetricsByName(OpenMetricsExporter.java:148)
18:23:40,561 ERROR [stderr] (management I/O-1)  at io.smallrye.metrics//io.smallrye.metrics.MetricsRequestHandler.handleRequest(MetricsRequestHandler.java:139)
18:23:40,561 ERROR [stderr] (management I/O-1)  at io.smallrye.metrics//io.smallrye.metrics.MetricsRequestHandler.handleRequest(MetricsRequestHandler.java:79)

Thread#dumpStackを入れていたのは、このためです。

    public int gause() {
        Thread.dumpStack();

他のメトリクスと異なり、Gaugeはメトリクス取得時に紐付けられた処理が呼び出されますよ、という話でした。

MetricRegistryを使う

最後に、MtricRegistryを使ってみましょう。

Metric Registries

Registering metrics dynamically

これまではアノテーションでメトリクスを定義したり、値を記録したりしていましたが、MetricRegistryを使うことで
メトリクスの定義や記録をAPIで行うことができます。

MetricRegistryはスコープ（Base metrics、Vendor specific metrics、Application metrics）ごとにシングルトンのインスタンスが
あり、@Injectアノテーションで取得できます。

MetricRegistryを使ったコードの雛形を、このように用意。

src/main/java/org/littlewings/microprofile/metrics/MetricRegistryResource.java

package org.littlewings.microprofile.metrics;

import javax.annotation.PostConstruct;
import javax.inject.Inject;
import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.Produces;
import javax.ws.rs.core.MediaType;

import org.eclipse.microprofile.metrics.Counter;
import org.eclipse.microprofile.metrics.Histogram;
import org.eclipse.microprofile.metrics.Metadata;
import org.eclipse.microprofile.metrics.MetricRegistry;
import org.eclipse.microprofile.metrics.MetricType;
import org.eclipse.microprofile.metrics.MetricUnits;
import org.eclipse.microprofile.metrics.Tag;

@Path("metric-registry")
public class MetricRegistryResource {
    @Inject
    MetricRegistry metricRegistry;

    // ここに、MetricRegistryを使ったコードを書く！！
}

MetricRegistryはこんな感じで@InjectでCDI管理Beanにインジェクションできますが、これでApplication metricsに対応する
インスタンスが取得できます。

    @Inject
    MetricRegistry metricRegistry;

こんな感じにするとBase metricsやVendor specific metricsに対応するインスタンスも取得できますが、アプリケーションでは
使うことはないでしょう。

@Inject
@RegistryType(type=MetricRegistry.Type.BASE)
MetricRegistry baseRegistry;


@Inject
@RegistryType(type=MetricRegistry.Type.VENDOR)
MetricRegistry vendorRegistry;

Application metricsを明示する場合は、こうなります。

@Inject
@RegistryType(type=MetricRegistry.Type.APPLICATION)
MetricRegistry metricRegistry;

では、進めていきます。

まずはCounterを使ってみましょう。

    @GET
    @Path("simple-counter")
    @Produces(MediaType.TEXT_PLAIN)
    public String simpleCounter() {
        Counter counter = metricRegistry.counter("simple_counter_by_registry");
        counter.inc();
        return "Hello World!!";
    }

MetricRegistryから名前を指定してCounterを取得し、Counter#incでカウンタを増加できます。

確認。

$ curl localhost:8080/microprofile-metrics-example/metric-registry/simple-counter
Hello World!!


$ curl localhost:8080/microprofile-metrics-example/metric-registry/simple-counter
Hello World!!

MetricRegistryを使って定義した場合は、メトリクスの名前は指定した名前そのものになります。

$ curl localhost:9990/metrics/application/simple_counter_by_registry
# TYPE application_simple_counter_by_registry_total counter
application_simple_counter_by_registry_total 2.0

MetricRegistry#counterのように、各種メトリクスに対応したメソッドがあるのですが、これはget-or-createなので
MetricIDがすでに存在していれば同じメトリクスが返されます。

List of methods of the MetricRegistry related to registering new metrics

        Counter counter = metricRegistry.counter("simple_counter_by_registry");

MetricIDとは、メトリクスの名前とタグの組み合わせです。

MetricID

次は、メタデータを定義してみましょう。

メトリクスのget-or-create時にメタデータを指定することもできるのですが、今回は最初に登録しておくことにしましょう。

    @PostConstruct
    public void init() {
        Metadata counterMetadata =
                Metadata
                        .builder()
                        .withName("registered_counter_by_registry")
                        .withDescription("pre registered counter by registry")
                        .withType(MetricType.COUNTER)
                        .withUnit(MetricUnits.NONE)
                        .build();

        metricRegistry.counter(counterMetadata);
    }

使用例。メタデータで指定した名前と、同じ名前でMetricRegistryからメトリクスを取得すればOKです。

    @GET
    @Path("pre-registered-counter")
    @Produces(MediaType.TEXT_PLAIN)
    public String preRegisteredCounter() {
        Counter counter = metricRegistry.counter("registered_counter_by_registry");
        counter.inc();
        return "Pre Registered Counter!!";
    }

また、メトリクスのクラスを直接使用する場合は、このようにタグを指定することもできます。
こちらは、先ほどと同じ名前のCounterを使用しています。

    @GET
    @Path("pre-registered-counter2")
    @Produces(MediaType.TEXT_PLAIN)
    public String preRegisteredCounter2() {
        Counter counter =
                metricRegistry
                        .counter(
                                "registered_counter_by_registry",
                                new Tag("path", "/metric-registry/pre-registered-counter2"),
                                new Tag("type", "2")
                        );
        counter.inc();

        return "Pre Registered Counter2!!";
    }

それぞれにアクセス。

$ curl localhost:8080/microprofile-metrics-example/metric-registry/pre-registered-counter
Pre Registered Counter!!


$ curl localhost:8080/microprofile-metrics-example/metric-registry/pre-registered-counter
Pre Registered Counter!!


$ curl localhost:8080/microprofile-metrics-example/metric-registry/pre-registered-counter2
Pre Registered Counter2!!


$ curl localhost:8080/microprofile-metrics-example/metric-registry/pre-registered-counter2
Pre Registered Counter2!!

メトリクスを確認。

$ curl localhost:9990/metrics/application/registered_counter_by_registry
# HELP application_registered_counter_by_registry_total pre registered counter by registry
# TYPE application_registered_counter_by_registry_total counter
application_registered_counter_by_registry_total{path="/metric-registry/pre-registered-counter2",type="2"} 2.0
application_registered_counter_by_registry_total 2.0

タグの有無で、結果が別々になりましたね。

これで、タグの確認もできました。

Histgram

アノテーションではメトリクスを記録できず、メトリクスに対応するクラスを直接扱って記録するものとしてHistogramが
あります。

最後にこちらを使ってみましょう。

メタデータはCounterと同じように登録しておきます。

    @PostConstruct
    public void init() {
        Metadata counterMetadata =
                Metadata
                        .builder()
                        .withName("registered_counter_by_registry")
                        .withDescription("pre registered counter by registry")
                        .withType(MetricType.COUNTER)
                        .withUnit(MetricUnits.NONE)
                        .build();

        metricRegistry.counter(counterMetadata);

        Metadata histogramMetadata =
                Metadata
                        .builder()
                        .withName("my_histogram")
                        .withDescription("my histogram example")
                        .withType(MetricType.HISTOGRAM)
                        .withUnit(MetricUnits.BYTES)
                        .build();

        metricRegistry.histogram(histogramMetadata);
    }

単位を見たらわかりますが、バイト数をテーマにしてみます。

Histogramを使った例。タグも使ってみます。

    @GET
    @Path("histogram")
    @Produces(MediaType.TEXT_PLAIN)
    public String histogram() {
        Histogram histogram =
                metricRegistry.histogram(
                        "my_histogram",
                        new Tag("path", "/metric-registry/histogram")
                );

        long randomInt = randomService.randomInt(1024);
        histogram.update(randomInt);

        return String.format("Histogram, random = %d", randomInt);
    }

ランダムな数字を記録してみます。

アクセスしてみます。

$ curl localhost:8080/microprofile-metrics-example/metric-registry/histogram
Histogram, random = 171


$ curl localhost:8080/microprofile-metrics-example/metric-registry/histogram
Histogram, random = 86


$ curl localhost:8080/microprofile-metrics-example/metric-registry/histogram
Histogram, random = 819

メトリクスも見てみます。

$ curl localhost:9990/metrics/application/my_histogram
# HELP application_my_histogram_bytes my histogram example
# TYPE application_my_histogram_min_bytes gauge
application_my_histogram_min_bytes{path="/metric-registry/histogram"} 86.0
# TYPE application_my_histogram_max_bytes gauge
application_my_histogram_max_bytes{path="/metric-registry/histogram"} 819.0
# TYPE application_my_histogram_mean_bytes gauge
application_my_histogram_mean_bytes{path="/metric-registry/histogram"} 361.91676959746343
# TYPE application_my_histogram_stddev_bytes gauge
application_my_histogram_stddev_bytes{path="/metric-registry/histogram"} 328.6816538560838
# TYPE application_my_histogram_bytes summary
application_my_histogram_bytes_count{path="/metric-registry/histogram"} 3.0
application_my_histogram_bytes_sum{path="/metric-registry/histogram"} 1076.0
application_my_histogram_bytes{path="/metric-registry/histogram",quantile="0.5"} 171.0
application_my_histogram_bytes{path="/metric-registry/histogram",quantile="0.75"} 819.0
application_my_histogram_bytes{path="/metric-registry/histogram",quantile="0.95"} 819.0
application_my_histogram_bytes{path="/metric-registry/histogram",quantile="0.98"} 819.0
application_my_histogram_bytes{path="/metric-registry/histogram",quantile="0.99"} 819.0
application_my_histogram_bytes{path="/metric-registry/histogram",quantile="0.999"} 819.0
application_my_histogram_min_bytes 0.0
application_my_histogram_max_bytes 0.0
application_my_histogram_mean_bytes 0.0
application_my_histogram_stddev_bytes 0.0
application_my_histogram_bytes_count 0.0
application_my_histogram_bytes_sum 0.0
application_my_histogram_bytes{quantile="0.5"} 0.0
application_my_histogram_bytes{quantile="0.75"} 0.0
application_my_histogram_bytes{quantile="0.95"} 0.0
application_my_histogram_bytes{quantile="0.98"} 0.0
application_my_histogram_bytes{quantile="0.99"} 0.0
application_my_histogram_bytes{quantile="0.999"} 0.0

こんな感じで、いろいろ記録されます。タグなしの方が記録されていないのは、スルーしましょう。

サフィックスは、メトリクスに指定した単位が反映されます。

Histogram OpenMetrics Text Format

とりあえず、こんなところでしょうか。

まとめ

Eclipse MicroProfile Metricsを試してみました。

いろいろ扱ってみたのですが、けっこう範囲が広くてカバーしきれないというか、エントリ自体が中途半端になったような
気がしますが…。

もう少し、絞って書いた方がよかったかもしれません…。

SmallRye MetricsのJAX-RSの部分がうまく扱えなかったりしたので、このあたりはまた別途やりたいですね。

とりあえず、今回はこんなところで。

オマケ

何回もWildFlyにデプロイして確認するのが面倒だったので、ソースコードを書いている時はWildFly Bootable JARで
変更をリアルタイムに反映しながら確認していました。

以下の設定をpom.xmlに入れて

    <profiles>
        <profile>
            <id>bootable</id>
            <build>
                <plugins>
                    <plugin>
                        <groupId>org.wildfly.plugins</groupId>
                        <artifactId>wildfly-jar-maven-plugin</artifactId>
                        <version>5.0.2.Final</version>
                        <configuration>
                            <feature-pack-location>wildfly@maven(org.jboss.universe:community-universe)#24.0.1.Final
                            </feature-pack-location>
                            <layers>
                                <layer>jaxrs-server</layer>
                                <layer>management</layer>
                                <layer>microprofile-metrics</layer>
                            </layers>
                            <plugin-options>
                                <jboss-maven-dist/>
                            </plugin-options>
                        </configuration>
                    </plugin>
                </plugins>
            </build>
        </profile>
    </profiles>

以下で、ソースコードの変更の度に反映されるようになります。

$ mvn -P bootable wildfly-jar:dev-watch

この形態だと、デプロイされるWARファイルはROOT.warになっていることになるので、その点だけ注意ですね。

$ curl localhost:8080/annotated/count-hello-world
Hello World!!

メトリクス取得のURLは、Bootable JARでも変わりません。

$ curl localhost:9990/metrics/application/org.littlewings.microprofile.metrics.SimpleAnnotatedResource.hello_world_call_count
# TYPE application_org_littlewings_microprofile_metrics_SimpleAnnotatedResource_hello_world_call_count_total counter
application_org_littlewings_microprofile_metrics_SimpleAnnotatedResource_hello_world_call_count_total 1.0

だいたいできたら、最後にWildFlyにデプロイして確認していました。