Application Insights pro aplikace ASP.NET Core

Článek
10/15/2024

Tento článek popisuje, jak povolit a nakonfigurovat Application Insights pro aplikaci ASP.NET Core .

Poznámka:

Následující dokumentace spoléhá na klasické rozhraní API Application Insights. Dlouhodobým plánem application Insights je shromažďovat data pomocí OpenTelemetry. Další informace najdete v tématu Povolení OpenTelemetry služby Azure Monitor pro aplikace .NET, Node.js, Python a Java a náš plán OpenTelemetry. Pokyny k migraci jsou k dispozici pro .NET, Node.js a Python.

Application Insights může shromažďovat následující telemetrická data z vaší aplikace ASP.NET Core:

Žádosti
Závislosti
Výjimky
Čítače výkonu
Prezenčních signálů
Protokoly

Používáme příklad aplikace MVC. Pokud používáte pracovní službu, postupujte podle pokynů v aplikacích Application Insights pro pracovní službu.

K dispozici je nabídka .NET založená na OpenTelemetry. Další informace najdete v tématu Přehled OpenTelemetry.

Poznámka:

Podpora příjmu dat založeného na instrumentačním klíči skončí 31. března 2025. Příjem klíčů instrumentace bude dál fungovat, ale už nebudeme poskytovat aktualizace ani podporu pro tuto funkci. Přechod na připojovací řetězec, abyste mohli využívat nové funkce.

Poznámka:

Pokud chcete použít samostatného zprostředkovatele ILogger, použijte Microsoft.Extensions.Logging.ApplicationInsight.

Podporované scénáře

Sada Application Insights SDK pro ASP.NET Core může monitorovat vaše aplikace bez ohledu na to, kde nebo jak běží. Pokud je vaše aplikace spuštěná a má síťové připojení k Azure, můžete shromažďovat telemetrická data. Monitorování Application Insights se podporuje všude, kde se podporuje .NET Core, a pokrývá následující scénáře:

Operační systém: Windows, Linux nebo Mac
Metoda hostování: V procesu nebo mimo proces
Metoda nasazení: Závislá nebo samostatná architektura
Webový server: Internetový informační server (IIS) nebo Kestrel
Platforma hostování: Funkce Web Apps pro službu Aplikace Azure, Azure Virtual Machines, Docker a Azure Kubernetes Service (AKS)
Verze .NET: Všechny oficiálně podporované verze .NET, které nejsou ve verzi Preview
INTEGROVANÉ VÝVOJOVÉ PROSTŘEDÍ: Visual Studio, Visual Studio Code nebo příkazový řádek

Požadavky

Potřebujete:

Funkční aplikace ASP.NET Core. Pokud potřebujete vytvořit aplikaci ASP.NET Core, postupujte podle tohoto kurzu ASP.NET Core.
Odkaz na podporovanou verzi balíčku NuGet Application Insights
Platný připojovací řetězec Application Insights. Tento řetězec se vyžaduje k odeslání jakékoli telemetrie do Application Insights. Pokud potřebujete vytvořit nový prostředek Application Insights, abyste získali připojovací řetězec, přečtěte si téma Vytvoření prostředku Application Insights.

Povolení telemetrie na straně serveru Application Insights (Visual Studio)

Pro Visual Studio pro Mac použijte ruční pokyny. Tento postup podporuje pouze verze windows sady Visual Studio.

Otevřete projekt v sadě Visual Studio.
Přejděte na Project>Add Application Insights Telemetry.
Vyberte další Aplikace Azure lication Insights>.
Zvolte své předplatné a instanci Application Insights. Nebo můžete vytvořit novou instanci pomocí příkazu Vytvořit novou. Vyberte Další.
Přidejte nebo potvrďte připojovací řetězec Application Insights. Měla by být předem vyplněna na základě vašeho výběru v předchozím kroku. Vyberte Dokončit.
Po přidání Application Insights do projektu zkontrolujte, jestli používáte nejnovější stabilní verzi sady SDK. Přejděte do >projektu Spravovat balíčky>NuGet Microsoft.ApplicationInsights.AspNetCore. Pokud potřebujete, vyberte Aktualizovat.

Povolení telemetrie na straně serveru Application Insights (bez sady Visual Studio)

Nainstalujte balíček NuGet sady Application Insights SDK pro ASP.NET Core.

Doporučujeme vždy používat nejnovější stabilní verzi. Úplné poznámky k verzi sady SDK najdete v opensourcovém úložišti GitHubu.

Následující ukázka kódu ukazuje změny, které se mají přidat do souboru projektu .csproj :
```
<ItemGroup>
    <PackageReference Include="Microsoft.ApplicationInsights.AspNetCore" Version="2.21.0" />
</ItemGroup>
```

Přidejte AddApplicationInsightsTelemetry() do předmětu nebo program.cs předmětustartup.cs. Volba závisí na vaší verzi .NET Core.

ASP.NET Core 6 a novější
ASP.NET Core 5 a starší

Přidejte builder.Services.AddApplicationInsightsTelemetry(); za metodu WebApplication.CreateBuilder() ve třídě Program , jak je znázorněno v tomto příkladu:

// 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();

Přidejte services.AddApplicationInsightsTelemetry(); do ConfigureServices() metody ve třídě Startup , jak je znázorněno v tomto příkladu:

// This method gets called by the runtime. Use this method to add services to the container.
public void ConfigureServices(IServiceCollection services)
{
    // The following line enables Application Insights telemetry collection.
    services.AddApplicationInsightsTelemetry();

    // This code adds other services for your application.
    services.AddMvc();
}

Poznámka:

Tato verze .NET se už nepodporuje.

Nastavte připojovací řetězec.

I když můžete jako součást argumentu ApplicationInsightsServiceOptions AddApplicationInsightsTelemetryzadat připojovací řetězec , doporučujeme zadat připojovací řetězec v konfiguraci. Následující ukázka kódu ukazuje, jak zadat připojovací řetězec v appsettings.json. Během publikování se ujistěte, že appsettings.json se zkopíruje do kořenové složky aplikace.
```
{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning"
    }
  },
  "AllowedHosts": "*",
  "ApplicationInsights": {
    "ConnectionString": "Copy connection string from Application Insights Resource Overview"
  }
}
```
Případně můžete zadat připojovací řetězec v APPLICATIONINSIGHTS_CONNECTION_STRING proměnné prostředí nebo ApplicationInsights:ConnectionString v konfiguračním souboru JSON.

Příklad:
- SET ApplicationInsights:ConnectionString = <Copy connection string from Application Insights Resource Overview>
- SET APPLICATIONINSIGHTS_CONNECTION_STRING = <Copy connection string from Application Insights Resource Overview>
- Obvykle se používá ve službě APPLICATIONINSIGHTS_CONNECTION_STRING Web Apps. Dá se použít také na všech místech, kde je tato sada SDK podporovaná.
Poznámka:

Připojovací řetězec zadaný v kódu vyhrává nad proměnnou APPLICATIONINSIGHTS_CONNECTION_STRINGprostředí, která vyhrává nad dalšími možnostmi.

Tajné kódy uživatelů a další poskytovatelé konfigurace

Pokud chcete uložit připojovací řetězec do tajných kódů uživatele ASP.NET Core nebo ho načíst od jiného zprostředkovatele konfigurace, můžete přetížení použít s parametremMicrosoft.Extensions.Configuration.IConfiguration. Příkladem parametru je services.AddApplicationInsightsTelemetry(Configuration);.

Ve Microsoft.ApplicationInsights.AspNetCore verzi 2.15.0 a novější volání services.AddApplicationInsightsTelemetry() automaticky přečte připojovací řetězec z Microsoft.Extensions.Configuration.IConfiguration aplikace. Není nutné explicitně zadávat IConfiguration.

Pokud IConfiguration se načetla konfigurace z více zprostředkovatelů, určuje services.AddApplicationInsightsTelemetry prioritu konfigurace z appsettings.json, bez ohledu na pořadí, ve kterém jsou zprostředkovatelé přidáni. Použijte metodu services.AddApplicationInsightsTelemetry(IConfiguration) ke čtení konfigurace bez IConfiguration této zvýhodněné zacházení pro appsettings.json.

Spusťte aplikaci

Spusťte aplikaci a proveďte požadavky na ni. Telemetrie by teď měla proudit do Application Insights. Sada Application Insights SDK automaticky shromažďuje příchozí webové požadavky do vaší aplikace spolu s následující telemetrií.

Živé metriky

Živé metriky se dají použít k rychlému ověření, jestli je správně nakonfigurované monitorování aplikací pomocí Application Insights. Zobrazení telemetrie na webu Azure Portal může trvat několik minut, ale v podokně živých metrik se zobrazuje využití procesoru spuštěného procesu téměř v reálném čase. Může také zobrazovat další telemetrii, jako jsou požadavky, závislosti a trasování.

Povolení živých metrik pomocí kódu pro libovolnou aplikaci .NET

Poznámka:

Živé metriky jsou ve výchozím nastavení povolené při jeho onboardingu pomocí doporučených pokynů pro aplikace .NET.

Ruční konfigurace živých metrik:

Nainstalujte balíček NuGet Microsoft.ApplicationInsights.PerfCounterCollector.
Následující ukázkový kód konzolové aplikace ukazuje nastavení živých metrik:

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

// Create a TelemetryConfiguration instance.
TelemetryConfiguration config = TelemetryConfiguration.CreateDefault();
config.InstrumentationKey = "INSTRUMENTATION-KEY-HERE";
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();
}

Předchozí ukázka je určená pro konzolovou aplikaci, ale stejný kód lze použít v libovolné aplikaci .NET. Pokud jsou povolené automatické protokolování telemetrických modulů, je důležité zajistit, aby se stejná konfigurace používaná k inicializaci těchto modulů používala pro modul živých metrik.

Protokoly ILoggeru

Výchozí konfigurace shromažďuje protokoly ILogger Warning a vážnější protokoly. Další informace najdete v tématu Návody přizpůsobení shromažďování protokolů ILogger?.

Závislosti

Kolekce závislostí je ve výchozím nastavení povolená. Sledování závislostí v Application Insights vysvětluje závislosti, které se automaticky shromažďují, a obsahuje také kroky pro ruční sledování.

Čítače výkonu

Podpora čítačů výkonu v ASP.NET Core je omezená:

Sada SDK verze 2.4.1 a novější shromažďuje čítače výkonu, pokud aplikace běží ve Službě Web Apps (Windows).
Sada SDK verze 2.7.1 a novější shromažďuje čítače výkonu, pokud aplikace běží ve Windows a cílech netstandard2.0 nebo novějších verzích.
U aplikací, které cílí na rozhraní .NET Framework, podporují všechny verze sady SDK čítače výkonu.
Sada SDK verze 2.8.0 a novější podporuje čítač procesoru a paměti v Linuxu. Linux nepodporuje žádný jiný čítač. K získání čítačů systému v linuxových a jiných prostředích mimo Windows použijte eventCounters.

EventCounter

Ve výchozím nastavení je EventCounterCollectionModule povoleno. Informace o konfiguraci seznamu čítačů, které se mají shromažďovat, najdete v úvodu ke službě EventCounters.

Obohacení dat prostřednictvím protokolu HTTP

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

Povolení telemetrie na straně klienta pro webové aplikace

Předchozí kroky vám pomůžou začít shromažďovat telemetrii na straně serveru. Pokud má vaše aplikace komponenty na straně klienta, podle dalších kroků začněte shromažďovat telemetrii využití pomocí injektáže skriptů zavaděče sady JavaScript (Web) SDK podle konfigurace.

Do _ViewImports.cshtml, přidat injektáž:

@inject Microsoft.ApplicationInsights.AspNetCore.JavaScriptSnippet JavaScriptSnippet

Vložte _Layout.cshtmlHtmlHelper na konec oddílu<head>, ale před jakýkoli jiný skript. Pokud chcete nahlásit vlastní telemetrii JavaScriptu ze stránky, zadejte ji za tento fragment kódu:
```
@Html.Raw(JavaScriptSnippet.FullScript)
</head>
```

Jako alternativu k použití FullScriptScriptBody je k dispozici počínaje sadou Application Insights SDK pro ASP.NET Core verze 2.14. Použijte ScriptBody , pokud potřebujete řídit <script> značku pro nastavení zásad zabezpečení obsahu:

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

Názvy .cshtml souborů, na které se odkazuje dříve, pocházejí z výchozí šablony aplikace MVC. Pokud chcete pro svou aplikaci správně povolit monitorování na straně klienta, musí se skript zavaděče javascriptové sady JavaScript (Web) SDK zobrazit v <head> části každé stránky aplikace, kterou chcete monitorovat. Přidejte skript zavaděče javascriptové sady JavaScript (Web) SDK do _Layout.cshtml šablony aplikace, aby se povolilo monitorování na straně klienta.

Pokud projekt neobsahuje _Layout.cshtml, můžete monitorování na straně klienta přidat přidáním javascriptového skriptu zavaděče sady JavaScript (Web) SDK do ekvivalentního souboru, který řídí <head> všechny stránky v aplikaci. Případně můžete přidat skript zavaděče javascriptové sady SDK na více stránek, ale nedoporučujeme ho.

Poznámka:

Injektáž JavaScriptu poskytuje výchozí prostředí konfigurace. Pokud vyžadujete konfiguraci nad rámec nastavení připojovací řetězec, musíte odebrat automatické injektáže, jak je popsáno, a ručně přidat javascriptovou sadu SDK.

Konfigurace sady Application Insights SDK

Sadu Application Insights SDK pro ASP.NET Core můžete přizpůsobit tak, aby se změnila výchozí konfigurace. Uživatelé sady Application Insights ASP.NET SDK můžou znát změnu konfigurace pomocí ApplicationInsights.config nebo úpravou TelemetryConfiguration.Active. V případě ASP.NET Core proveďte téměř všechny změny konfigurace v ConfigureServices() metodě třídy Startup.cs , pokud jste jinak nesměrováni. Další informace najdete v následujících částech.

Poznámka:

V aplikacích ASP.NET Core se změna konfigurace úpravou TelemetryConfiguration.Active nepodporuje.

Použití ApplicationInsightsServiceOptions

Můžete upravit několik běžných nastavení předáním ApplicationInsightsServiceOptions souboru AddApplicationInsightsTelemetry, jako v tomto příkladu:

ASP.NET Core 6 a novější
ASP.NET Core 5 a starší

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();

public void ConfigureServices(IServiceCollection services)
{
    Microsoft.ApplicationInsights.AspNetCore.Extensions.ApplicationInsightsServiceOptions aiOptions
                = new Microsoft.ApplicationInsights.AspNetCore.Extensions.ApplicationInsightsServiceOptions();
    // Disables adaptive sampling.
    aiOptions.EnableAdaptiveSampling = false;

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

Poznámka:

Tato verze .NET se už nepodporuje.

Tato tabulka obsahuje úplný seznam ApplicationInsightsServiceOptions nastavení:

Nastavení	Popis	Výchozí
EnablePerformanceCounterCollectionModule	Povolit nebo zakázat `PerformanceCounterCollectionModule`.	True
EnableRequestTrackingTelemetryModule	Povolit nebo zakázat `RequestTrackingTelemetryModule`.	True
EnableEventCounterCollectionModule	Povolit nebo zakázat `EventCounterCollectionModule`.	True
EnableDependencyTrackingTelemetryModule	Povolit nebo zakázat `DependencyTrackingTelemetryModule`.	True
EnableAppServicesHeartbeatTelemetryModule	Povolit nebo zakázat `AppServicesHeartbeatTelemetryModule`.	True
EnableAzureInstanceMetadataTelemetryModule	Povolit nebo zakázat `AzureInstanceMetadataTelemetryModule`.	True
EnableQuickPulseMetricStream	Povolení nebo zakázání funkce LiveMetrics	True
EnableAdaptiveSampling	Povolení nebo zakázání adaptivního vzorkování	True
EnableHeartbeat	Povolte nebo zakažte funkci prezenčních signálů. Pravidelně (15 min. výchozí) odesílá vlastní metriku s názvem `HeartbeatState` s informacemi o modulu runtime, jako je verze .NET a informace o prostředí Azure, pokud je to možné.	True
AddAutoCollectedMetricExtractor	Povolte nebo zakažte funkci `AutoCollectedMetrics extractor`. Tento procesor telemetrie odesílá předem agregované metriky o požadavcích a závislostech před vzorkováním.	True
RequestCollectionOptions.TrackExceptions	Povolte nebo zakažte generování sestav neošetřeného sledování výjimek modulem shromažďování požadavků.	Hodnota False in `netstandard2.0` (protože výjimky jsou sledovány pomocí `ApplicationInsightsLoggerProvider`). Jinak platí.
EnableDiagnosticsTelemetryModule	Povolit nebo zakázat `DiagnosticsTelemetryModule`. Zakázání způsobí ignorování následujících nastavení: `EnableHeartbeat`, `EnableAzureInstanceMetadataTelemetryModule`a `EnableAppServicesHeartbeatTelemetryModule`.	True

Nejnovější seznam najdete v konfigurovatelném nastavení v ApplicationInsightsServiceOptionssouboru .

Doporučení konfigurace pro Microsoft.ApplicationInsights.AspNetCore SDK 2.15.0 a novější

V sadě Microsoft.ApplicationInsights.AspNetCore SDK verze 2.15.0 a novější nakonfigurujte všechna nastavení, která jsou k dispozici, ApplicationInsightsServiceOptionsvčetně ConnectionString. Použijte instanci aplikace IConfiguration . Nastavení musí být pod částí ApplicationInsights, jak je znázorněno v následujícím příkladu. Následující část z appsettings.json nakonfiguruje připojovací řetězec a zakáže adaptivní vzorkování a shromažďování čítačů výkonu.

{
    "ApplicationInsights": {
    "ConnectionString": "Copy connection string from Application Insights Resource Overview",
    "EnableAdaptiveSampling": false,
    "EnablePerformanceCounterCollectionModule": false
    }
}

Pokud builder.Services.AddApplicationInsightsTelemetry(aiOptions) se používá ASP.NET Core 6.0 nebo services.AddApplicationInsightsTelemetry(aiOptions) pro ASP.NET Core 3.1 a starší, přepíše nastavení z Microsoft.Extensions.Configuration.IConfiguration.

Vzorkování

Sada Application Insights SDK pro ASP.NET Core podporuje pevné i adaptivní vzorkování. Ve výchozím nastavení je povolené adaptivní vzorkování.

Další informace najdete v tématu Konfigurace adaptivního vzorkování pro aplikace ASP.NET Core.

Přidání telemetrických inicializátorů

Pokud chcete rozšířit telemetrii o další informace, použijte inicializátory telemetrie.

Přidejte do kontejneru DependencyInjection všechny nové, TelemetryInitializer jak je znázorněno v následujícím kódu. Sada SDK automaticky vybere všechny TelemetryInitializer přidané do kontejneru DependencyInjection .

ASP.NET Core 6 a novější
ASP.NET Core 5 a starší

var builder = WebApplication.CreateBuilder(args);

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

var app = builder.Build();

Poznámka:

builder.Services.AddSingleton<ITelemetryInitializer, MyCustomTelemetryInitializer>(); funguje pro jednoduché inicializátory. Pro ostatní se builder.Services.AddSingleton(new MyCustomTelemetryInitializer() { fieldName = "myfieldName" }); vyžaduje.

public void ConfigureServices(IServiceCollection services)
{
    services.AddSingleton<ITelemetryInitializer, MyCustomTelemetryInitializer>();
}

Poznámka:

services.AddSingleton<ITelemetryInitializer, MyCustomTelemetryInitializer>(); funguje pro jednoduché inicializátory. Pro ostatní se services.AddSingleton(new MyCustomTelemetryInitializer() { fieldName = "myfieldName" }); vyžaduje. Tato verze .NET se už nepodporuje.

Odebrání telemetrických inicializátorů

Ve výchozím nastavení jsou k dispozici inicializátory telemetrie. Chcete-li odebrat všechny nebo konkrétní inicializátory telemetrie, použijte následující ukázkový kód po volání AddApplicationInsightsTelemetry().

ASP.NET Core 6 a novější
ASP.NET Core 5 a starší

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();

public void ConfigureServices(IServiceCollection services)
{
    services.AddApplicationInsightsTelemetry();

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

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

Poznámka:

Tato verze .NET se už nepodporuje.

Přidání procesorů telemetrie

Vlastní procesory telemetrie můžete přidat TelemetryConfiguration pomocí metody AddApplicationInsightsTelemetryProcessor rozšíření na .IServiceCollection Procesory telemetrie se používají v pokročilých scénářích filtrování. Použijte následující příklad:

ASP.NET Core 6 a novější
ASP.NET Core 5 a starší

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();

public void ConfigureServices(IServiceCollection services)
{
    // ...
    services.AddApplicationInsightsTelemetry();
    services.AddApplicationInsightsTelemetryProcessor<MyFirstCustomTelemetryProcessor>();

    // If you have more processors:
    services.AddApplicationInsightsTelemetryProcessor<MySecondCustomTelemetryProcessor>();
}

Poznámka:

Tato verze .NET se už nepodporuje.

Konfigurace nebo odebrání výchozího telemetrieModules

Application Insights automaticky shromažďuje telemetrii o konkrétních úlohách bez nutnosti ručního sledování uživatelem.

Ve výchozím nastavení jsou povoleny následující moduly automatické kolekce. Tyto moduly zodpovídají za automatické shromažďování telemetrie. Můžete je zakázat nebo nakonfigurovat tak, aby měnily výchozí chování.

RequestTrackingTelemetryModule: Shromažďuje RequestTelemetry z příchozích webových požadavků.
DependencyTrackingTelemetryModule: Shromažďuje DependencyTelemetry z odchozích volání HTTP a volání SQL.
PerformanceCollectorModule: Shromažďuje nástroje Windows PerformanceCounters.
QuickPulseTelemetryModule: Shromažďuje telemetrii, která se má zobrazit v podokně živých metrik.
AppServicesHeartbeatTelemetryModule: Shromažďuje prezenční signály (které se odesílají jako vlastní metriky), o prostředí App Service, kde je aplikace hostovaná.
AzureInstanceMetadataTelemetryModule: Shromažďuje prezenční signály (které se odesílají jako vlastní metriky), o prostředí virtuálního počítače Azure, kde je aplikace hostovaná.
EventCounterCollectionModule: Shromažďuje třídy EventCounters. Tento modul je nová funkce a je k dispozici v sadě SDK verze 2.8.0 a novější.

Pokud chcete nakonfigurovat jakékoli výchozí TelemetryModulenastavení, použijte metodu ConfigureTelemetryModule<T> rozšíření zapnutou IServiceCollection, jak je znázorněno v následujícím příkladu:

ASP.NET Core 6 a novější
ASP.NET Core 5 a starší

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();

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

public void ConfigureServices(IServiceCollection services)
{
    services.AddApplicationInsightsTelemetry();

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

    // The following removes all default counters from EventCounterCollectionModule, and adds a single one.
    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 = services.FirstOrDefault<ServiceDescriptor>(t => t.ImplementationType == typeof(PerformanceCollectorModule));
    if (performanceCounterService != null)
    {
        services.Remove(performanceCounterService);
    }
}

Poznámka:

Tato verze .NET se už nepodporuje.

Ve verzích 2.12.2 a novějších ApplicationInsightsServiceOptions obsahuje jednoduchou možnost zakázat některý z výchozích modulů.

Konfigurace kanálu telemetrie

Výchozí kanál telemetrie je ServerTelemetryChannel. Následující příklad ukazuje, jak ji přepsat.

ASP.NET Core 6 a novější
ASP.NET Core 5 a starší

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();

using Microsoft.ApplicationInsights.Channel;

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

    services.AddApplicationInsightsTelemetry();
}

Poznámka:

Tato verze .NET se už nepodporuje.

Poznámka:

Pokud chcete vyrovnávací paměť vyprázdnit, přečtěte si téma Vyprazdňování dat. Pokud například používáte sadu SDK v aplikaci, která se vypne, možná budete muset vyrovnávací paměť vyprázdnit.

Dynamické zakázání telemetrie

Pokud chcete telemetrii podmíněně a dynamicky zakázat, můžete instanci přeložit TelemetryConfiguration pomocí kontejneru injektáže závislostí jádra ASP.NET kdekoli v kódu a nastavit DisableTelemetry příznak.

ASP.NET Core 6 a novější
ASP.NET Core 5 a starší

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();

public void ConfigureServices(IServiceCollection services)
{
    services.AddApplicationInsightsTelemetry();
}

public void Configure(IApplicationBuilder app, IHostingEnvironment env, TelemetryConfiguration configuration)
{
    configuration.DisableTelemetry = true;
    ...
}

Poznámka:

Tato verze .NET se už nepodporuje.

Předchozí ukázka kódu brání odesílání telemetrie do Application Insights. Nezabrání shromažďování telemetrických dat žádnými moduly automatické kolekce. Pokud chcete odebrat konkrétní modul autocollection, přečtěte si téma Odebrání modulu telemetrie.

Nejčastější dotazy

Tato část obsahuje odpovědi na běžné otázky.

Podporuje Application Insights ASP.NET Core 3.1?

ASP.NET Core 3.1 už Microsoft nepodporuje.

Sadu Application Insights SDK pro ASP.NET Core verze 2.8.0 a Visual Studio 2019 nebo novější je možné použít s aplikacemi ASP.NET Core 3.1.

Jak můžu sledovat telemetrii, která se neshromažďuje automaticky?

Získejte instanci TelemetryClient pomocí injektáže konstruktoru a zavolejte na ni požadovanou TrackXXX() metodu. V aplikaci ASP.NET Core nedoporučujeme vytvářet nové TelemetryClient instance ani TelemetryConfiguration instance. V kontejneru DependencyInjection je již zaregistrovaná jedna instanceTelemetryClient, která sdílí TelemetryConfiguration zbytek telemetrie. Vytvořte novou TelemetryClient instanci jenom v případě, že potřebuje konfiguraci, která je oddělená od zbytku telemetrie.

Následující příklad ukazuje, jak sledovat další telemetrii z kontroleru.

using Microsoft.ApplicationInsights;

public class HomeController : Controller
{
    private TelemetryClient telemetry;

    // Use constructor injection to get a TelemetryClient instance.
    public HomeController(TelemetryClient telemetry)
    {
        this.telemetry = telemetry;
    }

    public IActionResult Index()
    {
        // Call the required TrackXXX method.
        this.telemetry.TrackEvent("HomePageRequested");
        return View();
    }

Další informace o vytváření vlastních sestav dat v Application Insights najdete v referenčních informacích k rozhraní API pro vlastní metriky Application Insights. Podobný přístup se dá použít k odesílání vlastních metrik do Application Insights pomocí rozhraní GetMetric API.

Návody zachytávání textu požadavku a odpovědi v telemetrii?

ASP.NET Core má integrovanou podporu protokolování informací o požadavku a odpovědi HTTP (včetně textu) prostřednictvím ILogger. Doporučujeme ho využít. To může potenciálně vystavit identifikovatelné osobní údaje (PII) v telemetrii a může způsobit výrazné zvýšení nákladů (náklady na výkon a fakturace Application Insights), proto před použitím rizika pečlivě vyhodnoťte.

Návody přizpůsobit shromažďování protokolů ILogger?

Výchozím nastavením application Insights je zachytit pouze upozornění a vážnější protokoly.

Zachyťte informace a méně závažné protokoly změnou konfigurace protokolování pro zprostředkovatele Application Insights následujícím způsobem.

{
  "Logging": {
    "LogLevel": {
      "Default": "Information"
    },
    "ApplicationInsights": {
      "LogLevel": {
        "Default": "Information"
      }
    }
  },
  "ApplicationInsights": {
    "ConnectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000"
  }
}

Je důležité si uvědomit, že následující příklad nezpůsobí, že poskytovatel Application Insights zachytává Information protokoly. Nezachytí ho, protože sada SDK přidá výchozí filtr protokolování, který dává pokyn ApplicationInsights k zachycení pouze Warning protokolů a složitějších protokolů. Application Insights vyžaduje explicitní přepsání.

{
  "Logging": {
    "LogLevel": {
      "Default": "Information"
    }
  }
}

Další informace najdete v tématu Konfigurace ILoggeru.

Některé šablony sady Visual Studio používaly metodu rozšíření UseApplicationInsights() na IWebHostBuilder k povolení Application Insights. Je toto využití stále platné?

Metoda UseApplicationInsights() rozšíření je stále podporovaná, ale je označená jako zastaralá v sadě Application Insights SDK verze 2.8.0 a novější. Odebere se v další hlavní verzi sady SDK. Pokud chcete povolit telemetrii Application Insights, použijte AddApplicationInsightsTelemetry() ji, protože poskytuje přetížení pro řízení určité konfigurace. V aplikacích ASP.NET Core 3.X je také jediný způsob, services.AddApplicationInsightsTelemetry() jak povolit Application Insights.

Nasazujem svoji aplikaci ASP.NET Core do Služby Web Apps. Mám stále povolit rozšíření Application Insights z Web Apps?

Pokud je sada SDK nainstalovaná v době sestavení, jak je znázorněno v tomto článku, nemusíte rozšíření Application Insights povolit na portálu App Service. Pokud je rozšíření nainstalované, po zjištění, že už je sada SDK přidaná, se vypne. Pokud povolíte Application Insights z rozšíření, nemusíte sadu SDK instalovat a aktualizovat. Pokud ale povolíte Application Insights podle pokynů v tomto článku, máte větší flexibilitu, protože:

Telemetrie Application Insights nadále funguje:
- Všechny operační systémy, včetně Windows, Linuxu a Macu.
- Všechny režimy publikování, včetně samostatných nebo závislých architektur.
- Všechny cílové architektury, včetně úplného rozhraní .NET Framework.
- Všechny možnosti hostování, včetně Webových aplikací, virtuálních počítačů, Linuxu, kontejnerů, AKS a hostování mimo Azure.
- Všechny verze .NET Core, včetně verzí Preview.
Telemetrii můžete zobrazit místně při ladění ze sady Visual Studio.
Pomocí rozhraní API můžete sledovat další vlastní telemetrii TrackXXX() .
Máte plnou kontrolu nad konfigurací.

Můžu povolit monitorování Application Insights pomocí nástrojů, jako je agent Application Insights služby Azure Monitor (dříve Monitorování stavu v2)?

Ano. V agentu Application Insights 2.0.0-beta1 a novějších se podporují aplikace ASP.NET Core hostované ve službě IIS.

Jsou všechny funkce podporované, když spustím aplikaci v Linuxu?

Ano. Podpora funkcí sady SDK je stejná na všech platformách s následujícími výjimkami:

Sada SDK shromažďuje čítače událostí v Linuxu, protože čítače výkonu jsou podporovány pouze ve Windows. Většina metrik je stejná.

Je tato sada SDK podporovaná pro pracovní služby?

Ne. Pro pracovní služby použijte Application Insights pro aplikace pracovních služeb (aplikace jiné než HTTP).

Jak můžu odinstalovat sadu SDK?

Pokud chcete odebrat Application Insights, musíte odebrat balíčky NuGet a odkazy z rozhraní API ve vaší aplikaci. Balíčky NuGet můžete odinstalovat pomocí Správce balíčků NuGet v sadě Visual Studio.

Poznámka:

Tyto pokyny slouží k odinstalaci sady ASP.NET Core SDK. Pokud potřebujete odinstalovat sadu ASP.NET SDK, přečtěte si, jak můžu odinstalovat sadu ASP.NET SDK?.

Odinstalujte balíček Microsoft.ApplicationInsights.AspNetCore pomocí Správce balíčků NuGet.
Pokud chcete úplně odebrat Application Insights, zkontrolujte a ručně odstraňte přidaný kód nebo soubory spolu s libovolnými voláními rozhraní API, která jste přidali do projektu. Další informace najdete v tématu Co se vytvoří při přidání sady Application Insights SDK?.

Co se vytvoří při přidání sady Application Insights SDK?

Když do projektu přidáte Application Insights, vytvoří soubory a přidá do některých souborů kód. Pouze odinstalace balíčků NuGet nebude vždy zahodit soubory a kód. Pokud chcete úplně odebrat Application Insights, měli byste zkontrolovat a ručně odstranit přidaný kód nebo soubory spolu s případnými voláními rozhraní API, která jste přidali do projektu.

Když do projektu šablony Visual Studio ASP.NET Core přidáte telemetrii Application Insights, přidá následující kód:

[Název projektu].csproj

  <PropertyGroup>
    <TargetFramework>netcoreapp3.1</TargetFramework>
    <ApplicationInsightsResourceId>/subscriptions/00000000-0000-0000-0000-000000000000/resourcegroups/Default-ApplicationInsights-EastUS/providers/microsoft.insights/components/WebApplication4core</ApplicationInsightsResourceId>
  </PropertyGroup>

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

  <ItemGroup>
    <WCFMetadata Include="Connected Services" />
  </ItemGroup>

Appsettings.json:

"ApplicationInsights": {
    "InstrumentationKey": "00000000-0000-0000-0000-000000000000"

ConnectedService.json

{
  "ProviderId": "Microsoft.ApplicationInsights.ConnectedService.ConnectedServiceProvider",
  "Version": "16.0.0.0",
  "GettingStartedDocument": {
    "Uri": "https://go.microsoft.com/fwlink/?LinkID=798432"
  }
}

Startup.cs

   public void ConfigureServices(IServiceCollection services)
        {
            services.AddRazorPages();
            services.AddApplicationInsightsTelemetry(); // This is added
        }

Jak můžu zakázat korelaci telemetrie?

Pokud chcete zakázat korelaci telemetrie v kódu, přečtěte si <ExcludeComponentCorrelationHttpHeadersOnDomains> informace v Application Insights pro konzolové aplikace.

Řešení problému

Projděte si vyhrazený článek o řešení potíží.

Testování připojení mezi hostitelem vaší aplikace a službou příjmu dat

Sady Application Insights SDK a agenti odesílají telemetrii, aby se ingestovala jako volání REST do koncových bodů příjmu dat. Připojení z webového serveru nebo hostitelského počítače aplikace ke koncovým bodům služby pro příjem dat můžete otestovat pomocí nezpracovaných klientů REST z příkazů PowerShellu nebo curl. Viz Řešení potíží s chybějící telemetrií aplikací ve službě Azure Monitor Application Insights.

Opensourcová sada SDK

Čtení kódu a přispívání do kódu

Nejnovější aktualizace a opravy chyb najdete v poznámkách k verzi.

Poznámky k verzi

Pro verze 2.12 a novější: sady .NET SDK (včetně ASP.NET, ASP.NET core a adaptérů protokolování)

Naše aktualizace služeb také shrnují hlavní vylepšení Application Insights.

Další kroky

Prozkoumejte toky uživatelů, abyste pochopili, jak uživatelé procházejí vaší aplikací.
Nakonfigurujte kolekci snímků, aby se v okamžiku vyvolání výjimky zobrazil stav zdrojového kódu a proměnných.
Pomocí rozhraní API můžete odesílat vlastní události a metriky pro podrobné zobrazení výkonu a využití vaší aplikace.
Pomocí testů dostupnosti můžete aplikaci zkontrolovat nepřetržitě z celého světa.
Přečtěte si o injektáži závislostí v ASP.NET Core.

Sdílet prostřednictvím

Application Insights pro aplikace ASP.NET Core

Podporované scénáře

Požadavky

Povolení telemetrie na straně serveru Application Insights (Visual Studio)

Povolení telemetrie na straně serveru Application Insights (bez sady Visual Studio)

Tajné kódy uživatelů a další poskytovatelé konfigurace

Spusťte aplikaci

Živé metriky

Povolení živých metrik pomocí kódu pro libovolnou aplikaci .NET

Protokoly ILoggeru

Závislosti

Čítače výkonu

EventCounter

Obohacení dat prostřednictvím protokolu HTTP

Povolení telemetrie na straně klienta pro webové aplikace

Konfigurace sady Application Insights SDK

Použití ApplicationInsightsServiceOptions

Doporučení konfigurace pro Microsoft.ApplicationInsights.AspNetCore SDK 2.15.0 a novější

Vzorkování

Přidání telemetrických inicializátorů

Odebrání telemetrických inicializátorů

Přidání procesorů telemetrie

Konfigurace nebo odebrání výchozího telemetrieModules

Konfigurace kanálu telemetrie

Dynamické zakázání telemetrie

Nejčastější dotazy

Podporuje Application Insights ASP.NET Core 3.1?

Jak můžu sledovat telemetrii, která se neshromažďuje automaticky?

Návody zachytávání textu požadavku a odpovědi v telemetrii?

Návody přizpůsobit shromažďování protokolů ILogger?

Některé šablony sady Visual Studio používaly metodu rozšíření UseApplicationInsights() na IWebHostBuilder k povolení Application Insights. Je toto využití stále platné?

Nasazujem svoji aplikaci ASP.NET Core do Služby Web Apps. Mám stále povolit rozšíření Application Insights z Web Apps?

Můžu povolit monitorování Application Insights pomocí nástrojů, jako je agent Application Insights služby Azure Monitor (dříve Monitorování stavu v2)?

Jsou všechny funkce podporované, když spustím aplikaci v Linuxu?

Je tato sada SDK podporovaná pro pracovní služby?

Jak můžu odinstalovat sadu SDK?

Co se vytvoří při přidání sady Application Insights SDK?

Jak můžu zakázat korelaci telemetrie?

Řešení problému

Testování připojení mezi hostitelem vaší aplikace a službou příjmu dat

Opensourcová sada SDK

Poznámky k verzi

Další kroky

Váš názor

Další materiály