OpenTelemetry Python SDK を使用したメトリクスのカスタマイズ - Application Real-Time Monitoring Service

ARMS は一般的なアプリケーションモニタリングメトリクスを提供します。カスタムメトリクスを作成する必要がある場合は、OpenTelemetry Python SDK を使用できます。このトピックでは、カスタムメトリクスを作成し、Grafana でクエリする方法について説明します。

前提条件

アプリケーションを ARMS のアプリケーションモニタリングに統合済みであること。手順については、「Application integration」をご参照ください。
ARMS Python プローブのバージョンが 2.8.0 以降であること。

操作手順

手順 1：コードへのカスタムメトリクスの追加

OpenTelemetry Python SDK をインストールするには、次のコマンドを実行します。詳細については、「official OpenTelemetry documentation」をご参照ください。

pip install opentelemetry-api

OpenTelemetry は現在、次の 4 つの主要なメトリクスタイプをサポートしています。ARMS はこれらすべてのメトリクスタイプをサポートしていますが、ヒストグラムの扱いが異なります。

カウンター：単調増加するカウンターです。
アップダウンカウンター：増加または減少が可能なアップダウンカウンターです。
ゲージ：瞬時値を記録するゲージです。
ヒストグラム：値の分布を記録するヒストグラムです。

次のコードは、タイムセールのシナリオにおける簡単な例です。この例では、次の 2 つのメトリクスを定義します。

product_seckill_count：タイムセールの試行回数。
product_current_stock：現在の在庫数。

メトリクスを定義するための meter ファクトリークラスを取得する際、"product_seckill" パラメーターが渡されます。このパラメーターはグループと見なすことができます。この meter オブジェクトを使用して後から定義されるすべてのメトリクスは、このグループに配置され、後の設定で使用されます。

from fastapi import FastAPI
from opentelemetry.metrics import get_meter, Observation

app = FastAPI()

# 在庫をシミュレート
stock = {"count": 100}

# メーターを取得します。スコープ名 "product_seckill" は後の設定で重要となります。
meter = get_meter("product_seckill", "1.0.0")

# タイムセールの試行回数を記録するカウンターを作成します。
seckill_counter = meter.create_counter(
    name="product_seckill_count",
    unit="1",
    description="seckill product count",
)


# 現在の在庫レベルを表すゲージを作成します。
def stock_callback(options):
    # 現在の在庫数を記録します。
    yield Observation(stock["count"])


observable_gauge = meter.create_observable_gauge(
    name="product_current_stock",
    callbacks=[stock_callback],
    unit="1",
    description="current stock of product",
)


@app.post("/seckill")
def seckill_product():
    if stock["count"] <= 0:
        seckill_counter.add(1, {"seckill_result": "failed"})
        return {"message": "Purchase failed. The item is sold out."}
    stock["count"] -= 1
    seckill_counter.add(1, {"seckill_result": "success"})
    return {"message": f"Purchase successful. Remaining stock: {stock['count']}"}


@app.post("/stock/{count}")
def set_stock(count: int):
    stock["count"] = count
    return {"message": f"Stock has been set to: {count}"}


if __name__ == "__main__":
    import uvicorn
    uvicorn.run(app, host="0.0.0.0", port=8000)

その後、統合ドキュメントに従ってプローブをアタッチし、アプリケーションを起動します。

aliyun-instrument python3 main.py

手順 2：コンソールでのメトリクス収集の設定

コンソールで、プローブ収集設定を変更し、前のステップでメーターを作成したときに入力した product_seckill パラメーターを追加します。

この設定はプローブバージョン 2.8.0 以降でのみ有効で、アプリケーションの再起動は不要です。設定が完了したら、[Save] をクリックします。

ARMS コンソールにアクセスできない場合、またはネットワークの問題により動的設定を配信できない場合は、次の環境変数を追加してローカルで設定できます。

export APSARA_APM_METRIC_CUSTOM_ENABLED=true
# オプション：スコープの許可リストを設定します。設定しない場合、デフォルトですべてのスコープが収集されます。
export APSARA_APM_METRIC_CUSTOM_INCLUDE_SCOPE_LIST="my.scope,other.scope"

手順 3：メトリクスの表示とアラームの設定

ARMS コンソールの[Prometheus モニタリング > インスタンスリスト]ページで、トップメニューバーからアプリケーションが接続されているリージョンを選択します。名前が metricstore-apm-metrics-custom で始まる Prometheus ストレージインスタンスを検索し、[共有版] をクリックして Grafana に移動します。
Grafana ページで [Explore] をクリックし、前の手順で確認した Prometheus ストレージインスタンスをデータソースとして選択します。

対応する Grafana フォルダーページで、フォルダーにダッシュボードがない場合、ページにメッセージ このフォルダーにはまだダッシュボードがありません が表示されます。[+ ダッシュボードの作成] をクリックしてダッシュボードを作成するか、[ダッシュボードの管理] を使用して既存のダッシュボードをフォルダーに移動できます。

次の図のように、PromQL を使用してカスタムメトリクスをクエリできます。また、Grafana で可観測性ページをカスタマイズすることもできます。

これで、OpenTelemetry SDK からのカスタムメトリクスが ARMS Prometheus ストレージインスタンスに報告され、保存されます。続いて、それらに対して Prometheus アラームルールを作成できます。

注意事項

ARMS は 15秒間隔でメトリクスを報告します。
カウンターメトリクスについて、ARMS は累計値ではなく、15秒のレポート期間ごとの増分値を報告します。
ARMS のメトリクスモデルは OpenTelemetry のモデルと完全には整合していないため、各ヒストグラムメトリクスは次の個別メトリクスに分割されます。
- {name}_count：サンプル数。
- {name}_sum：サンプリングされたすべての値の合計。
- {name}_min：すべてのサンプルの最小値 (min データが利用可能な場合にのみ生成されます)。
- {name}_max：すべてのサンプルの最大値 (max データが利用可能な場合にのみ生成されます)。

たとえば、メトリクス custom.latency は次のように分割されます。

custom.latency_count：リクエスト数。
custom.latency_sum：レイテンシーの合計。
custom.latency_min：最小レイテンシー。
custom.latency_max：最大レイテンシー。