Configurare Application Insights SDK con ApplicationInsights.config o .xml

Application Insights .NET SDK è costituito da molti pacchetti NuGet. Il pacchetto di base fornisce l'API per l'invio di dati di telemetria ad Application Insights. Altri pacchetti forniscono moduli di telemetria e inizializzatori per tenere traccia automatica dei dati di telemetria dall'applicazione e dal relativo contesto. Modificando il file di configurazione, è possibile abilitare o disabilitare moduli di telemetria e inizializzatori. È anche possibile impostare parametri per alcuni di essi.

Nota

La documentazione seguente si basa sull'API classica di Application Insights. Il piano a lungo termine per Application Insights consiste nel raccogliere dati usando OpenTelemetry. Per altre informazioni, vedere Abilitare OpenTelemetry di Monitoraggio di Azure per le applicazioni .NET, Node.js, Python e Java.

Il file di configurazione è denominato ApplicationInsights.config o ApplicationInsights.xml. Il nome dipende dal tipo di applicazione. Viene aggiunto automaticamente al progetto quando si installa la maggior parte delle versioni dell'SDK. Per impostazione predefinita, quando si usa l'esperienza automatizzata dai progetti modello di Visual Studio che supportano Aggiungi>dati di telemetria di Application Insights, il ApplicationInsights.config file viene creato nella cartella radice del progetto. Quando viene compilato, viene copiato nella cartella bin. Viene anche aggiunto a un'app Web da Application Insights Agent in un server IIS. Il file di configurazione viene ignorato se viene usata l'estensione per i siti Web di Azure o l'estensione per macchine virtuali e set di scalabilità di macchine virtuali.

Non esiste un file equivalente per controllare l'SDK in una pagina Web.

Questo articolo descrive le sezioni visualizzate nel file di configurazione, come controllano i componenti dell'SDK e quali pacchetti NuGet caricano tali componenti.

Nota

Le ApplicationInsights.config istruzioni e .xml non si applicano a .NET Core SDK. Per configurare le applicazioni .NET Core, seguire le istruzioni in Application Insights per le applicazioni ASP.NET Core.

Moduli di telemetria (ASP.NET)

Ogni modulo di telemetria raccoglie un tipo specifico di dati e utilizza l’API principale per inviare i dati. I moduli sono installati da diversi pacchetti NuGet che aggiungono anche le linee necessarie al file .config.

Nel file di configurazione è presente un nodo per ogni modulo. Per disabilitare un modulo, eliminare il nodo o impostarlo come commento.

Verifica di dipendenza

Rilevamento delle dipendenze raccoglie la telemetria delle chiamate effettuate dall’applicazione ai database e ai database e servizi esterni. Per consentire il funzionamento di questo modulo in un server IIS, è necessario installare Application Insights Agent.

È anche possibile scrivere codice di rilevamento delle dipendenze usando l'API TrackDependency.

• Microsoft.ApplicationInsights.DependencyCollector.DependencyTrackingTelemetryModule
• Pacchetto NuGet Microsoft.ApplicationInsights.DependencyCollector

Le dipendenze possono essere raccolte automaticamente senza modificare il codice usando il collegamento basato su agente (senza codice). Per usarlo nelle app Web di Azure, abilitare l'estensione Application Insights. Per usarla in una macchina virtuale di Azure o in un set di scalabilità di macchine virtuali di Azure, abilitare l'estensione Monitoraggio applicazioni per le macchine virtuali e i set di scalabilità di macchine virtuali.

Agente di raccolta dati delle prestazioni

L'agente di raccolta delle prestazioni raccoglie i contatori delle prestazioni del sistema, ad esempio CPU, memoria e carico di rete dalle installazioni iis. È possibile specificare i contatori da raccogliere, inclusi i contatori delle prestazioni configurati manualmente.

• Microsoft.ApplicationInsights.Extensibility.PerfCounterCollector.PerformanceCollectorModule
• Pacchetto NuGet Microsoft.ApplicationInsights.PerfCounterCollector

Dati di telemetria di diagnostica di Application Insights

La DiagnosticsTelemetryModule classe segnala errori nel codice di strumentazione di Application Insights stesso. Gli esempi sono se il codice non può accedere ai contatori delle prestazioni o se ITelemetryInitializer genera un'eccezione. La telemetria di traccia rilevata da questo modulo viene visualizzata nella Ricerca diagnostica.

• Microsoft.ApplicationInsights.Extensibility.Implementation.Tracing.DiagnosticsTelemetryModule
• Microsoft.ApplicationInsights . Se si installa questo pacchetto, il file ApplicationInsights.config non viene creato automaticamente.

Modalità sviluppatore

La DeveloperModeWithDebuggerAttachedTelemetryModule classe forza Application Insights TelemetryChannel a inviare immediatamente i dati, un elemento di telemetria alla volta, quando un debugger viene collegato al processo dell'applicazione. Questa progettazione riduce la quantità di tempo tra il momento in cui l'applicazione tiene traccia dei dati di telemetria e quando viene visualizzata nel portale di Application Insights. Questo causa un costo significativo per la CPU e la larghezza di banda di rete.

• Microsoft.ApplicationInsights.WindowsServer.DeveloperModeWithDebuggerAttachedTelemetryModule
• Application Insights Windows Server

Rilevamento delle richieste Web

Il rilevamento delle richieste Web segnala il tempo di risposta e il codice di risultato delle richieste HTTP.

• Microsoft.ApplicationInsights.Web.RequestTrackingTelemetryModule
• Microsoft.ApplicationInsights.Web

Rilevamento delle eccezioni

La ExceptionTrackingTelemetryModule classe tiene traccia delle eccezioni non gestite nell'app Web. Per altre informazioni, vedere Errori ed eccezioni.

• Microsoft.ApplicationInsights.Web.ExceptionTrackingTelemetryModule.
• Pacchetto NuGet Microsoft.ApplicationInsights.Web .
• Microsoft.ApplicationInsights.WindowsServer.UnobservedExceptionTelemetryModule: tiene traccia dell'attività non osservata. Eccezioni.
• Microsoft.ApplicationInsights.WindowsServer.UnhandledExceptionTelemetryModule: tiene traccia delle eccezioni non gestite per i ruoli di lavoro, i servizi Windows e le applicazioni console.
• Application Insights Windows Server .

Rilevamento eventSource

La EventSourceTelemetryModule classe consente di configurare gli eventi EventSource da inviare ad Application Insights come tracce. Per informazioni sul rilevamento degli eventi EventSource, vedere Uso degli eventi EventSource.

• Microsoft.ApplicationInsights.EventSourceListener.EventSourceTelemetryModule
• Microsoft.ApplicationInsights.EventSourceListener

Rilevamento eventi ETW

La EtwCollectorTelemetryModule classe consente di configurare gli eventi dai provider ETW da inviare ad Application Insights come tracce. Per informazioni sul rilevamento degli eventi ETW, vedere Uso degli eventi ETW.

• Microsoft.ApplicationInsights.EtwCollector.EtwCollectorTelemetryModule
• Microsoft.ApplicationInsights.EtwCollector

Microsoft.ApplicationInsights

Il Microsoft.ApplicationInsights pacchetto fornisce l'APIdi base dell'SDK. Gli altri moduli di telemetria usano questa API. È anche possibile usarlo per definire i propri dati di telemetria.

• Non ci sono voci in ApplicationInsights.config.
• Microsoft.ApplicationInsights . Se si installa questo NuGet, non viene generato nessun file .config.

Canale di telemetria

Il canale di telemetria gestisce il buffering e la trasmissione dei dati di telemetria al servizio Application Insights.

• Microsoft.ApplicationInsights.WindowsServer.TelemetryChannel.ServerTelemetryChannel è il canale predefinito per le applicazioni Web. Memorizza nel buffer i dati in memoria e usa meccanismi di ripetizione dei tentativi e archiviazione su disco locale per un recapito più affidabile dei dati di telemetria.
• Microsoft.ApplicationInsights.InMemoryChannel è un canale di telemetria leggero. Viene usato se non è configurato alcun altro canale.

Inizializzatori di telemetria (ASP.NET)

Gli inizializzatori di telemetria impostano proprietà di contesto che vengono inviate insieme ad ogni elemento di telemetria.

E’ possibile scrivere i propri inizializzatori per impostare proprietà di contesto.

Gli inizializzatori standard sono tutti impostati dai pacchetti NuGet Web o WindowsServer:

• AccountIdTelemetryInitializer imposta la AccountId proprietà .

• AuthenticatedUserIdTelemetryInitializer imposta la AuthenticatedUserId proprietà come impostata da JavaScript SDK.

• AzureRoleEnvironmentTelemetryInitializer aggiorna le proprietà RoleName e RoleInstance del contesto Device per tutti gli elementi di telemetria con le informazioni estratte dall'ambiente di runtime di Azure.

• BuildInfoConfigComponentVersionTelemetryInitializer aggiorna la proprietà Version del contesto Component per tutti gli elementi di telemetria con il valore estratto dal file BuildInfo.config prodotto dalla compilazione MS.

• ClientIpHeaderTelemetryInitializer aggiorna la proprietà Ip del contesto Location di tutti gli elementi di telemetria in base all'intestazione HTTP X-Forwarded-For della richiesta.

• DeviceTelemetryInitializer aggiorna le proprietà seguenti del contesto Device per tutti gli elementi di telemetria.

  • Type è impostato su PC.
  • Id viene impostato sul nome di dominio del computer in cui è in esecuzione l'applicazione Web.
  • OemName è impostato sul valore estratto dal Win32_ComputerSystem.Manufacturer campo tramite WMI.
  • Model è impostato sul valore estratto dal Win32_ComputerSystem.Model campo tramite WMI.
  • NetworkType è impostato sul valore estratto dalla NetworkInterface proprietà .
  • Language è impostato sul nome della CurrentCulture proprietà.

• DomainNameRoleInstanceTelemetryInitializer aggiorna la proprietà RoleInstance del contesto Device per tutti gli elementi di telemetria con il nome di dominio del computer in cui è in esecuzione l'applicazione Web.

• OperationNameTelemetryInitializer aggiorna la Name proprietà di RequestTelemetry e la Name proprietà del Operation contesto di tutti gli elementi di telemetria in base al metodo HTTP e i nomi del controller MVC ASP.NET e dell'azione richiamati per elaborare la richiesta.

• OperationIdTelemetryInitializer o OperationCorrelationTelemetryInitializer aggiorna la proprietà di contesto Operation.Id di tutti gli elementi di telemetria rilevati durante la gestione di una richiesta con il RequestTelemetry.Id generato automaticamente.

• SessionTelemetryInitializer aggiorna la Id proprietà del Session contesto per tutti gli elementi di telemetria con valore estratto dal ai_session cookie generato dal ApplicationInsights codice di strumentazione JavaScript in esecuzione nel browser dell'utente.

• SyntheticTelemetryInitializer o SyntheticUserAgentTelemetryInitializer aggiorna le Userproprietà di contesto , Sessione Operation di tutti gli elementi di telemetria rilevati durante la gestione di una richiesta da un'origine sintetica, ad esempio un test di disponibilità o un bot del motore di ricerca. Per impostazione predefinita, Esplora metriche non visualizza i dati di telemetria sintetici.

  <Filters> imposta le proprietà di identificazione delle richieste.

• UserTelemetryInitializer aggiorna le Id proprietà e AcquisitionDate del contesto per tutti gli elementi di User telemetria con valori estratti dal ai_user cookie generato dal codice di strumentazione JavaScript di Application Insights in esecuzione nel browser dell'utente.

• WebTestTelemetryInitializer imposta l'ID utente, l'ID sessione e le proprietà di origine sintetica per le richieste HTTP provenienti dai test di disponibilità. <Filters> imposta le proprietà di identificazione delle richieste.

Per le applicazioni .NET in esecuzione in Azure Service Fabric, è possibile includere il Microsoft.ApplicationInsights.ServiceFabric pacchetto NuGet. Questo pacchetto include una FabricTelemetryInitializer proprietà che aggiunge proprietà di Service Fabric agli elementi di telemetria. Per ulteriori informazioni, vedere la pagina GitHub sulle proprietà aggiunte dal pacchetto NuGet.

Processori di telemetria (ASP.NET)

I processori di telemetria possono filtrare e modificare ogni elemento di telemetria prima che venga inviato dall'SDK al portale.

E’ possibile scrivere i propri processori di telemetria.

Processore di telemetria di campionamento adattivo (da 2.0.0-beta3)

Questa funzionalità è abilitata per impostazione predefinita. Se l'app invia dati di telemetria considerevoli, questo processore lo rimuove.

    <TelemetryProcessors>
      <Add Type="Microsoft.ApplicationInsights.WindowsServer.TelemetryChannel.AdaptiveSamplingTelemetryProcessor, Microsoft.AI.ServerTelemetryChannel">
        <MaxTelemetryItemsPerSecond>5</MaxTelemetryItemsPerSecond>
      </Add>
    </TelemetryProcessors>

Il parametro fornisce la destinazione che l'algoritmo tenta di ottenere. Ogni istanza dell'SDK funziona in modo indipendente. Pertanto, se il server è un cluster di più computer, il volume effettivo dei dati di telemetria verrà moltiplicato di conseguenza.

Altre informazioni sul campionamento.

Processore di telemetria di campionamento adattivo (da 2.0.0-beta1)

È disponibile anche un processore di telemetria di campionamento standard (dalla versione 2.0.1):

    <TelemetryProcessors>
     <Add Type="Microsoft.ApplicationInsights.WindowsServer.TelemetryChannel.SamplingTelemetryProcessor, Microsoft.AI.ServerTelemetryChannel">

     <!-- Set a percentage close to 100/N where N is an integer. -->
     <!-- E.g. 50 (=100/2), 33.33 (=100/3), 25 (=100/4), 20, 1 (=100/100), 0.1 (=100/1000) -->
     <SamplingPercentage>10</SamplingPercentage>
     </Add>
   </TelemetryProcessors>

ConnectionString

Vedere stringa di connessione esempi di codice.

InstrumentationKey

Nota

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

Questa impostazione determina la risorsa di Application Insights in cui vengono visualizzati i dati. In genere, si crea una risorsa separata, con una chiave separata, per ognuna delle applicazioni.

Se ad esempio si desidera impostare la chiave in modo dinamico, ad esempio se si vogliono inviare risultati dall'applicazione a risorse diverse, è possibile omettere la chiave dal file di configurazione e impostarla nel codice.

Per impostare la chiave per tutte le istanze di , inclusi i moduli di TelemetryClienttelemetria standard, eseguire questo passaggio in un metodo di inizializzazione, ad esempio global.aspx.cs in un servizio ASP.NET:

using Microsoft.ApplicationInsights.Extensibility;
using Microsoft.ApplicationInsights;

    protected void Application_Start()
    {
        TelemetryConfiguration configuration = TelemetryConfiguration.CreateDefault();
        configuration.InstrumentationKey = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx";
        var telemetryClient = new TelemetryClient(configuration);

Se si vuole inviare un set specifico di eventi a una risorsa diversa, è possibile impostare la chiave per un client di telemetria specifico:

    var tc = new TelemetryClient();
    tc.Context.InstrumentationKey = "----- my key ----";
    tc.TrackEvent("myEvent");
    // ...

Per ottenere una nuova chiave, creare una nuova risorsa nel portale di Application Insights.

Provider ApplicationId

Il provider è disponibile a partire dalla versione 2.6.0.

Lo scopo di questo provider è cercare un ID applicazione basato su una chiave di strumentazione. L'ID applicazione è incluso in RequestTelemetry e DependencyTelemetry viene usato per determinare la correlazione nel portale.

Questa funzionalità è disponibile impostando TelemetryConfiguration.ApplicationIdProvider nel codice o nel file di configurazione.

Interfaccia: IApplicationIdProvider

public interface IApplicationIdProvider
{
    bool TryGetApplicationId(string instrumentationKey, out string applicationId);
}

Sono disponibili due implementazioni in Microsoft.ApplicationInsights SDK: ApplicationInsightsApplicationIdProvider e DictionaryApplicationIdProvider.

ApplicationInsightsApplicationIdProvider

Questo wrapper è per l'API Profilo. Limita le richieste e i risultati nella cache.

Questo provider viene aggiunto al file di configurazione quando si installa Microsoft.ApplicationInsights.DependencyCollector o Microsoft.ApplicationInsights.Web.

Questa classe ha una proprietà ProfileQueryEndpoint facoltativa. Per impostazione predefinita, è impostato su https://dc.services.visualstudio.com/api/profiles/{0}/appId. Se è necessario configurare un proxy per questa configurazione, è consigliabile eseguire il proxy dell'indirizzo di base e includere "/api/profiles/{0}/appId". Un {0} oggetto viene sostituito in fase di esecuzione per richiesta con la chiave di strumentazione.

Configurazione di esempio tramite ApplicationInsights.config

<ApplicationInsights>
    ...
    <ApplicationIdProvider Type="Microsoft.ApplicationInsights.Extensibility.Implementation.ApplicationId.ApplicationInsightsApplicationIdProvider, Microsoft.ApplicationInsights">
        <ProfileQueryEndpoint>https://dc.services.visualstudio.com/api/profiles/{0}/appId</ProfileQueryEndpoint>
    </ApplicationIdProvider>
    ...
</ApplicationInsights>

Esempio di configurazione tramite codice

TelemetryConfiguration.Active.ApplicationIdProvider = new ApplicationInsightsApplicationIdProvider();

DictionaryApplicationIdProvider

Questo provider statico si basa sulle coppie chiave/ID applicazione di strumentazione configurate.

Questa classe ha la Defined proprietà , ovvero una Dictionary<string,string> delle coppie chiave/ID applicazione di strumentazione.

Questa classe ha la proprietà Nextfacoltativa , che può essere usata per configurare un altro provider da usare quando viene richiesta una chiave di strumentazione che non esiste nella configurazione.

Configurazione di esempio tramite ApplicationInsights.config

<ApplicationInsights>
    ...
    <ApplicationIdProvider Type="Microsoft.ApplicationInsights.Extensibility.Implementation.ApplicationId.DictionaryApplicationIdProvider, Microsoft.ApplicationInsights">
        <Defined>
            <Type key="InstrumentationKey_1" value="ApplicationId_1"/>
            <Type key="InstrumentationKey_2" value="ApplicationId_2"/>
        </Defined>
        <Next Type="Microsoft.ApplicationInsights.Extensibility.Implementation.ApplicationId.ApplicationInsightsApplicationIdProvider, Microsoft.ApplicationInsights" />
    </ApplicationIdProvider>
    ...
</ApplicationInsights>

Esempio di configurazione tramite codice

TelemetryConfiguration.Active.ApplicationIdProvider = new DictionaryApplicationIdProvider{
 Defined = new Dictionary<string, string>
    {
        {"InstrumentationKey_1", "ApplicationId_1"},
        {"InstrumentationKey_2", "ApplicationId_2"}
    }
};

Configurare la raccolta di snapshot per le applicazioni ASP.NET

Configurare una raccolta snapshot per le applicazioni ASP.NET.

Passaggi successivi

Altre informazioni sull'API