Azure API Management と Azure Application Insights を統合する方法
適用対象: すべての API Management レベル
Azure Application Insights を Azure API Management と簡単に統合できます。 Azure Application Insights は、複数のプラットフォームでアプリを構築および管理する Web 開発者向けの拡張可能なサービスです。 このガイドで行うこと:
- Application Insights の API Management への 統合について説明します。
- API Management サービス インスタンスに対するパフォーマンスへの影響を軽減する戦略について説明します。
前提条件
Azure API Management インスタンスが必要です。 まず、作成できます。
Application Insights を使用するには、Application Insights サービスのインスタンスを作成します。 Azure portal を使用してインスタンスを作成するには、「ワークスペースベースの Application Insights リソース」を参照してください。
Note
Application Insights リソースは別のサブスクリプションに含まれていても構いません。さらには、API Management リソース以外のテナントに含まれていても構いません。
Application Insights で使用する API Management のマネージド ID を構成する場合は、次の手順を実行する必要があります。
API Management インスタンスで、システムによって割り当てられた、またはユーザーが割り当てた API Management 用のマネージド ID を有効にします。
- ユーザー割り当てマネージド ID を有効にする場合は、ID のクライアント ID をメモします。
ID に、Application Insights リソースをスコープとする監視メトリック 発行者ロールを割り当てます。 ロールは、Azure portal または他の Azure ツールを使用して割り当てることができます。
シナリオの概要
このシナリオの大まかな手順を次に示します。
まず、Application Insights と API Management 間の接続を作成します
Application Insights と API Management 間の接続は、Azure portal、REST API、または関連する Azure ツールを使用して作成できます。 API Management によって、接続用の "ロガー" リソースが構成されます。
Note
Application Insights リソースが別のテナントにある場合は、REST API を使用してロガーを作成する必要があります。
重要
現在、ポータルでは、API Management は Application Insights インストルメンテーション キーを使用した Application Insights への接続のみをサポートしています。 Application Insights 接続文字列または API Management マネージド ID を使用するには、REST API、Bicep、または ARM テンプレートを使用してロガーを作成します。 Application Insights の接続文字列の詳細については、こちらを参照してください。
次に、1 つまたは複数の API の Application Insights ログを有効にします。
この記事では、Azure portal を使用して API の Application Insights ログを有効にします。 API Management によって、API の "診断" リソースが構成されます。
Azure portal を使用して接続を作成する
Azure portal を使用して Application Insights とAPI Management の間の接続を作成するには、次の手順に従います。
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 テンプレートを使用して、Application Insights と API Management の間の接続を作成するには、次の手順に従います。 接続文字列、システム割り当てマネージド ID、またはユーザー割り当てマネージド ID を使用するロガーを構成できます。
接続文字列の資格情報を持つロガー
Application Insights 接続文字列は、Application Insights リソースの [概要] セクションに表示されます。
次の要求本文を含む API Management REST API を使用します。
{
"properties": {
"loggerType": "applicationInsights",
"description": "adding a new logger with connection string",
"credentials": {
"connectionString":"InstrumentationKey=00000000-0000-0000-0000-000000000000;IngestionEndpoint=https://xxxx.applicationinsights.azure.com/;..."
}
}
}
システム割り当てマネージド ID の資格情報を持つロガー
API Managementマネージド ID を使用するための前提条件を参照してください。
次の要求本文を含む API Management REST API を使用します。
{
"properties": {
"loggerType": "applicationInsights",
"description": "adding a new logger with system-assigned managed identity",
"credentials": {
"connectionString":"InstrumentationKey=00000000-0000-0000-0000-000000000000;IngestionEndpoint=https://xxxx.applicationinsights.azure.com/;...",
"identityClientId":"SystemAssigned"
}
}
}
ユーザー割り当てマネージド ID の資格情報を持つロガー
API Managementマネージド ID を使用するための前提条件を参照してください。
次の要求本文を含む API Management REST API を使用します。
{
"properties": {
"loggerType": "applicationInsights",
"description": "adding a new logger with user-assigned managed identity",
"credentials": {
"connectionString":"InstrumentationKey=00000000-0000-0000-0000-000000000000;IngestionEndpoint=https://xxxx.applicationinsights.azure.com/;...",
"identityClientId":"<ClientID>"
}
}
}
API で Application Insights ログを有効にする
API の Application Insights ログを有効にするには、次の手順に従います。 すべての API の Application Insights ログを有効にすることもできます。
Azure Portal で Azure API Management サービス インスタンスに移動します。
左にあるメニューから [API] を選択します。
API をクリックします。今回は Demo Conference 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 | 失敗した要求ごと:
|
| トレース | トレース ポリシーを構成した場合。 trace ポリシーの severity 設定は、Application Insights ログの verbosity 設定と同じかそれ以上である必要があります。 |
Note
Application Insights インスタンスあたりのメトリックとイベントに設定されている最大のサイズと数については、Application Insights の制限に関する記事を参照してください。
カスタム メトリックを出力する
API Management インスタンスから Application Insights にカスタム メトリックを出力できます。 API Management は、emit-metric ポリシーを使用してカスタム メトリックを出力します。
カスタム メトリックを出力するには、次の構成手順を実行します。
Application Insights インスタンスで [カスタム メトリック (プレビュー)] を有効にし、カスタム ディメンションを使用します。
- ポータルの Application Insights インスタンスに移動します。
- 左側のメニューで [使用量と推定コスト] を選択します。
- [カスタム メトリック (プレビュー)]>[ディメンションあり] の順に選択します。
- [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ポリシーごとに最大 10 のカスタム ディメンションを構成できます。12 時間以内に
emit-metricポリシーで生成されるアクティブな時系列の数は、期間中に構成された各ディメンションで一意な値の数の積です。 たとえば、ポリシーで 3 つのカスタム ディメンションが構成され、各ディメンションが期間内に 10 の使用可能な値を持つ場合、emit-metricポリシーは 1,000 (10 x 10 x 10) のアクティブな時系列を提供します。サブスクリプション内の同じリージョンにある複数の API Management インスタンスで
emit-metricポリシーを構成した場合、すべてのインスタンスがリージョンのアクティブな時系列の制限に影響します。
パフォーマンス上の影響とログ サンプリング
警告
すべてのイベントを記録すると、受信要求の頻度によっては、パフォーマンスに重大な影響を与える可能性があります。
社内負荷テストによると、要求のペースが毎秒 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 からのデータの視覚化について説明します