ASP.NET Core アプリケーション向け Application Insights

この記事では、ASP.NET Core アプリケーションで Application Insights を有効にして構成する方法について説明します。

Application Insights では、ASP.NET Core アプリケーションから次のテレメトリを収集できます。

MVC アプリケーションの例を使います。 Worker サービスを使用している場合は、ワーカー サービス アプリケーション向け Application Insights に関する手順を使用します。

OpenTelemetry ベースの .NET オファリングを利用できます。 詳細については、「OpenTelemetry の概要」を参照してください。

サポートされるシナリオ

Application Insights SDK for ASP.NET Core では、実行されている場所や方法に関係なく、アプリケーションを監視できます。 アプリケーションが実行されていて、Azure へのネットワーク接続がある場合は、テレメトリを収集することができます。 Application Insights の監視は、.NET Core がサポートされているすべての場所でサポートされ、次のシナリオを対象としています。

前提条件

Application Insights のサーバー側テレメトリを有効にする (Visual Studio)

Visual Studio for Mac の場合は、手動のガイダンスを使用します。 この手順は、Visual Studio の Windows バージョンでのみサポートされています。

1. Visual Studio でプロジェクトを開きます。

2. [プロジェクト]>[Application Insights Telemetry の追加] に移動します。

3. [Azure Application Insights]>[次へ] を選択します。

4. サブスクリプションと Application Insights インスタンスを選択します。 または、[新規作成] を使用して新しいインスタンスを作成することもできます。 [次へ] を選択します。

5. Application Insights の接続文字列を追加または確認します。 これは、前の手順で選択した内容に基づいてあらかじめ設定されているはずです。 [完了] を選びます。

6. Application Insights をプロジェクトに追加した後、SDK の最新の安定リリースを使用していることを確認します。 [プロジェクト]>[NuGet パッケージの管理]>[Microsoft.ApplicationInsights.AspNetCore] に移動します。 必要であれば、[更新] を選択します。

   

Application Insights のサーバー側テレメトリを有効にする (Visual Studio なし)

1. ASP.NET Core 用の Application Insights SDK NuGet パッケージをインストールします。

   常に最新の安定バージョンを使用することをお勧めします。 オープンソースの GitHub リポジトリで、SDK の完全なリリース ノートを探します。

   次のコード サンプルは、プロジェクトの .csproj ファイルに追加する変更を示しています。

   <ItemGroup>
       <PackageReference Include="Microsoft.ApplicationInsights.AspNetCore" Version="2.21.0" />
   </ItemGroup>
   

2. AddApplicationInsightsTelemetry() を program.cs クラスに追加します。

   この例のように、builder.Services.AddApplicationInsightsTelemetry(); メソッドの後に WebApplication.CreateBuilder() を追加します。

   // This method gets called by the runtime. Use this method to add services to the container.
   var builder = WebApplication.CreateBuilder(args);
   
   // The following line enables Application Insights telemetry collection.
   builder.Services.AddApplicationInsightsTelemetry();
   
   // This code adds other services for your application.
   builder.Services.AddMvc();
   
   var app = builder.Build();
   

3. 接続文字列を追加します。このためには、次の 3 つの方法があります。

   • (推奨) 構成に接続文字列を設定します。

     appsettings.json に接続文字列を設定し、発行時に構成ファイルがアプリケーションのルート フォルダーにコピーされるようにします。

     {
         "Logging": {
             "LogLevel": {
                 "Default": "Information",
                 "Microsoft.AspNetCore": "Warning"
             }
         },
         "AllowedHosts": "*",
         "ApplicationInsights": {
             "ConnectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000"
         }
     }
     

   • APPLICATIONINSIGHTS_CONNECTION_STRING 環境変数に、または JSON 構成ファイルの ApplicationInsights:ConnectionString に接続文字列を設定します。

     次に例を示します。

     • SET ApplicationInsights:ConnectionString = <Copy connection string from Application Insights Resource Overview>
     • SET APPLICATIONINSIGHTS_CONNECTION_STRING = <Copy connection string from Application Insights Resource Overview>
     • 通常、APPLICATIONINSIGHTS_CONNECTION_STRING は Web Apps で使用されます。 また、この SDK がサポートされているすべての場所でも使用できます。

     注意

     コードで指定された接続文字列は、他のオプションより優先される環境変数 APPLICATIONINSIGHTS_CONNECTION_STRING より優先されます。

   • コードに接続文字列を設定します。

     接続文字列を、ApplicationInsightsServiceOptions クラスの AddApplicationInsightsTelemetry に 引数の一部として指定します。

ユーザー シークレットとその他の構成プロバイダー

接続文字列を ASP.NET Core ユーザー シークレットに格納するか、別の構成プロバイダーから取得する場合は、Microsoft.Extensions.Configuration.IConfiguration パラメーターでオーバーロードを使用できます。 パラメーターの例は services.AddApplicationInsightsTelemetry(Configuration); です。

Microsoft.ApplicationInsights.AspNetCore バージョン 2.15.0 以降では、services.AddApplicationInsightsTelemetry() の呼び出しによって、アプリケーションの Microsoft.Extensions.Configuration.IConfiguration から接続文字列が自動的に読み取られます。 IConfiguration を明示的に指定する必要はありません。

IConfiguration で複数のプロバイダーから構成を読み込んだ場合、services.AddApplicationInsightsTelemetry では、プロバイダーが追加された順序に関係なく、appsettings.json の構成が優先されます。 services.AddApplicationInsightsTelemetry(IConfiguration) メソッドを使用して、IConfiguration の優先処理なしで から構成を読み取ります。

アプリケーションを実行する

アプリケーションを実行し、それに対して要求を行います。 これで Application Insights にテレメトリが送られるはずです。 Application Insights SDK によって、次のテレメトリと共に、アプリケーションへの受信 Web 要求が自動的に収集されます。

ライブ メトリック

Live Metrics を使用すると、Application Insights を使用したアプリケーションの監視が正しく構成されているかどうかをすばやく確認できます。 テレメトリが Azure portal 内に表示されるまで数分かかることがありますが、[ライブ メトリック] ペインには、実行中のプロセスの CPU 使用率がほぼリアルタイムで表示されます。 また、要求、依存関係、トレースなどの他のテレメトリも表示できます。

任意の .NET アプリケーションのコードを使用して Live Metrics を有効にする

Live Metrics を手動で構成するには:

1. NuGet パッケージ Microsoft.ApplicationInsights.PerfCounterCollector をインストールします。

2. 次のサンプル コンソール アプリ コードは、Live Metrics の設定方法を示しています。

using Microsoft.ApplicationInsights;
using Microsoft.ApplicationInsights.Extensibility;
using Microsoft.ApplicationInsights.Extensibility.PerfCounterCollector.QuickPulse;

// Create a TelemetryConfiguration instance.
TelemetryConfiguration config = TelemetryConfiguration.CreateDefault();
config.ConnectionString = "InstrumentationKey=00000000-0000-0000-0000-000000000000";
QuickPulseTelemetryProcessor quickPulseProcessor = null;
config.DefaultTelemetrySink.TelemetryProcessorChainBuilder
    .Use((next) =>
    {
        quickPulseProcessor = new QuickPulseTelemetryProcessor(next);
        return quickPulseProcessor;
    })
    .Build();

var quickPulseModule = new QuickPulseTelemetryModule();

// Secure the control channel.
// This is optional, but recommended.
quickPulseModule.AuthenticationApiKey = "YOUR-API-KEY-HERE";
quickPulseModule.Initialize(config);
quickPulseModule.RegisterTelemetryProcessor(quickPulseProcessor);

// Create a TelemetryClient instance. It is important
// to use the same TelemetryConfiguration here as the one
// used to set up live metrics.
TelemetryClient client = new TelemetryClient(config);

// This sample runs indefinitely. Replace with actual application logic.
while (true)
{
    // Send dependency and request telemetry.
    // These will be shown in live metrics.
    // CPU/Memory Performance counter is also shown
    // automatically without any additional steps.
    client.TrackDependency("My dependency", "target", "http://sample",
        DateTimeOffset.Now, TimeSpan.FromMilliseconds(300), true);
    client.TrackRequest("My Request", DateTimeOffset.Now,
        TimeSpan.FromMilliseconds(230), "200", true);
    Task.Delay(1000).Wait();
}

上記のサンプルはコンソール アプリ用ですが、あらゆる .NET アプリケーションで同じコードを使用できます。 他のテレメトリ モジュールでテレメトリの自動収集が有効な場合は、それらのモジュールの初期化に使用されるのと同じ構成が、その Live Metrics モジュールに使用されるようにすることが重要です。

ILogger によるログ記録

既定の構成では、ILoggerWarning ログ以上の重大度のログが収集されます。 詳細については、「ILogger logs コレクションをカスタマイズする方法」を参照してください。

依存関係

依存関係の収集は既定で有効になっています。 「Application Insights での依存関係の追跡」では、自動収集される依存関係について説明されており、手動で追跡するための手順も示されています。

パフォーマンス カウンター

ASP.NET Core でのパフォーマンス カウンターのサポートは制限されています。

• SDK バージョン 2.4.1 以降では、アプリケーションが Web Apps (Windows) で実行されている場合、パフォーマンス カウンターが収集されます。
• SDK バージョン 2.7.1 以降では、アプリケーションが Windows で実行されていて、netstandard2.0 以降を対象とする場合、パフォーマンス カウンターが収集されます。
• .NET Framework を対象とするアプリケーションの場合、すべてのバージョンの SDK でパフォーマンス カウンターがサポートされます。
• SDK バージョン 2.8.0 以降では、Linux の CPU/メモリ カウンターがサポートされます。 Linux では、その他のカウンターはサポートされません。 Linux (およびその他の非 Windows 環境) でシステム カウンターを取得するには、EventCounters を使用してください。

EventCounter

既定では、EventCounterCollectionModule は有効になっています。 収集されるカウンターの一覧を構成する方法については、「EventCounter の概要」を参照してください。

HTTP を使用してデータを強化する

HttpContext.Features.Get<RequestTelemetry>().Properties["myProp"] = someData

Web アプリケーションに対してクライアント側のテレメトリを有効にする

サーバー側テレメトリの収集を始めるためなら、上記の手順で十分です。 アプリケーションにクライアント側コンポーネントがある場合は、次の手順に従って、構成による JavaScript (Web) SDK ローダー スクリプトの挿入を使用して使用状況テレメトリの収集を開始します。

1. _ViewImports.cshtml で、次のインジェクションを追加します。

   @inject Microsoft.ApplicationInsights.AspNetCore.JavaScriptSnippet JavaScriptSnippet
   

2. _Layout.cshtml で、HtmlHelper セクションの終わりに (ただし、他のスクリプトの前に) <head> を挿入します。 ページからカスタム JavaScript テレメトリを報告する場合は、このスニペットの後に挿入します。

       @Html.Raw(JavaScriptSnippet.FullScript)
   </head>
   

Application Insights SDK for ASP.NET Core バージョン 2.14 以降では、FullScript を使用する代わりに、ScriptBody を使用できます。 コンテンツ セキュリティ ポリシーを設定するために ScriptBody タグをコントロールする必要がある場合は、<script> を使用します。

<script> // apply custom changes to this script tag.
    @Html.Raw(JavaScriptSnippet.ScriptBody)
</script>

上で参照されている .cshtml ファイル名は、既定の MVC アプリケーション テンプレートからのものです。 最終的に、アプリケーションに対するクライアント側の監視を正しく有効にするためには、JavaScript (Web) SDK ローダー スクリプトが、監視するアプリケーションの各ページの <head> セクションにある必要があります。 クライアント側の監視を有効にするために、アプリケーション テンプレートの _Layout.cshtml に JavaScript (Web) SDK ローダー スクリプトを追加します。

プロジェクトに _Layout.cshtml が含まれていない場合でも、アプリ内のすべてのページの を制御する同等のファイルに JavaScript (Web) SDK ローダー スクリプトを追加することで、<head>を追加できます。 または、複数のページに JavaScript (Web) SDK ローダー スクリプトを追加することもできますが、お勧めしません。

Application Insights SDK を構成する

Application Insights SDK for ASP.NET Core をカスタマイズして、既定の構成を変更できます。 Application Insights ASP.NET SDK のユーザーであれば、ApplicationInsights.config を使用するか、TelemetryConfiguration.Active を変更することによって、構成を変更することに慣れている場合もあります。 ASP.NET Core の場合、他の方法が指定されていない限り、ほとんどすべての構成の変更は、ConfigureServices() クラスの メソッドで行います。 以下のセクションではさらに詳しく説明します。

ApplicationInsightsServiceOptions を使用する

次の例のように ApplicationInsightsServiceOptions を AddApplicationInsightsTelemetry に渡すことで、いくつかの一般的な設定を変更できます。

var builder = WebApplication.CreateBuilder(args);

var aiOptions = new Microsoft.ApplicationInsights.AspNetCore.Extensions.ApplicationInsightsServiceOptions();

// Disables adaptive sampling.
aiOptions.EnableAdaptiveSampling = false;

// Disables live metrics (also known as QuickPulse).
aiOptions.EnableQuickPulseMetricStream = false;

builder.Services.AddApplicationInsightsTelemetry(aiOptions);
var app = builder.Build();

次の表は、ApplicationInsightsServiceOptions の設定の完全な一覧です。

最新の一覧については、ApplicationInsightsServiceOptions での構成可能な設定に関するページを参照してください。

Microsoft.ApplicationInsights.AspNetCore SDK 2.15.0 以降の構成に関する推奨事項

Microsoft.ApplicationInsights.AspNetCore SDK バージョン 2.15.0 以降では、ApplicationInsightsServiceOptions で使用できるすべての設定 (ConnectionString を含む) を構成します。 アプリケーションの IConfiguration インスタンスを使用します。 次の例に示すように、設定は ApplicationInsights セクションの下に記載されている必要があります。 appsettings.json の次のセクションによって、接続文字列が構成され、アダプティブ サンプリングとパフォーマンス カウンターの収集が無効にされます。

{
    "ApplicationInsights": {
    "ConnectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000",
    "EnableAdaptiveSampling": false,
    "EnablePerformanceCounterCollectionModule": false
    }
}

ASP.NET Core 6.0 の builder.Services.AddApplicationInsightsTelemetry(aiOptions) または ASP.NET Core 3.1 以前の services.AddApplicationInsightsTelemetry(aiOptions) を使った場合、Microsoft.Extensions.Configuration.IConfiguration からの設定をオーバーライドします。

サンプリング

Application Insights SDK for ASP.NET Core では、固定レートとアダプティブ サンプリングの両方がサポートされています。 既定では、アダプティブ サンプリングは有効になっています。

詳しくは、「ASP.NET Core アプリケーションのためのアダプティブ サンプリングの構成」をご覧ください。

TelemetryInitializers を追加する

追加の情報でテレメトリをエンリッチする必要がある場合は、テレメトリ初期化子を使用します。

次のコードで示すように、新しい TelemetryInitializer を DependencyInjection コンテナーに追加します。 TelemetryInitializer コンテナーに追加された DependencyInjection は、SDK によって自動的に認識されます。

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddSingleton<ITelemetryInitializer, MyCustomTelemetryInitializer>();

var app = builder.Build();

TelemetryInitializers を削除する

既定では、テレメトリ初期化子は存在します。 すべてまたは特定のテレメトリ初期化子を削除するには、 を呼び出した "後AddApplicationInsightsTelemetry()" で、次のサンプル コードを使用します。

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddApplicationInsightsTelemetry();

// Remove a specific built-in telemetry initializer
var tiToRemove = builder.Services.FirstOrDefault<ServiceDescriptor>
                    (t => t.ImplementationType == typeof(AspNetCoreEnvironmentTelemetryInitializer));
if (tiToRemove != null)
{
    builder.Services.Remove(tiToRemove);
}

// Remove all initializers
// This requires importing namespace by using Microsoft.Extensions.DependencyInjection.Extensions;
builder.Services.RemoveAll(typeof(ITelemetryInitializer));

var app = builder.Build();

テレメトリ プロセッサを追加する

拡張メソッド TelemetryConfiguration を AddApplicationInsightsTelemetryProcessor で使用することで、カスタム テレメトリ プロセッサを IServiceCollection に追加できます。 テレメトリ プロセッサは、高度なフィルター処理のシナリオで使用します。 次の例を使用してください。

var builder = WebApplication.CreateBuilder(args);

// ...
builder.Services.AddApplicationInsightsTelemetry();
builder.Services.AddApplicationInsightsTelemetryProcessor<MyFirstCustomTelemetryProcessor>();

// If you have more processors:
builder.Services.AddApplicationInsightsTelemetryProcessor<MySecondCustomTelemetryProcessor>();

var app = builder.Build();

既定の TelemetryModules を構成または削除する

Application Insights では、ユーザーによる手動の追跡を必要とせずに特定のワークロードに関するテレメトリが自動収集されます。

既定では、次の自動収集モジュールが有効になります。 これらのモジュールでは、自動的にテレメトリが収集されます。 それらを無効にするか構成して、既定の動作を変更できます。

• RequestTrackingTelemetryModule: 受信 Web 要求から RequestTelemetry を収集します。
• DependencyTrackingTelemetryModule: HTTPとSQLの送信呼び出しからDependencyTelemetryを収集します。
• PerformanceCollectorModule: Windows PerformanceCounters を収集します。
• QuickPulseTelemetryModule: [ライブ メトリック] ペイン内に表示するテレメトリを収集します。
• AppServicesHeartbeatTelemetryModule: アプリケーションがホストされる App Service 環境について、(カスタム メトリックとして送信される) ハート ビートを収集します。
• AzureInstanceMetadataTelemetryModule: アプリケーションがホストされる Azure VM 環境について、(カスタム メトリックとして送信される) ハート ビートを収集します。
• EventCounterCollectionModule: EventCounters を収集します。 このモジュールは新機能であり、SDK バージョン 2.8.0 以降で使用できます。

既定の TelemetryModule を構成するには、次の例のように、拡張メソッド ConfigureTelemetryModule<T> を IServiceCollection で使用します。

using Microsoft.ApplicationInsights.DependencyCollector;
using Microsoft.ApplicationInsights.Extensibility.PerfCounterCollector;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddApplicationInsightsTelemetry();

// The following configures DependencyTrackingTelemetryModule.
// Similarly, any other default modules can be configured.
builder.Services.ConfigureTelemetryModule<DependencyTrackingTelemetryModule>((module, o) =>
        {
            module.EnableW3CHeadersInjection = true;
        });

// The following removes all default counters from EventCounterCollectionModule, and adds a single one.
builder.Services.ConfigureTelemetryModule<EventCounterCollectionModule>((module, o) =>
        {
            module.Counters.Add(new EventCounterCollectionRequest("System.Runtime", "gen-0-size"));
        });

// The following removes PerformanceCollectorModule to disable perf-counter collection.
// Similarly, any other default modules can be removed.
var performanceCounterService = builder.Services.FirstOrDefault<ServiceDescriptor>(t => t.ImplementationType == typeof(PerformanceCollectorModule));
if (performanceCounterService != null)
{
    builder.Services.Remove(performanceCounterService);
}

var app = builder.Build();

バージョン 2.12.2 以降では、ApplicationInsightsServiceOptions には、任意の既定のモジュールを無効にする簡単なオプションが含まれています。

テレメトリ チャネルの構成

既定のテレメトリ チャネルは ServerTelemetryChannel です。 次の例は、それをオーバーライドする方法を示したものです。

using Microsoft.ApplicationInsights.Channel;

var builder = WebApplication.CreateBuilder(args);

// Use the following to replace the default channel with InMemoryChannel.
// This can also be applied to ServerTelemetryChannel.
builder.Services.AddSingleton(typeof(ITelemetryChannel), new InMemoryChannel() {MaxTelemetryBufferCapacity = 19898 });

builder.Services.AddApplicationInsightsTelemetry();

var app = builder.Build();

テレメトリを動的に無効にする

テレメトリを条件付きで動的に無効にする必要がある場合は、コードの任意の場所で ASP.NET Core の依存関係挿入コンテナーを使用して TelemetryConfiguration インスタンスを解決し、それに DisableTelemetry フラグを設定することができます。

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddApplicationInsightsTelemetry();

// any custom configuration can be done here:
builder.Services.Configure<TelemetryConfiguration>(x => x.DisableTelemetry = true);

var app = builder.Build();

前のコード サンプルでは、Application Insights にテレメトリが送信されなくなります。 これにより、自動収集モジュールでテレメトリが収集されなくなることはありません。 特定の自動収集モジュールを削除する場合は、テレメトリ モジュールの削除に関する記事を参照してください。

トラブルシューティング

専用のトラブルシューティングに関する記事をご覧ください。

アプリケーション ホストとインジェスト サービスの間の接続をテストする

Application Insights SDK とエージェントからテレメトリが送信され、インジェスト エンドポイントへの REST 呼び出しとして取り込まれます。 Web サーバーまたはアプリケーション ホスト マシンからインジェスト サービス エンドポイントへの接続は、PowerShell の生の REST クライアントを使用するか、curl コマンドを使用してテストできます。 「Azure Monitor Application Insights でアプリケーション テレメトリが見つからない場合のトラブルシューティング」をご覧ください。

オープンソース SDK

コードを読んで協力してください。

最新の更新プログラムとバグ修正については、リリース ノートを参照してください。

リリース ノート

バージョン2.12 以降の場合：.NET SDK (ASP.NET、ASP.NET Core、およびログ アダプターを含む)

Application Insights の主な機能強化は、サービスの更新に関するページでも要約しています。

次のステップ

• よく寄せられる質問 (FAQ) を確認するには、「Application Insights for ASP.NET Core の FAQ」を参照してください
• サポートされているバージョンの Application Insights SDK を実行していることを確認します。
• ユーザー フローの探索: ユーザーがアプリ内をどのように移動しているかを把握します。
• スナップショット コレクションを構成して、例外がスローされたときのソース コードと変数の状態を確認します。
• API を使用して、アプリのパフォーマンスと使用の詳細を表示するための独自のイベントとメトリックスを送信します。
• 可用性テストの使用: 世界中からアプリを常にチェックします。
• ASP.NET Core での依存関係の挿入について学習します。