Azure API Management と Azure Application Insights を統合する方法

[アーティクル]
09/04/2024

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

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

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

Note

API Management ワークスペースでは、ワークスペース所有者は Application Insights を個別に統合し、ワークスペースの API に対して Application Insights のログ記録を有効にすることができます。ワークスペースと Application Insights を統合するための一般的なガイダンスは、API Management インスタンスのガイダンスと同様ですが、構成の対象はワークスペースのみとなります。現時点では、接続文字列 (推奨) またはインストルメンテーションキーを構成して、ワークスペースに Application Insights を統合する必要があります。

警告

セルフホステッドゲートウェイを使用する場合、Application Insights のメモリ内バッファリングに依存しているため、すべてのテレメトリが Azure Application Insights にプッシュされるとは限りません。

前提条件

Azure API Management インスタンスが必要です。まず、作成できます。
Application Insights を使用するには、Application Insights サービスのインスタンスを作成します。 Azure portal を使用してインスタンスを作成するには、「ワークスペースベースの Application Insights リソース」を参照してください。

Note

Application Insights リソースは別のサブスクリプションに含まれていても構いません。さらには、API Management リソース以外のテナントに含まれていても構いません。
Application Insights で使用するマネージド ID の資格情報を構成する場合は、次の手順を実行します。
1. API Management で、システムによって割り当てられた、またはユーザーが割り当てたマネージド ID を有効にします。
  - ユーザー割り当てマネージド ID を有効にする場合は、ID のクライアント ID をメモします。
2. ID に、Application Insights リソースをスコープとする監視メトリック発行者ロールを割り当てます。ロールは、Azure portal または他の Azure ツールを使用して割り当てることができます。

シナリオの概要

このシナリオの大まかな手順を次に示します。

最初に、Application Insights と API Management 間の接続を作成します

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

重要

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

Note

Application Insights リソースが別のテナントにある場合は、この記事の後半のセクションに示すように REST API または関連するツールを使用してロガーを作成する必要があります。
次に、1 つまたは複数の API の Application Insights ログを有効にします。

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

Azure portal を使用して接続を作成する

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

Note

可能であれば、セキュリティを強化するために、マネージド ID 資格情報と共に接続文字列を使用することをお勧めします。これらの資格情報を構成するには、この記事の後のセクションに示すように、REST API または関連ツールを使用します。

Azure Portal で Azure API Management サービスインスタンスに移動します。
左にあるメニューから [Application Insights] を選択します。
[+ 追加] を選択します。
前に作成した Application Insights インスタンスを選択し、簡単な説明を入力します。
Application Insights で API Management インスタンスの可用性監視を有効にするには、 [可用性の監視の追加] のチェックボックスを選択します。
- この設定では、API Management ゲートウェイエンドポイントが応答しているかどうかが定期的に検証されます。
- 結果は Application Insights インスタンスの [可用性] ペインに表示されます。
［作成］ を選択します
新しい Application Insights ロガーが一覧に表示されていることを確認します。

Note

バックグラウンドで、API Management インスタンスのインストルメンテーションキーを含むロガーエンティティが Application Insights インスタンス内に作成されます。

ヒント

Application Insights ロガーで構成されているインストルメンテーションキーを更新する必要がある場合は、(ロガー名ではなく) 一覧のロガーの行を選びます。インストルメンテーションキーを入力し、[保存] を選びます。

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

REST API、Bicep、または ARM テンプレートを使用して、API Management インスタンス用の Application Insights ロガーを作成するには、次の手順に従います。マネージド ID 資格情報を持つ接続文字列を使用するロガー (推奨)、または接続文字列のみを使用するロガーを構成できます。

マネージド ID 資格情報を持つ接続文字列を使用するロガー (推奨)

API Managementマネージド ID を使用するための前提条件を参照してください。

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

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

次の要求本文で API Management Logger - Create または Update REST API を使用します。

{
  "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"
    }
  }
}

Bicep テンプレートに次のようなスニペットを含めます。

resource aiLoggerWithSystemAssignedIdentity 'Microsoft.ApiManagement/service/loggers@2022-08-01' = {
  name: 'ContosoLogger1'
  parent: '<APIManagementInstanceName>'
  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'
    }
  }
}

Azure Resource Manager テンプレートに次のような JSON スニペットを含めます。

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

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

次の要求本文で API Management Logger - Create または Update REST API を使用します。

{
  "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":"<ClientID>"
    }
  }
}

Bicep テンプレートに次のようなスニペットを含めます。

resource aiLoggerWithUserAssignedIdentity 'Microsoft.ApiManagement/service/loggers@2022-08-01' = {
  name: 'ContosoLogger1'
  parent: '<APIManagementInstanceName>'
  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: '<ClientID>'
    }
  }
}

Azure Resource Manager テンプレートに次のような JSON スニペットを含めます。

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

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

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

次の要求本文で API Management Logger - Create または Update REST API を使用します。

ワークスペースのロガーを構成する場合は、Workspace Logger - Create または Update REST API を使用します。

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

Bicep テンプレートに次のようなスニペットを含めます。

ワークスペースのロガーを構成する場合は、代わりに Microsoft.ApiManagement/service.workspace/loggers@2023-09-01-preview リソースを作成します。

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

Azure Resource Manager テンプレートに次のような JSON スニペットを含めます。

ワークスペースのロガーを構成する場合は、Microsoft.ApiManagement/service.workspace/loggers リソースを作成し、代わりに apiVersion を 2023-09-01-preview に設定します。

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

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

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

Azure Portal で Azure API Management サービスインスタンスに移動します。
左にあるメニューから [API] > [API] を選択します。
Swagger Petstore などの API を選択します。構成されている場合は、バージョンを選択します。

ヒント

すべての API のログを有効にするには、[すべての API] を選択します。
上のバーで [設定] 他部に移動します。
下にスクロールし、 [診断ログ] セクションを表示します。
[有効化] ボックスをオンにします。
[Destination](出力先) ドロップダウンで、接続済みのロガーを選択します。
[Sampling (%)](サンプリング (%)) に 100 と入力し、 [Always log errors](エラーは常に記録する) チェックボックスをオンにします。
残りの設定はそのままにします。設定の詳細については、「診断ログ設定のリファレンス」を参照してください。

警告

[Number of payload bytes to log](ログに記録するペイロードのバイト数) の既定の値 0 を上書きすると、API のパフォーマンスが大幅に低下する可能性があります。
[保存] を選択します。
バックグラウンドで、applicationinsights という名前の診断エンティティが API レベルで作成されます。

Note

要求は、API Management が応答全体をクライアントに送信すると成功します。

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

ロガーは、さまざまなレベルで指定できます。

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

次の両方を指定します。

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

Application Insights に追加されるデータ

Application Insights に届くデータ:

テレメトリ項目	説明
Request	受信要求ごと: フロントエンド要求フロントエンド応答
依存関係	バックエンドサービスに転送される要求ごと: バックエンド要求バックエンド応答
Exception	失敗した要求ごと: クライアント接続が閉じられたため、失敗した要求 API ポリシーの "エラー状態" セクションをトリガーした要求応答 HTTP ステータスコードが 4xx または 5xx に一致する要求
トレース	トレースポリシーを構成した場合。 `trace` ポリシーの `severity` 設定は、Application Insights ログの `verbosity` 設定と同じかそれ以上である必要があります。

Note

Application Insights インスタンスあたりのメトリックとイベントに設定されている最大のサイズと数については、Application Insights の制限に関する記事を参照してください。

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

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

Note

カスタムメトリックは、Azure Monitor のプレビュー機能であり、制限が適用されます。

カスタムメトリックを出力するには、次の構成手順を実行します。

Application Insights インスタンスで [カスタムメトリック (プレビュー)] を有効にし、カスタムディメンションを使用します。
1. ポータルの Application Insights インスタンスに移動します。
2. 左側のメニューで [使用量と推定コスト] を選択します。
3. [カスタムメトリック (プレビュー)]>[ディメンションあり] の順に選択します。
4. [OK] を選択します。

API Management で構成されている applicationInsights 診断エンティティに "metrics": true プロパティを追加します。現時点では、API Management Diagnostic - Create or Update REST API を使用して、このプロパティを追加する必要があります。次に例を示します。

PUT https://management.azure.com/subscriptions/{SubscriptionId}/resourceGroups/{ResourceGroupName}/providers/Microsoft.ApiManagement/service/{APIManagementServiceName}/diagnostics/applicationinsights

{
    [...]
    {
    "properties": {
        "loggerId": "/subscriptions/{SubscriptionId}/resourceGroups/{ResourceGroupName}/providers/Microsoft.ApiManagement/service/{APIManagementServiceName}/loggers/{ApplicationInsightsLoggerName}",
        "metrics": true
        [...]
    }
}

Application Insights ロガーが、カスタムメトリックを出力するスコープ (すべての API、または 1 つの API) で構成されていることを確認します。詳細については、この記事の前半の「API で Application Insights ログを有効にする」を参照してください。
Application Insights ログが構成され、カスタムメトリックが有効になっているスコープ (すべての API または 1 つの API) で emit-metric ポリシーを構成します。ポリシーの詳細については、emit-metricポリシーリファレンスを参照してください。

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

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

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

ポリシーごとに最大 10 のカスタムディメンションを構成できます。
12 時間以内にポリシーで生成されるアクティブな時系列の数は、期間中に構成された各ディメンションで一意な値の数の積です。たとえば、ポリシーで 3 つのカスタムディメンションが構成され、各ディメンションが期間内に 10 の使用可能な値を持つ場合、ポリシーは 1,000 (10 x 10 x 10) のアクティブな時系列を提供します。
サブスクリプション内の同じリージョンにある複数の API Management インスタンスでポリシーを構成した場合、すべてのインスタンスがリージョンのアクティブな時系列の制限に影響します。

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

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

警告

すべてのイベントを記録すると、受信要求の頻度によっては、パフォーマンスに重大な影響を与える可能性があります。

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

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

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

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

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

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

ビデオ

トラブルシューティング

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

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

Azure Application Insights についてさらに学習します。
Azure Event Hubs によるログ記録を検討します。
Azure Managed Grafana を使用した Application Insights からのデータの視覚化について説明します

次の方法で共有

Azure API Management と Azure Application Insights を統合する方法

前提条件

シナリオの概要

Azure portal を使用して接続を作成する

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

マネージド ID 資格情報を持つ接続文字列を使用するロガー (推奨)

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

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

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

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

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

Application Insights に追加されるデータ

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

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

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

ビデオ

トラブルシューティング

フィードバック

その他のリソース

次の方法で共有

Azure API Management と Azure Application Insights を統合する方法

前提条件

シナリオの概要

Azure portal を使用して接続を作成する

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

マネージド ID 資格情報を持つ接続文字列を使用するロガー (推奨)

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

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

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

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

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

Application Insights に追加されるデータ

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

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

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

ビデオ

トラブルシューティング

関連するコンテンツ

フィードバック

その他のリソース

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

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

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