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

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

Note

以下のドキュメントは、Application Insights クラシック API に関するものです。 Application Insights の長期的な計画は、OpenTelemetry を使用してデータを収集することです。 詳しくは、「.NET、Node.js、Python、Java アプリケーション用の Azure Monitor OpenTelemetry を有効にする」をご覧ください。

構成ファイルの名前は 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 を使用して、独自の依存関係追跡コードを記述することもできます。

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

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

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

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 とネットワーク帯域幅のオーバーヘッドが著しく費やされます。

Web 要求の追跡

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

例外の追跡

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

  • 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 イベントを使用する」をご覧ください。

ETW イベントの追跡

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

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 パッケージによりすべて設定されます。

  • AccountIdTelemetryInitializerAccountId プロパティを設定します。

  • AuthenticatedUserIdTelemetryInitializer は JavaScript SDK による設定に基づき AuthenticatedUserId プロパティを設定します。

  • AzureRoleEnvironmentTelemetryInitializer は、Azure ランタイム環境から抽出された情報により、すべてのテレメトリ項目の Device コンテキストの RoleName および RoleInstance プロパティを更新します。

  • BuildInfoConfigComponentVersionTelemetryInitializer は、MS ビルドによって生成された BuildInfo.config ファイルから抽出された値を使用して、すべてのテレメトリ項目の Component コンテキストの Version プロパティを更新します。

  • ClientIpHeaderTelemetryInitializer は、要求の X-Forwarded-For HTTP ヘッダーに基づいて、すべてのテレメトリ項目の Location コンテキストの Ip プロパティを更新します。

  • DeviceTelemetryInitializer は、すべてのテレメトリ項目の Device コンテキストの次のプロパティを更新します。

    • TypePC に設定されます。
    • Id は Web アプリケーションが実行中のコンピューターのドメイン名に設定します。
    • OemName は WMI を使用して Win32_ComputerSystem.Manufacturer フィールドから抽出された値に設定します。
    • Model は WMI を使用して Win32_ComputerSystem.Model フィールドから抽出された値に設定します。
    • NetworkTypeNetworkInterface プロパティから抽出された値に設定します。
    • LanguageCurrentCulture プロパティの名前に設定します。
  • DomainNameRoleInstanceTelemetryInitializer は、Web アプリケーションを実行中のコンピューターのドメイン名を使用して、すべてのテレメトリ項目の Device コンテキストの RoleInstance プロパティを更新します。

  • OperationNameTelemetryInitializer は、HTTP メソッド、ASP.NET MVC コントローラーの名前、要求の処理のために呼び出されるアクションに基づいて、すべてのテレメトリ項目の RequestTelemetryName プロパティと Operation コンテキストの Name プロパティを更新します。

  • OperationIdTelemetryInitializer または OperationCorrelationTelemetryInitializer は、追跡されたすべてのテレメトリ項目の Operation.Id コンテキスト プロパティを更新し、自動生成された RequestTelemetry.Id が付いた要求を処理します。

  • SessionTelemetryInitializer は、ユーザーのブラウザーで実行する ApplicationInsights JavaScript インストルメンテーション コードが生成する ai_session Cookie から抽出された値を使用して、すべてのテレメトリ項目の Session コンテキストの Id プロパティを更新します。

  • SyntheticTelemetryInitializer または SyntheticUserAgentTelemetryInitializer は、可用性テストや検索エンジン ボットなど、合成ソースからの要求の処理時に追跡されるすべてのテレメトリ項目の UserSessionOperation のコンテキスト プロパティを更新します。 既定では、メトリックス エクスプローラーには合成テレメトリは表示されません。

    <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 は RequestTelemetryDependencyTelemetry に含まれており、ポータルでの相関関係を決定するために使用されます。

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

インターフェイス:IApplicationIdProvider

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

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

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 アプリケーションのスナップショット コレクションの構成

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

次のステップ

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