Micrometerアダプタ¶

DefaultMeterBinderListProviderをコンポーネントとして宣言する¶

Micrometerには、 MeterBinder(外部サイト、英語) というインタフェースが存在する。

JVMのメモリ使用量やCPU使用率など、よく利用するメトリクスの収集は、このインタフェースを実装したクラスとしてあらかじめ用意されている。 （例：JVMのメモリ使用量は JvmMemoryMetrics(外部サイト、英語) 、CPU使用率は ProcessorMetrics(外部サイト、英語) ）

DefaultMeterBinderListProvider は、この MeterBinder(外部サイト、英語) のリストを提供するクラスで、本クラスを使用することでJVMのメモリ使用量やCPU使用率などのメトリクスを収集できるようになる。

まず src/main/resources/web-component-configuration.xml に、この DefaultMeterBinderListProvider の宣言を追加する。

<component name="meterBinderListProvider"
           class="nablarch.integration.micrometer.DefaultMeterBinderListProvider" />

収集されるメトリクスの具体的な説明については、 DefaultMeterBinderListProviderで収集されるメトリクス を参照。

DefaultMeterBinderListProviderを廃棄処理対象にする¶

DefaultMeterBinderListProvider は廃棄処理が必要なコンポーネントなので、下記のように廃棄処理対象として宣言する。

<component name="disposer"
    class="nablarch.core.repository.disposal.BasicApplicationDisposer">

  <property name="disposableList">
    <list>
      <component-ref name="meterBinderListProvider"/>
    </list>
  </property>

</component>

オブジェクトの廃棄処理については、 オブジェクトの廃棄処理を行う を参照

レジストリのファクトリクラスをコンポーネントとして宣言する¶

<component class="nablarch.integration.micrometer.logging.LoggingMeterRegistryFactory">
  <property name="meterBinderListProvider" ref="meterBinderListProvider" />
  <property name="applicationDisposer" ref="disposer" />
</component>

次に、使用するレジストリごとに用意されているファクトリクラスをコンポーネントとして宣言する。

このとき、 meterBinderListProvider と applicationDisposer の２つのプロパティを設定する。 それぞれのプロパティには、上で宣言した DefaultMeterBinderListProvider と BasicApplicationDisposer を設定する。

なお、本アダプタが提供しているファクトリクラスについては レジストリファクトリ に一覧を記載している。

設定ファイルを作成する¶

最後に、 src/main/resources の下に micrometer.properties という名前のテキストファイルを作成する。

ここでは、中身を次のように記述する。

# 5秒ごとにメトリクスを出力する
nablarch.micrometer.logging.step=5s

実行結果¶

以上で、 LoggingMeterRegistry を用いたメトリクスの収集ができるようになる。

アプリケーションを起動すると、以下のように収集されたメトリクスが標準出力に出力されていることを確認できる。

2020-09-04 15:33:40.689 [INFO ]      i.m.c.i.l.LoggingMeterRegistry: jvm.gc.count{memory.manager.name=PS Scavenge} throughput=2.6/s
2020-09-04 15:33:40.690 [INFO ]      i.m.c.i.l.LoggingMeterRegistry: jvm.gc.count{memory.manager.name=PS MarkSweep} throughput=0.4/s
2020-09-04 15:33:40.691 [INFO ]      i.m.c.i.l.LoggingMeterRegistry: jvm.buffer.count{id=mapped} value=0 buffers
2020-09-04 15:33:40.691 [INFO ]      i.m.c.i.l.LoggingMeterRegistry: jvm.buffer.count{id=direct} value=2 buffers
2020-09-04 15:33:40.692 [INFO ]      i.m.c.i.l.LoggingMeterRegistry: jvm.buffer.memory.used{id=direct} value=124 KiB
2020-09-04 15:33:40.692 [INFO ]      i.m.c.i.l.LoggingMeterRegistry: jvm.buffer.memory.used{id=mapped} value=0 B
2020-09-04 15:33:40.692 [INFO ]      i.m.c.i.l.LoggingMeterRegistry: jvm.buffer.total.capacity{id=mapped} value=0 B
2020-09-04 15:33:40.692 [INFO ]      i.m.c.i.l.LoggingMeterRegistry: jvm.buffer.total.capacity{id=direct} value=124 KiB
2020-09-04 15:33:40.693 [INFO ]      i.m.c.i.l.LoggingMeterRegistry: jvm.classes.loaded{} value=9932 classes
2020-09-04 15:33:40.693 [INFO ]      i.m.c.i.l.LoggingMeterRegistry: jvm.gc.live.data.size{} value=0 B
2020-09-04 15:33:40.693 [INFO ]      i.m.c.i.l.LoggingMeterRegistry: jvm.gc.max.data.size{} value=2.65918 GiB
2020-09-04 15:33:40.694 [INFO ]      i.m.c.i.l.LoggingMeterRegistry: jvm.memory.committed{area=heap,id=PS Old Gen} value=182.5 MiB
2020-09-04 15:33:40.694 [INFO ]      i.m.c.i.l.LoggingMeterRegistry: jvm.memory.committed{area=heap,id=PS Survivor Space} value=44 MiB
2020-09-04 15:33:40.694 [INFO ]      i.m.c.i.l.LoggingMeterRegistry: jvm.memory.committed{area=heap,id=PS Eden Space} value=197 MiB
2020-09-04 15:33:40.694 [INFO ]      i.m.c.i.l.LoggingMeterRegistry: jvm.memory.committed{area=nonheap,id=Code Cache} value=29.125 MiB
2020-09-04 15:33:40.694 [INFO ]      i.m.c.i.l.LoggingMeterRegistry: jvm.memory.committed{area=nonheap,id=Compressed Class Space} value=6.796875 MiB
2020-09-04 15:33:40.695 [INFO ]      i.m.c.i.l.LoggingMeterRegistry: jvm.memory.committed{area=nonheap,id=Metaspace} value=55.789062 MiB
2020-09-04 15:33:40.695 [INFO ]      i.m.c.i.l.LoggingMeterRegistry: jvm.memory.max{area=heap,id=PS Old Gen} value=2.65918 GiB
2020-09-04 15:33:40.695 [INFO ]      i.m.c.i.l.LoggingMeterRegistry: jvm.memory.max{area=heap,id=PS Survivor Space} value=44 MiB
2020-09-04 15:33:40.696 [INFO ]      i.m.c.i.l.LoggingMeterRegistry: jvm.memory.max{area=nonheap,id=Code Cache} value=240 MiB
2020-09-04 15:33:40.696 [INFO ]      i.m.c.i.l.LoggingMeterRegistry: jvm.memory.max{area=nonheap,id=Metaspace} value=-1 B
2020-09-04 15:33:40.696 [INFO ]      i.m.c.i.l.LoggingMeterRegistry: jvm.memory.max{area=heap,id=PS Eden Space} value=1.243652 GiB
2020-09-04 15:33:40.696 [INFO ]      i.m.c.i.l.LoggingMeterRegistry: jvm.memory.max{area=nonheap,id=Compressed Class Space} value=1 GiB
2020-09-04 15:33:40.697 [INFO ]      i.m.c.i.l.LoggingMeterRegistry: jvm.memory.used{area=nonheap,id=Code Cache} value=28.618713 MiB
2020-09-04 15:33:40.697 [INFO ]      i.m.c.i.l.LoggingMeterRegistry: jvm.memory.used{area=nonheap,id=Compressed Class Space} value=6.270714 MiB
2020-09-04 15:33:40.697 [INFO ]      i.m.c.i.l.LoggingMeterRegistry: jvm.memory.used{area=nonheap,id=Metaspace} value=54.118324 MiB
2020-09-04 15:33:40.698 [INFO ]      i.m.c.i.l.LoggingMeterRegistry: jvm.memory.used{area=heap,id=PS Old Gen} value=69.320663 MiB
2020-09-04 15:33:40.698 [INFO ]      i.m.c.i.l.LoggingMeterRegistry: jvm.memory.used{area=heap,id=PS Survivor Space} value=7.926674 MiB
2020-09-04 15:33:40.698 [INFO ]      i.m.c.i.l.LoggingMeterRegistry: jvm.memory.used{area=heap,id=PS Eden Space} value=171.750542 MiB
2020-09-04 15:33:40.698 [INFO ]      i.m.c.i.l.LoggingMeterRegistry: jvm.threads.daemon{} value=28 threads
2020-09-04 15:33:40.698 [INFO ]      i.m.c.i.l.LoggingMeterRegistry: jvm.threads.live{} value=29 threads
2020-09-04 15:33:40.699 [INFO ]      i.m.c.i.l.LoggingMeterRegistry: jvm.threads.peak{} value=31 threads
2020-09-04 15:33:40.702 [INFO ]      i.m.c.i.l.LoggingMeterRegistry: jvm.threads.states{state=blocked} value=0 threads
2020-09-04 15:33:40.703 [INFO ]      i.m.c.i.l.LoggingMeterRegistry: jvm.threads.states{state=runnable} value=9 threads
2020-09-04 15:33:40.703 [INFO ]      i.m.c.i.l.LoggingMeterRegistry: jvm.threads.states{state=new} value=0 threads
2020-09-04 15:33:40.703 [INFO ]      i.m.c.i.l.LoggingMeterRegistry: jvm.threads.states{state=timed-waiting} value=3 threads
2020-09-04 15:33:40.703 [INFO ]      i.m.c.i.l.LoggingMeterRegistry: jvm.threads.states{state=terminated} value=0 threads
2020-09-04 15:33:40.704 [INFO ]      i.m.c.i.l.LoggingMeterRegistry: jvm.threads.states{state=waiting} value=17 threads
2020-09-04 15:33:41.199 [INFO ]      i.m.c.i.l.LoggingMeterRegistry: process.cpu.usage{} value=0.111672
2020-09-04 15:33:41.199 [INFO ]      i.m.c.i.l.LoggingMeterRegistry: process.start.time{} value=444222h 33m 14.544s
2020-09-04 15:33:41.199 [INFO ]      i.m.c.i.l.LoggingMeterRegistry: process.uptime{} value=26.729s
2020-09-04 15:33:41.200 [INFO ]      i.m.c.i.l.LoggingMeterRegistry: system.cpu.count{} value=8
2020-09-04 15:33:41.200 [INFO ]      i.m.c.i.l.LoggingMeterRegistry: system.cpu.usage{} value=0.394545

配置場所¶

本アダプタの設定ファイルは、クラスパス直下に micrometer.properties という名前で配置されるように作成する。

フォーマット¶

このファイルに記載する設定は、以下のフォーマットで記述する。

nablarch.micrometer.<subPrefix>.<key>=設定する値

ここで、 <subPrefix> に設定する値は、使用するレジストリファクトリごとに異なる値を指定する。

レジストリファクトリごとに、 <subPrefix> で指定する値を下記表に記載する。

また、 <key> には Micrometer がレジストリごとに提供している 設定クラス(外部サイト、英語) で定義されたメソッドと同じ名前を指定する。

例えば、 DatadogMeterRegistry(外部サイト、英語) に対しては DatadogConfig(外部サイト、英語) という設定クラスが用意されている。 そして、この設定クラスには apyKey(外部サイト、英語) というメソッドが定義されている。

したがって、 micrometer.properties に次のように記述することで、 apiKey を設定できる。

nablarch.micrometer.datadog.apiKey=XXXXXXXXXXXXXXXXXXXX

OS環境変数・システムプロパティで上書きする¶

micrometer.properties に記述した設定の値は、OS環境変数およびシステムプロパティで上書きできる。

設定値は、優先度の高い順に次の順番で採用される。

1. システムプロパティで指定した値
2. OS環境変数で指定した値
3. micrometer.properties の設定値

例えば、次のような条件で設定したとする。

micrometer.properties

nablarch.micrometer.example.one=PROPERTIES
nablarch.micrometer.example.two=PROPERTIES
nablarch.micrometer.example.three=PROPERTIES

OS環境変数

$ export NABLARCH_MICROMETER_EXAMPLE_TWO=OS_ENV

$ export NABLARCH_MICROMETER_EXAMPLE_THREE=OS_ENV

システムプロパティ

-Dnablarch.micrometer.example.three=SYSTEM_PROP

この場合、それぞれの設定値は最終的に次の値が採用される。

OS環境変数で上書きするときの名前のルールについては、 OS環境変数の名前について を参照。

設定のプレフィックスを変更する¶

設定のプレフィックス (nablarch.micrometer.<subPrefix>) は、各レジストリファクトリごとに prefix プロパティを指定することで変更できる。

以下に、プレフィックスを変更する例を記載する。

<component name="meterRegistry" class="nablarch.integration.micrometer.logging.LoggingMeterRegistryFactory">
  <property name="meterBinderListProvider" ref="meterBinderListProvider" />
  <property name="applicationDisposer" ref="disposer" />

  <!-- prefix プロパティに任意のプレフィックスを設定する -->
  <property name="prefix" value="sample.prefix" />
</component>

この場合、 micrometer.properties は次のように設定できるようになる。

sample.prefix.step=10s

設定ファイルの場所を変更する¶

設定ファイル（micrometer.properties）の場所は、以下の方法で変更できる。

まず、レジストリファクトリの xmlConfigPath プロパティに、設定ファイルを読み込むXMLファイルのパスを指定する。

<component name="meterRegistry" class="nablarch.integration.micrometer.logging.LoggingMeterRegistryFactory">
  <property name="meterBinderListProvider" ref="meterBinderListProvider" />
  <property name="applicationDisposer" ref="disposer" />

  <!-- 設定ファイルを読み込むXMLファイルのパスを指定 -->
  <property name="xmlConfigPath" value="config/metrics.xml" />
</component>

そして、 xmlConfigPath プロパティで指定した場所に、設定ファイルを読み込むXMLファイルを配置する。 下記設定では、クラスパス内の config/metrics.properties が設定ファイルとして読み込まれるようになる。

<?xml version="1.0" encoding="UTF-8"?>
<component-configuration
        xmlns="http://tis.co.jp/nablarch/component-configuration"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="http://tis.co.jp/nablarch/component-configuration https://nablarch.github.io/schema/component-configuration.xsd">

  <!-- Micrometerアダプタの設定を読み込む -->
  <config-file file="config/metrics.properties" />

</component-configuration>

Datadog と連携する¶

依存関係を追加する

<dependency>
  <groupId>io.micrometer</groupId>
  <artifactId>micrometer-registry-datadog</artifactId>
  <version>1.5.4</version>
</dependency>

レジストリファクトリを宣言する

<component name="meterRegistry" class="nablarch.integration.micrometer.datadog.DatadogMeterRegistryFactory">
  <property name="meterBinderListProvider" ref="meterBinderListProvider" />
  <property name="applicationDisposer" ref="disposer" />
</component>

APIキーを設定する

nablarch.micrometer.datadog.apiKey=XXXXXXXXXXXXXXXX

API キーは nablarch.micrometer.datadog.apyKey で設定できる。

その他の設定については DatadogConfig(外部サイト、英語) を参照。

CloudWatch と連携する¶

依存関係を追加する

<dependency>
  <groupId>io.micrometer</groupId>
  <artifactId>micrometer-registry-cloudwatch2</artifactId>
  <version>1.5.4</version>
</dependency>

レジストリファクトリを宣言する

<component name="meterRegistry" class="nablarch.integration.micrometer.cloudwatch.CloudWatchMeterRegistryFactory">
  <property name="meterBinderListProvider" ref="meterBinderListProvider" />
  <property name="applicationDisposer" ref="disposer" />
</component>

リージョンやアクセスキーを設定する

$ export AWS_REGION=ap-northeast-1

$ export AWS_ACCESS_KEY_ID=XXXXXXXXXXXXXXXXXXXXX

$ export AWS_SECRET_ACCESS_KEY=YYYYYYYYYYYYYYYYYYYYY

micrometer-registry-cloudwatch2 モジュールは AWS SDK を利用している。 したがって、リージョンやアクセスキーなどの設定は AWS SDK の方法に準拠する。

上記は、LinuxでOS環境変数を使って設定する場合の例を記載している。 より詳細な情報は、 AWSのドキュメント(外部サイト) を参照。

名前空間を設定する

nablarch.micrometer.cloudwatch.namespace=test

メトリクスのカスタム名前空間は nablarch.micrometer.cloudwatch.namespace で設定できる。

その他の設定については CloudWatchConfig(外部サイト、英語) を参照。

より詳細な設定

OS環境変数や設定ファイルでは指定できない、より詳細な設定を行いたい場合は、 CloudWatchAsyncClientProvider を実装したカスタムプロバイダを作ることで対応できる。

package example.micrometer.cloudwatch;

import nablarch.integration.micrometer.cloudwatch.CloudWatchAsyncClientProvider;
import software.amazon.awssdk.services.cloudwatch.CloudWatchAsyncClient;

public class CustomCloudWatchAsyncClientProvider implements CloudWatchAsyncClientProvider {
    @Override
    public CloudWatchAsyncClient provide() {
        return CloudWatchAsyncClient
                .builder()
                .asyncConfiguration(...) // 任意の設定を行う
                .build();
    }
}

CloudWatchAsyncClientProvider は CloudWatchAsyncClient を提供する provide() メソッドを持つ。 カスタムプロバイダでは、任意の設定を行った CloudWatchAsyncClient を構築して返すように provide() メソッドを実装する。

<component name="meterRegistry" class="nablarch.integration.micrometer.cloudwatch.CloudWatchMeterRegistryFactory">
  <property name="meterBinderListProvider" ref="meterBinderListProvider" />
  <property name="applicationDisposer" ref="disposer" />

  <!-- cloudWatchAsyncClientProvider プロパティにカスタムプロバイダを設定する -->
  <property name="cloudWatchAsyncClientProvider">
    <component class="example.micrometer.cloudwatch.CustomCloudWatchAsyncClientProvider" />
  </property>
</component>

作成したカスタムプロバイダは、 CloudWatchMeterRegistryFactory の cloudWatchAsyncClientProvider プロパティに設定する。

これにより、カスタムプロバイダが生成した CloudWatchAsyncClient がメトリクスの連携で使用されるようになる。

補足

デフォルトでは、 CloudWatchAsyncClient.create() (外部サイト、英語) で作成されたインスタンスが使用される。

StatsD で連携する¶

Datadog は DogStatsD(外部サイト) という StatsD(外部サイト、英語) プロトコルを使った連携をサポートしている。 したがって、 micrometer-registry-statsd モジュールを用いることで、 StatsD で Datadog と連携することもできる。

ここでは、 Datadog に StatsD プロトコルで連携する場合を例にして説明する。 なお、DogStatsD のインストール方法などについては Datadogのサイト(外部サイト) を参照。

依存関係を追加する

<dependency>
  <groupId>io.micrometer</groupId>
  <artifactId>micrometer-registry-statsd</artifactId>
  <version>1.5.4</version>
</dependency>

レジストリファクトリを宣言する

<component name="meterRegistry" class="nablarch.integration.micrometer.statsd.StatsdMeterRegistryFactory">
  <property name="meterBinderListProvider" ref="meterBinderListProvider" />
  <property name="applicationDisposer" ref="disposer" />
</component>

必要に応じて設定ファイルを記述する

StatsD デーモンと連携するための設定は、デフォルト値が DogStatsD をデフォルト構成でインストールした場合と一致するように調整されている。

したがって、 DogStatsD をデフォルトの構成でインストールしている場合は、特に設定を明示しなくても DogStatsD による連携が動作する。

もしデフォルト構成以外でインストールしている場合は、 StatsdConfig(外部サイト、英語) を参照して、実際の環境に合わせた設定を行うこと。

# ポートを変更
nablarch.micrometer.statsd.port=9999