Configurare Application Insights SDK con ApplicationInsights.config o .xml

  • Articolo

Application Insights .NET SDK è costituito da numerosi pacchetti NuGet. Il pacchetto di base fornisce l'API per l'invio di dati di telemetria ad Application Insights. Altri pacchetti forniscono moduli e inizializzatori di telemetria per il rilevamento automatico dei dati di telemetria dall'applicazione e dal rispettivo 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 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.

Il file di configurazione è denominato ApplicationInsights.config o ApplicationInsights.xml. Il nome dipende dal tipo di applicazione. Viene aggiunto automaticamente al progetto quando si installano alcune versioni dell'SDK. Per impostazione predefinita, quando si usa l'esperienza automatizzata dai progetti modello di Visual Studio che supportano Aggiungi>Application Insights Telemetry, il file ApplicationInsights.config viene creato nella cartella radice del progetto. Quando viene compilato, viene copiato nella cartella di collocazione. 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 di Azure.

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

Questo articolo illustra le sezioni visibili nel file di configurazione, il modo in cui esse controllano i componenti SDK, e quali pacchetti NuGet caricano questi componenti.

Nota

Le istruzioni ApplicationInsights.config 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 personalizzato di monitoraggio delle dipendenze mediante l'API TrackDependency.

Le dipendenze possono essere raccolte automaticamente senza modificare il codice usando il collegamento basato su agente (senza codice). Per usarlo nelle app Web, 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 di prestazioni raccoglie contatori delle prestazioni di sistema come CPU, memoria e rete caricate dalle istallazioni IIS. È possibile specificare quali contatori raccogliere, inclusi i contatori delle prestazioni installati.

Telemetria delle diagnostiche Application Insights

La classe DiagnosticsTelemetryModule segnala errori nel codice di strumentazione stesso di Application Insights. Alcuni esempi includono 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 classe DeveloperModeWithDebuggerAttachedTelemetryModule impone a TelemetryChannel di Application Insights di inviare immediatamente i dati, un elemento di telemetria alla volta, quando un debugger viene collegato al processo dell'applicazione. Questo modello permette di ridurre la quantità di tempo tra il momento in cui l'applicazione rileva i dati di telemetria e il momento in cui vengono visualizzati nel portale di Application Insights. Questo causa un costo significativo per la CPU e la larghezza di banda di rete.

Rilevamento delle richieste web

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

Rilevamento delle eccezioni

La classe ExceptionTrackingTelemetryModule rileva le 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: rileva le eccezioni non gestite per i ruoli di lavoro, servizi Windows e applicazioni della console.
  • Application Insights Windows Server .

Rilevamento EventSource

La classe EventSourceTelemetryModule consente di configurare eventi EventSource da inviare ad Application Insights come tracce. Per informazioni su eventi EventSource di rilevamento, vedere Using EventSource Events (uso degli eventi EventSource).

Registrazione degli eventi ETW

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

Microsoft.ApplicationInsights

Il pacchetto Microsoft.ApplicationInsights fornisce l'API principale dell'SDK. Gli altri moduli di telemetria usano questa API. È anche possibile usarla 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 i buffering e la trasmissione della 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 dal Web o dai pacchetti NuGet WindowsServer:

  • AccountIdTelemetryInitializer imposta la proprietà AccountId.

  • AuthenticatedUserIdTelemetryInitializer imposta la proprietà AuthenticatedUserId 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 campo Win32_ComputerSystem.Manufacturer mediante WMI.
    • Model è impostato sul valore estratto dal campo Win32_ComputerSystem.Model mediante WMI.
    • NetworkType è impostato sul valore estratto dalla proprietà NetworkInterface.
    • Language è impostato sul nome della proprietà CurrentCulture.

  • 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 proprietà Name di RequestTelemetry e la proprietà Name del contesto Operation di tutti gli elementi di telemetria in base al metodo HTTP, e i nomi del controller MVC ASP.NET e l'azione richiamata 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 proprietà Id del contesto Session per tutti gli elementi di telemetria con il valore estratto dal cookie ai_session generato dal codice di strumentazione JavaScript di ApplicationInsights in esecuzione nel browser dell'utente.

  • SyntheticTelemetryInitializer o SyntheticUserAgentTelemetryInitializer aggiorna le proprietà di contesto User, Session e 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 robot del motore di ricerca. Per impostazione predefinita, esplora metriche non mostra la telemetria sintetica.

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

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

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

Per le applicazioni .NET in esecuzione in Service Fabric di Azure, è possibile includere il pacchetto NuGet Microsoft.ApplicationInsights.ServiceFabric. Questo pacchetto include una proprietà FabricTelemetryInitializer, che aggiunge le proprietà di Service Fabric per gli 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 ciascun elemento di telemetria prima di inviarlo dal 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 numerosi dati di telemetria, questo processore ne rimuove alcuni.


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

È inoltre disponibile un processore di telemetria di campionamento standard (da 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 esempi di codice della stringa di connessione.

InstrumentationKey

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à.

Queste impostazioni determinano la risorsa di Application Insights in cui vengono visualizzati i dati. In genere, viene creata una risorsa separata, con una chiave separata, per ognuna delle applicazioni.

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

Per impostare la chiave per tutte le istanze di TelemetryClient, inclusi i moduli di telemetria 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 oggetto 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 è quello di cercare un ID applicazione in base a 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);
}

Vengono fornite due implementazioni nell'SDK Microsoft.ApplicationInsights: ApplicationInsightsApplicationIdProvider e DictionaryApplicationIdProvider.

ApplicationInsightsApplicationIdProvider

Questo wrapper è per l'API del 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, questo valore è 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} viene sostituito in fase di esecuzione per ogni 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>

Configurazione di esempio 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 proprietà Defined, ovvero un Dictionary<string,string> delle coppie chiave/ID applicazione di strumentazione.

Questa classe ha la proprietà Next facoltativa 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>

Configurazione di esempio 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 di snapshot per le applicazioni ASP.NET.

Passaggi successivi

Altre informazioni sull'API