Azure API Management と Azure アプリケーション Insights を統合する方法

適用対象: すべての API Management レベル

Azure アプリケーション Insights を Azure API Management と簡単に統合できます。 Azure アプリケーション Insights は、複数のプラットフォームでアプリを構築および管理する Web 開発者向けの拡張可能なサービスです。 このガイドで行うこと:

• Application Insights の API Management への 統合について説明します。
• API Management サービス インスタンスに対するパフォーマンスへの影響を軽減する戦略について説明します。

Prerequisites

• Azure API Management インスタンスを作成します。

• Application Insights サービスのインスタンスを作成します。 Azureポータルを使ってインスタンスを作成するには、ワークスペースベースのアプリケーションインサイトリソースをご覧ください。

  Note

  Application Insights リソースは別のサブスクリプションに含まれていても構いません。さらには、API Management リソース以外のテナントに含まれていても構いません。

• Application Insights で使用するマネージド ID の資格情報を構成する場合は、次の手順を実行します。

  1. API Management で、システムによって割り当てられた、またはユーザーが割り当てたマネージド ID を有効にします。

     • ユーザー割り当てマネージド ID を有効にする場合は、ID のクライアント ID をメモします。

  2. ID に、Application Insights リソースをスコープとする監視メトリック発行者ロールを割り当てます。 ロールは、Azure portal または他の Azure ツールを使用して割り当てることができます。

シナリオの概要

以下のステップは、このシナリオの概要を示しています。

1. Application Insights と API Management の間に接続を作成します。

   Application Insights と API Management の間の接続は、Azure portal、REST API、または関連する Azure ツールを使用して作成できます。 API Management によって、接続用の "ロガー" リソースが構成されます。

   Important

   現在、ポータルでは、API Management は Application Insights インストルメンテーション キーを使用した Application Insights への接続のみをサポートしています。 セキュリティを強化するには、API Management のマネージド ID で Application Insights の接続文字列を使用します。 マネージド ID 資格情報を使用して接続文字列を構成するには、この記事の後のセクションに示すように、REST API または関連ツールを使用します。 詳細については、 Application Insights の接続文字列に関するページを参照してください。

   Note

   もしあなたのApplication Insightsリソースが別のテナントにある場合は、この記事の後半で示すREST API や関連ツールを使ってロガーを作成します。

2. API または APIs で Application Insights ログを有効にします。

   この記事では、Azure portal を使用して API の Application Insights ログを有効にします。 API Management によって、API の "診断" リソースが構成されます。

Azureポータルを使って接続を作成してください

Azure portal を使用して Application Insights とAPI Management の間の接続を作成するには、次の手順に従います。

1. Azure portalのAzure API Managementサービスインスタンスに行ってください。

2. サイドバー メニューの [ 監視 ] で、[ Application Insights] を選択します。

3. [+ 追加]を選択します。
   

4. 前に作成した Application Insights インスタンスを選択し、簡単な説明を入力します。

5. Application Insights で API Management インスタンスの可用性監視を有効にするには、[可用性の監視の追加]のチェックボックスを選択します。

   • この設定は、API管理ゲートウェイエンドポイントが応答しているかどうかを定期的にチェックします。
   • 結果は Application Insights インスタンスの [可用性] ペインに表示されます。

6. を選択してを作成します。

7. 新しい Application Insights ロガーが一覧に表示されていることを確認します。

   

REST API、Bicep、またはARMテンプレートを使って接続を作成します

REST API、Bicep、または ARM テンプレートを使用して、API Management インスタンス用の Application Insights ロガーを作成するには、次の手順に従います。 管理されたID認証情報付きの接続文字列を使うロガーを設定することも、接続文字列のみを使うロガーを設定できます(推奨)。

接続文字列とマネージド ID 資格情報を使用するロガー（推奨）

API Management のマネージド ID の使用については、「前提条件」をご覧ください。

Application Insights の接続文字列は、Application Insights リソースの [概要] セクションに表示されます。

システム割り当てマネージド ID を持つ接続文字列

{
  "properties": {
    "loggerType": "applicationInsights",
    "description": "Application Insights logger with system-assigned managed identity",
    "credentials": {
         "connectionString":"InstrumentationKey=00000000-0000-0000-0000-000000000000;IngestionEndpoint=https://xxxx.applicationinsights.azure.com/;...",
         "identityClientId":"SystemAssigned"
    }
  }
}

resource aiLoggerWithSystemAssignedIdentity 'Microsoft.ApiManagement/service/loggers@2022-08-01' = {
  name: 'ContosoLogger1'
  parent: '<API-management-instance-name>'
  properties: {
    loggerType: 'applicationInsights'
    description: 'Application Insights logger with system-assigned managed identity'
    credentials: {
      connectionString: 'InstrumentationKey=00000000-0000-0000-0000-000000000000;IngestionEndpoint=https://xxxx.applicationinsights.azure.com/;...'
      identityClientId: 'systemAssigned'
    }
  }
}

{
  "type": "Microsoft.ApiManagement/service/loggers",
  "apiVersion": "2022-08-01",
  "name": "ContosoLogger1",
  "properties": {
    "loggerType": "applicationInsights",
    "description": "Application Insights logger with system-assigned managed identity",
    "resourceId": "<application-insights-resource-ID>",
    "credentials": {
      "connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000;IngestionEndpoint=https://xxxx.applicationinsights.azure.com/;...",
      "identityClientId": "SystemAssigned"
    }
  }
}

ユーザー割り当てマネージド ID を持つ接続文字列

{
  "properties": {
    "loggerType": "applicationInsights",
    "description": "Application Insights logger with user-assigned managed identity",
    "credentials": {
         "connectionString":"InstrumentationKey=00000000-0000-0000-0000-000000000000;IngestionEndpoint=https://xxxx.applicationinsights.azure.com/;...",
         "identityClientId":"<client-ID>"
    }
  }
}

resource aiLoggerWithUserAssignedIdentity 'Microsoft.ApiManagement/service/loggers@2022-08-01' = {
  name: 'ContosoLogger1'
  parent: '<API-management-instance-name>'
  properties: {
    loggerType: 'applicationInsights'
    description: 'Application Insights logger with user-assigned managed identity'
    credentials: {
      connectionString: 'InstrumentationKey=00000000-0000-0000-0000-000000000000;IngestionEndpoint=https://xxxx.applicationinsights.azure.com/;...'
      identityClientId: '<client-ID>'
    }
  }
}

{
  "type": "Microsoft.ApiManagement/service/loggers",
  "apiVersion": "2022-08-01",
  "name": "ContosoLogger1",
  "properties": {
    "loggerType": "applicationInsights",
    "description": "Application Insights logger with user-assigned managed identity",
    "resourceId": "<application-insights-resource-ID>",
    "credentials": {
      "connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000;IngestionEndpoint=https://xxxx.applicationinsights.azure.com/;...",
      "identityClientId": "<client-ID>"
    }
  }
}

接続文字列の資格情報のみを持つロガー

Application Insights の接続文字列は、Application Insights リソースの [概要] セクションに表示されます。

{
  "properties": {
    "loggerType": "applicationInsights",
    "description": "Application Insights logger with connection string",
    "credentials": {
         "connectionString":"InstrumentationKey=00000000-0000-0000-0000-000000000000;IngestionEndpoint=https://xxxx.applicationinsights.azure.com/;..."    
    }
  }
}

resource aiLoggerWithSystemAssignedIdentity 'Microsoft.ApiManagement/service/loggers@2022-08-01' = {
  name: 'ContosoLogger1'
  parent: '<API-management-instance-name>'
  properties: {
    loggerType: 'applicationInsights'
    description: 'Application Insights logger with connection string'
    credentials: {
      connectionString: 'InstrumentationKey=00000000-0000-0000-0000-000000000000;IngestionEndpoint=https://xxxx.applicationinsights.azure.com/;...'
    }
  }
}

{
  "type": "Microsoft.ApiManagement/service/loggers",
  "apiVersion": "2022-08-01",
  "name": "ContosoLogger1",
  "properties": {
    "loggerType": "applicationInsights",
    "description": "Application Insights logger with connection string",
    "resourceId": "<application-insights-resource-ID>",
    "credentials": {
      "connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000;IngestionEndpoint=https://xxxx.applicationinsights.azure.com/;..."
    },
  }
}

API で Application Insights ログを有効にする

API の Application Insights ログを有効にするには、次の手順に従います。 すべての API の Application Insights ログを有効にすることもできます。

1. Azure portalのAzure API Managementサービスインスタンスに行ってください。

2. サイドバー メニューから [API>API] を選択します。

3. Swagger Petstore などの API を選択します。 構成されている場合は、バージョンを選択します。

   Tip

   すべての API のログを有効にするには、[すべての API] を選択します。

4. 上部のバーの [設定] タブを選択します。

5. [ 診断ログ ] セクションまで下にスクロールし、[ 有効] ボックスをオンにします。

6. [Destination]\(出力先\) ドロップダウンで、接続済みのロガーを選択します。

7. 100をサンプリング (%)に入力し、常にエラーをログに記録するチェック ボックスを選択します。

8. 残りの設定はそのままにします。 設定の詳細については、「診断ログ設定のリファレンス」を参照してください。

   Warning

   デフォルトの ペイロードバイト数をログ 値に上書きすると、APIのパフォーマンスが大幅に低下する 0 恐れがあります。

9. 保存 を選択します。

10. バックグラウンドで、 という名前のapplicationinsightsエンティティが API レベルで作成されます。

1 つの API またはすべての API のロガー

ロガーは異なるレベルで指定できます:

• 1 つの API のロガー
• すべての API のロガー

両方指定すると:

• 既定では、1 つの API のロガー (詳細なレベル) はすべての API のロガーをオーバーライドします。
• 2 つのレベルで構成されたロガーが異なり、テレメトリを受信するために両方のロガーが必要な場合 (多重化)、Microsoft サポートにお問い合わせください。 同じロガー(Application Insightsの宛先)を「All API」レベルとシングルAPIレベルで使っている場合、マルチプレクシングはサポートされていません。 多重化を正常に機能させるためには、"すべての API" と個々の API レベルで異なるロガーを構成し、サービスに対して多重化を有効にするよう Microsoft サポートにサポートを依頼する必要があります。

Application Insights に追加されるデータ

Application Insights に届くデータ:

サポート対象ポリシーの外部依存関係のテレメトリ

Application Insightsのログングを設定し有効化した後、APIマネジメントは以下のポリシーの外部依存関係テレメトリを自動的に収集します。 追加のポリシーやテレメトリ設定は不要です:

• authentication-managed-identity
• authentication-token
• azure-openai-semantic-cache-lookup
• cosmosdb-request-handler
• forward-request
• get-authorization-context
• http-data-source
• invoke-dapr-binding
• llm-content-safety
• llm-semantic-cache-lookup
• send-request
• send-one-way-request
• send-service-bus-message
• sql-data-source
• validate-jwt

Application Insights は、これらの外部呼び出しを相関付けられた子操作として記録します。 例えば、再試行、OpenID Connectのメタデータ取得、validate-jwtによるメタデータ取得、Service Bus送信、バックエンドフォワーディングなど、関連する操作として確認できます。 Azureポータルでテレメトリを確認するには、Application Insightsリソースでエンドツーエンドトランザクション詳細を開き、リクエストの関連操作を確認します。

現在、依存関係追跡は前述のポリシーのみをサポートしています。

カスタム メトリックを出力する

API Management インスタンスから Application Insights にカスタム メトリックを出力できます。 API Managementは 、emit-metric や llm-emit-token-metricなどのポリシーを用いてカスタムメトリクスを発行します。 次のセクションでは、例として emit-metric ポリシーを使用します。

カスタムメトリクスを発行するには、以下の設定ステップを完了してください:

1. Application Insights インスタンスで [カスタム メトリック (プレビュー)] を有効にし、カスタム ディメンションを使用します。

   1. ポータル内のApplication Insightsインスタンスに行ってください。
   2. サイドバー メニューの [ 構成 ] で、[ 使用量と推定コスト] を選択します。
   3. [カスタム メトリック (プレビュー)]>[ディメンションあり] の順に選択します。
   4. [OK] を選択.

2. API Managementで設定するapplicationInsights診断エンティティに"metrics": trueプロパティを追加します。 現在、このプロパティはAPI Management Diagnostic - Create or Update REST APIを使って追加する必要があります。 例えば次が挙げられます。

   PUT https://management.azure.com/subscriptions/<subscription-ID>/resourceGroups/<resource-group-name>/providers/Microsoft.ApiManagement/service/<API-management-service-name>/diagnostics/applicationinsights
   
   {
       [...]
       {
       "properties": {
           "loggerId": "/subscriptions/<subscription-ID>/resourceGroups/<resource-group-name>/providers/Microsoft.ApiManagement/service/<API-management-service-name>/loggers/<application-insights-logger-name>",
           "metrics": true
           [...]
       }
     }
   }
   

3. Application Insightsロガーが、カスタムメトリクスを発行したい範囲(すべてのAPIまたは単一のAPIのいずれか)に設定されていることを確認してください。 詳細については、この記事の前半の「API で Application Insights ログを有効にする」を参照してください。

4. emit-metricポリシーは、Application Insightsログが設定されている範囲(すべてのAPIまたは単一のAPIのいずれか)で設定し、カスタムメトリクスで有効化しています。 ポリシーの詳細については、emit-metricポリシー リファレンスを参照してください。

カスタム メトリックの制限

Azure Monitor では、API Management からメトリックを出力する機能に影響を与える可能性があるカスタム メトリックに対して使用制限が課されます。 たとえば、現在 Azure Monitor では、メトリックあたりで 10 ディメンション キーの制限と、サブスクリプション内のリージョンあたりでアクティブな時系列に合計 50,000 の制限 (12 時間以内) が設定されています。 API Management では、これらのうちの 5 つが以下のような既定のディメンションに使われます。

• Region
• サービス識別子
• サービス名
• サービスの種類

これらの制限により、API Management ポリシーでカスタム メトリック (emit-metric や azure-openai-emit-token-metric など) を構成する場合に次のような影響があります。

• ポリシーごとに最大で 5 個のカスタム ディメンションを構成できます。

• ポリシーによって生成されるアクティブ時系列数は、各設定済み次元の名前空間ごとに固有の値の数の積です。 たとえば、ポリシーで 3 つのカスタム ディメンションが構成されていて、各ディメンションが期間内に持つことのできた値が 10 個である場合、ポリシーは 1,000 (10 x 10 x 10) のアクティブな時系列を提供します。

• API管理は、各次元を100個のユニークな値に、各メトリック名前空間を1,000個のアクティブな時系列に制限します。 いずれかの限界に達すると、新しい次元値や時系列は追跡されず、対応する指標データは静かに破棄されます。

• 1 つのサブスクリプション内の同じリージョンにある複数の API Management インスタンスでポリシーを構成した場合、すべてのインスタンスがリージョンのアクティブな時系列の制限に影響します。

Azure Monitor のカスタム メトリックに関する設計上の制限事項と考慮事項の詳細については、こちらを参照してください。

パフォーマンス上の影響とログ サンプリング

社内負荷テストによると、要求のペースが毎秒 1,000 件を超えるとき、このログ機能を有効にすると、スループットに 40% から 50% の減少がありました。 Application Insights は、アプリケーション パフォーマンスの評価に統計分析を利用するように設計されています。 そうじゃありません：

• 監査システムを意図しています。
• ハイボリューム API の個々の要求をログに記録する場合に適しています。

[サンプリング] 設定を調整することで、ログに記録された要求の数を操作できます。 値が 100% の場合、すべての要求が記録されます。値が 0% の場合、何も記録されません。

サンプリングを利用することで利用統計情報の量が減り、パフォーマンスの大きな低下を効果的に回避しながら、ログ利用の長所を維持できます。

パフォーマンスの問題を改善するには、以下をスキップします。

• 要求ヘッダーと応答ヘッダー
• 本文のログ記録

Troubleshooting

API Management から Application Insights へのテレメトリ データ フローの問題に対処する:

• リンクされた Azure Monitor Private Link Scope (AMPLS) リソースが、API Management リソースが接続されている仮想ネットワーク内に存在するかどうかを調査します。 AMPLS リソースは、サブスクリプション全体のグローバル スコープを持ち、すべての Azure Monitor リソースのデータ クエリとインジェストの管理を担当します。 AMPLS がデータ インジェスト専用の Private-Only アクセス モードで構成されている可能性があります。 このような場合は、Application Insights リソースとそれに関連付けられている Log Analytics リソースを AMPLS に含めます。 この追加が行われると、API Management データが Application Insights リソースに正常に取り込まれるので、テレメトリ データ送信の問題が解決します。

関連コンテンツ

• Application Insights の概要 - OpenTelemetry の可観測性
• Azure API Management で Azure Event Hubs にイベントを記録する方法
• API Management の監視