ApplicationInsights.config または .xml を使って Application Insights SDK を構成する

[アーティクル]
10/15/2024

Application Insights .NET SDK は多くの NuGet パッケージで構成されています。コアパッケージは、テレメトリを Application Insights に送信するための API を提供します。追加パッケージは、アプリケーションとそのコンテキストからテレメトリを自動的に追跡するためのテレメトリ モジュールと初期化子を提供します。構成ファイルを調整することによって、テレメトリモジュールと初期化子を有効または無効にできます。その中のいくつかに対し、パラメーターを設定することもできます。

Note

以下のドキュメントは、Application Insights クラシック API に関するものです。 Application Insights の長期的な計画は、OpenTelemetry を使用してデータを収集することです。詳細については、「.NET、Node.js、Python、Java アプリケーション用の Azure Monitor OpenTelemetry を有効にする」と「Microsoft の OpenTelemetry ロードマップ」を参照してください。 .NET、Node.js、Python 向けの移行ガイダンスを利用できます。

構成ファイルの名前は ApplicationInsights.config または ApplicationInsights.xml です。名前はアプリケーションの種類によって異なります。構成ファイルは、SDK のほとんどのバージョンのインストール時に、プロジェクトに自動的に追加されます。既定では、[追加]>[Application Insights Telemetry] がサポートされている Visual Studio テンプレートプロジェクトからの自動化されたエクスペリエンスを使用すると、ApplicationInsights.config ファイルがプロジェクトのルートフォルダーに作成されます。コンパイルされると、bin フォルダーにコピーされます。また、IIS サーバー上の Application Insights エージェントによって Web アプリにも追加されます。 Azure Web サイトの拡張機能または Azure VM の拡張機能と仮想マシンスケールセットが使用されている場合、構成ファイルは無視されます。

Web ページの SDK を制御するための同等のファイルはありません。

この記事では、構成ファイルの各セクション、SDK のコンポーネントの制御方法、それらのコンポーネントを読み込む NuGet パッケージについて説明します。

Note

ApplicationInsights.config および .xml の手順は、.NET Core SDK には適用されません。 .NET Core アプリケーションを構成するには、「Application Insights for ASP.NET Core アプリケーション」の指示に従ってください。

テレメトリモジュール (ASP.NET)

各テレメトリモジュールは特定の種類のデータを回収し、コア API を利用してデータを送信します。モジュールはさまざまな NuGet パッケージによりインストールされます。NuGet パッケージはまた、必要な行を .config ファイルに追加します。

各モジュールの構成ファイルにノードが存在します。モジュールを無効にするには、ノードを削除するか、コメントアウトします。

依存関係の追跡

依存関係の追跡により、アプリがデータベースと外部サービスに行った呼び出しに関するテレメトリが回収されます。このモジュールを IIS サーバーで機能させるには、Application Insights エージェントをインストールする必要があります。

TrackDependency API を使用して、独自の依存関係追跡コードを記述することもできます。

Microsoft.ApplicationInsights.DependencyCollector.DependencyTrackingTelemetryModule
Microsoft.ApplicationInsights.DependencyCollector NuGet パッケージ

エージェントベース (コードなし) アタッチを使用してコードを変更することなく、依存関係を自動収集できます。これを Azure Web アプリで使用するには、Application Insights 拡張機能を有効にします。 Azure VM または Azure 仮想マシンスケールセットで使用するには、VM と仮想マシンスケールセットのアプリケーション監視拡張を有効にします。

パフォーマンスコレクター

パフォーマンスコレクターでは、CPU、メモリ、IIS インストールのネットワーク負荷など、システムパフォーマンスカウンターを収集します。自分で設定したパフォーマンスカウンターなど、回収するカウンターを指定できます。

Microsoft.ApplicationInsights.Extensibility.PerfCounterCollector.PerformanceCollectorModule
Microsoft.ApplicationInsights.PerfCounterCollector NuGet パッケージ

Application Insights 診断テレメトリ

DiagnosticsTelemetryModule クラスでは Application Insights インストルメンテーションコード自体のエラーを報告します。たとえば、コードがパフォーマンスカウンターにアクセスできない場合や、ITelemetryInitializer が例外をスローする場合などです。診断検索に、このモジュールが追跡するトレーステレメトリが表示されます。

Microsoft.ApplicationInsights.Extensibility.Implementation.Tracing.DiagnosticsTelemetryModule
Microsoft.ApplicationInsights NuGet パッケージこのパッケージのみをインストールする場合、ApplicationInsights.config ファイルは自動作成されません。

開発者モード

DeveloperModeWithDebuggerAttachedTelemetryModule クラスでは、デバッガーがアプリケーションプロセスに接続されているときに、Application Insights の TelemetryChannel にデータを即座に、一度に 1 つのテレメトリ項目を送信するよう強制します。この設計により、アプリケーションがテレメトリを追跡してから、それが Application Insights ポータルに表示されるまでの時間が縮小されます。ここでは、CPU とネットワーク帯域幅のオーバーヘッドが著しく費やされます。

Microsoft.ApplicationInsights.WindowsServer.DeveloperModeWithDebuggerAttachedTelemetryModule
Application Insights Windows Server NuGet パッケージ

Web 要求の追跡

Web 要求の追跡では、HTTP 要求の応答時間と結果コードを報告します。

Microsoft.ApplicationInsights.Web.RequestTrackingTelemetryModule
Microsoft.ApplicationInsights.Web NuGet パッケージ

例外の追跡

ExceptionTrackingTelemetryModule クラスは Web アプリで処理されない例外を追跡します。詳細については、「失敗と例外」を参照してください。

[https://login.microsoftonline.com/consumers/](Microsoft.ApplicationInsights.Web.ExceptionTrackingTelemetryModule)
Microsoft.ApplicationInsights.Web NuGet パッケージ。
Microsoft.ApplicationInsights.WindowsServer.UnobservedExceptionTelemetryModule: 監視されていないタスクを追跡します。例外。
Microsoft.ApplicationInsights.WindowsServer.UnhandledExceptionTelemetryModule: worker ロール、Windows サービス、コンソールアプリケーションのハンドルされない例外を追跡します。
Application Insights Windows Server NuGet パッケージ

EventSource の追跡

EventSourceTelemetryModule クラスを使用すると、Application Insights にトレースとして送信される EventSource イベントを構成できます。 EventSource イベントの追跡については、「EventSource イベントを使用する」をご覧ください。

Microsoft.ApplicationInsights.EventSourceListener.EventSourceTelemetryModule
Microsoft.ApplicationInsights.EventSourceListener

ETW イベントの追跡

EtwCollectorTelemetryModule クラスを使用すると、Application Insights にトレースとして送信される ETW プロバイダーを構成できます。 ETW イベントの追跡については、「ETW イベントを使用する」をご覧ください。

Microsoft.ApplicationInsights.EtwCollector.EtwCollectorTelemetryModule
Microsoft.ApplicationInsights.EtwCollector

Microsoft.ApplicationInsights

Microsoft.ApplicationInsights パッケージには、SDK のコア API が用意されています。他のテレメトリモジュールでは、この API を使用します。独自のテレメトリを定義するために使用することもできます。

ApplicationInsights.config にエントリがありません。
Microsoft.ApplicationInsights NuGet パッケージこの NuGet だけをインストールする場合、.config ファイルは生成されません。

テレメトリチャネル

テレメトリチャネルでは、テレメトリのバッファリングと Application Insights サービスへの送信が管理されます。

Microsoft.ApplicationInsights.WindowsServer.TelemetryChannel.ServerTelemetryChannel は Web アプリケーション用の既定のチャネルです。メモリ内にデータをバッファーし、より信頼性の高いテレメトリ配信のために、再試行のメカニズムとローカルディスクストレージを採用しています。
Microsoft.ApplicationInsights.InMemoryChannel は軽量なテレメトリチャネルです。他のチャネルが構成されていない場合に使用されます。

テレメトリの初期化子 (ASP.NET)

テレメトリの初期化子は、テレメトリのあらゆるアイテムと共に送信されるコンテキストプロパティを設定します。

独自の初期化子を記述し、コンテキストプロパティを設定できます。

標準の初期化子は Web または WindowsServer NuGet パッケージによりすべて設定されます。

AccountIdTelemetryInitializer は AccountId プロパティを設定します。
AuthenticatedUserIdTelemetryInitializer は JavaScript SDK による設定に基づき AuthenticatedUserId プロパティを設定します。
AzureRoleEnvironmentTelemetryInitializer は、Azure ランタイム環境から抽出された情報により、すべてのテレメトリ項目の Device コンテキストの RoleName および RoleInstance プロパティを更新します。
BuildInfoConfigComponentVersionTelemetryInitializer は、MS ビルドによって生成された BuildInfo.config ファイルから抽出された値を使用して、すべてのテレメトリ項目の Component コンテキストの Version プロパティを更新します。
ClientIpHeaderTelemetryInitializer は、要求の X-Forwarded-For HTTP ヘッダーに基づいて、すべてのテレメトリ項目の Location コンテキストの Ip プロパティを更新します。
DeviceTelemetryInitializer は、すべてのテレメトリ項目の Device コンテキストの次のプロパティを更新します。
- Type は PC に設定されます。
- Id は Web アプリケーションが実行中のコンピューターのドメイン名に設定します。
- OemName は WMI を使用して Win32_ComputerSystem.Manufacturer フィールドから抽出された値に設定します。
- Model は WMI を使用して Win32_ComputerSystem.Model フィールドから抽出された値に設定します。
- NetworkType は NetworkInterface プロパティから抽出された値に設定します。
- Language は CurrentCulture プロパティの名前に設定します。
DomainNameRoleInstanceTelemetryInitializer は、Web アプリケーションを実行中のコンピューターのドメイン名を使用して、すべてのテレメトリ項目の Device コンテキストの RoleInstance プロパティを更新します。
OperationNameTelemetryInitializer は、HTTP メソッド、ASP.NET MVC コントローラーの名前、要求の処理のために呼び出されるアクションに基づいて、すべてのテレメトリ項目の RequestTelemetry の Name プロパティと Operation コンテキストの Name プロパティを更新します。
OperationIdTelemetryInitializer または OperationCorrelationTelemetryInitializer は、追跡されたすべてのテレメトリ項目の Operation.Id コンテキストプロパティを更新し、自動生成された RequestTelemetry.Id が付いた要求を処理します。
SessionTelemetryInitializer は、ユーザーのブラウザーで実行する ApplicationInsights JavaScript インストルメンテーションコードが生成する ai_session Cookie から抽出された値を使用して、すべてのテレメトリ項目の Session コンテキストの Id プロパティを更新します。
SyntheticTelemetryInitializer または SyntheticUserAgentTelemetryInitializer は、可用性テストや検索エンジンボットなど、合成ソースからの要求の処理時に追跡されるすべてのテレメトリ項目の User、Session、Operation のコンテキストプロパティを更新します。既定では、メトリックスエクスプローラーには合成テレメトリは表示されません。

<Filters> は、要求の識別プロパティを設定します。
UserTelemetryInitializer は、ユーザーのブラウザーで実行する Application Insights JavaScript インストルメンテーションコードが生成する ai_user Cookie から抽出された値を使用して、すべてのテレメトリ項目の User コンテキストの Id および AcquisitionDate のプロパティを更新します。
WebTestTelemetryInitializer は、可用性テストからの HTTP 要求に対してユーザー ID、セッション ID、および合成ソースプロパティを設定します。 <Filters> は、要求の識別プロパティを設定します。

Azure Service Fabric で実行されている .NET アプリケーションの場合、Microsoft.ApplicationInsights.ServiceFabric NuGet パッケージを含めることができます。このパッケージには、Service Fabric のプロパティをテレメトリ項目に追加する FabricTelemetryInitializer プロパティが含まれています。詳細については、この NuGet パッケージによって追加されるプロパティに関する GitHub のページをご覧ください。

テレメトリプロセッサ (ASP.NET)

テレメトリプロセッサは、SDK からポータルに送信される前に、各テレメトリ項目をフィルター処理して変更できます。

独自のテレメトリプロセッサを記述できます。

アダプティブサンプリングテレメトリプロセッサー (2.0.0-beta3 以降)

この機能は既定で有効化されています。アプリが多数のテレメトリを送信する場合、このプロセッサはその一部を削除します。


    <TelemetryProcessors>
      <Add Type="Microsoft.ApplicationInsights.WindowsServer.TelemetryChannel.AdaptiveSamplingTelemetryProcessor, Microsoft.AI.ServerTelemetryChannel">
        <MaxTelemetryItemsPerSecond>5</MaxTelemetryItemsPerSecond>
      </Add>
    </TelemetryProcessors>

パラメーターは、アルゴリズムが実現しようとするターゲットを指定します。 SDK の各インスタンスは独立して動作します。サーバーが複数のコンピューターのクラスターである場合、テレメトリの実際の量もそれに応じて増加します。

詳細については、サンプリングに関する記事を参照してください。

固定レートサンプリングテレメトリプロセッサー (2.0.0-beta1 以降)

標準的なサンプリングテレメトリプロセッサも用意されています (2.0.1 以降)。


    <TelemetryProcessors>
     <Add Type="Microsoft.ApplicationInsights.WindowsServer.TelemetryChannel.SamplingTelemetryProcessor, Microsoft.AI.ServerTelemetryChannel">

     <!-- Set a percentage close to 100/N where N is an integer. -->
     <!-- E.g. 50 (=100/2), 33.33 (=100/3), 25 (=100/4), 20, 1 (=100/100), 0.1 (=100/1000) -->
     <SamplingPercentage>10</SamplingPercentage>
     </Add>
   </TelemetryProcessors>

ConnectionString

接続文字列のコードサンプルを参照してください。

InstrumentationKey

注意

インストルメンテーションキーのインジェストのサポートは、2025 年 3 月 31 日に終了します。インストルメンテーションキーのインジェストは引き続き機能しますが、この機能の更新プログラムやサポートは提供されなくなります。接続文字列に移行することで、新機能をご利用いただけます。

この設定により、データが表示される Application Insights リソースが決定されます。通常、アプリケーションごとに、個別のキーを持つリソースを作成します。

キーを動的に設定する場合 (たとえば、アプリケーションからの結果を別のリソースに送信する場合)、構成ファイルからキーを省略し、代わりにコードで設定することができます。

標準テレメトリモジュールを含むすべてのインスタンスの TelemetryClient キーを設定するには、ASP.NET サービスの global.aspx.cs などの初期化メソッドで次の手順を実行します。

using Microsoft.ApplicationInsights.Extensibility;
using Microsoft.ApplicationInsights;

    protected void Application_Start()
    {
        TelemetryConfiguration configuration = TelemetryConfiguration.CreateDefault();
        configuration.InstrumentationKey = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx";
        var telemetryClient = new TelemetryClient(configuration);

特定のイベントセットを異なるリソースに送信する場合、特定のテレメトリクライアントのキーを設定できます。


    var tc = new TelemetryClient();
    tc.Context.InstrumentationKey = "----- my key ----";
    tc.TrackEvent("myEvent");
    // ...

新しいキーを取得するには、Application Insights ポータルで新しいリソースを作成します。

ApplicationId プロバイダー

このプロバイダーは v2.6.0 以降で使用できます。

このプロバイダーの目的は、インストルメンテーションキーに基づいて、アプリケーション ID を検索することです。アプリケーション ID は RequestTelemetry と DependencyTelemetry に含まれており、ポータルでの相関関係を決定するために使用されます。

この機能は、TelemetryConfiguration.ApplicationIdProvider をコード内または構成ファイル内に設定することで有効化されます。

インターフェイス:IApplicationIdProvider

public interface IApplicationIdProvider
{
    bool TryGetApplicationId(string instrumentationKey, out string applicationId);
}

Microsoft.ApplicationInsights SDK 内に次の 2 つの実装が用意されています。ApplicationInsightsApplicationIdProvider と DictionaryApplicationIdProvider。

ApplicationInsightsApplicationIdProvider

このラッパーはプロファイル API 用です。要求とキャッシュの結果を調整します。

このプロバイダーは、Microsoft.ApplicationInsights.DependencyCollector または Microsoft.ApplicationInsights.Web のいずれかをインストールしたときに、構成ファイルに追加されます。

このクラスには、省略可能なプロパティ ProfileQueryEndpoint があります。既定では、https://dc.services.visualstudio.com/api/profiles/{0}/appId に設定されています。この構成のプロキシを構成する必要がある場合は、ベースアドレスのプロキシ化と "/api/profiles/{0}/appId" を含めることをお勧めします。 {0} は実行時に要求ごとにインストルメンテーションキーに置き換わることに注意してください。

ApplicationInsights.config による構成の例

<ApplicationInsights>
    ...
    <ApplicationIdProvider Type="Microsoft.ApplicationInsights.Extensibility.Implementation.ApplicationId.ApplicationInsightsApplicationIdProvider, Microsoft.ApplicationInsights">
        <ProfileQueryEndpoint>https://dc.services.visualstudio.com/api/profiles/{0}/appId</ProfileQueryEndpoint>
    </ApplicationIdProvider>
    ...
</ApplicationInsights>

コードによる構成の例

TelemetryConfiguration.Active.ApplicationIdProvider = new ApplicationInsightsApplicationIdProvider();

DictionaryApplicationIdProvider

この静的プロバイダーは、構成済みのインストルメンテーションキーとアプリケーション ID のペアに依存しています。

このクラスには Defined プロパティがあります。これは、インストルメンテーションキーとアプリケーション ID のペアである Dictionary<string,string> です。

このクラスには、オプションのプロパティ Next があり、構成にないインストルメンテーションキーが要求されたときに使用する、別のプロバイダーの構成に使うことができます。

ApplicationInsights.config による構成の例

<ApplicationInsights>
    ...
    <ApplicationIdProvider Type="Microsoft.ApplicationInsights.Extensibility.Implementation.ApplicationId.DictionaryApplicationIdProvider, Microsoft.ApplicationInsights">
        <Defined>
            <Type key="InstrumentationKey_1" value="ApplicationId_1"/>
            <Type key="InstrumentationKey_2" value="ApplicationId_2"/>
        </Defined>
        <Next Type="Microsoft.ApplicationInsights.Extensibility.Implementation.ApplicationId.ApplicationInsightsApplicationIdProvider, Microsoft.ApplicationInsights" />
    </ApplicationIdProvider>
    ...
</ApplicationInsights>

コードによる構成の例

TelemetryConfiguration.Active.ApplicationIdProvider = new DictionaryApplicationIdProvider{
 Defined = new Dictionary<string, string>
    {
        {"InstrumentationKey_1", "ApplicationId_1"},
        {"InstrumentationKey_2", "ApplicationId_2"}
    }
};

ASP.NET アプリケーションのスナップショットコレクションの構成

次のステップ

API の詳細については、こちらをご覧ください。

次の方法で共有

ApplicationInsights.config または .xml を使って Application Insights SDK を構成する

テレメトリモジュール (ASP.NET)

依存関係の追跡

パフォーマンスコレクター

Application Insights 診断テレメトリ

開発者モード

Web 要求の追跡

例外の追跡

EventSource の追跡

ETW イベントの追跡

Microsoft.ApplicationInsights

テレメトリチャネル

テレメトリの初期化子 (ASP.NET)

テレメトリプロセッサ (ASP.NET)

アダプティブサンプリングテレメトリプロセッサー (2.0.0-beta3 以降)

固定レートサンプリングテレメトリプロセッサー (2.0.0-beta1 以降)

ConnectionString

InstrumentationKey

ApplicationId プロバイダー

インターフェイス:IApplicationIdProvider

ApplicationInsightsApplicationIdProvider

ApplicationInsights.config による構成の例

コードによる構成の例

DictionaryApplicationIdProvider

ApplicationInsights.config による構成の例

コードによる構成の例

ASP.NET アプリケーションのスナップショットコレクションの構成

次のステップ

フィードバック

その他のリソース

次の方法で共有

ApplicationInsights.config または .xml を使って Application Insights SDK を構成する

テレメトリ モジュール (ASP.NET)

依存関係の追跡

パフォーマンス コレクター

Application Insights 診断テレメトリ

開発者モード

Web 要求の追跡

例外の追跡

EventSource の追跡

ETW イベントの追跡

Microsoft.ApplicationInsights

テレメトリ チャネル

テレメトリの初期化子 (ASP.NET)

テレメトリ プロセッサ (ASP.NET)

アダプティブ サンプリング テレメトリ プロセッサー (2.0.0-beta3 以降)

固定レート サンプリング テレメトリ プロセッサー (2.0.0-beta1 以降)

ConnectionString

InstrumentationKey

ApplicationId プロバイダー

インターフェイス:IApplicationIdProvider

ApplicationInsightsApplicationIdProvider

ApplicationInsights.config による構成の例

コードによる構成の例

DictionaryApplicationIdProvider

ApplicationInsights.config による構成の例

コードによる構成の例

ASP.NET アプリケーションのスナップショット コレクションの構成

次のステップ

フィードバック

その他のリソース

テレメトリモジュール (ASP.NET)

パフォーマンスコレクター

テレメトリチャネル

テレメトリプロセッサ (ASP.NET)

アダプティブサンプリングテレメトリプロセッサー (2.0.0-beta3 以降)

固定レートサンプリングテレメトリプロセッサー (2.0.0-beta1 以降)

ASP.NET アプリケーションのスナップショットコレクションの構成