REST API を使用して Azure リソースのカスタムメトリックを取り込む

[アーティクル]
01/08/2024

この記事では、Azure リソースのカスタムメトリックを REST API 経由で Azure Monitor メトリックストアに送信する方法について説明します。メトリックが Azure Monitor に送信されると、それらを使用して、標準メトリックを使用して実行できるすべての処理を実行できます。たとえば、グラフやアラートを生成し、メトリックを他の外部ツールにルーティングできます。

Note

REST API では、Azure リソースのカスタムメトリックの送信のみを許可します。他の環境またはオンプレミスにあるリソースのメトリックを送信するには、Application Insights を使用します。

REST 要求を送信してカスタムメトリックを取り込む

Azure Monitor にカスタムメトリックを送信するときは、メトリックで報告する各データポイント (または値) に次の情報が含まれている必要があります。

認証トークン
情報カテゴリ
リージョン
Timestamp
名前空間
名前
ディメンションキー
ディメンション値
メトリック値

認証

Azure Monitor にカスタムメトリックを送信するには、メトリックを送信する側のエンティティが、要求の Bearer ヘッダーに設定される有効な Microsoft Entra トークンを必要とします。有効なベアラートークンを取得するには、次の方法がサポートされています。

Azure リソースの管理 ID。マネージド ID を使用して、特定の操作を実行するためのアクセス許可をリソースに付与できます。たとえば、自身に関するメトリックをリソースが出力できるようにします。リソース (またはそのマネージド ID) には、別のリソースに対する "メトリックの発行元の監視" アクセス許可を付与することもできます。このアクセス許可を付与すると、そのマネージド ID で他のリソースのメトリックも生成できるようになります。
Microsoft Entra サービスプリンシパル。このシナリオでは、Microsoft Entra のアプリケーションまたはサービスに、Azure リソースに関するメトリックを出力する権限を割り当てることができます。要求を認証するために、Azure Monitor は Microsoft Entra 公開キーを使用してアプリケーショントークンを検証します。既存の "メトリックの発行元の監視" ロールには、既にこのアクセス許可が付与されています。これは Azure portal で入手できます。

サービスプリンシパルには、どのようなリソースについてのカスタムメトリックをそれが出力するのかに応じて、必要なスコープで "メトリックの発行元の監視" ロールを付与することができます。 (たとえば、サブスクリプション、リソースグループ、または特定のリソース)。

ヒント

カスタムメトリックを出力するための Microsoft Entra トークンを要求する際には、トークンの要求対象であるユーザーやリソースが https://monitoring.azure.com/ であることを確認してください。必ず、末尾のスラッシュを含めるようにしてください。

承認トークンを取得する

マネージド ID またはサービスプリンシパルを作成し、監視メトリック発行者アクセス許可を割り当てたら、次の要求を使用して承認トークンを取得できます。

curl -X POST 'https://login.microsoftonline.com/<tennant ID>/oauth2/token' \
-H 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'client_id=<your apps client ID>' \
--data-urlencode 'client_secret=<your apps client secret' \
--data-urlencode 'resource=https://monitoring.azure.com'

応答本文は、次の形式で表示されます。

{
    "token_type": "Bearer",
    "expires_in": "86399",
    "ext_expires_in": "86399",
    "expires_on": "1672826207",
    "not_before": "1672739507",
    "resource": "https://monitoring.azure.com",
    "access_token": "eyJ0eXAiOiJKV1Qi....gpHWoRzeDdVQd2OE3dNsLIvUIxQ"
}

次の HTTP 要求で使用するために、応答のアクセストークンを保存します。

情報カテゴリ

サブジェクトプロパティは、どの Azure リソース ID についてのカスタムメトリックが報告されるのかを表します。この情報は、API 呼び出しの URL にエンコードされます。各 API は、単一の Azure リソースのみのメトリック値を送信できます。

Note

リソースグループまたはサブスクリプションのリソース ID に対してカスタムメトリックを出力することはできません。

リージョン

リージョンプロパティは、メトリックを出力する対象のリソースがデプロイされている Azure リージョンを表します。メトリックは、リソースがデプロイされているリージョンと同じリージョンの Azure Monitor エンドポイントに出力される必要があります。たとえば、米国西部にデプロイされている VM についてのカスタムメトリックは、WestUS リージョンの Azure Monitor エンドポイントに送信される必要があります。リージョン情報は API 呼び出しの URL にもエンコードされます。

Timestamp

Azure Monitor に送信されるデータポイントには、それぞれタイムスタンプが記録されている必要があります。このタイムスタンプはメトリック値が測定または収集された日時を表します。 Azure Monitor は、現在から 20 分前までの、および現在から 5 分後までのタイムスタンプが付いたメトリックデータを受け付けます。タイムスタンプは、ISO 8601 形式である必要があります。

名前空間

名前空間は類似のメトリックを分類またはグループ化する方法です。名前空間を使用すると、収集する情報またはパフォーマンス指標に基づいてメトリックのグループを分離できます。たとえば、contosomemorymetrics という名前空間では、アプリをプロファイリングするメモリ使用量メトリックを追跡し、 contosoapptransaction という別の名前空間では、アプリケーション内のユーザートランザクションに関するすべてのメトリックを追跡するといったことが可能です。

名前

名前プロパティは、報告されるメトリックの名前です。通常は、測定内容を識別するのに十分なほど説明的な名前です。たとえば、VM で使用されるメモリのバイト数を測定するメトリックです。 Memory Bytes In Use などのようなメトリック名になります。

ディメンションキー

ディメンションは、収集されているメトリックに関する他の特性を説明するのに役立つキーと値のペアです。他の特性を使用することで、より多くの情報をメトリックについて収集し、より深い洞察を得ることが可能になります。

たとえば、Memory Bytes In Use メトリックに Process というディメンションキーを追加して、VM 上の各プロセスが消費するメモリのバイト数を取得することもできます。このキーを使用すれば、メトリックをフィルタリングし、メモリ固有のプロセスが使用する容量を確認したり、メモリ使用量で上位 5 つのプロセスを識別したりすることが可能になります。

ディメンションは省略可能です。すべてのメトリックがディメンションを持つとは限りません。カスタムメトリックは最大 10 個のディメンションを持つことができます。

ディメンション値

メトリックのデータポイントを報告するとき、報告されるメトリックのディメンションキーごとに、対応するディメンション値が存在します。たとえば、VM で ContosoApp によって使用されているメモリを報告する場合以下のようになります。

メトリック名は Memory Bytes in Use、
ディメンションキーは Process、
ディメンション値は ContosoApp.exe のようになります。

メトリック値を発行するとき、ディメンションキーごとに 1 つのディメンション値しか指定できません。 VM 上の複数のプロセスについて同じメモリ使用率を収集する場合、そのタイムスタンプで複数のメトリック値を報告できます。各メトリック値は、Process ディメンションキーに異なるディメンション値を指定します。

ディメンションは省略可能ですが、メトリックの投稿にディメンションキーが定義されている場合、対応するディメンション値は必須です。

メトリックの値

Azure Monitor では、すべてのメトリックが 1 分刻みの間隔で保存されます。場合によっては、メトリックを 1 分間に複数回サンプリングする必要があります。たとえば、CPU 使用率などがそうです。または、サインイントランザクションの待機時間など、多くの不連続イベントに対してメトリックを測定する必要がある場合があります。

出力して Azure Monitor に送信し、費用を支払う必要がある未処理値の数を制限するには、ローカルで事前に集計して集計値を出力します。

Min:1 分間のすべてのサンプルと測定値からの最小観測値。
Max:1 分間のすべてのサンプルと測定値からの最大観測値。
Sum:1 分間のすべてのサンプルと測定値からのすべての観測値の合計。
Count:1 分間に取得されたサンプルと測定値の数。

Note

Azure Monitor では、カスタムメトリックの単位の定義はサポートされていません。

たとえば、1 分の間に、アプリへのサインイントランザクションが 4 件あり、それぞれについて測定された待機時間の結果が次のとおりであったとします。

トランザクション 1	トランザクション 2	トランザクション 3	トランザクション 4
7 ミリ秒	4 ミリ秒	13 ミリ秒	16 ミリ秒

この結果として Azure Monitor に送信されるメトリックは次のようになります。

最小:4
最大:16
合計:40
カウント:4

アプリケーションにおいて、ローカルでの事前集計ができず、収集してすぐに個別のサンプルまたはイベントを出力する必要がある場合、未処理の測定値を出力することができます。たとえば、アプリでサインイントランザクションが発生するたびに、ただ 1 つの測定値と共にメトリックを Azure Monitor に発行することもできます。その場合、サインイントランザクションに要した時間が 12 ミリ秒だとすると、送信されるメトリックは次のようになります。

最小:12
最大:12
合計:12
カウント:1

このプロセスでは、ある 1 分の間に、同じメトリックとディメンションの組み合わせに対して複数の値を出力できます。その場合は、Azure Monitor によって、ある 1 分の間に出力されたすべての未処理値が集計されます。

カスタムメトリックの送信例

次の例では、仮想マシン用のメトリック名前空間 Memory Profile の下に Memory Bytes in Use という名前のカスタムメトリックを作成します。このメトリックは Process という 1 つのディメンションを持ちます。タイムスタンプについては、メトリック値は 2 つのプロセスに対して出力されます。

次の JSON をローカルコンピューター上の custommetric.json という名前のファイルに格納します。過去 20 分以内になるように time パラメーターを更新します。出力からの時間が 20 分を超えたメトリックはストアに保存できません。

{
    "time": "2024-01-07T11:25:20-7:00",
    "data": {

      "baseData": {

        "metric": "Memory Bytes in Use",
        "namespace": "Memory Profile",
        "dimNames": [
          "Process"
        ],
        "series": [
          {
            "dimValues": [
              "ContosoApp.exe"
            ],
            "min": 10,
            "max": 89,
            "sum": 190,
            "count": 4
          },
          {
            "dimValues": [
              "SalesApp.exe"
            ],
            "min": 10,
            "max": 23,
            "sum": 86,
            "count": 4
          }
        ]
      }
    }
  }

次の変数を使用して、次の HTTP POST 要求を送信します。

location: メトリックを出力するリソースのデプロイリージョン。
resourceId: メトリックを追跡する Azure リソースのリソース ID。

accessToken: 「承認トークンを取得する」の手順で取得した承認トークン。

curl -X POST 'https://<location>/.monitoring.azure.com<resourceId>/metrics' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <accessToken>' \
-d @custommetric.json

メトリックの表示

Azure portal にサインインします。
左側のメニューで [監視] を選択します。
[モニター] ページで、 [メトリック] を選択します。
集計の期間を [過去 1 時間] に変更します。
[スコープ] ドロップダウンリストで、メトリックを送信する対象のリソースを選択します。
[メトリックの名前空間] ドロップダウンリストで、[メモリプロファイル] を選択します。
[メトリック] ドロップダウンリストで、[使用中のメモリバイト数] を選択します。

トラブルシューティング

プロセスのどこかでエラーメッセージを受信した場合は、次のトラブルシューティング情報を考慮してください。

サブスクリプションまたはリソースグループまたはリソースに対してメトリックを発行できない場合は、[アクセスの制御 (IAM)] でアプリケーションまたはサービスプリンシパルに監視メトリック発行者ロールが割り当てられていることを確認します。
ディメンション名の数が値の数と一致することを確認します。
メトリックが正しい Azure Monitor リージョンエンドポイントに出力されていることを確認してください。たとえば、リソースが米国西部にデプロイされている場合、米国西部のリージョンエンドポイントにメトリックを出力する必要があります。
タイムスタンプが過去 20 分以内であることを確認します。
タイムスタンプが ISO 8601 形式であることを確認します。
メトリック名が有効であることを確認します。たとえば、名前にスペースを含めることはできません。

次のステップ

カスタムメトリックの詳細を確認します。

REST API を使用して Azure リソースのカスタム メトリックを取り込む

REST 要求を送信してカスタム メトリックを取り込む

認証

承認トークンを取得する

情報カテゴリ

リージョン

Timestamp

名前空間

名前

ディメンション キー

ディメンション値

メトリックの値

カスタム メトリックの送信例

メトリックの表示

トラブルシューティング

次のステップ

その他のリソース

REST API を使用して Azure リソースのカスタムメトリックを取り込む

REST 要求を送信してカスタムメトリックを取り込む

ディメンションキー

カスタムメトリックの送信例