Application Insights pro ASP.NET Core aplikaceApplication Insights for ASP.NET Core applications

Tento článek popisuje, jak povolit Application Insights pro ASP.NET Core aplikaci.This article describes how to enable Application Insights for an ASP.NET Core application. Po dokončení pokynů v tomto článku bude Application Insights shromažďovat požadavky, závislosti, výjimky, čítače výkonu, prezenční signály a protokoly z vaší aplikace ASP.NET Core.When you complete the instructions in this article, Application Insights will collect requests, dependencies, exceptions, performance counters, heartbeats, and logs from your ASP.NET Core application.

Příklad, který budeme používat, je aplikace MVC , která se zaměřuje na netcoreapp3.0 .The example we'll use here is an MVC application that targets netcoreapp3.0. Tyto pokyny můžete použít pro všechny ASP.NET Core aplikace.You can apply these instructions to all ASP.NET Core applications. Pokud používáte službu pracovního procesu, postupujte podle pokynů zde.If you are using the Worker Service, use the instructions from here.

Podporované scénářeSupported scenarios

Sada Application Insights SDK pro ASP.NET Core může monitorovat aplikace bez ohledu na to, kde nebo jak jsou spuštěny.The Application Insights SDK for ASP.NET Core can monitor your applications no matter where or how they run. Pokud vaše aplikace běží a má síťové připojení k Azure, je možné shromažďovat telemetrii.If your application is running and has network connectivity to Azure, telemetry can be collected. Monitorování Application Insights je podporováno všude, kde je podporováno rozhraní .NET Core.Application Insights monitoring is supported everywhere .NET Core is supported. Podpora zahrnuje:Support covers:

  • Operační systém: Windows, Linux nebo Mac.Operating system: Windows, Linux, or Mac.
  • Metoda hostování: v procesu nebo mimo proces.Hosting method: In process or out of process.
  • Metoda nasazení: závislá na architektuře nebo samostatně obsažená.Deployment method: Framework dependent or self-contained.
  • Webový server: IIS (Internet Information Server) nebo Kestrel.Web server: IIS (Internet Information Server) or Kestrel.
  • Hostující platforma: funkce Web Apps Azure App Service, virtuální počítač Azure, Docker, Azure Kubernetes Service (AKS) a tak dále.Hosting platform: The Web Apps feature of Azure App Service, Azure VM, Docker, Azure Kubernetes Service (AKS), and so on.
  • Verze modulu runtime .NET Core: 1. xx, 2. xx nebo 3. xx.NET Core Runtime version: 1.XX, 2.XX, or 3.XX
  • IDE: Visual Studio, vs Code nebo příkazový řádek.IDE: Visual Studio, VS Code, or command line.

Poznámka

ASP.NET Core 3. X vyžaduje Application Insights 2.8.0 nebo novější.ASP.NET Core 3.X requires Application Insights 2.8.0 or later.

PředpokladyPrerequisites

  • Funkční aplikace ASP.NET Core.A functioning ASP.NET Core application. Pokud potřebujete vytvořit aplikaci ASP.NET Core, postupujte podle tohoto ASP.NET Core kurzu.If you need to create an ASP.NET Core application, follow this ASP.NET Core tutorial.
  • Platný klíč instrumentace Application Insights.A valid Application Insights instrumentation key. Tento klíč je nutný k odeslání jakékoli telemetrie do Application Insights.This key is required to send any telemetry to Application Insights. Pokud potřebujete vytvořit nový prostředek Application Insights, abyste získali klíč instrumentace, přečtěte si téma vytvoření prostředku Application Insights.If you need to create a new Application Insights resource to get an instrumentation key, see Create an Application Insights resource.

Povolit Application Insights telemetrie na straně serveru (Visual Studio)Enable Application Insights server-side telemetry (Visual Studio)

  1. Otevřete svůj projekt v sadě Visual Studio.Open your project in Visual Studio.

    Tip

    Pokud chcete, můžete pro svůj projekt nastavit správu zdrojového kódu, abyste mohli sledovat všechny změny, které Application Insights provede.If you want to, you can set up source control for your project so you can track all the changes that Application Insights makes. Chcete-li povolit správu zdrojového kódu, vyberte soubor > Přidat do správy zdrojového kódu.To enable source control, select File > Add to Source Control.

  2. Vyberte projekt > Přidat telemetrie Application Insights.Select Project > Add Application Insights Telemetry.

  3. Vyberte Začínáme.Select Get Started. Text tohoto výběru se může lišit v závislosti na vaší verzi sady Visual Studio.This selection's text might vary, depending on your version of Visual Studio. Některé starší verze používají místo toho tlačítko Spustit zdarma .Some earlier versions use a Start Free button instead.

  4. Vyberte předplatné.Select your subscription. Pak vyberte Resourcepoložku > registrprostředků.Then select Resource > Register.

  5. Po přidání Application Insights do projektu ověřte, že používáte nejnovější stabilní verzi sady SDK.After adding Application Insights to your project, check to confirm that you're using the latest stable release of the SDK. Přejít na projekt > Správa balíčků NuGet > Microsoft. ApplicationInsights. AspNetCoreGo to Project > Manage NuGet Packages > Microsoft.ApplicationInsights.AspNetCore. Pokud potřebujete, klikněte na tlačítko aktualizovat.If you need to, choose Update.

    Snímek obrazovky s informacemi o tom, kde vybrat balíček Application Insights pro aktualizaci

  6. Pokud jste postupovali podle volitelného tipu a Přidali jste projekt do správy zdrojových kódů, přejdete na Zobrazit > Team Explorer > změny.If you followed the optional tip and added your project to source control, go to View > Team Explorer > Changes. Pak vyberte jednotlivé soubory, abyste viděli rozdílové zobrazení změn provedených v telemetrie Application Insights.Then select each file to see a diff view of the changes made by Application Insights telemetry.

Povolit Application Insights telemetrie na straně serveru (bez sady Visual Studio)Enable Application Insights server-side telemetry (no Visual Studio)

  1. Nainstalujte balíček NuGet sady Application Insights SDK pro ASP.NET Core.Install the Application Insights SDK NuGet package for ASP.NET Core. Doporučujeme vždy používat nejnovější stabilní verzi.We recommend that you always use the latest stable version. Vyhledejte úplné poznámky k verzi pro sadu SDK na Open Source úložišti GitHub.Find full release notes for the SDK on the open-source GitHub repo.

    Následující ukázka kódu ukazuje změny, které mají být přidány do .csproj souboru projektu.The following code sample shows the changes to be added to your project's .csproj file.

        <ItemGroup>
          <PackageReference Include="Microsoft.ApplicationInsights.AspNetCore" Version="2.13.1" />
        </ItemGroup>
    
  2. Přidejte services.AddApplicationInsightsTelemetry(); do ConfigureServices() metody ve Startup třídě, jako v tomto příkladu:Add services.AddApplicationInsightsTelemetry(); to the ConfigureServices() method in your Startup class, as in this example:

        // 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();
        }
    
  3. Nastavte klíč instrumentace.Set up the instrumentation key.

    I když můžete zadat klíč instrumentace jako argument pro, doporučujeme AddApplicationInsightsTelemetry zadat klíč instrumentace v konfiguraci.Although you can provide the instrumentation key as an argument to AddApplicationInsightsTelemetry, we recommend that you specify the instrumentation key in configuration. Následující ukázka kódu ukazuje, jak zadat klíč instrumentace v appsettings.json .The following code sample shows how to specify an instrumentation key in appsettings.json. Ujistěte se, že appsettings.json se během publikování kopíruje do kořenové složky aplikace.Make sure appsettings.json is copied to the application root folder during publishing.

        {
          "ApplicationInsights": {
            "InstrumentationKey": "putinstrumentationkeyhere"
          },
          "Logging": {
            "LogLevel": {
              "Default": "Warning"
            }
          }
        }
    

    Případně můžete zadat klíč instrumentace v některé z následujících proměnných prostředí:Alternatively, specify the instrumentation key in either of the following environment variables:

    • APPINSIGHTS_INSTRUMENTATIONKEY

    • ApplicationInsights:InstrumentationKey

    Příklad:For example:

    • SET ApplicationInsights:InstrumentationKey=putinstrumentationkeyhere

    • SET APPINSIGHTS_INSTRUMENTATIONKEY=putinstrumentationkeyhere

    • APPINSIGHTS_INSTRUMENTATIONKEYse obvykle používá v Azure Web Apps, ale dá se použít i na všech místech, kde je tato sada SDK podporovaná.APPINSIGHTS_INSTRUMENTATIONKEY is typically used in Azure Web Apps, but can also be used in all places where this SDK is supported. (Pokud provádíte monitorování webové aplikace bez kódu, je tento formát vyžadován, pokud nepoužíváte připojovací řetězce.)(If you are doing codeless web app monitoring, this format is required if you aren't using connection strings.)

    Místo nastavování klíčů instrumentace teď můžete také použít připojovací řetězce.In lieu of setting instrumentation keys you can now also use Connection Strings.

    Poznámka

    Klíč instrumentace zadaný v kódu služby WINS přes proměnnou prostředí APPINSIGHTS_INSTRUMENTATIONKEY , která je službou WINS nad jinými možnostmi.An instrumentation key specified in code wins over the environment variable APPINSIGHTS_INSTRUMENTATIONKEY, which wins over other options.

Spusťte aplikaciRun your application

Spusťte aplikaci a proveďte na ni požadavky.Run your application and make requests to it. Telemetrii by teď měla přesměrovat do Application Insights.Telemetry should now flow to Application Insights. Sada Application Insights SDK automaticky shromažďuje příchozí webové požadavky do vaší aplikace spolu s následující telemetrii.The Application Insights SDK automatically collects incoming web requests to your application, along with the following telemetry as well.

Live MetricsLive Metrics

Živé metriky lze použít k rychlému ověření, zda je monitorování Application Insights správně nakonfigurováno.Live Metrics can be used to quickly verify if Application Insights monitoring is configured correctly. I když může trvat několik minut, než se telemetrie spustí na portálu a v analýze, zobrazí se v reálném čase využití CPU běžícího procesu téměř v reálném čase.While it might take a few minutes before telemetry starts appearing in the portal and analytics, Live Metrics would show CPU usage of the running process in near real-time. Může také zobrazit další telemetrie, jako jsou požadavky, závislosti, trasování atd.It can also show other telemetry like Requests, Dependencies, Traces, etc.

Protokoly ILoggerILogger logs

Protokoly emitované pomocí ILogger závažnosti Warning nebo většího jsou zachyceny automaticky.Logs emitted via ILogger of severity Warning or greater are automatically captured. Dodržujte ILogger docs k přizpůsobení, které úrovně protokolu jsou zachyceny Application Insights.Follow ILogger docs to customize which log levels are captured by Application Insights.

ZávislostiDependencies

Kolekce závislostí je ve výchozím nastavení povolená.Dependency collection is enabled by default. Tento článek vysvětluje závislosti, které jsou shromažďovány automaticky, a obsahuje také Postup ručního sledování.This article explains the dependencies that are automatically collected, and also contain steps to do manual tracking.

Čítače výkonuPerformance counters

Podpora čítačů výkonu v ASP.NET Core je omezená:Support for performance counters in ASP.NET Core is limited:

  • Sady SDK verze 2.4.1 a novější shromažďují čítače výkonu, pokud aplikace běží v Azure Web Apps (Windows).SDK versions 2.4.1 and later collect performance counters if the application is running in Azure Web Apps (Windows).
  • Verze sady SDK 2.7.1 a novější shromažďují čítače výkonu, pokud je aplikace spuštěná ve Windows a cílících NETSTANDARD2.0 nebo novějších.SDK versions 2.7.1 and later collect performance counters if the application is running in Windows and targets NETSTANDARD2.0 or later.
  • Pro aplikace cílené na .NET Framework všechny verze sady SDK podporují čítače výkonu.For applications targeting the .NET Framework, all versions of the SDK support performance counters.
  • Verze sady SDK 2.8.0 a novější podporují čítač procesorů a paměti v systému Linux.SDK Versions 2.8.0 and later support cpu/memory counter in Linux. V systému Linux není podporován žádný jiný čítač.No other counter is supported in Linux. Doporučený způsob, jak získat systémové čítače v systémech Linux (a dalších prostředích mimo Windows), je použití EventCountersThe recommended way to get system counters in Linux (and other non-Windows environments) is by using EventCounters

EventCounterEventCounter

EventCounterCollectionModuleje ve výchozím nastavení povolená a bude shromažďovat výchozí sadu čítačů z aplikací .NET Core 3. X.EventCounterCollectionModule is enabled by default, and it will collect a default set of counters from .NET Core 3.X apps. Kurz EventCounter obsahuje seznam výchozích sad čítačů, které jsou shromažďovány.The EventCounter tutorial lists the default set of counters collected. Obsahuje také pokyny k přizpůsobení seznamu.It also has instructions on customizing the list.

Povolení telemetrie na straně klienta pro webové aplikaceEnable client-side telemetry for web applications

Předchozí kroky jsou dostatečné, aby vám pomohly začít shromažďovat telemetrie na straně serveru.The preceding steps are enough to help you start collecting server-side telemetry. Pokud má aplikace komponenty na straně klienta, spusťte následující postup a zahajte shromažďování telemetrie využití.If your application has client-side components, follow the next steps to start collecting usage telemetry.

  1. Do _ViewImports.cshtml přidejte injektáže:In _ViewImports.cshtml, add injection:

        @inject Microsoft.ApplicationInsights.AspNetCore.JavaScriptSnippet JavaScriptSnippet
    
  2. V nástroji _Layout.cshtml vložte HtmlHelper na konec <head> oddílu, ale před jakýkoli jiný skript.In _Layout.cshtml, insert HtmlHelper at the end of the <head> section but before any other script. Pokud chcete vykázat jakékoli vlastní telemetrie JavaScriptu ze stránky, zastavte ji za tento fragment kódu:If you want to report any custom JavaScript telemetry from the page, inject it after this snippet:

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

Alternativně můžete použít FullScript sadu, která ScriptBody je k dispozici od verze sady SDK v 2.14.Alternatively to using the FullScript the ScriptBody is available starting in SDK v2.14. Tento postup použijte v případě, že potřebujete řídit <script> značku pro nastavení zásad zabezpečení obsahu:Use this if you need to control the <script> tag to set a Content Security Policy:

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

Názvy souborů, na které se .cshtml odkazuje dříve, jsou z výchozí šablony aplikace MVC.The .cshtml file names referenced earlier are from a default MVC application template. V konečném případě, pokud chcete pro vaši aplikaci správně povolit monitorování na straně klienta, musí být fragment kódu JavaScriptu uveden v <head> části každé stránky aplikace, kterou chcete monitorovat.Ultimately, if you want to properly enable client-side monitoring for your application, the JavaScript snippet must appear in the <head> section of each page of your application that you want to monitor. Tento cíl můžete pro tuto šablonu aplikace dosáhnout přidáním fragmentu JavaScriptu do _Layout.cshtml .You can accomplish this goal for this application template by adding the JavaScript snippet to _Layout.cshtml.

Pokud váš projekt nezahrnuje _Layout.cshtml , můžete přesto přidat monitorování na straně klienta.If your project doesn't include _Layout.cshtml, you can still add client-side monitoring. To můžete provést tak, že přidáte fragment kódu jazyka JavaScript do ekvivalentního souboru, který ovládá <head> všechny stránky v aplikaci.You can do this by adding the JavaScript snippet to an equivalent file that controls the <head> of all pages within your app. Nebo můžete fragment přidat na více stránek, ale toto řešení je obtížné udržovat a obecně nedoporučujeme.Or you can add the snippet to multiple pages, but this solution is difficult to maintain and we generally don't recommend it.

Konfigurace sady Application Insights SDKConfigure the Application Insights SDK

Můžete přizpůsobit sadu Application Insights SDK, aby ASP.NET Core změnila výchozí konfiguraci.You can customize the Application Insights SDK for ASP.NET Core to change the default configuration. Uživatelé sady Application Insights ASP.NET SDK mohou být obeznámeni se změnou konfigurace pomocí nástroje ApplicationInsights.config nebo úpravou TelemetryConfiguration.Active .Users of the Application Insights ASP.NET SDK might be familiar with changing configuration by using ApplicationInsights.config or by modifying TelemetryConfiguration.Active. Konfiguraci můžete změnit odlišně pro ASP.NET Core.You change configuration differently for ASP.NET Core. Přidejte sadu ASP.NET Core SDK do aplikace a nakonfigurujte ji pomocí vkládání integrovaných závislostíASP.NET Core.Add the ASP.NET Core SDK to the application and configure it by using ASP.NET Core built-in dependency injection. Udělejte téměř všechny změny konfigurace v ConfigureServices() metodě vaší Startup.cs třídy, pokud nebudete přesměrováni jinak.Make almost all configuration changes in the ConfigureServices() method of your Startup.cs class, unless you're directed otherwise. Následující části obsahují další informace.The following sections offer more information.

Poznámka

V ASP.NET Corech aplikacích se změna konfigurace podle úpravy TelemetryConfiguration.Active nepodporuje.In ASP.NET Core applications, changing configuration by modifying TelemetryConfiguration.Active isn't supported.

Použití ApplicationInsightsServiceOptionsUsing ApplicationInsightsServiceOptions

Můžete upravit několik běžných nastavení tak, že předáte ApplicationInsightsServiceOptions do AddApplicationInsightsTelemetry , jako v tomto příkladu:You can modify a few common settings by passing ApplicationInsightsServiceOptions to AddApplicationInsightsTelemetry, as in this example:

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

    // Disables QuickPulse (Live Metrics stream).
    aiOptions.EnableQuickPulseMetricStream = false;
    services.AddApplicationInsightsTelemetry(aiOptions);
}

Úplný seznam nastavení vApplicationInsightsServiceOptionsFull List of settings in ApplicationInsightsServiceOptions

NastaveníSetting PopisDescription VýchozíDefault
EnablePerformanceCounterCollectionModuleEnablePerformanceCounterCollectionModule Povolit/zakázatPerformanceCounterCollectionModuleEnable/Disable PerformanceCounterCollectionModule truetrue
EnableRequestTrackingTelemetryModuleEnableRequestTrackingTelemetryModule Povolit/zakázatRequestTrackingTelemetryModuleEnable/Disable RequestTrackingTelemetryModule truetrue
EnableEventCounterCollectionModuleEnableEventCounterCollectionModule Povolit/zakázatEventCounterCollectionModuleEnable/Disable EventCounterCollectionModule truetrue
EnableDependencyTrackingTelemetryModuleEnableDependencyTrackingTelemetryModule Povolit/zakázatDependencyTrackingTelemetryModuleEnable/Disable DependencyTrackingTelemetryModule truetrue
EnableAppServicesHeartbeatTelemetryModuleEnableAppServicesHeartbeatTelemetryModule Povolit/zakázatAppServicesHeartbeatTelemetryModuleEnable/Disable AppServicesHeartbeatTelemetryModule truetrue
EnableAzureInstanceMetadataTelemetryModuleEnableAzureInstanceMetadataTelemetryModule Povolit/zakázatAzureInstanceMetadataTelemetryModuleEnable/Disable AzureInstanceMetadataTelemetryModule truetrue
EnableQuickPulseMetricStreamEnableQuickPulseMetricStream Povolit nebo zakázat funkci LiveMetricsEnable/Disable LiveMetrics feature truetrue
EnableAdaptiveSamplingEnableAdaptiveSampling Povolit/zakázat adaptivní vzorkováníEnable/Disable Adaptive Sampling truetrue
EnableHeartbeatEnableHeartbeat Povolí nebo zakáže funkci prezenčních signálů, které pravidelně (ve výchozím nastavení 15 minut) pošle vlastní metriku s názvem HeartbeatState s informacemi o modulu runtime, jako je verze .NET, informace o prostředí Azure, pokud jsou k dispozici atd.Enable/Disable Heartbeats feature, which periodically (15-min default) sends a custom metric named 'HeartbeatState' with information about the runtime like .NET Version, Azure Environment information, if applicable, etc. truetrue
AddAutoCollectedMetricExtractorAddAutoCollectedMetricExtractor Povolí nebo zakáže extraktor AutoCollectedMetrics, což je TelemetryProcessor, který posílá předem agregované metriky o požadavcích a závislostech, než proběhne vzorkování.Enable/Disable AutoCollectedMetrics extractor, which is a TelemetryProcessor that sends pre-aggregated metrics about Requests/Dependencies before sampling takes place. truetrue
RequestCollectionOptions.TrackExceptionsRequestCollectionOptions.TrackExceptions Povolí nebo zakáže vytváření sestav neošetřené sledování výjimek v modulu shromažďování požadavků.Enable/Disable reporting of unhandled Exception tracking by the Request collection module. false v NETSTANDARD 2.0 (protože výjimky jsou sledovány pomocí ApplicationInsightsLoggerProvider), v opačném případě true.false in NETSTANDARD2.0 (because Exceptions are tracked with ApplicationInsightsLoggerProvider), true otherwise.

Seznam konfigurovatelných nastavení v nástroji ApplicationInsightsServiceOptions najdete v tématu seznam nejaktuálnějších dat.See the configurable settings in ApplicationInsightsServiceOptions for the most up-to-date list.

VzorkováníSampling

Sada Application Insights SDK pro ASP.NET Core podporuje fixní i adaptivní vzorkování.The Application Insights SDK for ASP.NET Core supports both fixed-rate and adaptive sampling. Adaptivní vzorkování je ve výchozím nastavení povolené.Adaptive sampling is enabled by default.

Další informace najdete v tématu Konfigurace adaptivního vzorkování pro aplikace ASP.NET Core.For more information, see Configure adaptive sampling for ASP.NET Core applications.

Přidání TelemetryInitializersAdding TelemetryInitializers

Inicializátory telemetrie použijte, když chcete rozšířit telemetrii s dalšími informacemi.Use telemetry initializers when you want to enrich telemetry with additional information.

Přidejte všechny nové TelemetryInitializer kontejnery do DependencyInjection kontejneru, jak je znázorněno v následujícím kódu.Add any new TelemetryInitializer to the DependencyInjection container as shown in the following code. Sada SDK automaticky vybere všechny TelemetryInitializer , které jsou přidány do DependencyInjection kontejneru.The SDK automatically picks up any TelemetryInitializer that's added to the DependencyInjection container.

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

Odebírá se TelemetryInitializersRemoving TelemetryInitializers

Ve výchozím nastavení jsou Inicializátory telemetrie přítomné.Telemetry initializers are present by default. Chcete-li odebrat všechny nebo konkrétní Inicializátory telemetrie, použijte následující vzorový kód po volání AddApplicationInsightsTelemetry() .To remove all or specific telemetry initializers, use the following sample code after you call AddApplicationInsightsTelemetry().

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

Přidávání procesorů telemetrieAdding telemetry processors

Vlastní procesory telemetrie můžete přidat TelemetryConfiguration pomocí metody rozšíření AddApplicationInsightsTelemetryProcessor na IServiceCollection .You can add custom telemetry processors to TelemetryConfiguration by using the extension method AddApplicationInsightsTelemetryProcessor on IServiceCollection. Procesory telemetrie se používají ve scénářích pokročilého filtrování.You use telemetry processors in advanced filtering scenarios. Použijte následující příklad.Use the following example.

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

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

Konfigurace nebo odebrání výchozích TelemetryModulesConfiguring or removing default TelemetryModules

Application Insights používá moduly telemetrie k automatickému shromažďování užitečných telemetrie o konkrétních úlohách, aniž by bylo nutné ručně sledovat uživatele.Application Insights uses telemetry modules to automatically collect useful telemetry about specific workloads without requiring manual tracking by user.

Ve výchozím nastavení jsou povoleny následující moduly automatických kolekcí.The following automatic-collection modules are enabled by default. Tyto moduly zodpovídají za automatické shromažďování telemetrie.These modules are responsible for automatically collecting telemetry. Můžete je zakázat nebo nakonfigurovat, aby se změnily jejich výchozí chování.You can disable or configure them to alter their default behavior.

  • RequestTrackingTelemetryModule– Shromáždí RequestTelemetry z příchozích webových požadavků.RequestTrackingTelemetryModule - Collects RequestTelemetry from incoming web requests.
  • DependencyTrackingTelemetryModule– Shromažďuje DependencyTelemetry z odchozích volání http a volání SQL.DependencyTrackingTelemetryModule - Collects DependencyTelemetry from outgoing http calls and sql calls.
  • PerformanceCollectorModule-Shromažďuje Windows čítače výkonu.PerformanceCollectorModule - Collects Windows PerformanceCounters.
  • QuickPulseTelemetryModule– Shromažďuje telemetrii pro zobrazení na portálu živých metrik.QuickPulseTelemetryModule - Collects telemetry for showing in Live Metrics portal.
  • AppServicesHeartbeatTelemetryModule– Shromažďuje srdce Beats (které se odesílají jako vlastní metriky) o Azure App Service prostředí, ve kterém je aplikace hostovaná.AppServicesHeartbeatTelemetryModule - Collects heart beats (which are sent as custom metrics), about Azure App Service environment where application is hosted.
  • AzureInstanceMetadataTelemetryModule– Shromažďuje srdce Beats (které se odesílají jako vlastní metriky) o prostředí Azure VM, ve kterém je aplikace hostovaná.AzureInstanceMetadataTelemetryModule - Collects heart beats (which are sent as custom metrics), about Azure VM environment where application is hosted.
  • EventCounterCollectionModule– Shromažďuje EventCounters.EventCounterCollectionModule - Collects EventCounters. Tento modul je novou funkcí a je k dispozici v sadě SDK verze 2.8.0 a vyšších.This module is a new feature and is available in SDK Version 2.8.0 and higher.

Pro konfiguraci všech výchozích možností TelemetryModule použijte metodu rozšíření ConfigureTelemetryModule<T> na IServiceCollection , jak je znázorněno v následujícím příkladu.To configure any default TelemetryModule, use the extension method ConfigureTelemetryModule<T> on IServiceCollection, as shown in the following example.

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.Clear();
                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);
    }
}

Počínaje verzí 2.12.2 ApplicationInsightsServiceOptions obsahuje snadnou možnost pro zákaz všech výchozích modulů.Starting with 2.12.2 version, ApplicationInsightsServiceOptions contains easy option to disable any of the default modules.

Konfigurace kanálu telemetrieConfiguring a telemetry channel

Výchozí kanál telemetrie je ServerTelemetryChannel .The default telemetry channel is ServerTelemetryChannel. Můžete ho přepsat, jak ukazuje následující příklad.You can override it as the following example shows.

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

Dynamické vypnutí telemetrieDisable telemetry dynamically

Pokud chcete vypnout telemetrii podmíněně a dynamicky, můžete vyřešit TelemetryConfiguration instanci s ASP.NET Core kontejnerem vkládání závislostí kdekoli v kódu a nastavit DisableTelemetry příznak.If you want to disable telemetry conditionally and dynamically, you may resolve TelemetryConfiguration instance with ASP.NET Core dependency injection container anywhere in your code and set DisableTelemetry flag on it.

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

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

Výše uvedené nebrání žádnému modulu automatické kolekce v shromažďování telemetrie.The above does not prevent any auto collection modules from collecting telemetry. U výše uvedeného přístupu se neaktivuje jenom odesílání telemetrie na Application Insights.Only the sending of telemetry to Application Insights gets disabled with the above approach. Pokud není určitý modul automatické kolekce žádoucí, je nejlepší odebrat modul telemetrie .If a particular auto collection module is not desired, it is best to remove the telemetry module

Nejčastější dotazyFrequently asked questions

Podporuje Application Insights ASP.NET Core 3. X?Does Application Insights support ASP.NET Core 3.X?

Ano.Yes. Aktualizace na sadu Application Insights SDK pro ASP.NET Core verze 2.8.0 nebo vyšší.Update to Application Insights SDK for ASP.NET Core version 2.8.0 or higher. Starší verze sady SDK nepodporují ASP.NET Core 3. X.Older versions of the SDK do not support ASP.NET Core 3.X.

Také Pokud používáte pokyny na základě sady Visual Studio z tohoto místa, aktualizujte na zprovoznění nejnovější verzi sady visual Studio 2019 (16.3.0).Also, if you are using Visual Studio based instructions from here, update to the latest version of Visual Studio 2019 (16.3.0) to onboard. Předchozí verze sady Visual Studio nepodporují automatickou registraci pro aplikace ASP.NET Core 3. X.Previous versions of Visual Studio do not support automatic onboarding for ASP.NET Core 3.X apps.

Jak můžu sledovat telemetrii, která se automaticky neshromažďuje?How can I track telemetry that's not automatically collected?

Získání instance TelemetryClient pomocí injektáže konstruktoru a volání požadované TrackXXX() metody.Get an instance of TelemetryClient by using constructor injection, and call the required TrackXXX() method on it. Nedoporučujeme vytvářet nové TelemetryClient instance v ASP.NET Core aplikaci.We don't recommend creating new TelemetryClient instances in an ASP.NET Core application. Instance typu Singleton TelemetryClient je již v kontejneru zaregistrována DependencyInjection , která sdílí TelemetryConfiguration se zbytkem telemetrie.A singleton instance of TelemetryClient is already registered in the DependencyInjection container, which shares TelemetryConfiguration with rest of the telemetry. Vytvoření nové TelemetryClient instance se doporučuje jenom v případě, že potřebuje konfiguraci, která je oddělená od zbytku telemetrie.Creating a new TelemetryClient instance is recommended only if it needs a configuration that's separate from the rest of the telemetry.

Následující příklad ukazuje, jak sledovat další telemetrii z kontroleru.The following example shows how to track additional telemetry from a controller.

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 vlastních datových sestavách v Application Insights najdete v tématu Application Insights referenční informace k rozhraní API pro vlastní metriky.For more information about custom data reporting in Application Insights, see Application Insights custom metrics API reference. Podobný přístup lze použít k posílání vlastních metrik pro Application Insights pomocí rozhraní Getmetric API.A similar approach can be used for sending custom metrics to Application Insights using the GetMetric API.

Některé šablony sady Visual Studio používaly metodu rozšíření UseApplicationInsights () na IWebHostBuilder pro povolení Application Insights.Some Visual Studio templates used the UseApplicationInsights() extension method on IWebHostBuilder to enable Application Insights. Je toto použití stále platné?Is this usage still valid?

I když je rozšiřující metoda UseApplicationInsights() stále podporovaná, je označená jako zastaralá v sadě Application Insights SDK verze 2.8.0 a vyšší.While the extension method UseApplicationInsights() is still supported, it is marked obsolete in Application Insights SDK version 2.8.0 onwards. V další hlavní verzi sady SDK se odebere.It will be removed in the next major version of the SDK. Doporučený způsob, jak povolit telemetrii Application Insights, je použití, AddApplicationInsightsTelemetry() protože poskytuje přetížení k řízení některých konfigurací.The recommended way to enable Application Insights telemetry is by using AddApplicationInsightsTelemetry() because it provides overloads to control some configuration. V aplikacích ASP.NET Core 3. X services.AddApplicationInsightsTelemetry() je také jediným způsobem, jak povolit službu Application Insights.Also, in ASP.NET Core 3.X apps, services.AddApplicationInsightsTelemetry() is the only way to enable application insights.

Nasazujem moji aplikaci ASP.NET Core do Web Apps.I'm deploying my ASP.NET Core application to Web Apps. Mám pořád povolit rozšíření Application Insights z Web Apps?Should I still enable the Application Insights extension from Web Apps?

Pokud je sada SDK nainstalována v době sestavení, jak je znázorněno v tomto článku, není nutné povolit rozšíření Application Insights z portálu App Service.If the SDK is installed at build time as shown in this article, you don't need to enable the Application Insights extension from the App Service portal. I v případě, že je rozšíření nainstalováno, bude po zjištění, že sada SDK již přidána do aplikace, vrácena.Even if the extension is installed, it will back off when it detects that the SDK is already added to the application. Pokud povolíte Application Insights z rozšíření, nemusíte instalovat a aktualizovat sadu SDK.If you enable Application Insights from the extension, you don't have to install and update the SDK. Pokud ale povolíte Application Insights podle pokynů v tomto článku, máte větší flexibilitu z těchto důvodů:But if you enable Application Insights by following instructions in this article, you have more flexibility because:

  • Application Insights telemetrie bude i nadále fungovat v:Application Insights telemetry will continue to work in:
    • Všechny operační systémy, včetně systémů Windows, Linux a Mac.All operating systems, including Windows, Linux, and Mac.
    • Všechny režimy publikování, včetně samostatného nebo závislého rozhraní.All publish modes, including self-contained or framework dependent.
    • Všechny cílové architektury, včetně úplného .NET Framework.All target frameworks, including the full .NET Framework.
    • Všechny možnosti hostování, včetně Web Apps, virtuálních počítačů, Linuxů, kontejnerů, služby Azure Kubernetes a hostování mimo Azure.All hosting options, including Web Apps, VMs, Linux, containers, Azure Kubernetes Service, and non-Azure hosting.
    • Všechny verze .NET Core včetně verze PreviewAll .NET Core versions including preview versions.
  • Telemetrii můžete zobrazit lokálně při ladění ze sady Visual Studio.You can see telemetry locally when you're debugging from Visual Studio.
  • Můžete sledovat další vlastní telemetrii pomocí TrackXXX() rozhraní API.You can track additional custom telemetry by using the TrackXXX() API.
  • Máte plnou kontrolu nad konfigurací.You have full control over the configuration.

Můžu Application Insights monitorování povolit pomocí nástrojů jako Monitorování stavu?Can I enable Application Insights monitoring by using tools like Status Monitor?

Ne.No. Monitorování stavu a monitorování stavu v2 aktuálně podporují pouze ASP.NET 4. x.Status Monitor and Status Monitor v2 currently support ASP.NET 4.x only.

Je Application Insights automaticky povolená pro moji aplikaci ASP.NET Core 2,0?Is Application Insights automatically enabled for my ASP.NET Core 2.0 application?

Microsoft.AspNetCore.All2,0 Metapackage zahrnuje sadu SDK pro Application Insights (verze 2.1.0).The Microsoft.AspNetCore.All 2.0 metapackage included the Application Insights SDK (version 2.1.0). Pokud spustíte aplikaci v ladicím programu sady Visual Studio, Visual Studio povolí Application Insights a zobrazí telemetrii místně v samotném integrovaném vývojovém prostředí.If you run the application under Visual Studio debugger, Visual Studio enables Application Insights and shows telemetry locally in the IDE itself. Do služby Application Insights nebyla odeslána telemetrie, pokud nebyl zadán klíč instrumentace.Telemetry wasn't sent to the Application Insights service unless an instrumentation key was specified. Doporučujeme vám postupovat podle pokynů v tomto článku a povolit Application Insights, i pro aplikace 2,0.We recommend following the instructions in this article to enable Application Insights, even for 2.0 apps.

Pokud Spouštím aplikaci v systému Linux, jsou podporovány všechny funkce?If I run my application in Linux, are all features supported?

Ano.Yes. Podpora funkcí pro sadu SDK je stejná na všech platformách, s následujícími výjimkami:Feature support for the SDK is the same in all platforms, with the following exceptions:

  • Sada SDK shromažďuje čítače událostí v systému Linux, protože čítače výkonu jsou podporovány pouze ve Windows.The SDK collects Event Counters on Linux because Performance Counters are only supported in Windows. Většina metrik je stejná.Most metrics are the same.
  • I když ServerTelemetryChannel je ve výchozím nastavení povolená, pokud je aplikace spuštěná v systému Linux nebo MacOS, kanál automaticky nevytvoří místní složku úložiště, aby se telemetrie dočasně zachovala v případě, že dojde k problémům se sítí.Even though ServerTelemetryChannel is enabled by default, if the application is running in Linux or MacOS, the channel doesn't automatically create a local storage folder to keep telemetry temporarily if there are network issues. Z důvodu tohoto omezení dojde ke ztrátě telemetrie, pokud dojde k dočasným problémům se sítí nebo serverem.Because of this limitation, telemetry is lost when there are temporary network or server issues. Pokud chcete tento problém obejít, nakonfigurujte pro tento kanál místní složku:To work around this issue, configure a local folder for the channel:
using Microsoft.ApplicationInsights.Channel;
using Microsoft.ApplicationInsights.WindowsServer.TelemetryChannel;

    public void ConfigureServices(IServiceCollection services)
    {
        // The following will configure the channel to use the given folder to temporarily
        // store telemetry items during network or Application Insights server issues.
        // User should ensure that the given folder already exists
        // and that the application has read/write permissions.
        services.AddSingleton(typeof(ITelemetryChannel),
                                new ServerTelemetryChannel () {StorageFolder = "/tmp/myfolder"});
        services.AddApplicationInsightsTelemetry();
    }

Podporuje se tato sada SDK pro nové aplikace šablon pracovních služeb .NET Core 3. X?Is this SDK supported for the new .NET Core 3.X Worker Service template applications?

Tato sada SDK vyžaduje HttpContext , a proto nefunguje v aplikacích, které nepoužívají protokol HTTP, včetně aplikací pracovní služby .NET Core 3. X Worker.This SDK requires HttpContext, and hence does not work in any non-HTTP applications, including the .NET Core 3.X Worker Service applications. V tomto dokumentu najdete informace o povolení Application Insights v takových aplikacích s využitím nově vydané sady Microsoft. ApplicationInsights. WorkerService SDK.Refer to this document for enabling application insights in such applications, using the newly released Microsoft.ApplicationInsights.WorkerService SDK.

Open-Source sada SDKOpen-source SDK

Nejnovější aktualizace a opravy chyb najdete v poznámkách k verzi.For the latest updates and bug fixes consult the release notes.

Další krokyNext steps