Aplikační Přehledy pro aplikace ASP.NET Core

Tento článek popisuje, jak povolit Přehledy aplikace pro ASP.NET Core aplikaci.

Aplikační Přehledy může shromažďovat následující telemetrická data z vaší ASP.NET Core aplikace:

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

Použijeme příklad aplikace MVC , který cílí netcoreapp3.0. Tyto pokyny můžete použít pro všechny aplikace ASP.NET Core. Pokud používáte službu Worker Service, postupujte podle pokynů odsud.

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 této funkce. Přechod na připojovací řetězce , abyste mohli využívat nové funkce.

Podporované scénáře

Sada Application Přehledy 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í Přehledy aplikací se podporuje všude, kde se podporuje .NET Core. Podpora se zabývá následujícími scénáři:

  • Operační systém: Windows, Linux nebo Mac
  • Metoda hostování: Proces nebo mimo proces
  • Metoda nasazení: Závislá architektura nebo samostatná
  • Webový server: IIS (internetový informační server) nebo Kestrel
  • Platforma hostování: Funkce Web Apps Azure App Service, virtuálního počítače Azure, Dockeru, Azure Kubernetes Service (AKS) atd.
  • Verze .NET Core: Všechny oficiálně podporované verze .NET Core , které nejsou ve verzi Preview
  • IDE: Visual Studio, Visual Studio Kód nebo příkazový řádek

Poznámka

ASP.NET Core 3.1 vyžaduje aplikaci Přehledy 2.8.0 nebo novější.

Požadavky

  • Funkční ASP.NET Core aplikace. Pokud potřebujete vytvořit ASP.NET Core aplikaci, postupujte podle tohoto ASP.NET Core kurzu.
  • Platný připojovací řetězec Přehledy aplikace. Tento řetězec je nutný k odeslání jakékoli telemetrie do Přehledy aplikace. Pokud potřebujete vytvořit nový prostředek Přehledy aplikace, abyste získali připojovací řetězec, přečtěte si téma Vytvoření prostředku Přehledy aplikace.

Povolení telemetrie na straně serveru Přehledy aplikací (Visual Studio)

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

  1. Otevřete svůj projekt v sadě Visual Studio.

    Tip

    Pokud chcete sledovat všechny změny, které aplikace Přehledy dělá, můžete pro svůj projekt nastavit správu zdrojového kódu. Pokud ho chcete nastavit , vyberte>Přidat soubor do správy zdrojového kódu.

  2. Vyberte telemetrii Project>Add application Přehledy.

  3. Vyberte Začínáme. V závislosti na vaší verzi Visual Studio se název tohoto tlačítka může lišit. V některých dřívějších verzích se jmenuje tlačítko Start Free .

  4. Vyberte své předplatné a pak vyberteRegistrprostředků>.

  5. Po přidání Přehledy aplikace do projektu zkontrolujte, jestli používáte nejnovější stabilní verzi sady SDK. Přejděte na Project>Manage NuGet Packages>Microsoft.ApplicationInsights.AspNetCore. Pokud potřebujete, vyberte Aktualizovat.

    Screenshot showing where to select the Application Insights package for update

  6. Pokud jste projekt přidali do správy zdrojového kódu, přejděte do zobrazení>změnTeam Exploreru>. Můžete vybrat každý soubor a zobrazit rozdílové zobrazení změn provedených aplikací Přehledy telemetrii.

Povolení telemetrie na straně serveru Přehledy aplikací (bez Visual Studio)

  1. Nainstalujte balíček sady Application Přehledy SDK NuGet pro ASP.NET Core. Doporučujeme vždy používat nejnovější stabilní verzi. Najděte úplné poznámky k verzi sady SDK v opensourcovém úložišti GitHub.

    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.16.0" />
        </ItemGroup>
    
  2. Přidejte services.AddApplicationInsightsTelemetry(); do ConfigureServices() metody ve třídě Startup , jak je uvedeno 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();
        }
    
  3. Nastavte připojovací řetězec.

    I když můžete připojovací řetězec zadat jako součást argumentu ApplicationInsightsServiceOptions pro AddApplicationInsightsTelemetry, 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. Ujistěte se, že appsettings.json se během publikování zkopíruje do kořenové složky aplikace.

        {
          "ApplicationInsights": {
            "ConnectionString" : "Copy connection string from Application Insights Resource Overview"
          },
          "Logging": {
            "LogLevel": {
              "Default": "Warning"
            }
          }
        }
    

    Případně zadejte připojovací řetězec v proměnné prostředí "APPLICATIONINSIGHTS_CONNECTION_STRING" 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á v Azure Web Apps, ale dá se použít také na všech místech, APPLICATIONINSIGHTS_CONNECTION_STRING 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 připojovací řetězec uložit do ASP.NET Core tajných kódů uživatelů nebo ho načíst z jiného poskytovatele konfigurace, můžete přetížení použít s parametremMicrosoft.Extensions.Configuration.IConfiguration. Například, services.AddApplicationInsightsTelemetry(Configuration);. V Microsoft.ApplicationInsights.AspNetCore verze 2.15.0 a novějších volání services.AddApplicationInsightsTelemetry() automaticky přečte připojovací řetězec z Microsoft.Extensions.Configuration.IConfiguration aplikace. Není nutné explicitně zadat IConfiguration.

Pokud IConfiguration se načetla konfigurace z více zprostředkovatelů, services.AddApplicationInsightsTelemetry určuje prioritu konfigurace bez appsettings.jsonohledu na pořadí, ve kterém se přidají zprostředkovatelé. Použijte metodu services.AddApplicationInsightsTelemetry(IConfiguration) ke čtení konfigurace z IConfiguration bez tohoto přednostního zacházení pro appsettings.json.

Spusťte aplikaci

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

Live Metrics

Živé metriky se dají použít k rychlému ověření, jestli je správně nakonfigurované monitorování Přehledy aplikací. Může trvat několik minut, než se telemetrie zobrazí na portálu a analýze, ale živé metriky zobrazují využití procesoru spuštěného procesu téměř v reálném čase. Může také zobrazit další telemetrii, jako jsou požadavky, závislosti a trasování.

Protokoly ILoggeru

Výchozí konfigurace shromažďuje ILoggerWarning protokoly a přísnější protokoly. Projděte si nejčastější dotazy k přizpůsobení této konfigurace.

Závislosti

Kolekce závislostí je ve výchozím nastavení povolená. Tento článek vysvětluje závislosti, které se automaticky shromažďují, a obsahuje také kroky k ručnímu 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 je aplikace spuštěná v Azure Web Apps (Windows).
  • Sada SDK verze 2.7.1 a novější shromažďuje čítače výkonu, pokud je aplikace spuštěná v 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č. Doporučený způsob, jak získat systémové čítače v Linuxu (a dalších prostředích bez Windows), je použití eventCounters.

EventCounter

Ve výchozím nastavení EventCounterCollectionModule je povolená. Informace o konfiguraci seznamu čítačů, které se mají shromažďovat, najdete v úvodu k 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 jsou dostatečné, abyste mohli začít shromažďovat telemetrii na straně serveru. Pokud má vaše aplikace komponenty na straně klienta, začněte shromažďovat telemetrii využití podle následujících kroků.

  1. V _ViewImports.cshtml, přidat injektáž:
    @inject Microsoft.ApplicationInsights.AspNetCore.JavaScriptSnippet JavaScriptSnippet
  1. V _Layout.cshtmlčásti vložte HtmlHelper na konec oddílu <head> , ale před jakýkoli jiný skript. Pokud chcete na stránce nahlásit libovolnou vlastní telemetrii JavaScriptu, zadejte ji za tento fragment kódu:
    @Html.Raw(JavaScriptSnippet.FullScript)
    </head>

Jako alternativu k použití FullScriptScriptBody je k dispozici sada Application Přehledy SDK pro ASP.NET Core verze 2.14. Tuto ScriptBody značku použijte, pokud potřebujete řídit <script> 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é odkazujeme dříve, pocházejí z výchozí šablony aplikace MVC. Pokud chcete pro aplikaci správně povolit monitorování na straně klienta, musí se fragment kódu JavaScriptu zobrazit v <head> části každé stránky aplikace, kterou chcete monitorovat. Přidejte do šablony aplikace fragment kódu _Layout.cshtml JavaScriptu, abyste povolili monitorování na straně klienta.

Pokud projekt neobsahuje _Layout.cshtml, můžete monitorování na straně klienta přidat přidáním fragmentu kódu JavaScriptu do ekvivalentního souboru, který řídí <head> všechny stránky v aplikaci. Alternativně můžete fragment kódu přidat na více stránek, ale nedoporučujeme ho.

Poznámka

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

Konfigurace sady Application Přehledy SDK

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

Poznámka

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

Použití ApplicationInsightsServiceOptions

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

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

Tato tabulka obsahuje úplný seznam ApplicationInsightsServiceOptions nastavení:

Nastavení Popis Výchozí
EnablePerformanceCounterCollectionModule Povolení nebo zakázání PerformanceCounterCollectionModule true
EnableRequestTrackingTelemetryModule Povolení nebo zakázání RequestTrackingTelemetryModule true
EnableEventCounterCollectionModule Povolení nebo zakázání EventCounterCollectionModule true
EnableDependencyTrackingTelemetryModule Povolení nebo zakázání DependencyTrackingTelemetryModule true
EnableAppServicesHeartbeatTelemetryModule Povolení nebo zakázání AppServicesHeartbeatTelemetryModule true
EnableAzureInstanceMetadataTelemetryModule Povolení nebo zakázání AzureInstanceMetadataTelemetryModule true
EnableQuickPulseMetricStream Povolení nebo zakázání funkce LiveMetrics true
EnableAdaptiveSampling Povolení nebo zakázání adaptivního vzorkování true
EnableHeartbeat Povolení nebo zakázání funkce prezenčních signálů, která pravidelně (výchozí 15 minut) odesílá vlastní metriku s názvem HeartbeatState s informacemi o modulu runtime, jako je verze .NET, informace o prostředí Azure, pokud je to možné atd. true
AddAutoCollectedMetricExtractor Enable/Disable AutoCollectedMetrics extractor, což je TelemetryProcessor, který před zahájením vzorkování odesílá předem agregované metriky o požadavcích a závislostech. true
RequestCollectionOptions.TrackExceptions Povolte nebo zakažte generování sestav neošetřeného sledování výjimek modulem Kolekce požadavků. false v NETSTANDARD2.0 (protože výjimky jsou sledovány pomocí ApplicationInsightsLoggerProvider), true jinak.
EnableDiagnosticsTelemetryModule Povolit nebo zakázat DiagnosticsTelemetryModule. Zakázání způsobí ignorování následujících nastavení; EnableHeartbeat, EnableAzureInstanceMetadataTelemetryModule, EnableAppServicesHeartbeatTelemetryModule true

Nejaktuálně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ší doporučujeme nakonfigurovat každé nastavení, které je k dispozici, ApplicationInsightsServiceOptionsvčetně ConnectionString pomocí instance aplikace IConfiguration . Nastavení musí být v části ApplicationInsights, jak je znázorněno v následujícím příkladu. Následující část souboru 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 services.AddApplicationInsightsTelemetry(aiOptions) se použije, přepíše nastavení z Microsoft.Extensions.Configuration.IConfiguration.

Vzorkování

Sada Application Přehledy SDK pro ASP.NET Core podporuje jak pevnou rychlost, tak adaptivní vzorkování. Ve výchozím nastavení je adaptivní vzorkování povolené.

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

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 převezme všechny TelemetryInitializer přidané položky do kontejneru DependencyInjection .

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

Poznámka

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

Odebrání telemetrických inicializátorů

Ve výchozím nastavení jsou k dispozici inicializátory telemetrie. Pokud chcete odebrat všechny nebo specifické inicializátory telemetrie, použijte následující ukázkový kód po volání 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ání procesorů telemetrie

Vlastní procesory TelemetryConfiguration telemetrie můžete přidat 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.

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

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

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

Aplikace Přehledy 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 Windows PerformanceCounters
  • QuickPulseTelemetryModule – Shromažďuje telemetrii pro zobrazení na portálu Živé metriky.
  • AppServicesHeartbeatTelemetryModule- Shromažďuje tepové beaty (které se odesílají jako vlastní metriky) o Azure App Service prostředí, ve kterém je aplikace hostovaná.
  • AzureInstanceMetadataTelemetryModule – Shromažďuje srdeční tepy (které se odesílají jako vlastní metriky) o prostředí virtuálních počítačů Azure, ve kterém je aplikace hostovaná.
  • EventCounterCollectionModule - Shromažďuje EventCounters; tento modul je nová funkce a je k dispozici v sadě SDK verze 2.8.0 a novější.

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

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

Ve verzích 2.12.2 a novějších ApplicationInsightsServiceOptions obsahuje snadnou 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 ho přepsat.

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

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

Dynamické zakázání telemetrie

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

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

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

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

Opensourcová sada SDK

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

Další kroky