次の方法で共有


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

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

Note

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

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

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

認証

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 またはサービス プリンシパルを作成し、監視メトリック発行者アクセス許可を割り当てたら、認可トークンを取得できます。 トークンを要求するときは、resource: https://monitoring.azure.com を指定します。

次のいずれかの方法を使って認可トークンを取得します。

  • CLI
  • REST API
  • SDK

トークンを要求する際は、resource パラメーターを指定する必要があります。 resource パラメーターは、アクセスするリソースの URL です。

リソースには以下が含まれます。

  • https://management.azure.com
  • https://api.loganalytics.io
  • https://monitoring.azure.com

REST 要求を使用してトークンを取得する

トークンを取得するには、次の REST API 呼び出しを使用します。 この要求では、クライアント ID とクライアント シークレットを使用して要求を認証します。 クライアント ID とクライアント シークレットは、アプリケーションを Microsoft Entra ID に登録するときに取得されます。 詳細については、「承認トークンを要求し、API を操作するために、アプリを登録する」を参照してください。

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 
    

メトリックの表示

  1. Azure portal にサインインします。

  2. 左側のメニューで [監視] を選択します。

  3. [モニター] ページで、 [メトリック] を選択します。

    Azure portal でメトリックを選択する方法を示すスクリーンショット。

  4. 集計の期間を [過去 1 時間] に変更します。

  5. [スコープ] ドロップダウン リストで、メトリックを送信する対象のリソースを選択します。

  6. [メトリックの名前空間] ドロップダウン リストで、[メモリ プロファイル] を選択します。

  7. [メトリック] ドロップダウン リストで、[使用中のメモリ バイト数] を選択します。

トラブルシューティング

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

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

次のステップ

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