OpenTelemetry メトリクス計測器の種類と活用 ​

OpenTelemetryでは、システムの様々な側面を数値化し監視するために、複数のメトリクス計測器（Instruments）を提供しています。これらの計測器を適切に選択し活用することで、アプリケーションの健全性やパフォーマンスを正確に把握できます。本記事では、主要なメトリクス計測器である Counter、Gauge、Histogram、UpDownCounter の概念、適切な使用例、および実装方法について解説します。

メトリクス計測器の基本 ​

メトリクス計測器は、アプリケーション内で発生するイベントや状態変化を数値データとして収集するためのAPIです。OpenTelemetryのメトリクスAPIは、これらの計測器を通じてデータを収集し、Collectorやエクスポーターを介してバックエンドに送信します。

なぜ複数の計測器が必要なのか？ ​

システムの振る舞いを表現する数値データには、様々な性質があります。例えば、リクエスト数は常に増加する一方ですが、CPU使用率は上下に変動します。また、リクエストの処理時間は分布として捉える必要があります。これらの異なる性質のデータを適切に表現するために、OpenTelemetryは用途に応じた計測器を提供しています。

実装例 (Python) ​

以降の各計測器の実装例では、以下の共通セットアップが完了しているものとします。

python
from opentelemetry import metrics
from opentelemetry.sdk.metrics import MeterProvider
from opentelemetry.sdk.resources import Resource

resource = Resource.create({"service.name": "my-service"})
meter_provider = MeterProvider(resource=resource)
metrics.set_meter_provider(meter_provider)
meter = metrics.get_meter(__name__)

1. Counter (カウンター) ​

Counter は、単調に増加する数値データを計測するための計測器です。一度増加した値が減少することはありません。主に、イベントの発生回数や累積値を追跡するのに使用されます。

概念と特徴 ​

  • 単調増加: 値は常に増加するか、現状維持します。減少することはありません。
  • 累積値: 特定のイベントの総数を表します。
  • リセット: プロセスが再起動された場合や、バックエンドで集計期間が終了した場合にリセットされることがあります。

適切な使用例 ​

  • リクエスト数: APIエンドポイントへの総リクエスト数
  • エラー発生回数: アプリケーション内で発生したエラーの総数
  • 処理されたタスク数: キューから取り出され処理されたタスクの総数
  • バイト転送量: ネットワーク経由で送受信されたバイトの累積量

実装例 (Python) ​

python
# Counterの作成と使用
requests_counter = meter.create_counter(
    name="api.requests.total",
    description="Total number of API requests",
    unit="1"
)

requests_counter.add(1, {"http.method": "GET", "http.route": "/users"})
requests_counter.add(1, {"http.method": "POST", "http.route": "/products"})

2. UpDownCounter (アップダウンカウンター) ​

UpDownCounter は、増加も減少もする数値データを計測するための計測器です。Counter とは異なり、値が単調である必要はありません。

概念と特徴 ​

  • 増減可能: 値は増加することも減少することもあります。
  • 累積値: 特定の時点での累積値を表します。

適切な使用例 ​

  • アクティブな接続数: サーバーへの現在のアクティブな接続数
  • キュー内のアイテム数: 処理待ちのキュー内のアイテム数
  • メモリ使用量: 現在アプリケーションが使用しているメモリ量（ただし、Gaugeの方が適している場合も多い）

実装例 (Python) ​

python
# UpDownCounterの作成と使用
active_connections = meter.create_up_down_counter(
    name="network.active_connections",
    description="Number of active network connections",
    unit="1"
)

active_connections.add(1, {"protocol": "TCP"})
active_connections.add(-1, {"protocol": "TCP"})

3. Gauge (ゲージ) ​

Gauge は、現在の値を計測するための非同期計測器（Observable Instrument）です。特定の時点でのスナップショット値や、時間とともに変動する値を追跡するのに使用されます。UpDownCounter と似ていますが、Gauge はコールバック関数を通じて定期的に値を報告する非同期方式であるのに対し、UpDownCounter はアプリケーションコードから直接増減を記録する同期方式という違いがあります。

概念と特徴 ​

  • 非同期計測器: コールバック関数を登録し、エクスポート時に自動的に呼び出されて現在の値を報告します。
  • 現在の値: 特定の時点での最新の値を表します。
  • 非累積: 値は累積されず、常に最新の値が報告されます。

適切な使用例 ​

  • CPU使用率: 現在のCPU使用率
  • メモリ使用量: 現在のメモリ使用量
  • ディスク空き容量: 現在のディスク空き容量
  • キューの深さ: 現在のキュー内のアイテム数（UpDownCounterでも可能だが、Gaugeの方が直感的）

実装例 (Python) ​

Gauge は非同期計測器のため、コールバック関数（定期的に呼び出される関数）を通じて値を報告します。

python
import psutil

def get_cpu_usage(options):
    yield metrics.Observation(psutil.cpu_percent(interval=None))

# Observable Gaugeの作成（コールバック関数を登録）
cpu_gauge = meter.create_observable_gauge(
    name="system.cpu.usage",
    description="Current CPU usage percentage",
    unit="%",
    callbacks=[get_cpu_usage]
)

4. Histogram (ヒストグラム) ​

Histogram は、観測された値の分布を計測するための計測器です。特定のイベントの発生頻度だけでなく、その値がどのような範囲に分布しているかを把握するのに役立ちます。レイテンシーやリクエストサイズなど、値の範囲が重要なメトリクスに適しています。

概念と特徴 ​

  • 値の分布: 観測された値を複数のバケット（区間）に分類し、各バケット内の値の数をカウントします。
  • 統計情報: 合計値、カウント、最小値、最大値、平均値、パーセンタイルなどの統計情報を計算できます。
  • レイテンシー分析: サービス応答時間などのパフォーマンス指標の分布を把握するのに最適です。

適切な使用例 ​

  • リクエスト処理時間: APIリクエストの処理時間の分布
  • データ転送サイズ: ネットワーク経由で転送されたデータのサイズの分布
  • データベースクエリ時間: データベースクエリの実行時間の分布

実装例 (Python) ​

python
# Histogramの作成と使用
request_duration = meter.create_histogram(
    name="http.server.request.duration",
    description="Duration of HTTP server requests",
    unit="ms"
)

request_duration.record(245, {"http.route": "/data", "http.method": "GET"})
request_duration.record(123, {"http.route": "/data", "http.method": "GET"})

まとめ ​

OpenTelemetryのメトリクス計測器は、アプリケーションの様々な側面を数値化し、監視するための強力なツールです。

計測器用途特徴使用例
Counter単調増加する累積値常に増加、リセットなしリクエスト数、エラー数
UpDownCounter増減する累積値増加・減少可能アクティブ接続数、キューサイズ
Gauge現在の瞬間的な値最新のスナップショットCPU使用率、メモリ使用量
Histogram値の分布バケット化、統計情報リクエスト処理時間、データサイズ

これらの計測器を適切に使い分けることで、システムの健全性を多角的に把握し、問題の早期発見やパフォーマンス改善に役立てることができます。

関連記事: メトリクスと時系列データベース(TSDB)の連携設計関連記事: メトリクスのクエリと分析パターン関連記事: メトリクスに基づいたアラーティング設計