nablarch-micrometer-otlpとは

nablarch-micrometer-otlpとは、nablarchで各種指標(メトリクス)を取得するライブラリ。

opentelemetryは、2024年時点で最新の業界標準となっている。

nablarch-micrometer-otlpを使用することで、クラウドネイティブ環境でもtempファイルやlogファイルに依存することなく各種指標(メトリクス)を測定できる
- また、nablarch-micrometer-otlpの機能として特徴的な機能には下記がある
  - 任意のHTTPヘッダーを添加できる機能(APIキーを付加できる)
  - resourceAttributesを付与することにより、v1アプリとv2アプリ、あるいはサービス名ごとに指標をラベリングすることができる
otlp対応機能はnablarch5u25/6u2(2024/09/30)から新たにリリースされた機能。詳細はリリースノート参照

https://nablarch.github.io/docs/5u25/doc/_downloads/nablarch5u25-releasenote.xlsx

実際の設定例

設定に必要なポイント

依存関係の追加

基本的な設定方法は、下記ドキュメントに従う。
下記はドキュメントをベースとして実際に設定した例となる。

実装時に著者がテストした内容も参考にできる
https://github.com/nablarch/nablarch-micrometer-adaptor/pull/21/files#diff-00818f617cff932d4451f0a7add0235351646d7455d3d6a672ee8afa52c96c13

依存関係(pom.xml)の設定

pom.xml


  <dependencyManagement>
    <dependencies>
      <!-- (中略) -->
      <!-- 下記bomを追加。そうしないと、動作しない。 -->
      <dependency>
        <groupId>io.micrometer</groupId>
        <artifactId>micrometer-bom</artifactId>
        <version>1.13.0</version>
        <type>pom</type>
        <scope>import</scope>
      </dependency>
    </dependencies>
  </dependencyManagement>

  <!-- (中略) -->

  <dependencies>
    <!-- (中略) -->
    <!-- 下記3つの依存関係を追加 -->
    <dependency>
      <groupId>com.nablarch.integration</groupId>
      <artifactId>nablarch-micrometer-adaptor</artifactId>
      <version>1.3.0</version>
    </dependency>

    <dependency>
      <groupId>io.micrometer</groupId>
      <artifactId>micrometer-registry-otlp</artifactId>
    </dependency>

    <dependency>
      <groupId>io.micrometer</groupId>
      <artifactId>micrometer-core</artifactId>
    </dependency>
  </dependencies>

レジストリファクトリとコンポーネントの宣言(component-configuration.xml)

src/main/resources/rest-component-configuration.xml

  <!-- BeanValidation実装クラス -->
  <component name="validationStrategy" class="nablarch.common.web.validator.BeanValidationStrategy" />

  <!-- ↓ここからmicrometer独自の設定 -->

  <!-- ★DefaultMeterBinderListProviderをコンポーネントとして宣言する -->
  <component name="meterBinderListProvider" class="nablarch.integration.micrometer.DefaultMeterBinderListProvider" />

  <!-- ★DefaultMeterBinderListProviderを廃棄処理対象にする -->
  <component name="disposer" class="nablarch.core.repository.disposal.BasicApplicationDisposer">
    <property name="disposableList">
      <list>
        <component-ref name="meterBinderListProvider"/>
      </list>
    </property>
  </component>

  <!-- ★レジストリのファクトリクラスをコンポーネントとして宣言する -->
  <component name="meterRegistry" class="nablarch.integration.micrometer.otlp.OtlpMeterRegistryFactory">
    <property name="meterBinderListProvider" ref="meterBinderListProvider" />
    <property name="applicationDisposer" ref="disposer" />
  </component>

  <!-- ↑ここまでmicrometer独自の設定 -->

  <!-- 環境設定ファイル -->
  <config-file file="common.properties" />
  <config-file file="env.properties" />

  <!-- (中略) -->

  <!-- ハンドラキュー構成 -->
  <component name="webFrontController" class="nablarch.fw.web.servlet.WebFrontController">
    <property name="handlerQueue">
      <list>
        <!-- ↓ここからmicrometer独自の設定 -->
        <!-- ★HTTPリクエストの処理時間のメトリクス収集ハンドラ -->
        <component class="nablarch.integration.micrometer.instrument.handler.TimerMetricsHandler">
          <!-- ★レジストリファクトリが生成する otlpMeterRegistry を meterRegistry プロパティに設定する -->
          <property name="meterRegistry" ref="meterRegistry" />

          <!-- ★HttpRequestTimeMetricsMetaDataBuilder を handlerMetricsMetaDataBuilder に設定する -->
          <property name="handlerMetricsMetaDataBuilder">
            <component class="nablarch.integration.micrometer.instrument.http.HttpRequestTimeMetricsMetaDataBuilder" />
          </property>
        </component>
        <!-- ↑ここまでmicrometer独自の設定 -->
      </list>
    </property>
  </component>
<!-- (中略) -->

プロパティファイルの指定(micrometer.xml)

src/main/resources/micrometer.xml

<?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">

  <config-file file="micrometer.properties" />
</component-configuration>

指定されたmicrometer.propertiesの設定

src/main/resources/micrometer.properties

nablarch.micrometer.otlp.step=2s
nablarch.micrometer.otlp.logInactive=true
# docker compose。ここではprometheusを使用し、コンテナ名がprom/ポートが9090なので下記のようになる。
nablarch.micrometer.otlp.url=http://prom:9090/api/v1/otlp/v1/metrics

# resourceAttributes。opentelemetryのsemconv(命名規則)に従って設定することが望ましい。
# 例えば、アプリバージョンアップ時に`service.version`のresourceAttributesを`v1beta1`にすると、`v1alpha1`と`v1beta1との間で指標の比較ができる。`
nablarch.micrometer.otlp.resourceAttributes=service.name=nablarch-example-rest,url.scheme=http,service.version=v1alpha1,os.type=windows

(任意)監視環境構築用docker

監視環境構築用dockerの動作する例を示す。

compose.yml

services:
  web:
    build: .
    tty: true
    ports:
      - target: 8080
        published: 8080
　#監視が必要なければ不要。
  prom:
    restart: always
    image: prom/prometheus:v3.0.0-beta.0
    command:
      - '--config.file=/etc/prometheus/prometheus.yml'
      - '--enable-feature=otlp-write-receiver'
      - '--enable-feature=native-histograms'
    ports:
      - '9090:9090'
    configs:
      - source: prometheus
        target: /etc/prometheus/prometheus.yml
        mode: 440

configs:
  prometheus:
    file: ./prometheus.yml

prometheus.yml

global:
  scrape_interval:     10s
  evaluation_interval: 10s

otlp:
  promote_resource_attributes: ["service.name", "url.scheme", "service.version"]

storage:
  tsdb:
    # A 10min time window is enough because it can easily absorb retries and network delays.
    out_of_order_time_window: 10m

最終的な出力結果

http://localhost:9090/queryにアクセスし、指標http_server_requests_milliseconds_countで検索すると、下記の結果となる。

グラフ表示

ポイントは下記

メトリクスのグラフが出力されていること
下記のラベルが付与されていること
- service.name
- url.scheme
- service.version

テーブル表示

取得できるメトリック