Application Insights per applicazioni ASP.NET Core

Articolo
10/15/2024

Questo articolo descrive come abilitare e configurare Application Insights per un'applicazione ASP.NET Core.

Nota

La documentazione seguente si basa sull'API classica di Application Insights. Il piano a lungo termine per Application Insights prevede la raccolta di dati con OpenTelemetry. Per altre informazioni, vedere Abilitare OpenTelemetry di Monitoraggio di Azure per le applicazioni .NET, Node.js, Python e Java oltre che la Roadmap OpenTelemetry. Le indicazioni sulla migrazione sono disponibili per .NET, Node.js e Python.

Application Insights può raccogliere i dati di telemetria seguenti dall'applicazione ASP.NET Core:

Richieste
Dipendenze
Eccezioni
Contatori delle prestazioni
Heartbeat
Registri

Viene usata un'applicazione MVC di esempio. Se si usa il Servizio del ruolo di lavoro, usare le istruzioni in Application Insights per le applicazioni del Servizio del ruolo di lavoro.

È disponibile un 'offerta .NET basata su OpenTelemetry. Per altre informazioni, vedere Panoramica di OpenTelemetry.

Nota

Il 31 marzo 2025, il supporto per l'inserimento delle chiavi di strumentazione terminerà. L'inserimento delle chiavi di strumentazione continuerà a funzionare, ma non saranno più garantiti aggiornamenti o supporto per la funzionalità. Eseguire la transizione alle stringhe di connessione per sfruttare le nuove funzionalità.

Nota

Se si vuole usare il provider ILogger autonomo, usare Microsoft.Extensions.Logging.ApplicationInsight.

Scenari supportati

Application Insights SDK per ASP.NET Core può monitorare le applicazioni indipendentemente da dove o come vengono eseguite. Se l'applicazione è in esecuzione e ha connettività di rete ad Azure, è possibile raccogliere i dati di telemetria. Il monitoraggio di Application Insights è supportato ovunque sia supportato .NET Core e comprende gli scenari seguenti:

Sistema operativo: Windows, Linux o Mac
Metodo di hosting: interno o esterno al processo
Metodo di distribuzione: dipendente dal framework o autonomo
Server Web: IIS (Internet Information Server) o Kestrel
Piattaforma di hosting: la funzionalità App Web del Servizio app di Azure, Macchine virtuali di Azure, Docker e servizio Azure Kubernetes
Versione di .NET: tutte le versioni di .NET supportate ufficialmente non in anteprima
IDE: Visual Studio, Visual Studio Code o riga di comando

Prerequisiti

È necessario:

Un'applicazione ASP.NET Core funzionante. Se è necessario creare un'applicazione ASP.NET Core, seguire questa esercitazione di ASP.NET Core.
Un riferimento a una versione supportata del pacchetto NuGet Application Insights.
Una stringa di connessione valida di Application Insights. Questa stringa è necessaria per inviare dati di telemetria ad Application Insights. Se è necessario creare una nuova risorsa di Application Insights per ottenere una stringa di connessione, vedere Creare una risorsa di Application Insights.

Abilitare i dati di telemetria lato server di Application Insights (Visual Studio)

Per Visual Studio per Mac, usare le linee guida manuali. Solo la versione di Windows di Visual Studio supporta questa procedura.

Aprire il progetto in Visual Studio.
Passare a Progetto>Aggiungi Application Insights Telemetry.
Selezionare Azure Application Insights>Avanti.
Scegliere la sottoscrizione e l'istanza di Application Insights. In alternativa, è possibile creare una nuova istanza con Crea nuovo. Selezionare Avanti.
Aggiungere o confermare la stringa di connessione di Application Insights. Deve essere prepopolata in base alla selezione nel passaggio precedente. Selezionare Fine.
Dopo aver aggiunto Application Insights al progetto, verificare di usare la versione stabile più recente dell'SDK. Passare a Progetto>Gestisci pacchetti NuGet>Microsoft.ApplicationInsights.AspNetCore. Se necessario, selezionare Aggiorna.

Abilitare i dati di telemetria lato server di Application Insights (senza usare Visual Studio)

Installare il pacchetto NuGet Application Insights SDK per ASP.NET Core.

È consigliabile usare sempre la versione stabile più recente. Le note sulla versione complete per l'SDK sono disponibili nel repository GitHub open source.

L'esempio di codice seguente illustra le modifiche da aggiungere al file .csproj del progetto:
```
<ItemGroup>
    <PackageReference Include="Microsoft.ApplicationInsights.AspNetCore" Version="2.21.0" />
</ItemGroup>
```

Aggiungere AddApplicationInsightsTelemetry() alla classe startup.cs o program.cs. La scelta dipende dalla versione di .NET Core.

ASP.NET Core 6 e versioni successive
ASP.NET Core 5 e versioni precedenti

Aggiungere builder.Services.AddApplicationInsightsTelemetry(); dopo il metodo WebApplication.CreateBuilder() nella classe Program, come nell'esempio seguente:

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

Aggiungere services.AddApplicationInsightsTelemetry(); al metodo ConfigureServices() nella classe Startup, come nell'esempio seguente:

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

Nota

Questa versione di .NET non è più supportata.

Configurare la stringa di connessione.

Sebbene sia possibile specificare una stringa di connessione come parte dell'argomento ApplicationInsightsServiceOptions per AddApplicationInsightsTelemetry, è consigliabile specificare la stringa di connessione nella configurazione. L'esempio di codice seguente illustra come specificare una stringa di connessione in appsettings.json. Assicurarsi che appsettings.json venga copiato nella cartella radice dell'applicazione durante la pubblicazione.
```
{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning"
    }
  },
  "AllowedHosts": "*",
  "ApplicationInsights": {
    "ConnectionString": "Copy connection string from Application Insights Resource Overview"
  }
}
```
In alternativa, specificare la stringa di connessione nella variabile di ambiente APPLICATIONINSIGHTS_CONNECTION_STRING o ApplicationInsights:ConnectionString nel file di configurazione JSON.

Ad esempio:
- SET ApplicationInsights:ConnectionString = <Copy connection string from Application Insights Resource Overview>
- SET APPLICATIONINSIGHTS_CONNECTION_STRING = <Copy connection string from Application Insights Resource Overview>
- In genere, la variabile APPLICATIONINSIGHTS_CONNECTION_STRING viene usata in App Web. Può essere usata anche in tutte le posizioni in cui è supportato questo SDK.
Nota

Una stringa di connessione specificata nel codice prevale sulla variabile di ambiente APPLICATIONINSIGHTS_CONNECTION_STRING, che prevale su altre opzioni.

Segreti utente e altri provider di configurazione

Se si vuole archiviare la stringa di connessione in segreti utente di ASP.NET Core o recuperarla da un altro provider di configurazione, è possibile usare l'overload con un parametro Microsoft.Extensions.Configuration.IConfiguration. Un parametro di esempio è services.AddApplicationInsightsTelemetry(Configuration);.

Nella versione 2.15.0 di Microsoft.ApplicationInsights.AspNetCore e versioni successive, chiamando services.AddApplicationInsightsTelemetry() la stringa di connessione viene letta automaticamente da Microsoft.Extensions.Configuration.IConfiguration dell'applicazione. Non è necessario specificare in modo esplicito IConfiguration.

Se IConfiguration ha caricato la configurazione da più provider, services.AddApplicationInsightsTelemetry assegna priorità alla configurazione da appsettings.json, indipendentemente dall'ordine in cui vengono aggiunti i provider. Usare il metodo services.AddApplicationInsightsTelemetry(IConfiguration) per leggere la configurazione da IConfiguration senza questo trattamento preferenziale per appsettings.json.

Eseguire l'applicazione

Eseguire l'applicazione ed effettuare richieste. I dati di telemetria dovrebbero ora fluire in Application Insights. Application Insights SDK raccoglie automaticamente le richieste Web in ingresso all'applicazione, insieme ai dati di telemetria seguenti.

Metriche attive

È possibile usare le metriche attive per verificare rapidamente se il monitoraggio delle applicazioni con Application Insights è configurato correttamente. La visualizzazione dei dati di telemetria nel portale di Azure può richiedere alcuni minuti, ma il riquadro delle metriche attive mostra l'utilizzo della CPU del processo in esecuzione quasi in tempo reale. Può anche visualizzare altri dati di telemetria, ad esempio richieste, dipendenze e tracce.

Abilitare le metriche attive usando il codice per qualsiasi applicazione .NET

Nota

Le metriche attive sono abilitate per impostazione predefinita quando si esegue l'onboarding seguendo le istruzioni consigliate per le applicazioni .NET.

Per configurare manualmente le metriche attive:

Installare il pacchetto NuGet Microsoft.ApplicationInsights.PerfCounterCollector.
Il codice dell'app console di esempio seguente mostra la configurazione delle metriche attive:

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

L'esempio precedente riguarda un'app console, ma lo stesso codice può essere usato in qualsiasi applicazione .NET. Se sono abilitati altri moduli di telemetria per la raccolta automatica dei dati di telemetria, è importante assicurarsi che la stessa configurazione usata per l'inizializzazione di tali moduli venga usata per il modulo delle metriche attive.

Log ILogger

La configurazione predefinita raccoglie log ILoggerWarning e log di maggiore gravità. Per altre informazioni, vedere Come si personalizza la raccolta dei log ILogger?.

Dipendenze

La raccolta delle dipendenze è abilitata per impostazione predefinita. L'articolo Rilevamento della dipendenza in Application Insights illustra le dipendenze raccolte automaticamente e contiene anche le istruzioni per eseguire il rilevamento manuale.

Contatori delle prestazioni

Il supporto dei contatori delle prestazioni nelle applicazioni ASP.NET Core è limitato:

Le versioni dell'SDK 2.4.1 e successive raccolgono i contatori delle prestazioni se l'applicazione è in esecuzione in App Web (Windows).
Le versioni di SDK 2.7.1 e successive raccolgono contatori delle prestazioni se l'applicazione è in esecuzione in Windows e ha come destinazione netstandard2.0 o versioni successive.
Per le applicazioni destinate a .NET Framework, tutte le versioni dell'SDK supportano i contatori delle prestazioni.
Le versioni dell'SDK 2.8.0 e successive supportano il contatore di CPU/memoria in Linux. Linux non supporta nessun altro contatore. Per ottenere i contatori di sistema in Linux e in altri ambienti non Windows, usare EventCounter.

EventCounter

Per impostazione predefinita, EventCounterCollectionModule è abilitata. Per informazioni su come configurare l'elenco dei contatori da raccogliere, vedere Introduzione a EventCounter.

Arricchire i dati tramite HTTP

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

Abilitare la telemetria lato client per le applicazioni Web

I passaggi precedenti sono sufficienti per iniziare a raccogliere i dati di telemetria lato server. Se l'applicazione include componenti sul lato client, seguire i passaggi successivi per iniziare a raccogliere dati di telemetria sull'utilizzo usando l'inserimento di script del caricatore SDK JavaScript (Web) in base alla configurazione.

In _ViewImports.cshtml aggiungere l'inserimento:

@inject Microsoft.ApplicationInsights.AspNetCore.JavaScriptSnippet JavaScriptSnippet

In _Layout.cshtml inserire HtmlHelper alla fine della sezione <head> ma prima di qualsiasi altro script. Per segnalare dati di telemetria JavaScript personalizzati dalla pagina, inserirli dopo questo frammento di codice:
```
@Html.Raw(JavaScriptSnippet.FullScript)
</head>
```

In alternativa all'uso di FullScript, è disponibile ScriptBody a partire da Application Insights SDK per ASP.NET Core versione 2.14. Usare ScriptBody se è necessario controllare il tag <script> per impostare criteri di sicurezza del contenuto:

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

I nomi di file .cshtml a cui si fa riferimento in precedenza provengono da un modello di applicazione MVC predefinito. In definitiva, se si vuole abilitare correttamente il monitoraggio lato client per l'applicazione, lo script del caricatore SDK JavaScript (Web) deve comparire nella sezione <head> di ogni pagina dell'applicazione che si vuole monitorare. Aggiungere lo script del caricatore SDK JavaScript (Web) a _Layout.cshtml in un modello di applicazione per abilitare il monitoraggio lato client.

Se il progetto non include _Layout.cshtml, è comunque possibile aggiungere il monitoraggio lato client aggiungendo lo script del caricatore JavaScript SDK (Web) a un file equivalente che controlla il contenuto di <head> di tutte le pagine all'interno dell'app. In alternativa, è possibile aggiungere lo script del caricatore SDK JavaScript (Web) a più pagine, ma non è consigliabile.

Nota

L'inserimento di JavaScript offre un'esperienza di configurazione predefinita. Se sono necessari interventi di configurazione oltre l'impostazione della stringa di connessione, è necessario rimuovere l'inserimento automatico come descritto e aggiungere manualmente JavaScript SDK.

Configurare Application Insights SDK

È possibile personalizzare Application Insights SDK per ASP.NET Core per modificare la configurazione predefinita. Gli utenti di Application Insights ASP.NET SDK potrebbero avere familiarità con la modifica della configurazione usando ApplicationInsights.config o modificando TelemetryConfiguration.Active. Per ASP.NET Core, apportare quasi tutte le modifiche di configurazione nel metodo ConfigureServices() della classe Startup.cs, se non diversamente indicato. Nelle sezioni seguenti sono disponibili altre informazioni.

Nota

Nelle applicazioni ASP.NET Core la modifica della configurazione modificando TelemetryConfiguration.Active non è supportata.

Usare ApplicationInsightsServiceOptions

È possibile modificare alcune impostazioni comuni passando ApplicationInsightsServiceOptions a AddApplicationInsightsTelemetry, come in questo esempio:

ASP.NET Core 6 e versioni successive
ASP.NET Core 5 e versioni precedenti

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

Nota

Questa versione di .NET non è più supportata.

Questa tabella include l'elenco completo delle impostazioni di ApplicationInsightsServiceOptions:

Impostazione	Descrizione	Default
EnablePerformanceCounterCollectionModule	Abilitare/disabilitare `PerformanceCounterCollectionModule`.	Vero
EnableRequestTrackingTelemetryModule	Abilitare/disabilitare `RequestTrackingTelemetryModule`.	Vero
EnableEventCounterCollectionModule	Abilitare/disabilitare `EventCounterCollectionModule`.	Vero
EnableDependencyTrackingTelemetryModule	Abilitare/disabilitare `DependencyTrackingTelemetryModule`.	Vero
EnableAppServicesHeartbeatTelemetryModule	Abilitare/disabilitare `AppServicesHeartbeatTelemetryModule`.	Vero
EnableAzureInstanceMetadataTelemetryModule	Abilitare/disabilitare `AzureInstanceMetadataTelemetryModule`.	Vero
EnableQuickPulseMetricStream	Abilitare/disabilitare la funzionalità LiveMetrics.	Vero
EnableAdaptiveSampling	Abilita/disabilita il campionamento adattivo.	Vero
EnableHeartbeat	Abilitare/disabilitare la funzionalità heartbeat. Invia periodicamente (impostazione predefinita 15 minuti) una metrica personalizzata denominata `HeartbeatState` con informazioni sul runtime, ad esempio la versione di .NET e le informazioni sull'ambiente di Azure, se applicabile.	Vero
AddAutoCollectedMetricExtractor	Abilitare/disabilitare `AutoCollectedMetrics extractor`. Questo processore di telemetria invia metriche preaggregate relative a richieste/dipendenze prima che venga eseguito il campionamento.	Vero
RequestCollectionOptions.TrackExceptions	Abilitare/disabilitare la segnalazione di rilevamento delle eccezioni non gestite dal modulo di raccolta delle richieste.	False in `netstandard2.0` (perché le eccezioni vengono rilevate con `ApplicationInsightsLoggerProvider`). True in caso contrario.
EnableDiagnosticsTelemetryModule	Abilitare/disabilitare `DiagnosticsTelemetryModule`. Con la disabilitazione vengono ignorate le impostazioni seguenti: `EnableHeartbeat`, `EnableAzureInstanceMetadataTelemetryModule` e `EnableAppServicesHeartbeatTelemetryModule`.	Vero

Per l'elenco più recente, vedere le impostazioni configurabili in ApplicationInsightsServiceOptions.

Raccomandazione di configurazione per Microsoft.ApplicationInsights.AspNetCore SDK 2.15.0 e versioni successive

In Microsoft.ApplicationInsights.AspNetCore SDK versione 2.15.0 e versioni successive configurare ogni impostazione disponibile in ApplicationInsightsServiceOptions, inclusa ConnectionString. Usare l'istanza di IConfiguration dell'applicazione. Le impostazioni devono trovarsi nella sezione ApplicationInsights, come illustrato nell'esempio seguente. La sezione seguente di appsettings.json configura la stringa di connessione e disabilita il campionamento adattivo e la raccolta dei contatori delle prestazioni.

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

Se builder.Services.AddApplicationInsightsTelemetry(aiOptions) per ASP.NET Core 6.0 o services.AddApplicationInsightsTelemetry(aiOptions) per ASP.NET Core 3.1 e versioni precedenti, viene eseguito l'override delle impostazioni da Microsoft.Extensions.Configuration.IConfiguration.

Campionamento

Application Insights SDK per ASP.NET Core supporta sia il campionamento a frequenza fissa che il campionamento adattivo. Per impostazione predefinita, il campionamento adattivo è abilitato.

Per altre informazioni, vedere Configurare il campionamento adattivo per le applicazioni ASP.NET Core.

Aggiungere TelemetryInitializer

Per arricchire i dati di telemetria con altre informazioni, usare gli inizializzatori di telemetria.

Aggiungere qualsiasi nuovo TelemetryInitializer al contenitore DependencyInjection, come illustrato nel codice seguente. L'SDK preleva automaticamente qualsiasi TelemetryInitializer aggiunto al contenitore DependencyInjection.

ASP.NET Core 6 e versioni successive
ASP.NET Core 5 e versioni precedenti

var builder = WebApplication.CreateBuilder(args);

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

var app = builder.Build();

Nota

builder.Services.AddSingleton<ITelemetryInitializer, MyCustomTelemetryInitializer>(); funziona per inizializzatori semplici. Per gli altri, è necessario builder.Services.AddSingleton(new MyCustomTelemetryInitializer() { fieldName = "myfieldName" });.

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

Nota

services.AddSingleton<ITelemetryInitializer, MyCustomTelemetryInitializer>(); funziona per inizializzatori semplici. Per gli altri, è necessario services.AddSingleton(new MyCustomTelemetryInitializer() { fieldName = "myfieldName" });. Questa versione di .NET non è più supportata.

Rimuovere TelemetryInitializer

Per impostazione predefinita, gli inizializzatori di telemetria sono presenti. Per rimuovere tutti gli inizializzatori di telemetria o alcuni specifici, usare il codice di esempio seguente dopo la chiamata di AddApplicationInsightsTelemetry().

ASP.NET Core 6 e versioni successive
ASP.NET Core 5 e versioni precedenti

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

Nota

Questa versione di .NET non è più supportata.

Aggiungere processori di telemetria

È possibile aggiungere processori di telemetria personalizzati a TelemetryConfiguration usando il metodo di estensione AddApplicationInsightsTelemetryProcessor in IServiceCollection. I processori di telemetria vengono usati in scenari di filtro avanzati. Usare l'esempio seguente:

ASP.NET Core 6 e versioni successive
ASP.NET Core 5 e versioni precedenti

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

Nota

Questa versione di .NET non è più supportata.

Configurare o rimuovere i moduli di telemetria predefiniti

Application Insights raccoglie automaticamente i dati di telemetria relativi a carichi di lavoro specifici senza richiedere il rilevamento manuale da parte dell'utente.

Per impostazione predefinita, sono abilitati i seguenti moduli di raccolta automatica. Questi moduli sono responsabili della raccolta automatica dei dati di telemetria. È possibile disabilitarli o configurarli per modificarne il comportamento predefinito.

RequestTrackingTelemetryModule: raccoglie RequestTelemetry dalle richieste Web in ingresso.
DependencyTrackingTelemetryModule: raccoglie DependencyTelemetry da chiamate HTTP e chiamate SQL in uscita.
PerformanceCollectorModule: raccoglie PerformanceCounters di Windows.
QuickPulseTelemetryModule: raccoglie i dati di telemetria da visualizzare nel riquadro delle metriche attive.
AppServicesHeartbeatTelemetryModule: raccoglie gli heartbeat (che vengono inviati come metriche personalizzate) sull'ambiente di Servizio app in cui è ospitata l'applicazione.
AzureInstanceMetadataTelemetryModule: raccoglie gli heartbeat (che vengono inviati come metriche personalizzate) sull'ambiente di Macchine virtuali di Azure in cui è ospitata l'applicazione.
EventCounterCollectionModule: raccoglie EventCounter. Questo modulo è una nuova funzionalità ed è disponibile nell'SDK versione 2.8.0 e successive.

Per configurare qualsiasi TelemetryModule predefinito, usare il metodo di estensione ConfigureTelemetryModule<T> in IServiceCollection, come illustrato nell'esempio seguente:

ASP.NET Core 6 e versioni successive
ASP.NET Core 5 e versioni precedenti

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

Nota

Questa versione di .NET non è più supportata.

Nelle versioni 2.12.2 e successive ApplicationInsightsServiceOptions include un'opzione semplice per disabilitare qualsiasi modulo predefinito.

Configurare un canale di telemetria

Il canale di telemetria predefinito è ServerTelemetryChannel. Nell'esempio seguente viene illustrato come eseguirne l'override.

ASP.NET Core 6 e versioni successive
ASP.NET Core 5 e versioni precedenti

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

Nota

Questa versione di .NET non è più supportata.

Nota

Per scaricare il buffer, vedere Scaricare i dati. Ad esempio, potrebbe essere necessario scaricare il buffer se si usa l'SDK in un'applicazione che si arresta.

Disabilitare la telemetria in modo dinamico

Per disabilitare la telemetria in modo condizionale e dinamico, è possibile risolvere l'istanza di TelemetryConfiguration con un contenitore di inserimento delle dipendenze ASP.NET Core in qualsiasi punto del codice e impostarvi il flag DisableTelemetry.

ASP.NET Core 6 e versioni successive
ASP.NET Core 5 e versioni precedenti

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

Nota

Questa versione di .NET non è più supportata.

L'esempio di codice precedente impedisce l'invio di dati di telemetria ad Application Insights. Non impedisce ai moduli di raccolta automatica di raccogliere dati di telemetria. Per rimuovere un particolare modulo di raccolta automatica, vedere Rimuovere il modulo di telemetria.

Domande frequenti

Questa sezione fornisce le risposte alle domande comuni.

Application Insights supporta ASP.NET Core 3.1?

ASP.NET Core 3.1 non è più supportato da Microsoft.

Application Insights SDK per ASP.NET Core versione 2.8.0 e Visual Studio 2019 o versione successiva possono essere usati con applicazioni ASP.NET Core 3.1.

Come è possibile tenere traccia dei dati di telemetria non raccolti automaticamente?

Ottenere un'istanza di TelemetryClient usando l'inserimento del costruttore e chiamare il metodo TrackXXX() richiesto. Non è consigliabile creare nuove istanze di TelemetryClient o di TelemetryConfiguration in un'applicazione ASP.NET Core. Un'istanza singleton di TelemetryClient è già registrata nel contenitore DependencyInjection, che condivide TelemetryConfiguration con il resto dei dati di telemetria. Creare una nuova istanza di TelemetryClient solo se è necessaria una configurazione separata dal resto dei dati di telemetria.

Nell'esempio seguente viene illustrato come tenere traccia di più dati di telemetria da un 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();
    }

Per altre informazioni sulla creazione di report dei dati personalizzati in Application Insights, vedere informazioni di riferimento sulle API per le metriche personalizzate di Application Insights. Un approccio simile può essere usato per inviare metriche personalizzate ad Application Insights usando l'API GetMetric.

Come si acquisisce il corpo della richiesta e della risposta nei dati di telemetria?

ASP.NET Core include il supporto predefinito per la registrazione delle informazioni di richiesta/risposta HTTP (incluso il corpo) tramite ILogger. È consigliabile utilizzare questa funzionalità. Ciò può potenzialmente esporre informazioni personali (PII) nei dati di telemetria e può causare un aumento significativo dei costi (costi delle prestazioni e fatturazione di Application Insights), quindi valutare attentamente i rischi prima di usarlo.

Come si personalizza la raccolta dei log ILogger?

L'impostazione predefinita per Application Insights consiste nell'acquisire solo log di avviso e di maggiore gravità.

Acquisire i log di informazioni e di minore gravità modificando la configurazione di registrazione per il provider di Application Insights come indicato di seguito.

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

È importante notare che l'esempio seguente non causa l'acquisizione dei log Information dal provider di Application Insights. Questi log non vengono acquisiti perché l'SDK aggiunge un filtro di registrazione predefinito che indica ad ApplicationInsights di acquisire solo i log Warning e i log di maggiore gravità. Application Insights richiede un override esplicito.

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

Per altre informazioni, vedere Configurazione di ILogger.

Alcuni modelli di Visual Studio usavano il metodo di estensione UseApplicationInsights() in IWebHostBuilder per abilitare Application Insights. Questo utilizzo è ancora valido?

Il metodo di estensione UseApplicationInsights() è ancora supportato, ma è contrassegnato come obsoleto in Application Insights SDK versione 2.8.0 e successive. Viene rimosso nella versione principale successiva dell'SDK. Per abilitare la telemetria di Application Insights, usare AddApplicationInsightsTelemetry() perché fornisce overload per controllare alcune configurazioni. Inoltre, per le app ASP.NET Core 3.X, services.AddApplicationInsightsTelemetry() è l'unico modo per abilitare Application Insights.

Sto distribuendo un'applicazione ASP.NET Core in App Web. È comunque necessario abilitare l'estensione Application Insights da App Web?

Se l'SDK viene installato in fase di compilazione, come illustrato in questo articolo, non è necessario abilitare l'estensione Application Insights dal portale di Servizio app. Se l'estensione è installata, non si attiva quando rileva che l'SDK è già stato aggiunto. Se si abilita Application Insights dall'estensione, non è necessario installare e aggiornare l'SDK. Tuttavia, se si abilita Application Insights seguendo le istruzioni riportate in questo articolo, si ha maggiore flessibilità perché:

La telemetria di Application Insights continua a funzionare in:
- Tutti i sistemi operativi, inclusi Windows, Linux e Mac.
- Tutte le modalità di pubblicazione, incluse quelle autonome o dipendenti dal framework.
- Tutti i framework di destinazione, incluso .NET Framework completo.
- Tutte le opzioni di hosting, tra cui App Web, macchine virtuali, Linux, contenitori, servizio Azure Kubernetes e hosting non Azure.
- Tutte le versioni di .NET Core, incluse le versioni di anteprima.
È possibile visualizzare i dati di telemetria in locale durante il debug da Visual Studio.
È possibile tenere traccia di più dati di telemetria personalizzati usando l'API TrackXXX().
Si ha il controllo completo sulla configurazione.

È possibile abilitare il monitoraggio di Application Insights usando strumenti come l'agente di Application Insights di Monitoraggio di Azure (in precedenza Status Monitor v2)?

Sì. Nell'agente di Application Insights 2.0.0-beta1 e versioni successive sono supportate le applicazioni ASP.NET Core ospitate in IIS.

Sono supportate tutte le funzionalità se si esegue l'applicazione in Linux?

Sì. Il supporto delle funzionalità per l'SDK è lo stesso in tutte le piattaforme, con le eccezioni seguenti:

L'SDK raccoglie contatori di eventi in Linux perché i contatori delle prestazioni sono supportati solo in Windows. La maggior parte delle metriche è la stessa.

Questo SDK è supportato per i servizi del ruolo di lavoro?

No. Usare Application Insights per le applicazioni del Servizio del ruolo di lavoro (applicazioni non HTTP) per i servizi del ruolo di lavoro.

Qual è la procedura per disinstallare l'SDK?

Per rimuovere Application Insights, è necessario rimuovere i pacchetti NuGet e i riferimenti dall'API nell'applicazione. È possibile disinstallare i pacchetti NuGet usando Gestione pacchetti NuGet in Visual Studio.

Nota

Queste istruzioni sono per la disinstallazione di ASP.NET Core SDK. Se è necessario disinstallare ASP.NET SDK, vedere Come è possibile disinstallare ASP.NET SDK?.

Disinstallare il pacchetto Microsoft.ApplicationInsights.AspNetCore usando Gestione pacchetti NuGet.
Per rimuovere completamente Application Insights, controllare ed eliminare manualmente il codice o i file aggiunti insieme alle chiamate API aggiunte nel progetto. Per altre informazioni, vedere Cosa viene creato quando si aggiunge Application Insights SDK?.

Cosa viene creato quando si aggiunge Application Insights SDK?

Quando si aggiunge Application Insights al progetto, vengono creati file e viene aggiunto codice ad alcuni dei file. Disinstallare solo i pacchetti NuGet non sempre consente di rimuovere i file e il codice. Per rimuovere completamente Application Insights, controllare ed eliminare manualmente il codice o i file aggiunti insieme alle chiamate API aggiunte nel progetto.

Quando si aggiunge Application Insights Telemetry a un progetto modello ASP.NET Core di Visual Studio, viene aggiunto il codice seguente:

[Nome del progetto].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
        }

In che modo è possibile disabilitare la correlazione dei dati di telemetria?

Per disabilitare la correlazione dei dati di telemetria nel codice, vedere <ExcludeComponentCorrelationHttpHeadersOnDomains> in Application Insights per le applicazioni console.

Risoluzione dei problemi

Vedere l'articolo sulla risoluzione dei problemi dedicato.

Testare la connettività tra l'host dell'applicazione e il servizio di inserimento

Gli SDK e gli agenti di Application Insights inviano dati di telemetria per l'inserimento come chiamate REST agli endpoint di inserimento. È possibile testare la connettività dal server Web o dal computer host dell'applicazione agli endpoint del servizio di inserimento usando client REST non elaborati da comandi PowerShell o curl. Vedere Risolvere i problemi di dati di telemetria delle applicazioni mancanti in Application Insights per Monitoraggio di Azure.

SDK open source

Leggere e contribuire al codice.

Per gli aggiornamenti e le correzioni di bug più recenti, vedere le note sulla versione.

Note sulla versione

Per le versioni 2.12 e successive: SDK .NET (inclusi ASP.NET, ASP.NET Core e adattatori di registrazione)

Gli aggiornamenti del servizio riepilogano anche i principali miglioramenti di Application Insights.

Passaggi successivi

Esplorare i flussi degli utenti per identificare in che modo gli utenti si spostano nell'app.
Configurare una raccolta di snapshot per visualizzare lo stato del codice sorgente e delle variabili nel momento in cui viene generata un'eccezione.
Usare l'API per inviare gli eventi e le metriche per una visualizzazione più dettagliata dell'utilizzo e delle prestazioni dell'app.
Usare test di disponibilità per controllare costantemente l'app da ogni parte del mondo.
Informazioni sull'inserimento delle dipendenze in ASP.NET Core.

Condividi tramite

Application Insights per applicazioni ASP.NET Core

Scenari supportati

Prerequisiti

Abilitare i dati di telemetria lato server di Application Insights (Visual Studio)

Abilitare i dati di telemetria lato server di Application Insights (senza usare Visual Studio)

Segreti utente e altri provider di configurazione

Eseguire l'applicazione

Metriche attive

Abilitare le metriche attive usando il codice per qualsiasi applicazione .NET

Log ILogger

Dipendenze

Contatori delle prestazioni

EventCounter

Arricchire i dati tramite HTTP

Abilitare la telemetria lato client per le applicazioni Web

Configurare Application Insights SDK

Usare ApplicationInsightsServiceOptions

Raccomandazione di configurazione per Microsoft.ApplicationInsights.AspNetCore SDK 2.15.0 e versioni successive

Campionamento

Aggiungere TelemetryInitializer

Rimuovere TelemetryInitializer

Aggiungere processori di telemetria

Configurare o rimuovere i moduli di telemetria predefiniti

Configurare un canale di telemetria

Disabilitare la telemetria in modo dinamico

Domande frequenti

Application Insights supporta ASP.NET Core 3.1?

Come è possibile tenere traccia dei dati di telemetria non raccolti automaticamente?

Come si acquisisce il corpo della richiesta e della risposta nei dati di telemetria?

Come si personalizza la raccolta dei log ILogger?

Alcuni modelli di Visual Studio usavano il metodo di estensione UseApplicationInsights() in IWebHostBuilder per abilitare Application Insights. Questo utilizzo è ancora valido?

Sto distribuendo un'applicazione ASP.NET Core in App Web. È comunque necessario abilitare l'estensione Application Insights da App Web?

È possibile abilitare il monitoraggio di Application Insights usando strumenti come l'agente di Application Insights di Monitoraggio di Azure (in precedenza Status Monitor v2)?

Sono supportate tutte le funzionalità se si esegue l'applicazione in Linux?

Questo SDK è supportato per i servizi del ruolo di lavoro?

Qual è la procedura per disinstallare l'SDK?

Cosa viene creato quando si aggiunge Application Insights SDK?

In che modo è possibile disabilitare la correlazione dei dati di telemetria?

Risoluzione dei problemi

Testare la connettività tra l'host dell'applicazione e il servizio di inserimento

SDK open source

Note sulla versione

Passaggi successivi

Commenti e suggerimenti

Risorse aggiuntive