Monitorare applicazioni e servizi .NET con Application Insights (API classica)

Questo articolo illustra come abilitare e configurare Application Insights per applicazioni ASP.NET, ASP.NET Core e Worker Service (non HTTP). Application Insights può raccogliere dalle app i dati di telemetria seguenti:

Scenari supportati

Aggiungere Application Insights

Prerequisiti

Creare un'applicazione Web di base

Se non si dispone ancora di un'applicazione Web funzionante, è possibile usare le indicazioni seguenti per crearne una.

Aggiungere automaticamente Application Insights (Visual Studio)

Questa sezione illustra l'aggiunta automatica di Application Insights a un'app Web basata su modello.

Aggiungere Application Insights manualmente (senza Visual Studio)

Questa sezione illustra l'aggiunta manuale di Application Insights a un'app Web basata su modelli.

Verificare che Application Insights riceva i dati di telemetria

Configurare i dati di telemetria

Contenuto della sezione

• Metriche attive
• Tracce (log)
• Traccia distribuita
• Dipendenze
• Eccezioni
• Metriche personalizzate
• Operazioni personalizzate

Metriche in tempo reale

È 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

using Microsoft.ApplicationInsights;
using Microsoft.ApplicationInsights.Extensibility;
using Microsoft.ApplicationInsights.Extensibility.PerfCounterCollector.QuickPulse;
using System;
using System.Threading.Tasks;

namespace LiveMetricsDemo
{
    class Program
    {
        static void Main(string[] args)
        {
            // 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();
            }
        }
    }
}

using Microsoft.ApplicationInsights;
using Microsoft.ApplicationInsights.Extensibility;
using Microsoft.ApplicationInsights.Extensibility.PerfCounterCollector.QuickPulse;

// Create a TelemetryConfiguration instance.
TelemetryConfiguration config = TelemetryConfiguration.CreateDefault();
config.ConnectionString = "InstrumentationKey=00000000-0000-0000-0000-000000000000";
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();
}

{
  "Logging": {
    "LogLevel": {
      "Default": "Warning"
    },
    "ApplicationInsights": {
      "LogLevel": {
        "Default": "Information"
      }
    }
  }
}

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

Tracce (log)

Questa sezione illustra come inviare i log di traccia diagnostica da ASP.NET o ASP.NET applicazioni Core ad Application Insights e quindi esplorare o cercare tali log nel portale.

È possibile usare i log di traccia per identificare le tracce associate a ogni richiesta utente e correlarle con altri eventi ed eccezioni.

Application Insights acquisisce i log da ASP.NET Core e da altre app .NET tramite ILogger e dai ASP.NET classici (.NET Framework) tramite l'SDK e gli adattatori classici.

<configuration>
  <system.diagnostics>
    <trace>
      <listeners>
        <add name="myAppInsightsListener"
             type="Microsoft.ApplicationInsights.TraceListener.ApplicationInsightsTraceListener, Microsoft.ApplicationInsights.TraceListener" />
      </listeners>
    </trace>
  </system.diagnostics>
</configuration>

Installazione manuale

Usare questo metodo se il tipo di progetto non è supportato dal programma di installazione di Application Insights (ad esempio, alcuni scenari desktop/console) o se si preferisce un controllo esplicito a livello di pacchetto.

1. In Esplora soluzioni fare clic con il pulsante destro del mouse sul progetto e scegliere Gestisci pacchetti NuGet.

2. Effettua una ricerca di Application Insights.

3. Selezionare uno dei pacchetti seguenti:

   • ILogger: Microsoft.Extensions.Logging.ApplicationInsights
   • System.Diagnostics: Microsoft.ApplicationInsights.TraceListener
   • log4net: NuGet Log4Net bannerMicrosoft.ApplicationInsights.Log4NetAppender
   • NLog: Microsoft.ApplicationInsights.NLogTarget
   • Microsoft.ApplicationInsights.EventSourceListener
   • Microsoft.ApplicationInsights.DiagnosticSourceListener
   • Microsoft.ApplicationInsights.EtwCollector

Il pacchetto NuGet installa gli assembly necessari e modifica web.config o app.config, se applicabile.

Istruzioni di installazione:

using Microsoft.Extensions.Logging.ApplicationInsights;

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.

builder.Services.AddControllers();
// Learn more about configuring Swagger/OpenAPI at https://aka.ms/aspnetcore/swashbuckle
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

builder.Logging.AddApplicationInsights(
        configureTelemetryConfiguration: (config) => 
            config.ConnectionString = builder.Configuration.GetConnectionString("APPLICATIONINSIGHTS_CONNECTION_STRING"),
            configureApplicationInsightsLoggerOptions: (options) => { }
    );

builder.Logging.AddFilter<ApplicationInsightsLoggerProvider>("your-category", LogLevel.Trace);

var app = builder.Build();

// Configure the HTTP request pipeline.
if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();
}

app.UseHttpsRedirection();

app.UseAuthorization();

app.MapControllers();

app.Run();

public class ValuesController : ControllerBase
{
    private readonly ILogger _logger;

    public ValuesController(ILogger<ValuesController> logger)
    {
        _logger = logger;
    }

    [HttpGet]
    public ActionResult<IEnumerable<string>> Get()
    {
        _logger.LogWarning("An example of a Warning trace..");
        _logger.LogError("An example of an Error level message");

        return new string[] { "value1", "value2" };
    }
}

System.Diagnostics.Trace.TraceWarning("Slow response - database01");

    logger.Warn("Slow response - database01");

    <Add Type="Microsoft.ApplicationInsights.EtwCollector.EtwCollectorTelemetryModule, Microsoft.ApplicationInsights.EtwCollector">
      <Sources>
        <Add ProviderName="MyCompanyEventSourceName" Level="Verbose" />
      </Sources>
    </Add>

Usare direttamente l'API di traccia

È possibile chiamare direttamente l'API di traccia di Application Insights. Gli adattatori di registrazione usano questa API. Per esempio:

TelemetryConfiguration configuration = TelemetryConfiguration.CreateDefault();
var telemetryClient = new TelemetryClient(configuration);
telemetryClient.TrackTrace("Slow response - database01");

Un vantaggio di TrackTrace è che è possibile inserire dati relativamente lunghi nel messaggio. Ad esempio, è possibile codificare i dati POST in questa posizione.

È anche possibile aggiungere un livello di gravità al messaggio. Analogamente ad altri dati di telemetria, è possibile aggiungere valori di proprietà per filtrare o cercare set di tracce diversi. Per esempio:

TelemetryConfiguration configuration = TelemetryConfiguration.CreateDefault();
var telemetryClient = new TelemetryClient(configuration);
telemetryClient.TrackTrace("Slow database response",
                            SeverityLevel.Warning,
                            new Dictionary<string, string> { { "database", "db.ID" } });

È ora possibile filtrare facilmente in Ricerca transazioni tutti i messaggi di un particolare livello di gravità correlato a un determinato database.

Applicazione console

Per aggiungere la registrazione di Application Insights alle applicazioni console, installare prima di tutto i pacchetti NuGet seguenti:

• Microsoft.Extensions.Logging.ApplicationInsights
• Microsoft.Extensions.DependencyInjection

Nell'esempio seguente viene usato il Microsoft.Extensions.Logging.ApplicationInsights pacchetto e viene illustrato il comportamento predefinito per un'applicazione console. Il Microsoft.Extensions.Logging.ApplicationInsights pacchetto deve essere usato in un'applicazione console o ogni volta che si vuole un'implementazione minima di Application Insights senza il set di funzionalità completo, ad esempio metriche, traccia distribuita, campionamento e inizializzatori di telemetria.

using Microsoft.ApplicationInsights.Channel;
using Microsoft.ApplicationInsights.Extensibility;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Logging;

using var channel = new InMemoryChannel();

try
{
    IServiceCollection services = new ServiceCollection();
    services.Configure<TelemetryConfiguration>(config => config.TelemetryChannel = channel);
    services.AddLogging(builder =>
    {
        // Only Application Insights is registered as a logger provider
        builder.AddApplicationInsights(
            configureTelemetryConfiguration: (config) => config.ConnectionString = "<YourConnectionString>",
            configureApplicationInsightsLoggerOptions: (options) => { }
        );
    });

    IServiceProvider serviceProvider = services.BuildServiceProvider();
    ILogger<Program> logger = serviceProvider.GetRequiredService<ILogger<Program>>();

    logger.LogInformation("Logger is working...");
}
finally
{
    // Explicitly call Flush() followed by Delay, as required in console apps.
    // This ensures that even if the application terminates, telemetry is sent to the back end.
    channel.Flush();

    await Task.Delay(TimeSpan.FromMilliseconds(1000));
}

Per altre informazioni, vedere Che tipo di dati di telemetria di Application Insights viene prodotto dai log ILogger? Dove è possibile visualizzare i log ILogger in Application Insights?.

Ambiti di registrazione

ApplicationInsightsLoggingProvider supporta gli ambiti di log, che sono abilitati per impostazione predefinita.

Se l'ambito è di tipo IReadOnlyCollection<KeyValuePair<string,object>>, ogni coppia chiave/valore nella raccolta viene aggiunta ai dati di telemetria di Application Insights come proprietà personalizzate. Nell'esempio seguente, i log vengono acquisiti come TraceTelemetry e hanno ("MyKey", "MyValue") nelle proprietà.

using (_logger.BeginScope(new Dictionary<string, object> { ["MyKey"] = "MyValue" }))
{
    _logger.LogError("An example of an Error level message");
}

Se viene utilizzato un altro tipo come ambito, verrà archiviato sotto la proprietà Scope nei dati di telemetria di Application Insights. Nell'esempio seguente, TraceTelemetry ha una proprietà chiamata Scope che contiene l'ambito.

using (_logger.BeginScope("hello scope"))
{
    _logger.LogError("An example of an Error level message");
}

Trova i tuoi log

Eseguire l'app in modalità di debug o distribuirla in tempo reale.

Esplora nella Ricerca Transazioni

Nel riquadro di panoramica dell'app nel portale di Application Insights selezionare Ricerca transazioni in cui è possibile:

• Filtrare in base alle tracce di log o agli elementi con proprietà specifiche.
• Esaminare in dettaglio un elemento specifico.
• Trovare altri dati di log di sistema correlati alla stessa richiesta utente (con lo stesso ID operazione).
• Salvare la configurazione di una pagina come preferito.

Esplorare i log di Monitoraggio di Azure

I Log ILogger vengono visualizzati come dati di telemetria di traccia (tabella traces in Application Insights e AppTraces in Log Analytics).

Esempio

Nel portale di Azure passare ad Application Insights ed eseguire:

traces
| where severityLevel >= 2 // 2=Warning, 1=Information, 0=Verbose
| take 50

Tracciamento distribuito

Le architetture moderne di cloud e microservizi hanno abilitato servizi semplici e indipendenti che riducono i costi aumentando la disponibilità e la velocità effettiva. Tuttavia, ha reso i sistemi generali più difficili da ragionare e eseguire il debug. Il tracciamento distribuito risolve questo problema fornendo un profiler delle prestazioni che funziona come le pile di chiamate nelle architetture cloud e microservizi.

Monitoraggio di Azure offre due esperienze per l'utilizzo dei dati di traccia distribuiti: la visualizzazione diagnostica delle transazioni per una singola transazione/richiesta e la visualizzazione mappa dell'applicazione per mostrare l'interazione dei sistemi.

Application Insights può monitorare ogni componente separatamente e rilevare quale componente è responsabile di errori o riduzione delle prestazioni usando la correlazione di telemetria distribuita. Questo articolo illustra il modello di dati, le tecniche di propagazione del contesto, i protocolli e l'implementazione di tattiche di correlazione su linguaggi e piattaforme diversi usati da Application Insights.

Abilitare la traccia distribuita tramite Application Insights utilizzando l'autoinstrumentazione o gli SDK

Gli agenti e gli SDK di Application Insights per .NET, .NET Core, Java, Node.jse JavaScript supportano la traccia distribuita in modo nativo.

Dopo avere installato e configurato la versione corretta di Application Insights SDK, le informazioni di traccia vengono raccolte automaticamente per le librerie, le tecnologie e i framework più diffusi da agenti di raccolta delle dipendenze dell'SDK automatici. L'elenco completo delle tecnologie supportate è disponibile nella documentazione sulla raccolta automatica delle dipendenze.

Qualsiasi tecnologia può anche essere rilevata manualmente con una chiamata a TrackDependency in TelemetryClient.

Modello di dati per la correlazione dei dati di telemetria

Application Insights definisce un modello di dati per la correlazione di dati di telemetria distribuita. Per associare i dati di telemetria a un'operazione logica, ogni elemento di telemetria ha un campo di contesto denominato operation_Id. Ogni elemento di telemetria nella traccia distribuita condivide questo identificatore. Pertanto, anche se si perdono i dati di telemetria da un singolo livello, è comunque possibile associare i dati di telemetria segnalati da altri componenti.

Un'operazione logica distribuita è in genere costituita da un set di operazioni più piccole elaborate da uno dei componenti. I dati di telemetria delle richieste definiscono queste operazioni. Ogni elemento di telemetria della richiesta ha il proprio id, che lo identifica in modo globale e univoco. E tutti gli elementi di telemetria, ad esempio tracce ed eccezioni, associati alla richiesta devono impostare su operation_parentId il valore della richiesta id.

La telemetria delle dipendenze rappresenta ogni operazione in uscita, ad esempio una chiamata HTTP a un altro componente. Definisce anche il proprio id, un elemento univoco a livello globale. La telemetria delle richieste, avviata dalla chiamata di dipendenza, usa questo id come operation_parentId.

È possibile compilare una vista dell'operazione logica distribuita usando operation_Id, operation_parentIde request.id con dependency.id. Questi campi definiscono anche l'ordine di causalità delle chiamate di telemetria.

In un ambiente di microservizi, le tracce dei componenti possono passare a elementi di archiviazione diversi. Ogni componente può avere una propria stringa di connessione in Application Insights. Per ottenere dati di telemetria per l'operazione logica, Application Insights esegue query sui dati da ogni elemento di archiviazione.

Quando il numero di elementi di archiviazione è grande, è necessario un suggerimento su dove cercare successivamente. Il modello di dati di Application Insights definisce due campi per risolvere questo problema: request.source e dependency.target. Il primo campo identifica il componente che ha avviato la richiesta di dipendenza. Il secondo campo identifica il componente che ha restituito la risposta della chiamata di dipendenza.

Per informazioni sull'esecuzione di query da più istanze diverse, vedere Eseguire query sui dati tra aree di lavoro, applicazioni e risorse di Log Analytics in Monitoraggio di Azure.

Example

Esaminiamo un esempio. Un'applicazione denominata Stock Prices mostra il prezzo di mercato corrente di un titolo usando un'API esterna denominata Stock. L'applicazione Prezzi azionari ha una pagina denominata Pagina stock visualizzata dal Web browser client tramite GET /Home/Stock. L'applicazione esegue una query sull'API Stock usando la chiamata GET /api/stock/valueHTTP .

È possibile analizzare i dati di telemetria risultanti eseguendo una query:

(requests | union dependencies | union pageViews)
| where operation_Id == "STYz"
| project timestamp, itemType, name, id, operation_ParentId, operation_Id

Nei risultati tutti gli elementi di telemetria condividono la radice operation_Id. Quando viene effettuata una chiamata Ajax dalla pagina, viene assegnato un nuovo ID univoco (qJSXU) ai dati di telemetria delle dipendenze e l'ID di pageView viene usato come operation_ParentId. La richiesta del server usa quindi l'ID Ajax come operation_ParentId.

Quando la chiamata GET /api/stock/value viene effettuata a un servizio esterno, è necessario conoscere l'identità del server in modo da poter impostare il dependency.target campo in modo appropriato. Quando il servizio esterno non supporta il monitoraggio, target viene impostato sul nome host del servizio. Un esempio è stock-prices-api.com. Tuttavia, se il servizio si identifica restituendo un'intestazione HTTP predefinita, target contiene l'identità del servizio che consente ad Application Insights di compilare una traccia distribuita eseguendo query sui dati di telemetria da tale servizio.

Intestazioni di correlazione utilizzando W3C TraceContext

Application Insights esegue la transizione a W3C Trace-Context, che definisce:

• traceparent: Trasporta l'ID operativo univoco globale e l'identificatore univoco della chiamata.
• tracestate: contiene il contesto di tracciamento specifico del sistema.

La versione più recente di Application Insights SDK supporta il protocollo Trace-Context, ma potrebbe essere necessario acconsentire esplicitamente. La retrocompatibilità con il protocollo di correlazione precedente supportato dall'SDK di Application Insights è mantenuta.

Il protocollo HTTP di correlazione, detto anche Request-Id, è deprecato. Questo protocollo definisce due intestazioni:

• Request-Id: porta l'ID univoco globale della chiamata.
• Correlation-Context: contiene la raccolta di coppie nome-valore delle proprietà di tracciamento distribuito.

Application Insights definisce anche l'estensione per il protocollo HTTP di correlazione. Usa le coppie nome-valore Request-Context per propagare la raccolta di proprietà usate dal chiamante o dal destinatario della chiamata. Il SDK di Application Insights utilizza questo header per impostare i campi dependency.target e request.source.

I modelli di dati W3C Trace-Context e Application Insights sono mappati nel modo seguente:

Per altre informazioni, vedere Modello di dati di telemetria di Application Insights.

Abilitare il supporto per la traccia distribuita W3C

La traccia distribuita basata su W3C TraceContext è abilitata per impostazione predefinita in tutti gli SDK recenti di .NET Framework/.NET Core, insieme alla compatibilità con le versioni precedenti con il protocollo legacy Request-Id .

Correlazione dei dati di telemetria

La correlazione viene gestita automaticamente durante l'integrazione di un'app. Non sono necessarie azioni speciali.

Il runtime .NET supporta la distribuzione con l'aiuto di Activity e DiagnosticSource

Application Insights .NET SDK usa DiagnosticSource e Activity per raccogliere e correlare i dati di telemetria.

Dipendenze

Dipendenze rilevate automaticamente

Gli SDK di Application Insights per .NET e .NET Core vengono forniti con DependencyTrackingTelemetryModule, ovvero un modulo di telemetria che raccoglie automaticamente le dipendenze. Il modulo DependencyTrackingTelemetryModule viene fornito come pacchetto NuGet Microsoft.ApplicationInsights.DependencyCollector e usato automaticamente quando si usa il Microsoft.ApplicationInsights.Web pacchetto NuGet o il Microsoft.ApplicationInsights.AspNetCore pacchetto NuGet.

Attualmente, DependencyTrackingTelemetryModule tiene traccia delle dipendenze seguenti automaticamente:

Se la dipendenza non viene selezionata automaticamente, è possibile monitorarla manualmente con una chiamata di dipendenza di rilevamento.

Per altre informazioni sul funzionamento del rilevamento delle dipendenze, vedere Rilevamento delle dipendenze in Application Insights.

Configurare il rilevamento automatico delle dipendenze nelle app console

Per tenere traccia automaticamente delle dipendenze dalle app console .NET, installare il pacchetto NuGet Microsoft.ApplicationInsights.DependencyCollector e inizializzare DependencyTrackingTelemetryModule:

    DependencyTrackingTelemetryModule depModule = new DependencyTrackingTelemetryModule();
    depModule.Initialize(TelemetryConfiguration.Active);

Rilevamento manuale delle dipendenze

Gli esempi seguenti di dipendenze, che non vengono raccolti automaticamente, richiedono il rilevamento manuale:

• viene tenuta automaticamente traccia di Azure Cosmos DB solo se è usato HTTP/HTTPS. La modalità TCP non viene acquisita automaticamente da Application Insights per le versioni dell'SDK precedenti a 2.22.0-Beta1.
• Redis

Per tali dipendenze non raccolte automaticamente dall'SDK, è possibile tenerne traccia manualmente usando l'API TrackDependency usata dai moduli di raccolta automatica standard.

Esempio

Se si compila il codice con un assembly che non è stato scritto manualmente, è possibile eseguire tutte le chiamate. Questo scenario consente di scoprire quale contributo apporta ai tempi di risposta.

Per visualizzare i dati nei grafici relativi alle dipendenze in Application Insights, inviarli mediante TrackDependency:

    var startTime = DateTime.UtcNow;
    var timer = System.Diagnostics.Stopwatch.StartNew();
    try
    {
        // making dependency call
        success = dependency.Call();
    }
    finally
    {
        timer.Stop();
        telemetryClient.TrackDependency("myDependencyType", "myDependencyCall", "myDependencyData", startTime, timer.Elapsed, success);
    }

In alternativa, TelemetryClient fornisce i metodi di estensione StartOperation e StopOperation, che possono essere usati per tenere traccia manualmente delle dipendenze, come illustrato in Rilevamento delle dipendenze in uscita.

Disabilitazione del modulo di rilevamento delle dipendenze standard

Per altre informazioni, vedere Moduli di telemetria.

Rilevamento SQL avanzato per ottenere la query SQL completa

Per le chiamate SQL, il nome del server e del database viene sempre raccolto e archiviato come nome dell'oggetto raccolto DependencyTelemetry. Un altro campo, denominato dati, può contenere il testo completo della query SQL.

<TelemetryModules>
  <Add Type="Microsoft.ApplicationInsights.DependencyCollector.DependencyTrackingTelemetryModule, Microsoft.AI.DependencyCollector">
    <EnableSqlCommandTextInstrumentation>true</EnableSqlCommandTextInstrumentation>
  </Add>

services.ConfigureTelemetryModule<DependencyTrackingTelemetryModule>((module, o) => { module. EnableSqlCommandTextInstrumentation = true; });

Nei casi precedenti, il modo corretto per convalidare che il motore di strumentazione sia installato correttamente è convalidando che la versione SDK di raccolta DependencyTelemetry è rddp. L'uso di rdddsd o rddf indica che le dipendenze vengono raccolte tramite callback DiagnosticSource o EventSource, quindi la query SQL completa non viene acquisita.

Exceptions

Le eccezioni nelle applicazioni Web possono essere segnalate con Application Insights. È possibile correlare le richieste non riuscite con le eccezioni e altri eventi sia nel client che nel server, in modo da poter diagnosticare rapidamente le cause. Questa sezione illustra come configurare la segnalazione delle eccezioni, segnalare le eccezioni in modo esplicito, diagnosticare gli errori e altro ancora.

Configurare la creazione di report sulle eccezioni

È possibile configurare Application Insights per segnalare le eccezioni che si verificano nel server o nel client. A seconda della piattaforma da cui dipende l'applicazione, è necessario usare l'estensione o l'SDK appropriato.

Diagnosticare errori ed eccezioni

Dati di traccia e di log personalizzati

Per ottenere dati di diagnostica specifici per l'app, è possibile inserire codice per l'invio dei propri dati di telemetria. I propri dati di log o telemetria vengono visualizzati nella ricerca diagnostica insieme alla richiesta, alla visualizzazione di pagina e ad altri dati raccolti automaticamente.

Usando Microsoft.VisualStudio.ApplicationInsights.TelemetryClient, sono disponibili diverse API:

• TelemetryClient.TrackEvent viene usato in genere per il monitoraggio dei modelli di utilizzo, ma i dati inviati vengono visualizzati anche in Eventi personalizzati nella ricerca diagnostica. Gli eventi sono denominati e possono includere proprietà di stringa e metriche numeriche, in base alle quali è possibile filtrare le ricerche diagnostiche.
• TelemetryClient.TrackTrace consente di inviare dati più lunghi, ad esempio informazioni POST.
• TelemetryClient.TrackException invia i dettagli dell'eccezione, ad esempio l'analisi dello stack ad Application Insights.

Per visualizzare questi eventi, nel menu a sinistra aprire Cerca. Selezionare il menu a discesa Tipi di evento e quindi scegliere Evento personalizzato, Traccia o Eccezione.

Vedere i dati POST di una richiesta

I dettagli della richiesta non includono i dati inviati all'app in una chiamata POST. Per poter ottenere questi dati:

• Aggiungere Application Insights SDK al codice dell'app.
• Inserire il codice nell'applicazione per chiamare Microsoft.ApplicationInsights.TrackTrace(). Inviare i dati POST nel parametro del messaggio. Esiste un limite per le dimensioni consentite, quindi è consigliabile provare a inviare solo i dati essenziali.
• Quando si esamina una richiesta non riuscita, trovare le tracce associate.

Acquisire le delle eccezioni e i dati di diagnostica correlati

Per impostazione predefinita, non tutte le eccezioni che generano errori nell'app vengono visualizzate nel portale. Se si usa JavaScript SDK nelle pagine Web, vengono visualizzate eccezioni del browser. Tuttavia, la maggior parte delle eccezioni lato server vengono intercettate da IIS ed quindi è necessario aggiungere del codice per acquisirle e segnalarle.

È possibile:

• Registrare le eccezioni in modo esplicito inserendo il codice nei gestori di eccezioni per segnalare le eccezioni.
• Acquisire automaticamente le eccezioni configurando il framework di ASP.NET. Gli elementi da aggiungere variano a seconda dei diversi tipi di framework.

Segnalare le eccezioni in modo esplicito

Il modo più semplice per segnalare consiste nell'inserire una chiamata a trackException() in un gestore eccezioni.

var telemetry = new TelemetryClient();

try
{
    // ...
}
catch (Exception ex)
{
    var properties = new Dictionary<string, string>
    {
        ["Game"] = currentGame.Name
    };

    var measurements = new Dictionary<string, double>
    {
        ["Users"] = currentGame.Users.Count
    };

    // Send the exception telemetry:
    telemetry.TrackException(ex, properties, measurements);
}

try
{
    // ...
}
catch (ex)
{
    appInsights.trackException(ex, "handler loc",
    {
        Game: currentGame.Name,
        State: currentGame.State.ToString()
    });
}

I parametri delle proprietà e delle misurazioni sono facoltativi, ma sono utili per filtrare e aggiungere altre informazioni. Ad esempio, per un'app in grado di eseguire diversi giochi, è possibile trovare tutti i report di eccezione correlati a un gioco specifico. È possibile aggiungere il numero desiderato di elementi a ogni dizionario.

Eccezioni del browser

Viene segnalata la maggior parte delle eccezioni del browser.

Se la pagina Web include file di script provenienti da reti per la distribuzione di contenuti o da altri domini, verificare che il tag dello script contenga l'attributo crossorigin="anonymous" e che il server invii intestazioni CORS. Questo comportamento consente di ottenere un'analisi dello stack e i dettagli per le eccezioni JavaScript non gestite da queste risorse.

Riutilizzare il client di telemetria

Con l'inserimento delle dipendenze (DI) in .NET, il .NET SDK appropriato e la corretta configurazione di Application Insights per l'inserimento delle dipendenze, è possibile richiedere TelemetryClient come parametro del costruttore.

public class ExampleController : ApiController
{
    private readonly TelemetryClient _telemetryClient;

    public ExampleController(TelemetryClient telemetryClient)
    {
        _telemetryClient = telemetryClient;
    }
}

Nell'esempio precedente, l'oggetto TelemetryClient viene inserito nella classe ExampleController.

Web Form

Per Web Forms, il modulo HTTP può raccogliere le eccezioni quando non sono configurati reindirizzamenti con CustomErrors. Tuttavia, quando sono presenti reindirizzamenti attivi, aggiungere le righe seguenti alla funzione Application_Error in Global.asax.cs.

void Application_Error(object sender, EventArgs e)
{
    if (HttpContext.Current.IsCustomErrorEnabled &&
        Server.GetLastError () != null)
    {
        _telemetryClient.TrackException(Server.GetLastError());
    }
}

Nell'esempio precedente, _telemetryClient è una variabile con ambito classe di tipo TelemetryClient.

MVC

A partire da Application Insights Web SDK versione 2.6 (beta 3 e versioni successive), Application Insights raccoglie le eccezioni non gestite generate automaticamente nei metodi dei controller MVC 5+. Se in precedenza è stato aggiunto un gestore personalizzato per tenere traccia di tali eccezioni, è possibile rimuoverlo per evitare il doppio rilevamento delle eccezioni.

Esistono diversi scenari in cui un filtro eccezioni non riesce a gestire correttamente gli errori quando vengono generate eccezioni:

• Dai costruttori del controller
• Dai gestori di messaggi
• Durante il routing
• Durante la serializzazione del contenuto della risposta
• Durante l'avvio dell'applicazione
• Nelle attività in background

È ancora necessario tenere traccia manualmente di tutte le eccezioni gestite dall'applicazione. Le eccezioni non gestite provenienti dai controller in genere restituiscono una risposta 500 "Errore interno del server". Se tale risposta viene costruita manualmente come risultato di un'eccezione gestita o nessuna eccezione, viene rilevata nei dati di telemetria delle richieste corrispondenti con ResultCode 500. Tuttavia, l'SDK di Application Insights non è in grado di tenere traccia di un'eccezione corrispondente.

Supporto delle versioni precedenti

Se si usa MVC 4 (e versioni precedenti) di Application Insights Web SDK 2.5 (e versioni precedenti), vedere gli esempi seguenti per tenere traccia delle eccezioni.

using System;
using System.Web.Mvc;
using Microsoft.ApplicationInsights;

namespace MVC2App.Controllers
{
    [AttributeUsage(AttributeTargets.Class | AttributeTargets.Method, Inherited = true, AllowMultiple = true)]
    public class AiHandleErrorAttribute : HandleErrorAttribute
    {
        public override void OnException(ExceptionContext filterContext)
        {
            if (filterContext != null && filterContext.HttpContext != null && filterContext.Exception != null)
            {
                //The attribute should track exceptions only when CustomErrors setting is On
                //if CustomErrors is Off, exceptions will be caught by AI HTTP Module
                if (filterContext.HttpContext.IsCustomErrorEnabled)
                {   //Or reuse instance (recommended!). See note above.
                    var ai = new TelemetryClient();
                    ai.TrackException(filterContext.Exception);
                }
            }
            base.OnException(filterContext);
        }
    }
}

    namespace MVC2App.Controllers
    {
        [AiHandleError]
        public class HomeController : Controller
        {
            // Omitted for brevity
        }
    }

public class MyMvcApplication : System.Web.HttpApplication
{
    public static void RegisterGlobalFilters(GlobalFilterCollection filters)
    {
        filters.Add(new AiHandleErrorAttribute());
    }
}

public class FilterConfig
{
    public static void RegisterGlobalFilters(GlobalFilterCollection filters)
    {
        // Default replaced with the override to track unhandled exceptions
        filters.Add(new AiHandleErrorAttribute());
    }
}

API per il Web

A partire da Application Insights Web SDK versione 2.6 (beta 3 e versioni successive), Application Insights raccoglie le eccezioni non gestite generate automaticamente nei metodi dei controller per API Web 2+. Se in precedenza è stato aggiunto un gestore personalizzato per tenere traccia di tali eccezioni (come descritto nell'esempio seguente), è possibile rimuoverlo per evitare il doppio rilevamento delle eccezioni.

Esistono diversi casi in cui i filtri delle eccezioni non possono essere gestiti. Per esempio:

• Eccezioni generate dai costruttori dei controller.
• Eccezioni generate dai gestori di messaggi.
• Eccezioni generate durante il routing.
• Eccezioni generate durante la serializzazione del contenuto della risposta.
• Eccezione generata durante l'avvio dell'applicazione.
• Eccezione generata in attività in background.

È ancora necessario tenere traccia manualmente di tutte le eccezioni gestite dall'applicazione. Le eccezioni non gestite provenienti dai controller in genere restituiscono una risposta 500 "Errore interno del server". Se tale risposta viene costruita manualmente come risultato di un'eccezione gestita o nessuna eccezione, viene rilevata in una telemetria di richiesta corrispondente con ResultCode 500. Tuttavia, l'SDK di Application Insights non è in grado di tenere traccia di un'eccezione corrispondente.

Supporto delle versioni precedenti

Se si usa API Web 1 (e versioni precedenti) di Application Insights Web SDK 2.5 (e versioni precedenti), vedere gli esempi seguenti per tenere traccia delle eccezioni.

using System.Web.Http.Filters;
using Microsoft.ApplicationInsights;

namespace WebAPI.App_Start
{
    public class AiExceptionFilterAttribute : ExceptionFilterAttribute
    {
    public override void OnException(HttpActionExecutedContext actionExecutedContext)
    {
        if (actionExecutedContext != null && actionExecutedContext.Exception != null)
        {  //Or reuse instance (recommended!). See note above.
            var ai = new TelemetryClient();
            ai.TrackException(actionExecutedContext.Exception);
        }
        base.OnException(actionExecutedContext);
    }
    }
}

using System.Web.Http;
using WebApi1.x.App_Start;

namespace WebApi1.x
{
    public static class WebApiConfig
    {
        public static void Register(HttpConfiguration config)
        {
            config.Routes.MapHttpRoute(
                name: "DefaultApi",
                routeTemplate: "api/{controller}/{id}",
                defaults: new { id = RouteParameter.Optional });
    
            // ...
            config.EnableSystemDiagnosticsTracing();
    
            // Capture exceptions for Application Insights:
            config.Filters.Add(new AiExceptionFilterAttribute());
        }
    }
}

using System.Web.Http.ExceptionHandling;
using Microsoft.ApplicationInsights;

namespace ProductsAppPureWebAPI.App_Start
{
    public class AiExceptionLogger : ExceptionLogger
    {
        public override void Log(ExceptionLoggerContext context)
        {
            if (context != null && context.Exception != null)
            {
                //or reuse instance (recommended!). see note above
                var ai = new TelemetryClient();
                ai.TrackException(context.Exception);
            }
            base.Log(context);
        }
    }
}

using System.Web.Http;
using System.Web.Http.ExceptionHandling;
using ProductsAppPureWebAPI.App_Start;

namespace WebApi2WithMVC
{
    public static class WebApiConfig
    {
        public static void Register(HttpConfiguration config)
        {
            // Web API configuration and services
    
            // Web API routes
            config.MapHttpAttributeRoutes();
    
            config.Routes.MapHttpRoute(
                name: "DefaultApi",
                routeTemplate: "api/{controller}/{id}",
                defaults: new { id = RouteParameter.Optional });

            config.Services.Add(typeof(IExceptionLogger), new AiExceptionLogger());
        }
    }
}

WCF

Aggiungere una classe che estende Attribute e implementa IErrorHandler e IServiceBehavior.

    using System;
    using System.Collections.Generic;
    using System.Linq;
    using System.ServiceModel.Description;
    using System.ServiceModel.Dispatcher;
    using System.Web;
    using Microsoft.ApplicationInsights;

    namespace WcfService4.ErrorHandling
    {
      public class AiLogExceptionAttribute : Attribute, IErrorHandler, IServiceBehavior
      {
        public void AddBindingParameters(ServiceDescription serviceDescription,
            System.ServiceModel.ServiceHostBase serviceHostBase,
            System.Collections.ObjectModel.Collection<ServiceEndpoint> endpoints,
            System.ServiceModel.Channels.BindingParameterCollection bindingParameters)
        {
        }

        public void ApplyDispatchBehavior(ServiceDescription serviceDescription,
            System.ServiceModel.ServiceHostBase serviceHostBase)
        {
            foreach (ChannelDispatcher disp in serviceHostBase.ChannelDispatchers)
            {
                disp.ErrorHandlers.Add(this);
            }
        }

        public void Validate(ServiceDescription serviceDescription,
            System.ServiceModel.ServiceHostBase serviceHostBase)
        {
        }

        bool IErrorHandler.HandleError(Exception error)
        {//or reuse instance (recommended!). see note above
            var ai = new TelemetryClient();

            ai.TrackException(error);
            return false;
        }

        void IErrorHandler.ProvideFault(Exception error,
            System.ServiceModel.Channels.MessageVersion version,
            ref System.ServiceModel.Channels.Message fault)
        {
        }
      }
    }

Aggiungere l'attributo alle implementazioni del servizio:

namespace WcfService4
{
    [AiLogException]
    public class Service1 : IService1
    {
        // Omitted for brevity
    }
}

Esempio

Contatori delle prestazioni delle eccezioni

L'installazione dell'agente di Application Insights di Monitoraggio di Azure nel server permette di ottenere un grafico della frequenza delle eccezioni, misurata da .NET. Sono incluse le eccezioni .NET gestite e non gestite.

Aprire una scheda Esplora metriche e aggiungere un nuovo grafico. In Contatori delle prestazioni selezionare Frequenza eccezioni.

.NET framework calcola la frequenza contando il numero delle eccezioni in un intervallo e dividendolo per la lunghezza dell'intervallo.

Questo conteggio è diverso dal conteggio delle eccezioni calcolato dal portale di Application Insights, che conteggia i report TrackException. Gli intervalli di campionamento sono diversi e l'SDK non invia segnalazioni di TrackException per tutte le eccezioni gestite e non gestite.

Raccolta di metriche personalizzate

Gli SDK di Application Insights di Monitoraggio di Azure per .NET e .NET Core hanno due diversi metodi di raccolta di metriche personalizzate:

• Il metodo TrackMetric(), che non dispone della preaggregazione.
• Il metodo GetMetric(), che dispone della preaggregazione.

È consigliabile usare l'aggregazione, quindi TrackMetric()non è più il metodo preferito per raccogliere metriche personalizzate. Questo articolo illustra come usare il metodo GetMetric() e alcune delle motivazioni alla base del funzionamento.

Introduzione a GetMetric

Per gli esempi si userà un'applicazione di servizio di lavoro .NET Core 3.1 di base. Se si vuole replicare l'ambiente di test usato con questi esempi, seguire i passaggi da 1 a 6 nell'applicazione del servizio di lavoro .NET Core. Questi passaggi aggiungono Application Insights a un modello di progetto del servizio di lavoro di base. I concetti si applicano a qualsiasi applicazione generale in cui è possibile usare l'SDK, incluse le app Web e le app console.

Inviare metriche

Sostituire il contenuto del file worker.cs con il codice seguente:

using System;
using System.Threading;
using System.Threading.Tasks;
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Logging;
using Microsoft.ApplicationInsights;

namespace WorkerService3
{
    public class Worker : BackgroundService
    {
        private readonly ILogger<Worker> _logger;
        private TelemetryClient _telemetryClient;

        public Worker(ILogger<Worker> logger, TelemetryClient tc)
        {
            _logger = logger;
            _telemetryClient = tc;
        }

        protected override async Task ExecuteAsync(CancellationToken stoppingToken)
        {   // The following line demonstrates usages of GetMetric API.
            // Here "computersSold", a custom metric name, is being tracked with a value of 42 every second.
            while (!stoppingToken.IsCancellationRequested)
            {
                _telemetryClient.GetMetric("ComputersSold").TrackValue(42);

                _logger.LogInformation("Worker running at: {time}", DateTimeOffset.Now);
                await Task.Delay(1000, stoppingToken);
            }
        }
    }
}

Quando si esegue il codice di esempio, viene visualizzato il ciclo while in esecuzione ripetutamente senza inviare dati di telemetria nella finestra di output di Visual Studio. Un singolo elemento di telemetria viene inviato intorno al contrassegno di 60 secondi, che nel test ha un aspetto simile al seguente:

Application Insights Telemetry: {"name":"Microsoft.ApplicationInsights.Dev.00000000-0000-0000-0000-000000000000.Metric", "time":"2019-12-28T00:54:19.0000000Z",
"ikey":"00000000-0000-0000-0000-000000000000",
"tags":{"ai.application.ver":"1.0.0.0",
"ai.cloud.roleInstance":"Test-Computer-Name",
"ai.internal.sdkVersion":"m-agg2c:2.12.0-21496",
"ai.internal.nodeName":"Test-Computer-Name"},
"data":{"baseType":"MetricData",
"baseData":{"ver":2,"metrics":[{"name":"ComputersSold",
"kind":"Aggregation",
"value":1722,
"count":41,
"min":42,
"max":42,
"stdDev":0}],
"properties":{"_MS.AggregationIntervalMs":"42000",
"DeveloperMode":"true"}}}}

Questo singolo elemento di telemetria rappresenta un'aggregazione di 41 misurazioni di metriche distinte. Poiché stavamo inviando lo stesso valore più e più volte, abbiamo una deviazione standard (stDev) di 0 con valori massimi identici (max) e minimo (min). La proprietà value rappresenta una somma di tutti i singoli valori aggregati.

Se si esamina la risorsa di Application Insights nell'esperienza Log (Analytics), il singolo elemento di telemetria sarà simile allo screenshot seguente.

È anche possibile accedere ai dati di telemetria delle metriche personalizzati nella sezione Metriche del portale sia come metrica basata su log che personalizzata. Lo screenshot seguente è un esempio di metrica basata su log.

Informazioni di riferimento sulle metriche della cache per l'utilizzo a velocità effettiva elevata

I valori delle metriche possono essere osservati frequentemente in alcuni casi. Ad esempio, un servizio a velocità effettiva elevata che elabora 500 richieste al secondo potrebbe voler generare 20 metriche di telemetria per ogni richiesta. Il risultato indica il rilevamento di 10.000 valori al secondo. In questi scenari con velocità effettiva elevata, gli utenti potrebbero dover aiutare l'SDK evitando alcune ricerche.

Ad esempio, l'esempio precedente ha eseguito una ricerca per un handle per la metrica ComputersSold e quindi ha rilevato un valore osservato di 42. Al contrario, l'handle potrebbe essere memorizzato nella cache per più chiamate di traccia:

//...

        protected override async Task ExecuteAsync(CancellationToken stoppingToken)
        {
            // This is where the cache is stored to handle faster lookup
            Metric computersSold = _telemetryClient.GetMetric("ComputersSold");
            while (!stoppingToken.IsCancellationRequested)
            {

                computersSold.TrackValue(42);

                computersSold.TrackValue(142);

                _logger.LogInformation("Worker running at: {time}", DateTimeOffset.Now);
                await Task.Delay(50, stoppingToken);
            }
        }

Oltre a memorizzare nella cache l'handle delle metriche, l'esempio precedente si riduce Task.Delay anche a 50 millisecondi in modo che il ciclo venga eseguito più frequentemente. Il risultato è 772 chiamate TrackValue().

Metriche multidimensionali

Gli esempi nella sezione precedente mostrano le metriche zero-dimensionali. Le metriche possono anche essere multidimensionali. Attualmente sono supportate fino a 10 dimensioni.

Ecco un esempio di come creare una metrica unidimensionale:

//...

        protected override async Task ExecuteAsync(CancellationToken stoppingToken)
        {
            // This is an example of a metric with a single dimension.
            // FormFactor is the name of the dimension.
            Metric computersSold= _telemetryClient.GetMetric("ComputersSold", "FormFactor");

            while (!stoppingToken.IsCancellationRequested)
            {
                // The number of arguments (dimension values)
                // must match the number of dimensions specified while GetMetric.
                // Laptop, Tablet, etc are values for the dimension "FormFactor"
                computersSold.TrackValue(42, "Laptop");
                computersSold.TrackValue(20, "Tablet");
                computersSold.TrackValue(126, "Desktop");


                _logger.LogInformation("Worker running at: {time}", DateTimeOffset.Now);
                await Task.Delay(50, stoppingToken);
            }
        }

L'esecuzione del codice di esempio per almeno 60 secondi comporta l'invio di tre elementi di telemetria distinti ad Azure. Ogni elemento rappresenta l'aggregazione di uno dei tre fattori di forma. Come in precedenza, è possibile esaminare ulteriormente nella visualizzazione Log (Analytics).

In Esplora metriche:

Si noti che non è possibile suddividere la metrica in base alla nuova dimensione personalizzata o visualizzare la dimensione personalizzata con la visualizzazione delle metriche.

Per impostazione predefinita, le metriche multidimensionali all'interno di Esplora metriche non sono attivate nelle risorse di Application Insights.

Abilitare le metriche multidimensionali

Per abilitare le metriche multidimensionali per una risorsa di Application Insights, selezionare Utilizzo e costi stimati>Metriche personalizzate> Abilita avvisi sulle dimensioni delle metriche personalizzate> OK. Per altre informazioni, vedere Dimensioni e preaggregazione delle metriche personalizzate.

Dopo aver apportato questa modifica e inviato nuovi dati di telemetria multidimensionali, è possibile selezionare Applica suddivisione.

Visualizzare le aggregazioni delle metriche per ogni dimensione FormFactor.

Usare MetricIdentifier quando sono presenti più di tre dimensioni

Attualmente sono supportate 10 dimensioni. L'uso di più di tre dimensioni richiede l'uso di MetricIdentifier:

// Add "using Microsoft.ApplicationInsights.Metrics;" to use MetricIdentifier
// MetricIdentifier id = new MetricIdentifier("[metricNamespace]","[metricId],"[dim1]","[dim2]","[dim3]","[dim4]","[dim5]");
MetricIdentifier id = new MetricIdentifier("CustomMetricNamespace","ComputerSold", "FormFactor", "GraphicsCard", "MemorySpeed", "BatteryCapacity", "StorageCapacity");
Metric computersSold = _telemetryClient.GetMetric(id);
computersSold.TrackValue(110,"Laptop", "Nvidia", "DDR4", "39Wh", "1TB");

Configurazione della metrica personalizzata

Se si vuole modificare la configurazione della metrica, è necessario apportare modifiche nella posizione in cui viene inizializzata la metrica.

Nomi di dimensioni speciali

Le metriche non usano il contesto di telemetria dell'oggetto TelemetryClient usato per accedervi. L'uso di nomi di dimensioni speciali disponibili come costanti nella classe MetricDimensionNames è la soluzione migliore per questa limitazione.

Le aggregazioni di metriche inviate dalla metrica Special Operation Request Size seguente non hanno il parametro Context.Operation.Name impostato su Special Operation. Il metodo TrackMetric() o qualsiasi altro metodo TrackXXX() ha il parametro OperationName impostato correttamente su Special Operation.

        //...
        TelemetryClient specialClient;
        private static int GetCurrentRequestSize()
        {
            // Do stuff
            return 1100;
        }
        int requestSize = GetCurrentRequestSize()

        protected override async Task ExecuteAsync(CancellationToken stoppingToken)
        {
            while (!stoppingToken.IsCancellationRequested)
            {
                //...
                specialClient.Context.Operation.Name = "Special Operation";
                specialClient.GetMetric("Special Operation Request Size").TrackValue(requestSize);
                //...
            }
                   
        }

In questa circostanza, utilizzare i nomi delle dimensioni speciali elencati nella classe MetricDimensionNames per specificare i valori TelemetryContext.

Ad esempio, quando l'aggregazione di metriche risultante dall'istruzione successiva viene inviata all'endpoint cloud di Application Insights, il relativo campo dati Context.Operation.Name viene impostato su Special Operation:

_telemetryClient.GetMetric("Request Size", MetricDimensionNames.TelemetryContext.Operation.Name).TrackValue(requestSize, "Special Operation");

Il valore di questa dimensione speciale viene copiato in TelemetryContext e non viene usato come dimensione normale. Se si desidera mantenere anche una dimensione operativa per l'esplorazione normale delle metriche, è necessario creare una dimensione separata a tale scopo:

_telemetryClient.GetMetric("Request Size", "Operation Name", MetricDimensionNames.TelemetryContext.Operation.Name).TrackValue(requestSize, "Special Operation", "Special Operation");

Limite di dimensioni e serie temporali

Per impedire che il sottosistema di telemetria usi accidentalmente le risorse, è possibile controllare il numero massimo di serie di dati per metrica. I limiti predefiniti non sono più di 1.000 serie di dati totali per metrica e non più di 100 valori diversi per dimensione.

Nel contesto del limite di dimensioni e serie temporali, viene usato Metric.TrackValue(..) per assicurarsi che vengano osservati i limiti. Se i limiti sono già raggiunti, Metric.TrackValue(..) restituisce False e il valore non verrà monitorato. In caso contrario, viene restituito True. Questo comportamento è utile se i dati per una metrica provengono dall'input dell'utente.

Il costruttore MetricConfiguration accetta alcune opzioni su come gestire serie diverse all'interno della rispettiva metrica e un oggetto di una classe che implementa IMetricSeriesConfiguration che specifica il comportamento di aggregazione per ogni singola serie della metrica:

var metConfig = new MetricConfiguration(seriesCountLimit: 100, valuesPerDimensionLimit:2,
                new MetricSeriesConfigurationForMeasurement(restrictToUInt32Values: false));

Metric computersSold = _telemetryClient.GetMetric("ComputersSold", "Dimension1", "Dimension2", metConfig);

// Start tracking.
computersSold.TrackValue(100, "Dim1Value1", "Dim2Value1");
computersSold.TrackValue(100, "Dim1Value1", "Dim2Value2");

// The following call gives 3rd unique value for dimension2, which is above the limit of 2.
computersSold.TrackValue(100, "Dim1Value1", "Dim2Value3");
// The above call does not track the metric, and returns false.

• seriesCountLimit è il numero massimo di serie temporali di dati che una metrica può contenere. Quando viene raggiunto questo limite, le chiamate a TrackValue() che normalmente comportano la restituzione di una nuova serie, ora restituiscono false.
• valuesPerDimensionLimit limita il numero di valori distinti per dimensione in modo analogo.
• restrictToUInt32Values determina se devono essere rilevati solo valori integer non negativi.

Ecco un esempio di come inviare un messaggio per sapere se vengono superati i limiti limite:

if (! computersSold.TrackValue(100, "Dim1Value1", "Dim2Value3"))
{
// Add "using Microsoft.ApplicationInsights.DataContract;" to use SeverityLevel.Error
_telemetryClient.TrackTrace("Metric value not tracked as value of one of the dimension exceeded the cap. Revisit the dimensions to ensure they are within the limits",
SeverityLevel.Error);
}

Rilevamento delle operazioni personalizzate

Gli SDK di Application Insights verificano automaticamente le richieste HTTP in ingresso e le chiamate ai servizi dipendenti, come richieste HTTP e query SQL. La verifica e la correlazione di richieste e dipendenze offre visibilità sui tempi di risposta e sull'affidabilità dell'intera applicazione in tutti i microservizi che combinano questa applicazione.

Esiste una classe di modelli di applicazione che non può essere supportata in modo generico. Per il corretto monitoraggio di tali modelli, è necessaria la strumentazione manuale del codice. Questa sezione illustra alcuni modelli che potrebbero richiedere l'uso della strumentazione manuale, come l'elaborazione di code personalizzate e l'esecuzione di attività in background a lungo termine.

Questa sezione offre indicazioni su come tenere traccia delle operazioni personalizzate con Application Insights SDK.

Informazioni generali

Un'operazione è un lavoro logico eseguito da un'applicazione. Sono indicati nome, ora di avvio, durata, risultato e contesto dell'esecuzione, ad esempio nome utente, proprietà e risultato. Se l'operazione A è stata avviata dall'operazione B, l'operazione B è impostata come elemento padre per A. Un'operazione può avere un solo padre, ma può avere molte operazioni figlio. Per ulteriori informazioni sulle operazioni e la correlazione dei dati di telemetria, vedere Correlazione dei dati di telemetria di Application Insights.

Nell’SDK di Application Insights .NET l'operazione viene descritta dalla classe astratta OperationTelemetry e dai discendenti RequestTelemetry e DependencyTelemetry.

Verifica delle operazioni in ingresso

Application Insights Web SDK raccoglie automaticamente le richieste HTTP per le applicazioni ASP.NET eseguite nella pipeline di IIS e per tutte le applicazioni ASP.NET Core. Sono disponibili soluzioni supportate dalla community per altre piattaforme e altri framework. Se l'applicazione non è supportata dalle soluzioni standard o supportate dalla community, è possibile instrumentarla manualmente.

Un altro esempio che richiede la verifica personalizzata è offerto dal ruolo di lavoro che riceve gli elementi dalla coda. Per alcune code, la chiamata per aggiungere un messaggio a questa coda viene registrata come dipendenza. L'operazione generale che descrive l'elaborazione del messaggio non viene raccolta automaticamente.

Di seguito è illustrato come si può tenere traccia di queste operazioni.

A un livello elevato, l'attività consiste nel creare RequestTelemetry e impostare le proprietà note. Al termine dell'operazione, tenere traccia dei dati di telemetria. L'esempio seguente illustra questa attività.

Richiesta HTTP nell'app con self-hosting Owin

In questo esempio il contesto della traccia viene propagato in base al protocollo HTTP per la correlazione. Si deve prevedere di ricevere le intestazioni descritte qui.

public class ApplicationInsightsMiddleware : OwinMiddleware
{
    // You may create a new TelemetryConfiguration instance, reuse one you already have,
    // or fetch the instance created by Application Insights SDK.
    private readonly TelemetryConfiguration telemetryConfiguration = TelemetryConfiguration.CreateDefault();
    private readonly TelemetryClient telemetryClient = new TelemetryClient(telemetryConfiguration);
    
    public ApplicationInsightsMiddleware(OwinMiddleware next) : base(next) {}

    public override async Task Invoke(IOwinContext context)
    {
        // Let's create and start RequestTelemetry.
        var requestTelemetry = new RequestTelemetry
        {
            Name = $"{context.Request.Method} {context.Request.Uri.GetLeftPart(UriPartial.Path)}"
        };

        // If there is a Request-Id received from the upstream service, set the telemetry context accordingly.
        if (context.Request.Headers.ContainsKey("Request-Id"))
        {
            var requestId = context.Request.Headers.Get("Request-Id");
            // Get the operation ID from the Request-Id (if you follow the HTTP Protocol for Correlation).
            requestTelemetry.Context.Operation.Id = GetOperationId(requestId);
            requestTelemetry.Context.Operation.ParentId = requestId;
        }

        // StartOperation is a helper method that allows correlation of 
        // current operations with nested operations/telemetry
        // and initializes start time and duration on telemetry items.
        var operation = telemetryClient.StartOperation(requestTelemetry);

        // Process the request.
        try
        {
            await Next.Invoke(context);
        }
        catch (Exception e)
        {
            requestTelemetry.Success = false;
            requestTelemetry.ResponseCode;
            telemetryClient.TrackException(e);
            throw;
        }
        finally
        {
            // Update status code and success as appropriate.
            if (context.Response != null)
            {
                requestTelemetry.ResponseCode = context.Response.StatusCode.ToString();
                requestTelemetry.Success = context.Response.StatusCode >= 200 && context.Response.StatusCode <= 299;
            }
            else
            {
                requestTelemetry.Success = false;
            }

            // Now it's time to stop the operation (and track telemetry).
            telemetryClient.StopOperation(operation);
        }
    }
    
    public static string GetOperationId(string id)
    {
        // Returns the root ID from the '|' to the first '.' if any.
        int rootEnd = id.IndexOf('.');
        if (rootEnd < 0)
            rootEnd = id.Length;

        int rootStart = id[0] == '|' ? 1 : 0;
        return id.Substring(rootStart, rootEnd - rootStart);
    }
}

Il protocollo HTTP per la correlazione dichiara inoltre l’intestazione Correlation-Context. È omesso qui per motivi di semplicità.

Strumentazione della coda

Il contesto di traccia W3C e il protocollo HTTP per la correlazione consenta di passare i dettagli di correlazione con la richiesta HTTP, ma ogni protocollo di accodamento deve definire come passare gli stessi dettagli al messaggio della coda. Alcuni protocolli di coda, ad esempio AMQP, consentono di passare più metadati. Altri protocolli, ad esempio coda di Archiviazione di Azure, richiedono che il contesto venga codificato nel payload del messaggio.

Coda del bus di servizio

Per informazioni di tracciamento, vedere Correlazione e analisi distribuita tramite la messaggistica del bus di servizio di Azure.

Coda di archiviazione di Azure

L'esempio seguente illustra come tenere traccia delle operazioni della coda di archiviazione di Azure e correlare i dati di telemetria tra producer, consumer e Archiviazione di Azure.

La coda di archiviazione ha un'API HTTP. Tutte le chiamate alla coda vengono tracciate dall'agente di raccolta di dipendenze Application Insights per le richieste HTTP. Viene configurato per impostazione predefinita nelle applicazioni ASP.NET e ASP.NET Core. Con altri tipi di applicazioni, vedere la documentazione delle applicazioni console.

Inoltre è possibile correlare l'ID operazione di Application Insights con l'ID di richiesta di Archiviazione. Per informazioni su come impostare e ottenere un client di richiesta di Archivazione e un ID di richiesta del server, vedere Monitoraggio, diagnosi e risoluzione dei problemi dell'archiviazione di Azure.

public async Task Enqueue(CloudQueue queue, string message)
{
    var operation = telemetryClient.StartOperation<DependencyTelemetry>("enqueue " + queue.Name);
    operation.Telemetry.Type = "Azure queue";
    operation.Telemetry.Data = "Enqueue " + queue.Name;

    // MessagePayload represents your custom message and also serializes correlation identifiers into payload.
    // For example, if you choose to pass payload serialized to JSON, it might look like
    // {'RootId' : 'some-id', 'ParentId' : '|some-id.1.2.3.', 'message' : 'your message to process'}
    var jsonPayload = JsonConvert.SerializeObject(new MessagePayload
    {
        RootId = operation.Telemetry.Context.Operation.Id,
        ParentId = operation.Telemetry.Id,
        Payload = message
    });
    
    CloudQueueMessage queueMessage = new CloudQueueMessage(jsonPayload);

    // Add operation.Telemetry.Id to the OperationContext to correlate Storage logs and Application Insights telemetry.
    OperationContext context = new OperationContext { ClientRequestID = operation.Telemetry.Id};

    try
    {
        await queue.AddMessageAsync(queueMessage, null, null, new QueueRequestOptions(), context);
    }
    catch (StorageException e)
    {
        operation.Telemetry.Properties.Add("AzureServiceRequestID", e.RequestInformation.ServiceRequestID);
        operation.Telemetry.Success = false;
        operation.Telemetry.ResultCode = e.RequestInformation.HttpStatusCode.ToString();
        telemetryClient.TrackException(e);
    }
    finally
    {
        // Update status code and success as appropriate.
        telemetryClient.StopOperation(operation);
    }
}  

public async Task<MessagePayload> Dequeue(CloudQueue queue)
{
    var operation = telemetryClient.StartOperation<DependencyTelemetry>("dequeue " + queue.Name);
    operation.Telemetry.Type = "Azure queue";
    operation.Telemetry.Data = "Dequeue " + queue.Name;

    try
    {
        var message = await queue.GetMessageAsync();
    }
    catch (StorageException e)
    {
        operation.telemetry.Properties.Add("AzureServiceRequestID", e.RequestInformation.ServiceRequestID);
        operation.telemetry.Success = false;
        operation.telemetry.ResultCode = e.RequestInformation.HttpStatusCode.ToString();
        telemetryClient.TrackException(e);
    }
    finally
    {
        // Update status code and success as appropriate.
        telemetryClient.StopOperation(operation);
    }

    return null;
}

public async Task Process(MessagePayload message)
{
    // After the message is dequeued from the queue, create RequestTelemetry to track its processing.
    RequestTelemetry requestTelemetry = new RequestTelemetry { Name = "process " + queueName };
    
    // It might also make sense to get the name from the message.
    requestTelemetry.Context.Operation.Id = message.RootId;
    requestTelemetry.Context.Operation.ParentId = message.ParentId;

    var operation = telemetryClient.StartOperation(requestTelemetry);

    try
    {
        await ProcessMessage();
    }
    catch (Exception e)
    {
        telemetryClient.TrackException(e);
        throw;
    }
    finally
    {
        // Update status code and success as appropriate.
        telemetryClient.StopOperation(operation);
    }
}

Analogamente, è possibile instrumentare le altre operazioni della coda. L'operazione di visualizzazione deve essere instrumentata in modo simile a quella di rimozione dalla coda. Non è necessario instrumentare operazioni di gestione della coda. Application Insights tiene traccia di operazioni come HTTP e nella maggior parte dei casi è sufficiente.

Quando si instrumenta l'eliminazione di un messaggio, assicurarsi di impostare gli identificatori delle operazioni (correlazione). In alternativa, è possibile usare l'API Activity. Non è quindi necessario impostare gli identificatori delle operazioni negli elementi di telemetria perché Application Insights SDK esegue questa operazione automaticamente:

• Creare un nuovo oggetto Activity dopo avere ottenuto un elemento dalla coda.
• Usare Activity.SetParentId(message.ParentId) per correlare i log del consumer e del producer.
• Avviare il Activity.
• Tenere traccia delle operazioni di rimozione dalla coda, elaborazione ed eliminazione usando gli helper Start/StopOperation. dallo stesso flusso di controllo asincrono (contesto di esecuzione). In questo modo la correlazione sarà corretta.
• Arrestare il Activity.
• Usare Start/StopOperation o chiamare Track telemetry manualmente.

Tipi di dipendenza

Application Insights usa il tipo di dipendenza per personalizzare le esperienze dell'interfaccia utente. Per le code, riconosce i tipi seguenti diDependencyTelemetry che migliorano l'esperienza di diagnostica delle transazioni:

• Azure queue per le code di Archiviazione di Azure
• Azure Event Hubs per Hub eventi di Azure
• Azure Service Bus per bus di servizio di Azure

Elaborazione in batch

Per alcune code, è possibile una rimozione dalla coda di più messaggi con una singola richiesta. L'elaborazione di tali messaggi è presumibilmente indipendente e appartiene a diverse operazioni logiche. Non è possibile correlare l'operazione Dequeue a un determinato messaggio elaborato.

Ogni elaborazione dei messaggi deve essere eseguita nel proprio flusso di controllo asincrono. Per ulteriori informazioni, vedere la sezione Verifica delle dipendenze in uscita.

Attività in background a esecuzione prolungata

Alcune applicazioni avviano operazioni a esecuzione prolungata che possono essere causate dalle richieste degli utenti. Dal punto di vista della verifica/strumentazione, non c'è differenza dalla strumentazione delle richieste o delle dipendenze:

async Task BackgroundTask()
{
    var operation = telemetryClient.StartOperation<DependencyTelemetry>(taskName);
    operation.Telemetry.Type = "Background";
    try
    {
        int progress = 0;
        while (progress < 100)
        {
            // Process the task.
            telemetryClient.TrackTrace($"done {progress++}%");
        }
        // Update status code and success as appropriate.
    }
    catch (Exception e)
    {
        telemetryClient.TrackException(e);
        // Update status code and success as appropriate.
        throw;
    }
    finally
    {
        telemetryClient.StopOperation(operation);
    }
}

In questo esempio telemetryClient.StartOperation crea DependencyTelemetry e specifica il contesto di correlazione. Si supponga di avere un'operazione padre creata dalle richieste in ingresso che hanno pianificato l'operazione. BackgroundTask, purché venga avviato nello stesso flusso di controllo asincrono di una richiesta in ingresso, viene correlato con tale operazione padre. BackgroundTask e tutti gli elementi di telemetria annidati vengono automaticamente correlati alla richiesta che l'ha generato anche dopo la fine della richiesta.

Quando l'attività viene avviata dal thread in background a cui non sono associate operazioni (Activity), BackgroundTask non ha elementi padre. Tuttavia, può avere operazioni annidate. Tutti gli elementi di telemetria segnalati dall'attività sono correlati a DependencyTelemetry creato in BackgroundTask.

Verifica delle dipendenze in uscita

È possibile tenere traccia della propria tipologia di dipendenza o di operazioni non supportate da Application Insights.

Il metodo Enqueue nella coda del bus di servizio o nella coda di archiviazione è un esempio di tale verifica personalizzata.

L'approccio generale per la verifica personalizzata delle dipendenze è:

• Chiamare il metodo TelemetryClient.StartOperation (estensione) che riempie le proprietà DependencyTelemetry necessarie per la correlazione e altre proprietà, come avvio, timestamp e durata.
• Impostare le altre proprietà personalizzate in DependencyTelemetry, ad esempio nome e altri contesti necessari.
• Effettuare una chiamata di dipendenza e attendere.
• Al termine, arrestare l'operazione con StopOperation.
• Gestire le eccezioni.

public async Task RunMyTaskAsync()
{
    using (var operation = telemetryClient.StartOperation<DependencyTelemetry>("task 1"))
    {
        try 
        {
            var myTask = await StartMyTaskAsync();
            // Update status code and success as appropriate.
        }
        catch(...) 
        {
            // Update status code and success as appropriate.
        }
    }
}

L'eliminazione di un'operazione causa l'arresto dell'operazione, pertanto è possibile eseguirla invece di chiamare StopOperation.

Elaborazione e verifica di operazioni parallele

La chiamata StopOperation arresta solo l'operazione avviata. Se l'operazione corrente in esecuzione non corrisponde all'operazione che si desidera arrestare, StopOperation non esegue alcuna operazione. Questa situazione può verificarsi se si avviano più operazioni in parallelo nello stesso contesto di esecuzione.

var firstOperation = telemetryClient.StartOperation<DependencyTelemetry>("task 1");
var firstTask = RunMyTaskAsync();

var secondOperation = telemetryClient.StartOperation<DependencyTelemetry>("task 2");
var secondTask = RunMyTaskAsync();

await firstTask;

// FAILURE!!! This will do nothing and will not report telemetry for the first operation
// as currently secondOperation is active.
telemetryClient.StopOperation(firstOperation); 

await secondTask;

Chiamare sempre StartOperation ed elaborare l'operazione nello stesso metodo async per isolare le operazioni eseguite in parallelo. Se l'operazione è sincrona, o non asincrona, eseguire il wrapping del processo e verificare con Task.Run.

public void RunMyTask(string name)
{
    using (var operation = telemetryClient.StartOperation<DependencyTelemetry>(name))
    {
        Process();
        // Update status code and success as appropriate.
    }
}

public async Task RunAllTasks()
{
    var task1 = Task.Run(() => RunMyTask("task 1"));
    var task2 = Task.Run(() => RunMyTask("task 2"));
    
    await Task.WhenAll(task1, task2);
}

Operazioni di ApplicationInsights e System.Diagnostics.Activity

System.Diagnostics.Activity rappresenta il contesto di traccia distribuita e viene usato da framework e librerie per creare e propagare il contesto all'interno e all'esterno del processo e correlare gli elementi di telemetria. Activity interagisce con System.Diagnostics.DiagnosticSource come meccanismo di notifica tra il framework o la libreria per notificare eventi interessanti, ad esempio richieste in ingresso o in uscita ed eccezioni.

Le attività sono funzionalità di primo livello in Application Insights. Le dipendenze automatiche e la raccolta di richieste si basano principalmente su di essi insieme agli eventi DiagnosticSource. Se è stata creata Activity nell'applicazione, non verrà creata l'Application Insights Telemetry. Application Insights deve ricevere DiagnosticSource eventi e conoscere i nomi degli eventi e i payload da convertire Activity in dati di telemetria.

Ogni operazione di Application Insights (richiesta o dipendenza) comporta Activity. Quando StartOperation viene chiamato, crea Activity sotto. StartOperation è il modo consigliato per tenere traccia manualmente delle telemetrie di richiesta o dipendenza e assicurarsi che tutto sia correlato.

Contatori in Application Insights

Application Insights supporta contatori di prestazioni e contatori di eventi. Questa guida fornisce una panoramica di entrambi, compreso il loro scopo, nonché la configurazione e l'utilizzo nelle applicazioni .NET.

Informazioni generali

Contatori delle prestazioni

Windows offre una vasta gamma di contatori delle prestazioni, ad esempio quelli usati per raccogliere statistiche sull'utilizzo del processore, della memoria e del disco. È anche possibile definire contatori delle prestazioni personalizzati.

L'applicazione supporta la raccolta dei contatori di prestazioni se viene eseguita in Internet Information Server (IIS) su un host locale o su una macchina virtuale con accesso amministrativo. Le applicazioni in esecuzione come App Web di Azure non possono accedere direttamente ai contatori di prestazioni, ma Application Insights raccoglie un sottoinsieme dei contatori disponibili.

Prerequisiti

Concedere all'account del servizio pool di app, l'autorizzazione per monitorare i contatori delle prestazioni aggiungendolo al gruppo Utenti del Monitor prestazioni.

net localgroup "Performance Monitor Users" /add "IIS APPPOOL\NameOfYourPool"

Visualizzare i contatori

Nel riquadro Metrica è riportato un set predefinito di contatori delle prestazioni.

Aggiungere contatori

Se il contatore delle prestazioni desiderato non è incluso nell'elenco delle metriche, è possibile aggiungerlo.

using Microsoft.ApplicationInsights.Extensibility.PerfCounterCollector;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddApplicationInsightsTelemetry();

// The following configures PerformanceCollectorModule.

builder.Services.ConfigureTelemetryModule<PerformanceCollectorModule>((module, o) =>
    {
        // The application process name could be "dotnet" for ASP.NET Core self-hosted applications.
        module.Counters.Add(new PerformanceCounterCollectionRequest(@"\Process([replace-with-application-process-name])\Page Faults/sec", "DotnetPageFaultsPerfSec"));
    });

var app = builder.Build();

Raccogliere i contatori delle prestazioni nel codice per applicazioni Web ASP.NET o applicazioni Console .NET/.NET Core

Per raccogliere i contatori delle prestazioni di sistema e inviarli ad Application Insights, è possibile adattare il frammento di codice seguente:

    var perfCollectorModule = new PerformanceCollectorModule();
    perfCollectorModule.Counters.Add(new PerformanceCounterCollectionRequest(
      @"\Process([replace-with-application-process-name])\Page Faults/sec", "PageFaultsPerfSec"));
    perfCollectorModule.Initialize(TelemetryConfiguration.Active);

In alternativa, è possibile eseguire la stessa operazione con le metriche personalizzate create:

    var perfCollectorModule = new PerformanceCollectorModule();
    perfCollectorModule.Counters.Add(new PerformanceCounterCollectionRequest(
      @"\Sales(photo)\# Items Sold", "Photo sales"));
    perfCollectorModule.Initialize(TelemetryConfiguration.Active);

Contatori delle prestazioni per le applicazioni in esecuzione in App Web di Azure e in contenitori Windows in Servizio app di Azure

Le applicazioni ASP.NET e ASP.NET Core distribuite in App Web di Azure vengono eseguite in un ambiente sandbox speciale. Le applicazioni distribuite nel servizio app di Azure possono usare un Contenitore Windows o essere ospitate in un ambiente sandbox. Se l'applicazione viene distribuita in un contenitore Windows, tutti i contatori delle prestazioni standard sono disponibili nell'immagine del contenitore.

L'ambiente sandbox non consente l'accesso diretto ai contatori delle prestazioni di sistema. Tuttavia, un subset limitato di contatori viene esposto come variabile di ambiente, come descritto in Contatori delle prestazioni esposte come variabili di ambiente. In questo ambiente è disponibile solo un subset di contatori. Per l'elenco completo, vedere Contatori delle prestazioni esposti come variabili di ambiente.

Application Insights SDK per ASP.NET e ASP.NET Core rileva se il codice è distribuito in un'app Web o in un contenitore non Windows. Il rilevamento determina se raccoglie i contatori delle prestazioni in un ambiente sandbox o se utilizza il meccanismo di raccolta standard quando è ospitato in un contenitore Windows o in una macchina virtuale.

Query di Log Analytics per i contatori di prestazioni

È possibile cercare e visualizzare i report dei contatori delle prestazioni in Log Analytics.

Lo schema performanceCounters espone category, il nome counter e il nome instance per ogni contatore delle prestazioni. Nei dati di telemetria per ogni applicazione vengono visualizzati solo i contatori per l'applicazione specifica. Ad esempio, per visualizzare quali contatori sono disponibili:

performanceCounters | summarize count(), avg(value) by category, instance, counter

Qui Instance fa riferimento all'istanza del contatore delle prestazioni e non all'istanza del ruolo o del server. Solitamente, il nome dell'istanza del contatore delle prestazioni segmenta i contatori, ad esempio il tempo del processore, in base al nome del processo o dell'applicazione.

Per ottenere un grafico della memoria disponibile nel periodo recente:

performanceCounters | where counter == "Available Bytes" | summarize avg(value), min(value) by bin(timestamp, 1h) | render timechart

Come altri dati di telemetria, performanceCounters contiene anche una colonna cloud_RoleInstance che indica l'identità dell'istanza del server host in cui viene eseguita l'app. Ad esempio, per confrontare le prestazioni dell'applicazione su computer diversi:

performanceCounters | where counter == "% Processor Time" and instance == "SendMetrics" | summarize avg(value) by cloud_RoleInstance, bin(timestamp, 1d)

Domande frequenti sui contatori di prestazioni

Per consultare le domande frequenti, vedere Domande frequenti sui contatori di prestazioni.

Contatori di eventi

EventCounter è un meccanismo di .NET/.NET Core per pubblicare e utilizzare contatori o statistiche. Il supporto per EventCounter è disponibile in tutte le piattaforme del sistema operativo, ovvero Windows, Linux e macOS. Può essere considerato come un equivalente multipiattaforma per PerformanceCounters supportato solo nei sistemi Windows.

Anche se gli utenti possono pubblicare qualsiasi contatore di evento personalizzato per soddisfare le proprie esigenze, .NET pubblica un set di questi contatori per impostazione predefinita. Il documento illustra in modo dettagliato i passaggi necessari per raccogliere e visualizzare contatori degli eventi (definiti dal sistema o definiti dall'utente, in Azure Application Insights).

Uso di Application Insights per raccogliere EventCounters

Application Insights supporta la raccolta di EventCounters con EventCounterCollectionModule, che fa parte del pacchetto NuGet Microsoft.ApplicationInsights.EventCounterCollector rilasciato di recente. EventCounterCollectionModule viene abilitato automaticamente quando si usa AspNetCore o WorkerService. EventCounterCollectionModule raccoglie i contatori con una frequenza di raccolta non configurabile pari a 60 secondi. Non sono richieste autorizzazioni speciali per raccogliere EventCounters. Per le applicazioni ASP.NET Core è necessario aggiungere anche il pacchetto Microsoft.ApplicationInsights.AspNetCore.

dotnet add package Microsoft.ApplicationInsights.EventCounterCollector
dotnet add package Microsoft.ApplicationInsights.AspNetCore

Contatori predefiniti raccolti

A partire dalla versione 2.15.0 di AspNetCore SDK o WorkerService SDK, i contatori non vengono raccolti per impostazione predefinita. Il modulo stesso è abilitato, in questo modo gli utenti possono aggiungere i contatori desiderati per raccoglierli.

Per ottenere un elenco di contatori noti pubblicati da Runtime .NET, vedere il documento Contatori disponibili.

Personalizzazione dei contatori da raccogliere

L'esempio seguente illustra come aggiungere/rimuovere contatori. Questa personalizzazione viene eseguita come parte della configurazione del servizio dell'applicazione dopo l'abilitazione della telemetria di Application Insights con AddApplicationInsightsTelemetry() o AddApplicationInsightsWorkerService(). Di seguito è disponibile un esempio di codice da un'applicazione ASP.NET Core. Per altri tipi di applicazioni, vedere Configurare i moduli di telemetria.

using Microsoft.ApplicationInsights.Extensibility.EventCounterCollector;
using Microsoft.Extensions.DependencyInjection;

builder.Services.ConfigureTelemetryModule<EventCounterCollectionModule>(
        (module, o) =>
        {
            // Removes all default counters, if any.
            module.Counters.Clear();

            // Adds a user defined counter "MyCounter" from EventSource named "MyEventSource"
            module.Counters.Add(
                new EventCounterCollectionRequest("MyEventSource", "MyCounter"));

            // Adds the system counter "gen-0-size" from "System.Runtime"
            module.Counters.Add(
                new EventCounterCollectionRequest("System.Runtime", "gen-0-size"));
        }
    );

Disabilitazione del modulo di raccolta EventCounter

EventCounterCollectionModule può essere disabilitato utilizzando ApplicationInsightsServiceOptions.

Nell'esempio seguente viene utilizzato ASP.NET Core SDK.

using Microsoft.ApplicationInsights.AspNetCore.Extensions;
using Microsoft.Extensions.DependencyInjection;

var applicationInsightsServiceOptions = new ApplicationInsightsServiceOptions();
applicationInsightsServiceOptions.EnableEventCounterCollectionModule = false;
builder.Services.AddApplicationInsightsTelemetry(applicationInsightsServiceOptions);

Un approccio simile può essere usato anche per Worker Service SDK, ma lo spazio dei nomi deve essere modificato come illustrato nell'esempio seguente.

using Microsoft.ApplicationInsights.AspNetCore.Extensions;
using Microsoft.Extensions.DependencyInjection;

var applicationInsightsServiceOptions = new ApplicationInsightsServiceOptions();
applicationInsightsServiceOptions.EnableEventCounterCollectionModule = false;
builder.Services.AddApplicationInsightsTelemetry(applicationInsightsServiceOptions);

Query di Log Analytics per i contatori di eventi

È possibile cercare e visualizzare report dei contatori di eventi in Log Analytics, nella scheda customMetrics.

Eseguire ad esempio la query seguente per visualizzare i contatori raccolti e disponibili per le query:

customMetrics | summarize avg(value) by name

Per ottenere un grafico di un contatore specifico, ad esempio ThreadPool Completed Work Item Count, nel periodo recente, eseguire la query seguente.

customMetrics 
| where name contains "System.Runtime|ThreadPool Completed Work Item Count"
| where timestamp >= ago(1h)
| summarize avg(value) by cloud_RoleInstance, bin(timestamp, 1m)
| render timechart

Come altri dati di telemetria, customMetrics contiene anche una colonna cloud_RoleInstance che indica l'identità dell'istanza del server host in cui viene eseguita l'app. La query precedente mostra il valore del contatore per ogni istanza e può essere usata per confrontare le prestazioni di diverse istanze del server.

Domande frequenti sui contatore di eventi

Per consultare le domande frequenti, vedere Domande frequenti sui contatori di eventi.

Filtrare e arricchire i dati di telemetria

Contenuto della sezione

• Filtrare e pre-elaborare i dati di telemetria
• Inizializzatori di telemetria
• Processore di telemetria
• Campionamento
• Arricchire i dati tramite HTTP

Filtrare e pre-elaborare i dati di telemetria

È possibile scrivere codice per filtrare, modificare o arricchire i dati di telemetria prima dell'invio dall'SDK. L'elaborazione include i dati inviati dai moduli di telemetria standard, ad esempio la raccolta di richieste HTTP e la raccolta delle dipendenze.

• Il filtro può modificare o rimuovere i dati di telemetria prima che vengano inviati dall'SDK implementando ITelemetryProcessor. Ad esempio, è possibile ridurre il volume di dati di telemetria escludendo le richieste dai robot. A differenza del campionamento, si ha il controllo completo su ciò che viene inviato o rimosso, ma influisce su qualsiasi metrica basata su log aggregati. A seconda della modalità di eliminazione degli elementi, è anche possibile perdere la possibilità di spostarsi tra gli elementi correlati.

• Aggiungere o modificare proprietà a tutti i dati di telemetria inviati dall'app implementando un oggetto ITelemetryInitializer. Ad esempio, è possibile aggiungere valori calcolati o numeri di versione in base ai quali filtrare i dati nel portale.

• Il campionamento riduce il volume di dati di telemetria senza influire sulle statistiche. Mantiene insieme i punti dati correlati in modo che sia possibile spostarsi tra di essi durante la diagnosi di un problema. Nel portale i conteggi totali vengono moltiplicati per compensare il campionamento.

Filtraggio

Questa tecnica consente di controllare direttamente gli elementi inclusi o esclusi dal flusso di telemetria. Il filtro può essere usato per eliminare gli elementi di telemetria dall'invio ad Application Insights. È possibile usare il filtro con il campionamento o separatamente.

Per filtrare i dati di telemetria, scrivere un processore di telemetria e registrarlo con TelemetryConfiguration. Tutti i dati di telemetria passano attraverso il processore. È possibile scegliere di rilasciarlo dal flusso o assegnarlo al processore successivo nella catena. I dati di telemetria dai moduli standard, come il collettore di richieste HTTP e il collettore di dipendenze, e la telemetria che hai tracciato personalmente sono inclusi. Ad esempio, è possibile filtrare i dati di telemetria relativi alle richieste dei robot o alle chiamate di dipendenza riuscite.

ITelemetryProcessor e ITelemetryInitializer

Qual è la differenza tra processori di telemetria e inizializzatori di telemetria?

• Ci sono alcune sovrapposizioni in ciò che è possibile fare con loro. Entrambi possono essere usati per aggiungere o modificare le proprietà dei dati di telemetria, anche se è consigliabile usare gli inizializzatori a tale scopo.
• Gli inizializzatori di telemetria vengono sempre eseguiti prima dei processori di telemetria.
• Gli inizializzatori di telemetria possono essere chiamati più volte. Per convenzione, non impostano alcuna proprietà già impostata.
• I processori di telemetria consentono di sostituire o rimuovere completamente un elemento di telemetria.
• Tutti gli inizializzatori di telemetria registrati vengono chiamati per ogni elemento di telemetria. Per i processori di telemetria, SDK garantisce la chiamata al primo processore di telemetria. Se il resto dei processori viene chiamato o meno viene deciso dai processori di telemetria precedenti.
• Usare gli inizializzatori di telemetria per arricchire i dati di telemetria con più proprietà o eseguire l'override di uno esistente. Usare un processore di telemetria per filtrare i dati di telemetria.

Aggiungere/modificare le proprietà

Usare gli inizializzatori di telemetria per arricchire i dati di telemetria con informazioni aggiuntive o per eseguire l'override delle proprietà di telemetria impostate dai moduli di telemetria standard.

Ad esempio, Application Insights per un pacchetto Web raccoglie i dati di telemetria sulle richieste HTTP. Per impostazione predefinita, contrassegna qualsiasi richiesta con un codice >di risposta =400 come non riuscita. Se invece si vuole considerare 400 come un risultato positivo, è possibile fornire un inizializzatore di telemetria che imposti la proprietà Success.

Se si specifica un inizializzatore di telemetria, viene chiamato ogni volta che viene chiamato uno dei metodi Track*(). Questo inizializzatore include Track() metodi chiamati dai moduli di telemetria standard. Per convenzione, questi moduli non impostano alcuna proprietà già impostata da un inizializzatore. Gli inizializzatori di telemetria vengono chiamati prima di chiamare i processori di telemetria, quindi tutti gli arricchimenti eseguiti dagli inizializzatori sono visibili ai processori.

Inizializzatori di telemetria

Per arricchire i dati di telemetria con informazioni aggiuntive o per eseguire l'override delle proprietà di telemetria impostate dai moduli di telemetria standard, usare gli inizializzatori di telemetria.

Gli inizializzatori di telemetria impostano proprietà di contesto che vengono inviate insieme ad ogni elemento di telemetria. È possibile scrivere inizializzatori personalizzati per impostare le proprietà del contesto.

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

Aggiungere ITelemetryInitializer

Questo blog descrive un progetto per diagnosticare i problemi di dipendenza inviando automaticamente ping regolari alle dipendenze.

1. Definire l'inizializzatore

   using System;
   using Microsoft.ApplicationInsights.Channel;
   using Microsoft.ApplicationInsights.DataContracts;
   using Microsoft.ApplicationInsights.Extensibility;
   
   namespace MvcWebRole.Telemetry
   {
     /*
      * Custom TelemetryInitializer that overrides the default SDK
      * behavior of treating response codes >= 400 as failed requests
      *
      */
       public class MyTelemetryInitializer : ITelemetryInitializer
       {
           public void Initialize(ITelemetry telemetry)
           {
               var requestTelemetry = telemetry as RequestTelemetry;
               // Is this a TrackRequest() ?
               if (requestTelemetry == null) return;
               int code;
               bool parsed = Int32.TryParse(requestTelemetry.ResponseCode, out code);
               if (!parsed) return;
               if (code >= 400 && code < 500)
               {
                   // If we set the Success property, the SDK won't change it:
                   requestTelemetry.Success = true;
   
                   // Allow us to filter these requests in the portal:
                   requestTelemetry.Properties["Overridden400s"] = "true";
               }
               // else leave the SDK to set the Success property
           }
       }
   }
   

2. Caricare l'inizializzatore

protected void Application_Start()
{
    // ...
    TelemetryConfiguration.Active.TelemetryInitializers.Add(new MyTelemetryInitializer());
}

<ApplicationInsights>
    <TelemetryInitializers>
    <!-- Fully qualified type name, assembly name: -->
    <Add Type="MvcWebRole.Telemetry.MyTelemetryInitializer, MvcWebRole"/>
    ...
    </TelemetryInitializers>
</ApplicationInsights>

var builder = WebApplication.CreateBuilder(args);

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

var app = builder.Build();

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

    using Microsoft.ApplicationInsights.Extensibility;

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

   public void ConfigureServices(IServiceCollection services)
   {
        services.AddApplicationInsightsTelemetryWorkerService();
        // 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));
   }

Esempio di Inizializzatori di Telemetria

Aggiungere una proprietà personalizzata

L'inizializzatore di esempio seguente aggiunge una proprietà personalizzata a ogni telemetria rilevata.

public void Initialize(ITelemetry item)
{
    var itemProperties = item as ISupportProperties;
    if(itemProperties != null && !itemProperties.Properties.ContainsKey("customProp"))
    {
        itemProperties.Properties["customProp"] = "customValue";
    }
}

Aggiungere un nome del ruolo cloud e un'istanza del ruolo cloud

Passaggio 1: Scrivere un TelemetryInitializer personalizzato

L'inizializzatore di esempio seguente imposta il nome del ruolo cloud su ogni telemetria rilevata.

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

namespace CustomInitializer.Telemetry
{
    public class MyTelemetryInitializer : ITelemetryInitializer
    {
        public void Initialize(ITelemetry telemetry)
        {
            if (string.IsNullOrEmpty(telemetry.Context.Cloud.RoleName))
            {
                //set custom role name here
                telemetry.Context.Cloud.RoleName = "Custom RoleName";
                telemetry.Context.Cloud.RoleInstance = "Custom RoleInstance";
            }
        }
    }
}

Passaggio 2: Caricare un inizializzatore in TelemetryConfiguration

    <ApplicationInsights>
      <TelemetryInitializers>
        <!-- Fully qualified type name, assembly name: -->
        <Add Type="CustomInitializer.Telemetry.MyTelemetryInitializer, CustomInitializer"/>
        ...
      </TelemetryInitializers>
    </ApplicationInsights>

 using Microsoft.ApplicationInsights.Extensibility;
 using CustomInitializer.Telemetry;

    protected void Application_Start()
    {
        // ...
        TelemetryConfiguration.Active.TelemetryInitializers.Add(new MyTelemetryInitializer());
    }

 using Microsoft.ApplicationInsights.Extensibility;
 using CustomInitializer.Telemetry;
 public void ConfigureServices(IServiceCollection services)
{
    services.AddSingleton<ITelemetryInitializer, MyTelemetryInitializer>();
}

Controllare l'indirizzo IP client usato per i mapping di georilevazione

L'inizializzatore di esempio seguente imposta l'IP client, usato per la mappatura della geolocalizzazione al posto dell'indirizzo IP del socket client, durante l'acquisizione di telemetria.

public void Initialize(ITelemetry telemetry)
{
    var request = telemetry as RequestTelemetry;
    if (request == null) return true;
    request.Context.Location.Ip = "{client ip address}"; // Could utilize System.Web.HttpContext.Current.Request.UserHostAddress;   
    return true;
}

Processori di telemetria

I processori di telemetria possono filtrare e modificare ciascun elemento di telemetria prima di inviarlo dal SDK al portale.

1. Implementare ITelemetryProcessor.

   I processori di telemetria costruiscono una catena di elaborazione. Quando si crea un'istanza di un processore di telemetria, viene fornito un riferimento al processore successivo nella catena. Quando un punto dati di telemetria viene passato al metodo di processo, esegue il lavoro e quindi chiama (o non chiama) il processore di telemetria successivo nella catena.

   using Microsoft.ApplicationInsights.Channel;
   using Microsoft.ApplicationInsights.Extensibility;
   using Microsoft.ApplicationInsights.DataContracts;
   
   public class SuccessfulDependencyFilter : ITelemetryProcessor
   {
       private ITelemetryProcessor Next { get; set; }
   
       // next will point to the next TelemetryProcessor in the chain.
       public SuccessfulDependencyFilter(ITelemetryProcessor next)
       {
           this.Next = next;
       }
   
       public void Process(ITelemetry item)
       {
           // To filter out an item, return without calling the next processor.
           if (!OKtoSend(item)) { return; }
   
           this.Next.Process(item);
       }
   
       // Example: replace with your own criteria.
       private bool OKtoSend (ITelemetry item)
       {
           var dependency = item as DependencyTelemetry;
           if (dependency == null) return true;
   
           return dependency.Success != true;
       }
   }
   

2. Aggiungere il processore.

   • ASP.NET
   • ASP.NET Core
   • Servizio di lavoro

   Inserire questo frammento di codice in ApplicationInsights.config:

   <TelemetryProcessors>
     <Add Type="WebApplication9.SuccessfulDependencyFilter, WebApplication9">
       <!-- Set public property -->
       <MyParamFromConfigFile>2-beta</MyParamFromConfigFile>
     </Add>
   </TelemetryProcessors>
   

   È possibile passare valori stringa dal file .config fornendo proprietà denominate pubbliche nella classe.

   Avvertimento

   Prestare attenzione a associare il nome del tipo e i nomi delle proprietà nel file .config ai nomi di classe e proprietà nel codice. Se il file .config fa riferimento a un tipo o a una proprietà inesistente, l'SDK potrebbe non inviare dati di telemetria.

   In alternativa, è possibile inizializzare il filtro nel codice. In una classe di inizializzazione appropriata, ad esempio AppStart in Global.asax.cs, inserire il processore nella catena:

   Annotazioni

   L'esempio di codice seguente è obsoleto, ma viene reso disponibile qui per la posterità. È consigliabile iniziare a usare OpenTelemetry o eseguire la migrazione a OpenTelemetry.

   var builder = TelemetryConfiguration.Active.DefaultTelemetrySink.TelemetryProcessorChainBuilder;
   builder.Use((next) => new SuccessfulDependencyFilter(next));
   
   // If you have more processors:
   builder.Use((next) => new AnotherProcessor(next));
   
   builder.Build();
   

   I client di telemetria creati dopo questo punto usano i processori.

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

Filtri di esempio

Richieste sintetiche

Filtrare i robot e i test Web. Anche se Esplora metriche offre la possibilità di filtrare le origini sintetiche, questa opzione riduce il traffico e le dimensioni di inserimento filtrandoli nell'SDK stesso.

public void Process(ITelemetry item)
{
    if (!string.IsNullOrEmpty(item.Context.Operation.SyntheticSource)) {return;}
    
    // Send everything else:
    this.Next.Process(item);
}

Autenticazione non riuscita

Filtrare ed escludere le richieste che ricevono una risposta "401".

public void Process(ITelemetry item)
{
    var request = item as RequestTelemetry;

    if (request != null &&
    request.ResponseCode.Equals("401", StringComparison.OrdinalIgnoreCase))
    {
        // To filter out an item, return without calling the next processor.
        return;
    }

    // Send everything else
    this.Next.Process(item);
}

Filtrare le chiamate di dipendenza remote rapide

Se si desidera diagnosticare solo le chiamate lente, filtrarne le veloci.

public void Process(ITelemetry item)
{
    var request = item as DependencyTelemetry;

    if (request != null && request.Duration.TotalMilliseconds < 100)
    {
        return;
    }
    this.Next.Process(item);
}

campionamento

using Microsoft.ApplicationInsights.AspNetCore.Extensions;
using Microsoft.ApplicationInsights.Extensibility;

var builder = WebApplication.CreateBuilder(args);

builder.Services.Configure<TelemetryConfiguration>(telemetryConfiguration =>
{
   var telemetryProcessorChainBuilder = telemetryConfiguration.DefaultTelemetrySink.TelemetryProcessorChainBuilder;

   // Using adaptive sampling
   telemetryProcessorChainBuilder.UseAdaptiveSampling(maxTelemetryItemsPerSecond: 5);

   // Alternately, the following configures adaptive sampling with 5 items per second, and also excludes DependencyTelemetry from being subject to sampling:
   // telemetryProcessorChainBuilder.UseAdaptiveSampling(maxTelemetryItemsPerSecond:5, excludedTypes: "Dependency");
});

builder.Services.AddApplicationInsightsTelemetryWorkerService(new ApplicationInsightsServiceOptions
{
   EnableAdaptiveSampling = false,
});

var app = builder.Build();

Arricchire i dati tramite HTTP

var requestTelemetry = HttpContext.Current?.Items["Microsoft.ApplicationInsights.RequestTelemetry"] as RequestTelemetry;

if (requestTelemetry != null)
{
    requestTelemetry.Properties["myProp"] = "someData";
}

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

Gestire i componenti DELL'SDK

Contenuto della sezione

• Canali di telemetria
• Moduli di telemetria
• Disabilitare i dati di telemetria
• ApplicationId Provider
• Raccolta di snapshot

È possibile personalizzare Application Insights SDK per ASP.NET, ASP.NET Core e Il servizio di lavoro per modificare la configurazione predefinita.

Canali di telemetria

I canali di telemetria costituiscono parte integrante degli SDK di Application Insights. Essi gestiscono il buffering e la trasmissione dei dati di telemetria al servizio Application Insights. Le versioni .NET e .NET Core degli SDK hanno due canali di telemetria predefiniti: InMemoryChannel e ServerTelemetryChannel. Questa sezione descrive ogni canale e illustra come personalizzare il comportamento del canale.

Che cosa sono i canali di telemetria?

I canali di telemetria sono responsabili del buffering degli elementi di telemetria e del loro invio al servizio Application Insights, dove vengono archiviati per l'esecuzione di query e l'analisi. Un canale di telemetria è una qualsiasi classe che implementa l'interfaccia Microsoft.ApplicationInsights.ITelemetryChannel.

Il metodo Send(ITelemetry item) di un canale di telemetria viene chiamato dopo aver chiamato tutti gli inizializzatori e i processori di telemetria. Pertanto, tutti gli elementi eliminati da un processore di telemetria non raggiungono il canale. Solitamente, il metodo Send() non invia istantaneamente gli elementi al back-end. In genere, li memorizza nel buffer nella memoria e li invia in batch per una trasmissione efficiente.

Evitare di chiamare Flush() a meno che non sia fondamentale inviare immediatamente i dati di telemetria memorizzati nel buffer. Usarlo solo in scenari come l'arresto dell'applicazione, la gestione delle eccezioni o quando si usano processi di breve durata come i processi in background o gli strumenti da riga di comando. Nelle applicazioni Web o nei servizi a esecuzione prolungata, l'SDK gestisce automaticamente l'invio dei dati di telemetria. Chiamare Flush() inutilmente può causare problemi di prestazioni.

Live Metrics Stream include anche un canale personalizzato che supporta lo streaming live dei dati di telemetria. Questo canale è indipendente dal canale di telemetria normale, quindi questo documento non è pertinente.

Canali di telemetria predefiniti

Gli SDK .NET e .NET Core di Application Insights vengono forniti con due canali predefiniti:

• InMemoryChannel: un canale leggero che inserisce gli elementi nel buffer di memoria finché non vengono inviati. Gli elementi vengono memorizzati nel buffer di memoria e scaricati una volta ogni 30 secondi, oppure ogni volta che vengono inseriti 500 elementi nel buffer. Questo canale offre garanzie di affidabilità minime perché non riprova a inviare i dati di telemetria in seguito a un errore. Inoltre, questo canale non conserva gli elementi su disco. Pertanto, gli eventuali elementi non inviati vengono persi in modo permanente all'arresto dell'applicazione, che si un arresto normale o meno. Questo canale implementa un metodo Flush() che può essere usato per forzare lo scaricamento sincrono di tutti gli elementi di telemetria in memoria. Questo canale è ideale per le applicazioni a esecuzione breve per le quali è ideale lo scaricamento sincrono.

  Il canale fa parte del pacchetto NuGet Microsoft.ApplicationInsights più esteso ed è il canale predefinito usato dall'SDK in assenza di altre opzioni di configurazione.

• ServerTelemetryChannel: Un canale più avanzato con criteri di ripetizione dei tentativi e la possibilità di archiviare i dati in un disco locale. Questo canale ritenta l'invio dei dati di telemetria in caso di errori temporanei. Inoltre, questo canale si avvale dell'archiviazione su disco locale per mantenere gli elementi su disco durante interruzioni di rete o in presenza di volumi di telemetria elevati. A causa di questi meccanismi di ripetizione dei tentativi e dell'archiviazione su disco locale, questo è il canale ritenuto più affidabile. È consigliabile per tutti gli scenari di produzione. Questo è il canale predefinito per le applicazioni ASP.NET e ASP.NET Core configurate in base alla documentazione ufficiale. Il canale è ottimizzato per scenari server con processi a esecuzione prolungata. Il metodo Flush() implementato da questo canale non è sincrono.

  Questo canale viene fornito come pacchetto NuGet Microsoft.ApplicationInsights.WindowsServer.TelemetryChannel e viene acquisito automaticamente quando si usa il pacchetto NuGet Microsoft.ApplicationInsights.Web o Microsoft.ApplicationInsights.AspNetCore.

Configurare un canale di telemetria

Un canale di telemetria si configura impostandolo sulla configurazione di telemetria attiva. Per le applicazioni ASP.NET, la configurazione comporta l'impostazione dell'istanza del canale di telemetria su TelemetryConfiguration.Active oppure la modifica di ApplicationInsights.config. Per le applicazioni ASP.NET Core, la configurazione comporta l'aggiunta del canale al contenitore di inserimento delle dipendenze.

Nelle sezioni seguenti sono riportati esempi di configurazione dell'impostazione StorageFolder per il canale in diversi tipi di applicazioni. StorageFolder è solo una delle impostazioni configurabili. Per l'elenco completo delle impostazioni di configurazione, vedere la sezione Impostazioni configurabili nei canali, più avanti in questo articolo.

using Microsoft.ApplicationInsights.Extensibility;
using Microsoft.ApplicationInsights.WindowsServer.TelemetryChannel;
protected void Application_Start()
{
    var serverTelemetryChannel = new ServerTelemetryChannel();
serverTelemetryChannel.StorageFolder = @"d:\temp\applicationinsights";
    serverTelemetryChannel.Initialize(TelemetryConfiguration.Active);
    TelemetryConfiguration.Active.TelemetryChannel = serverTelemetryChannel;
}

    <TelemetrySinks>
        <Add Name="default">
            <TelemetryProcessors>
                <!-- Telemetry processors omitted for brevity -->
            </TelemetryProcessors>
            <TelemetryChannel Type="Microsoft.ApplicationInsights.WindowsServer.TelemetryChannel.ServerTelemetryChannel, Microsoft.AI.ServerTelemetryChannel">
                <StorageFolder>d:\temp\applicationinsights</StorageFolder>
            </TelemetryChannel>
        </Add>
    </TelemetrySinks>

using Microsoft.ApplicationInsights.Channel;
using Microsoft.ApplicationInsights.WindowsServer.TelemetryChannel;

public void ConfigureServices(IServiceCollection services)
{
    // This sets up ServerTelemetryChannel with StorageFolder set to a custom ___location.
    services.AddSingleton(typeof(ITelemetryChannel), new ServerTelemetryChannel() {StorageFolder = @"d:\temp\applicationinsights" });

    services.AddApplicationInsightsTelemetry();
}

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

Configurazione nel codice per applicazioni console

Per le app console, il codice è il medesimo per .NET e .NET Core:

var serverTelemetryChannel = new ServerTelemetryChannel();
serverTelemetryChannel.StorageFolder = @"d:\temp\applicationinsights";
serverTelemetryChannel.Initialize(TelemetryConfiguration.Active);
TelemetryConfiguration.Active.TelemetryChannel = serverTelemetryChannel;

Dettagli sul funzionamento di ServerTelemetryChannel

ServerTelemetryChannel archivia gli elementi in arrivo in un buffer di memoria. Gli elementi vengono serializzati, compressi e archiviati in un'istanza Transmission una volta ogni 30 secondi, oppure quando nel buffer sono stati inseriti 500 elementi. Una singola istanza Transmission può contenere fino a 500 elementi e rappresenta un batch di dati di telemetria inviati tramite una singola chiamata HTTPS al servizio Application Insights.

Per impostazione predefinita, è possibile inviare in parallelo un massimo di 10 istanze Transmission. Se i dati di telemetria arrivano a velocità più elevate o se la rete o il back-end di Application Insights sono lenti, le istanze Transmission vengono archiviate in memoria. La capacità predefinita di questo buffer di memoria Transmission è di 5 MB. Quando si supera la capacità di memoria, le istanze Transmission vengono archiviate sul disco locale fino a un limite di 50 MB.

Le istanze Transmission vengono archiviate sul disco locale anche in caso di problemi di rete. Solo gli elementi archiviati su un disco locale non subiscono conseguenze dopo un arresto anomalo dell'applicazione. Essi vengono inviati ogni volta che si riavvia l'applicazione. Se i problemi di rete persistono, ServerTelemetryChannel usa una logica di backoff esponenziale in un periodo compreso tra 10 secondi e 1 ora prima di ritentare l'invio dei dati di telemetria.

Impostazioni configurabili nei canali

Per l'elenco completo delle impostazioni configurabili per ogni canale, vedere:

• InMemoryChannel
• ServerTelemetryChannel

Di seguito sono riportate le impostazioni più comunemente usate per ServerTelemetryChannel:

• MaxTransmissionBufferCapacity: quantità massima di memoria, in byte, utilizzata dal canale per inserire le trasmissioni nel buffer di memoria. Quando viene raggiunta questa capacità, i nuovi elementi vengono archiviati direttamente sul disco locale. Il valore predefinito è 5 MB. L'impostazione di un valore superiore comporta un minore utilizzo del disco, tuttavia si deve ricordare che gli elementi in memoria vanno persi in caso di arresto anomalo dell'applicazione.

• MaxTransmissionSenderCapacity: il numero massimo di istanze Transmission che vengono inviate contemporaneamente ad Application Insights. Il valore predefinito è 10. Questa impostazione può essere configurata con un numero maggiore, consigliabile quando viene generato un enorme volume di dati di telemetria. Generalmente, un volume elevato si verifica durante i test di carico o quando il campionamento è disattivato.

• StorageFolder: la cartella usata dal canale per archiviare gli elementi su disco in base alle esigenze. In Windows si usa %LOCALAPPDATA% o %TEMP% se non viene specificato esplicitamente un altro percorso. Negli ambienti diversi da Windows, per impostazione predefinita vengono usati i percorsi seguenti (in ordine): %TMPDIR%, /var/tmp/ o /tmp/.

Quale canale è consigliabile usare?

È preferibile ServerTelemetryChannel per la maggior parte degli scenari di produzione che coinvolgano applicazioni a esecuzione prolungata. Per altre informazioni sullo scaricamento dei dati di telemetria, leggere la documentazione sull'uso di Flush().

Quando usare Flush()

Il metodo Flush() invia immediatamente tutti i dati di telemetria memorizzati nel buffer. Tuttavia, deve essere usato solo in scenari specifici.

Usare Flush() quando:

• L'applicazione sta per arrestarsi e si vuole assicurarsi che i dati di telemetria vengano inviati prima della chiusura.
• Si è in un gestore eccezioni e si ha bisogno di garantire che i dati di telemetria vengano recapitati.
• Si sta scrivendo un processo di breve durata, ad esempio un processo in background o uno strumento dell'interfaccia della riga di comando che si chiude rapidamente.

Evitare di usare Flush() in applicazioni a esecuzione prolungata come i servizi Web. L'SDK gestisce automaticamente il buffering e la trasmissione. Chiamare Flush() inutilmente può causare problemi di prestazioni e non garantisce che tutti i dati vengano inviati, specialmente quando si usa ServerTelemetryChannel, che non scarica in modo sincrono.

Moduli di telemetria

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. È possibile disabilitarli o configurarli per modificarne il comportamento predefinito.

Configurare i moduli di telemetria

<ApplicationInsights>
  <TelemetryModules>

    <!-- Dependency tracking -->
    <Add Type="Microsoft.ApplicationInsights.DependencyCollector.DependencyTrackingTelemetryModule, Microsoft.AI.DependencyCollector">
      <!-- Match Core example: enable W3C header injection -->
      <EnableW3CHeadersInjection>true</EnableW3CHeadersInjection>
    </Add>

    <!-- EventCounterCollectionModule: add a single counter (if you use event counters) -->
    <Add Type="Microsoft.ApplicationInsights.Extensibility.PerfCounterCollector.EventCounterCollectionModule, Microsoft.AI.PerfCounterCollector">
      <Counters>
        <!-- Mirrors Core example: only collect 'gen-0-size' from System.Runtime -->
        <Add ProviderName="System.Runtime" CounterName="gen-0-size" />
      </Counters>
    </Add>

    <!-- PerformanceCollectorModule (classic Windows performance counters).
         To DISABLE perf-counter collection, do NOT include this module.
         If it already exists in your file, remove or comment it out.
         Example of the line you would remove:
    <Add Type="Microsoft.ApplicationInsights.Extensibility.PerfCounterCollector.PerformanceCollectorModule, Microsoft.AI.PerfCounterCollector" />
    -->

  </TelemetryModules>
</ApplicationInsights>

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

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

{
    "ApplicationInsights": {
    "ConnectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000",
    "EnableAdaptiveSampling": false,
    "EnablePerformanceCounterCollectionModule": false
    }
}

    using Microsoft.ApplicationInsights.Extensibility.PerfCounterCollector.QuickPulse;
    using Microsoft.ApplicationInsights.Extensibility.PerfCounterCollector;

    public void ConfigureServices(IServiceCollection services)
    {
        services.AddApplicationInsightsTelemetryWorkerService();

            // The following configures QuickPulseTelemetryModule.
            // Similarly, any other default modules can be configured.
            services.ConfigureTelemetryModule<QuickPulseTelemetryModule>((module, o) =>
            {
                module.AuthenticationApiKey = "keyhere";
            });

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

using Microsoft.ApplicationInsights.WorkerService;

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

    // Disables live metrics (also known as QuickPulse).
    aiOptions.EnableQuickPulseMetricStream = false;
    services.AddApplicationInsightsTelemetryWorkerService(aiOptions);
}

Disabilitare telemetria

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

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

Stringa di connessione

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

Per esempi di codice, vedere Stringhe di connessione in Application Insights.

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

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

    protected void Application_Start()
    {
        TelemetryConfiguration configuration = TelemetryConfiguration.CreateDefault();
        configuration.ConnectionString = "InstrumentationKey=00000000-0000-0000-0000-000000000000";
        var telemetryClient = new TelemetryClient(configuration);

    var tc = new TelemetryClient();
    tc.Context.ConnectionString = "InstrumentationKey=00000000-0000-0000-0000-000000000000";
    tc.TrackEvent("myEvent");
    // ...

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

var builder = WebApplication.CreateBuilder(args);

// Add Application Insights
builder.Services.AddApplicationInsightsTelemetry();

var app = builder.Build();

// Resolve TelemetryConfiguration from DI and set the connection string
var config = app.Services.GetRequiredService<TelemetryConfiguration>();
config.ConnectionString = "InstrumentationKey=00000000-0000-0000-0000-000000000000";

app.Run();

using Microsoft.ApplicationInsights;

var tc = new TelemetryClient();
tc.Context.ConnectionString = "InstrumentationKey=00000000-0000-0000-0000-000000000000";
tc.TrackEvent("myEvent");
// ...

Fornitore di ApplicationId

Lo scopo di questo provider è quello di cercare un ID applicazione in base a una stringa di connessione. L'ID applicazione è incluso in RequestTelemetry e DependencyTelemetry viene usato per determinare la correlazione nel portale.

Questa funzionalità è disponibile impostando TelemetryConfiguration.ApplicationIdProvider.

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 della cache. Questo provider viene incluso automaticamente quando si installa Microsoft.ApplicationInsights.DependencyCollector o Microsoft.ApplicationInsights.Web.

La classe espone una proprietà facoltativa denominata ProfileQueryEndpoint. Per impostazione predefinita, è impostata su https://dc.services.visualstudio.com/api/profiles/{0}/appId.

Se è necessario configurare un proxy, si consiglia di usare il proxy per l'indirizzo di base e assicurarsi che il percorso includa /api/profiles/{0}/appId. In fase di runtime, {0} viene sostituito con la chiave di strumentazione per ogni richiesta.

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

TelemetryConfiguration.Active.ApplicationIdProvider = new ApplicationInsightsApplicationIdProvider();

using Microsoft.ApplicationInsights.Extensibility.Implementation.ApplicationId;

var builder = WebApplication.CreateBuilder(args);

// Add Application Insights
builder.Services.AddApplicationInsightsTelemetry();

// Replace default provider with custom configuration
builder.Services.AddSingleton<IApplicationIdProvider>(sp =>
    new ApplicationInsightsApplicationIdProvider
    {
        ProfileQueryEndpoint = "https://custom-proxy/api/profiles/{0}/appId"
    });

var app = builder.Build();
app.Run();

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 stringa di connessione che non esiste nella configurazione.

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

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

using Microsoft.ApplicationInsights.Extensibility.Implementation.ApplicationId;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddApplicationInsightsTelemetry();

// Register DictionaryApplicationIdProvider
builder.Services.AddSingleton<IApplicationIdProvider>(sp =>
    new DictionaryApplicationIdProvider
    {
        Defined = new Dictionary<string, string>
        {
            { "InstrumentationKey_1", "ApplicationId_1" },
            { "InstrumentationKey_2", "ApplicationId_2" }
        },
        Next = new ApplicationInsightsApplicationIdProvider() // optional fallback
    });

var app = builder.Build();
app.Run();

Configurare la raccolta di snapshot

Per informazioni su come configurare la raccolta di snapshot per applicazioni ASP.NET e ASP.NET Core, vedere Abilitare Snapshot Debugger per app .NET in Azure Service Fabric, Servizio cloud e macchine virtuali.

Aggiungere il monitoraggio sul lato client

Le sezioni precedenti forniscono indicazioni sui metodi per configurare automaticamente e manualmente il monitoraggio lato server. Per aggiungere il monitoraggio lato client, usare l'SDK JavaScript lato client. È possibile monitorare le transazioni lato client di qualsiasi pagina Web aggiungendo uno script del caricatore SDK JavaScript (Web) prima del tag di chiusura </head> del codice HTML della pagina.

Sebbene sia possibile aggiungere manualmente lo script di caricamento di JavaScript (Web) SDK all'intestazione di ogni pagina HTML, è consigliabile aggiungerlo a una pagina primaria. Questa azione inserisce lo script di caricamento di JavaScript (Web) SDK in tutte le pagine di un sito.

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

API di base per eventi personalizzati e metriche

Inserire alcune righe di codice nell'applicazione per scoprire le operazioni eseguite dagli utenti o per diagnosticare i problemi. È possibile inviare dati di telemetria da app desktop e dispositivi, client Web e server Web. Usare l'API di telemetria di base di Application Insights per inviare metriche e eventi personalizzati e versioni personalizzate dei dati di telemetria standard. Questa API è la stessa API usata dagli agenti di raccolta dati standard di Application Insights.

Riepilogo API

L'API principale è uniforme in tutte le piattaforme, a parte alcune varianti come GetMetric (solo.NET).

È possibile associare proprietà e metriche alla maggior parte di queste chiamate di telemetria.

Prerequisiti

Se non si ha ancora un riferimento in Application Insights SDK:

1. Aggiungere Application Insights SDK al progetto.

2. Nel codice del dispositivo o del server Web includere:

   • .NET
   • Node.js

   using Microsoft.ApplicationInsights;
   

Ottenere un'istanza di TelemetryClient

Ottenere un'istanza di TelemetryClient:

private TelemetryClient telemetry = new TelemetryClient();

TelemetryClient.Context.User.Id = "...";
TelemetryClient.Context.Device.Id = "...";

var telemetry = applicationInsights.defaultClient;

TrackEvent

In Application Insights un evento personalizzato è un punto dati che è possibile visualizzare in Esplora metriche come conteggio aggregato e in Ricerca diagnostica come singole occorrenze. Non è correlato a MVC o ad altri "eventi".

Inserire chiamate TrackEvent nel codice per contare i vari eventi. Ad esempio, è possibile tenere traccia della frequenza con cui gli utenti scelgono una determinata funzionalità. Oppure potresti voler sapere con quale frequenza raggiungono determinati obiettivi o commettono tipi specifici di errori.

Ad esempio, in un'app di gioco inviare un evento ogni volta che un utente vince il gioco:

telemetry.TrackEvent("WinGame");

telemetry.trackEvent({name: "WinGame"});

Eventi personalizzati in Log Analytics

I dati di telemetria sono disponibili nella customEvents tabella nella scheda Log di Application Insights o nell'esperienza di utilizzo. Gli eventi potrebbero provenire da trackEvent(..) o dal plug-in Click Analytics Autocollection.

Se il campionamento è attivo, la proprietà itemCount mostra un valore maggiore di 1. Ad esempio, itemCount==10 significa che di 10 chiamate a trackEvent(), il processo di campionamento ha trasmesso solo uno di essi. Per ottenere un conteggio corretto degli eventi personalizzati, usare codice come customEvents | summarize sum(itemCount).

GetMetric

Per informazioni su come usare in modo efficace la GetMetric() chiamata per acquisire metriche preaggregate in locale per le applicazioni .NET e .NET Core, vedere Raccolta di metriche personalizzate in .NET e .NET Core.

TrackMetric

Application Insights può creare un grafico delle metriche non associate a eventi specifici. Ad esempio, è possibile monitorare la lunghezza della coda a intervalli regolari. Con le metriche, le singole misurazioni sono di minore interesse rispetto alle variazioni e alle tendenze e quindi i grafici statistici sono utili.

Per inviare metriche ad Application Insights, è possibile usare l'API TrackMetric(..) . Esistono due modi per inviare una metrica:

• Valore singolo. Ogni volta che si esegue una misurazione nell'applicazione, si invia il valore corrispondente ad Application Insights.

  Si supponga, ad esempio, di avere una metrica che descrive il numero di elementi in un contenitore. Durante un determinato periodo di tempo, inserire prima tre elementi nel contenitore e quindi rimuovere due elementi. Pertanto, chiameresti TrackMetric due volte. Prima di tutto, passare il valore 3 e quindi passare il valore -2. Application Insights archivia entrambi i valori.

• Aggregazione. Quando si lavora con le metriche, ogni singola misura è raramente di interesse. È invece importante un riepilogo di ciò che è accaduto durante un determinato periodo di tempo. Un riepilogo di questo tipo è denominato aggregazione.

  Nell'esempio precedente la somma delle metriche di aggregazione per il periodo di tempo è 1 e il conteggio dei valori delle metriche è 2. Quando si usa l'approccio di aggregazione, si richiama TrackMetric una sola volta per periodo di tempo e si inviano i valori di aggregazione. È consigliabile questo approccio perché può ridurre significativamente il costo e il sovraccarico delle prestazioni inviando meno punti dati ad Application Insights, pur raccogliendo tutte le informazioni pertinenti.

Esempi di valore singolo

Per inviare un singolo valore metrica:

var sample = new MetricTelemetry();
sample.Name = "queueLength";
sample.Sum = 42.3;
telemetryClient.TrackMetric(sample);

telemetry.trackMetric({name: "queueLength", value: 42.0});

Metriche personalizzate in Log Analytics

I dati di telemetria sono disponibili nella customMetrics tabella in Application Insights Analytics. Ogni riga rappresenta una chiamata a trackMetric(..) nell'app.

• valueSum: somma delle misurazioni. Per ottenere il valore medio, dividere per valueCount.
• valueCount: numero di misurazioni aggregate in questa trackMetric(..) chiamata.

Visualizzazioni pagina

Nell'app per dispositivi o per pagine web, la telemetria delle visualizzazioni delle pagine viene inviata automaticamente quando ogni schermata o pagina viene caricata. Tuttavia, è possibile modificare l'impostazione predefinita per tenere traccia delle visualizzazioni di pagina in momenti più o diversi. Ad esempio, in un'app che visualizza schede o riquadri, è possibile tenere traccia di una pagina ogni volta che l'utente apre un nuovo riquadro.

I dati utente e di sessione vengono inviati come proprietà insieme alle visualizzazioni di pagina, così i grafici utenti e di sessione si animano quando sono presenti dati di telemetria di visualizzazione di pagina.

Visualizzazioni pagina personalizzate

telemetry.TrackPageView("GameReviewPage");

Telemetria delle pagine in Log Analytics

In Log Analytics due tabelle mostrano i dati delle operazioni del browser:

• pageViews: contiene i dati relativi all'URL e al titolo della pagina.
• browserTimings: contiene dati sulle prestazioni del client, ad esempio il tempo impiegato per elaborare i dati in ingresso.

Per trovare quanto tempo il browser richiede per elaborare pagine diverse:

browserTimings
| summarize avg(networkDuration), avg(processingDuration), avg(totalDuration) by name

Per scoprire la popolarità di browser diversi:

pageViews
| summarize count() by client_Browser

Per associare le visualizzazioni di pagina alle chiamate AJAX, collegare con le dipendenze:

pageViews
| join (dependencies) on operation_Id

TrackRequest

L'SDK del server usa TrackRequest per registrare le richieste HTTP.

È anche possibile chiamarlo manualmente se si desidera simulare le richieste in un contesto in cui non è in esecuzione il modulo del servizio Web.

Il modo consigliato per inviare i dati di telemetria delle richieste è la posizione in cui la richiesta funge da contesto operativo.

Contesto dell'operazione

È possibile correlare gli elementi di telemetria insieme associandoli al contesto dell'operazione. Il modulo standard di rilevamento delle richieste esegue le eccezioni e altri eventi inviati durante l'elaborazione di una richiesta HTTP. In Ricerca e Analisi è possibile trovare facilmente tutti gli eventi associati alla richiesta usando il relativo ID operazione.

Quando si tiene traccia dei dati di telemetria manualmente, il modo più semplice per garantire la correlazione dei dati di telemetria consiste nell'usare questo modello:

// Establish an operation context and associated telemetry item:
using (var operation = telemetryClient.StartOperation<RequestTelemetry>("operationName"))
{
    // Telemetry sent in here uses the same operation ID.
    ...
    telemetryClient.TrackTrace(...); // or other Track* calls
    ...

    // Set properties of containing telemetry item--for example:
    operation.Telemetry.ResponseCode = "200";

    // Optional: explicitly send telemetry item:
    telemetryClient.StopOperation(operation);

} // When operation is disposed, telemetry item is sent.

// Establish an operation context and associated telemetry item:
const operation = appInsights.startOperation(client, { name: "operationName" });

appInsights.wrapWithCorrelationContext(() => {
    // Telemetry sent in here uses the same operation ID.
    ...
    client.trackTrace({ message: "..." }); // or other track* calls
    ...

    // Set properties of containing telemetry item—for example:
    operation.telemetry.responseCode = "200";

    // Optional: explicitly send telemetry item:
    client.stopOperation(operation);

}, operation.context)(); // When callback completes, telemetry item is sent.

Insieme all'impostazione di un contesto dell'operazione, StartOperation crea un elemento di telemetria del tipo specificato. Invia l'elemento di telemetria quando si elimina l'operazione o si chiama esplicitamente StopOperation. Se si usa RequestTelemetry come tipo di telemetria, la relativa durata viene impostata sull'intervallo di tempo compreso tra inizio e arresto.

Gli elementi di telemetria segnalati all'interno di un ambito operativo diventano sotto-elementi di tale operazione. È possibile annidare i contesti dell'operazione.

In Ricerca il contesto dell'operazione viene usato per creare l'elenco Elementi correlati .

Per altre informazioni sul rilevamento delle operazioni personalizzate, vedere Tenere traccia delle operazioni personalizzate con Application Insights .NET SDK.

Richieste in Log Analytics

In Application Insights Analytics le richieste sono visualizzate nella requests tabella.

Se il campionamento è attivo, la proprietà itemCount mostra un valore maggiore di 1. Ad esempio, itemCount==10 significa che di 10 chiamate a trackRequest(), il processo di campionamento ha trasmesso solo uno di essi. Per ottenere un conteggio corretto delle richieste e della durata media segmentata in base ai nomi delle richieste, usare il codice, ad esempio:

requests
| summarize count = sum(itemCount), avgduration = avg(duration) by name

TrackException

Inviare eccezioni ad Application Insights:

• Per contarli, come indicazione della frequenza di un problema.
• Per esaminare le singole occorrenze.

I report includono le analisi dello stack.

try
{
    ...
}
catch (Exception ex)
{
    telemetry.TrackException(ex);
}

try
{
    ...
}
catch (ex)
{
    telemetry.trackException({exception: ex});
}

Gli SDK rilevano automaticamente molte eccezioni, quindi non è sempre necessario chiamare TrackException in modo esplicito.

Eccezioni in Log Analytics

In Application Insights Analytics le eccezioni vengono visualizzate nella exceptions tabella.

Se il campionamento è attivo, la proprietà itemCount mostra un valore maggiore di 1. Ad esempio, itemCount==10 significa che di 10 chiamate a trackException(), il processo di campionamento ha trasmesso solo uno di essi. Per ottenere un conteggio corretto delle eccezioni segmentate per tipo di eccezione, usare il codice, ad esempio:

exceptions
| summarize sum(itemCount) by type

La maggior parte delle informazioni importanti sullo stack è già estratta in variabili separate, ma è possibile separare la details struttura per ottenere di più. Poiché questa struttura è dinamica, è necessario eseguire il cast del risultato al tipo previsto. Per esempio:

exceptions
| extend method2 = tostring(details[0].parsedStack[1].method)

Per associare le eccezioni alle richieste correlate, utilizza un join:

exceptions
| join (requests) on operation_Id

TrackTrace

Usare TrackTrace per diagnosticare i problemi mediante l'invio di una traccia di navigazione ad Application Insights. È possibile inviare blocchi di dati di diagnostica ed esaminarli in Ricerca diagnostica.

telemetry.TrackTrace(message, SeverityLevel.Warning, properties);

telemetry.trackTrace({
    message: message,
    severity: applicationInsights.Contracts.SeverityLevel.Warning,
    properties: properties
});

Registrare un evento di diagnostica, ad esempio l'immissione o l'uscita di un metodo.

È possibile cercare il contenuto dei messaggi, ma a differenza dei valori delle proprietà, non è possibile filtrarlo.

Il limite di dimensioni su message è molto superiore al limite per le proprietà. Un vantaggio di TrackTrace è che è possibile inserire dati relativamente lunghi nel messaggio. Ad esempio, è possibile codificare i dati POST in questa posizione.

È anche possibile aggiungere un livello di gravità al messaggio. Analogamente ad altri dati di telemetria, è possibile aggiungere valori di proprietà per filtrare o cercare set di tracce diversi. Per esempio:

var telemetry = new Microsoft.ApplicationInsights.TelemetryClient();
telemetry.TrackTrace("Slow database response",
                SeverityLevel.Warning,
                new Dictionary<string,string> { {"database", db.ID} });

In Ricerca è quindi possibile filtrare facilmente tutti i messaggi di un particolare livello di gravità correlato a un determinato database.

Tracce in Log Analytics

In Application Insights Analytics le chiamate a TrackTrace vengono visualizzate nella traces tabella.

Se il campionamento è attivo, la proprietà itemCount mostra un valore maggiore di 1. Ad esempio, itemCount==10 significa che di 10 chiamate a trackTrace(), il processo di campionamento ha trasmesso solo uno di essi. Per ottenere un conteggio corretto delle chiamate di traccia, usare codice come traces | summarize sum(itemCount).

TrackDependency

Usare la TrackDependency chiamata per tenere traccia dei tempi di risposta e delle percentuali di esito positivo delle chiamate a un frammento di codice esterno. I risultati vengono visualizzati nei grafici delle dipendenze nel portale. Il frammento di codice seguente deve essere aggiunto ovunque venga effettuata una chiamata di dipendenza.

var success = false;
var startTime = DateTime.UtcNow;
var timer = System.Diagnostics.Stopwatch.StartNew();
try
{
    success = dependency.Call();
}
catch(Exception ex)
{
    success = false;
    telemetry.TrackException(ex);
    throw new Exception("Operation went wrong", ex);
}
finally
{
    timer.Stop();
    telemetry.TrackDependency("DependencyType", "myDependency", "myCall", startTime, timer.Elapsed, success);
}

var success = false;
var startTime = new Date().getTime();
try
{
    success = dependency.Call();
}
finally
{
    var elapsed = new Date() - startTime;
    telemetry.trackDependency({
        dependencyTypeName: "myDependency",
        name: "myCall",
        duration: elapsed,
        success: success
    });
}

Tenere presente che gli SDK del server includono un modulo di dipendenza che individua e tiene traccia di determinate chiamate di dipendenza automaticamente, ad esempio ai database e alle API REST. È necessario installare un agente nel server per eseguire il funzionamento del modulo.

Questa chiamata viene usata se si desidera tenere traccia delle chiamate che il rilevamento automatico non intercetta.

Per disattivare il modulo di rilevamento delle dipendenze standard in C#, modificare ApplicationInsights.config ed eliminare il riferimento a DependencyCollector.DependencyTrackingTelemetryModule.

Dipendenze in Log Analytics

In Application Insights Analytics le trackDependency chiamate sono visualizzate nella dependencies tabella.

Se il campionamento è attivo, la proprietà itemCount mostra un valore maggiore di 1. Ad esempio, itemCount==10 significa che di 10 chiamate a trackDependency(), il processo di campionamento ha trasmesso solo uno di essi. Per ottenere un conteggio corretto delle dipendenze segmentate per componente di destinazione, usare il codice, ad esempio:

dependencies
| summarize sum(itemCount) by target

Per associare le dipendenze alle richieste correlate, è possibile usare un join:

dependencies
| join (requests) on operation_Id

Cancellazione dei dati

In genere, l'SDK invia i dati a intervalli fissi, in genere 30 secondi o ogni volta che il buffer è pieno, che in genere è di 500 elementi. In alcuni casi, potrebbe essere necessario scaricare il buffer. Un esempio è se si usa l'SDK in un'applicazione che si arresta.

telemetry.Flush();
// Allow some time for flushing before shutdown.
System.Threading.Thread.Sleep(5000);

await telemetryClient.FlushAsync()
// No need to sleep

telemetry.flush();

Utenti autenticati

In un'app Web, gli utenti sono identificati dai cookie per impostazione predefinita. Un utente potrebbe essere conteggiato più volte se accede all'app da un computer o un browser diverso o se elimina i cookie.

Se gli utenti accedono all'app, è possibile ottenere un conteggio più accurato impostando l'ID utente autenticato nel codice del browser. Non è necessario usare il nome di accesso effettivo dell'utente. Deve essere solo un ID univoco per l'utente. Non deve includere spazi o caratteri ,;=|.

L'ID utente viene impostato anche in un cookie di sessione e inviato al server. Se l'SDK del server è installato, l'ID utente autenticato viene inviato come parte delle proprietà di contesto dei dati di telemetria client e server. È quindi possibile filtrare e cercare su di esso.

Se l'app raggruppa gli utenti negli account, è anche possibile passare un identificatore per l'account. Si applicano le stesse restrizioni relative ai caratteri.

In Esplora metriche è possibile creare un grafico che conta utenti, autenticati e account utente.

È anche possibile cercare punti dati client con nomi utente e account specifici.

Filtrare, cercare e segmentare i dati usando le proprietà

È possibile associare proprietà e misurazioni agli eventi, alle metriche, alle visualizzazioni di pagina, alle eccezioni e ad altri dati di telemetria.

Le proprietà sono valori stringa che è possibile usare per filtrare i dati di telemetria nei report di utilizzo. Ad esempio, se la tua app fornisce diversi giochi, puoi allegare il nome del gioco a ogni evento in modo da poter vedere quali giochi sono più popolari.

Esiste un limite di 8.192 sulla lunghezza della stringa. Per inviare blocchi di dati di grandi dimensioni, usare il parametro message di TrackTrace.

Le metriche sono valori numerici che possono essere presentati graficamente. Ad esempio, potresti voler vedere se c'è un aumento graduale dei punteggi ottenuti dai giocatori. I grafici possono essere segmentati in base alle proprietà inviate con l'evento in modo da poter ottenere grafici separati o in pila per giochi diversi.

I valori delle metriche devono essere maggiori o uguali a 0 per essere visualizzati correttamente.

Esistono alcuni limiti al numero di proprietà, valori delle proprietà e metriche che è possibile usare.

// Set up some properties and metrics:
var properties = new Dictionary <string, string>
    {{"game", currentGame.Name}, {"difficulty", currentGame.Difficulty}};
var metrics = new Dictionary <string, double>
    {{"Score", currentGame.Score}, {"Opponents", currentGame.OpponentCount}};

// Send the event:
telemetry.TrackEvent("WinGame", properties, metrics);

// Set up some properties and metrics:
var properties = {"game": currentGame.Name, "difficulty": currentGame.Difficulty};
var metrics = {"Score": currentGame.Score, "Opponents": currentGame.OpponentCount};

// Send the event:
telemetry.trackEvent({name: "WinGame", properties: properties, measurements: metrics});

Modo alternativo per impostare proprietà e metriche

Se è più conveniente, è possibile raccogliere i parametri di un evento in un oggetto separato:

var event = new EventTelemetry();

event.Name = "WinGame";
event.Metrics["processingTime"] = stopwatch.Elapsed.TotalMilliseconds;
event.Properties["game"] = currentGame.Name;
event.Properties["difficulty"] = currentGame.Difficulty;
event.Metrics["Score"] = currentGame.Score;
event.Metrics["Opponents"] = currentGame.Opponents.Length;

telemetry.TrackEvent(event);

Misurazioni e proprietà personalizzate in Log Analytics

In Log Analytics le metriche e le proprietà personalizzate vengono visualizzate negli customMeasurements attributi e customDimensions di ogni record di telemetria.

Ad esempio, se si aggiunge una proprietà denominata "game" ai dati di telemetria della richiesta, questa query conta le occorrenze di valori diversi di "gioco" e mostra la media della metrica personalizzata "score":

requests
| summarize sum(itemCount), avg(todouble(customMeasurements.score)) by tostring(customDimensions.game)

Si noti che:

• Quando si estrae un valore dal JSON customDimensions o customMeasurements, ha un tipo dinamico, quindi è necessario effettuare il cast su tostring o todouble.
• Per tenere conto della possibilità di campionamento, usare sum(itemCount) non count().

Eventi di temporizzazione

A volte si vuole creare un grafico del tempo necessario per eseguire un'azione. Ad esempio, potresti voler sapere quanto tempo gli utenti impiegano per prendere in considerazione le scelte in un gioco. Per ottenere queste informazioni, usare il parametro di misurazione.

var stopwatch = System.Diagnostics.Stopwatch.StartNew();

// ... perform the timed action ...

stopwatch.Stop();

var metrics = new Dictionary <string, double>
    {{"processingTime", stopwatch.Elapsed.TotalMilliseconds}};

// Set up some properties:
var properties = new Dictionary <string, string>
    {{"signalSource", currentSignalSource.Name}};

// Send the event:
telemetry.TrackEvent("SignalProcessed", properties, metrics);

Proprietà predefinite per i dati di telemetria personalizzati

Se desiderate impostare valori predefiniti delle proprietà per alcuni eventi personalizzati che scrivete, configurateli in un'istanza di TelemetryClient. Sono collegati a ogni elemento di telemetria inviato da tale client.

using Microsoft.ApplicationInsights.DataContracts;

var gameTelemetry = new TelemetryClient();
gameTelemetry.Context.GlobalProperties["Game"] = currentGame.Name;
// Now all telemetry is automatically sent with the context property:
gameTelemetry.TrackEvent("WinGame");

var gameTelemetry = new applicationInsights.TelemetryClient();
gameTelemetry.commonProperties["Game"] = currentGame.Name;

gameTelemetry.TrackEvent({name: "WinGame"});

Le singole chiamate di telemetria possono sovrascrivere i valori predefiniti nei dizionari delle proprietà.

Per aggiungere proprietà a tutti i dati di telemetria, inclusi i dati dei moduli di raccolta standard, implementare ITelemetryInitializer.

Disabilitare telemetria

Per arrestare e avviare dinamicamente la raccolta e la trasmissione dei dati di telemetria:

using  Microsoft.ApplicationInsights.Extensibility;

TelemetryConfiguration.Active.DisableTelemetry = true;

telemetry.config.disableAppInsights = true;

applicationInsights.setup()
    .setAutoCollectRequests(false)
    .setAutoCollectPerformance(false)
    .setAutoCollectExceptions(false)
    .setAutoCollectDependencies(false)
    .setAutoCollectConsole(false)
    .start();

Modalità sviluppatore

Durante il debug, è utile che i dati di telemetria vengano accelerati attraverso la pipeline in modo da poter visualizzare immediatamente i risultati. Si ottengono anche altri messaggi che consentono di tracciare eventuali problemi con i dati di telemetria. Disattivarlo nell'ambiente di produzione perché potrebbe rallentare l'app.

TelemetryConfiguration.Active.TelemetryChannel.DeveloperMode = true;

applicationInsights.setup("ikey")
  .setInternalLogging(true, true)
  .start()
applicationInsights.defaultClient.config.maxBatchSize = 0;

Impostare la chiave di strumentazione per la telemetria personalizzata selezionata

var telemetry = new TelemetryClient();
telemetry.InstrumentationKey = "---my key---";
// ...

Stringa di connessione dinamica

Per evitare di combinare i dati di telemetria dagli ambienti di sviluppo, test e produzione, è possibile creare risorse di Application Insights separate e modificarne le chiavi, a seconda dell'ambiente.

Anziché ottenere la chiave di strumentazione dal file di configurazione, è possibile impostarla nel codice. Impostare la chiave in un metodo di inizializzazione, ad esempio global.aspx.cs in un servizio ASP.NET:

protected void Application_Start()
{
    Microsoft.ApplicationInsights.Extensibility.
    TelemetryConfiguration.Active.InstrumentationKey =
        // - for example -
        WebConfigurationManager.Settings["ikey"];
    ...
}

TelemetryContext

TelemetryClient dispone di una proprietà Context, che contiene valori inviati insieme a tutti i dati di telemetria. Normalmente vengono impostati dai moduli di telemetria standard, ma è anche possibile impostarli manualmente. Per esempio:

telemetry.Context.Operation.Name = "MyOperationName";

Se si imposta uno di questi valori manualmente, è consigliabile rimuovere la riga pertinente da ApplicationInsights.config in modo che i valori e i valori standard non vengano confusi.

• Componente: l'app e la relativa versione.
• Dispositivo: dati sul dispositivo in cui è in esecuzione l'app. Nelle app Web si tratta del server o del dispositivo client da cui vengono inviati i dati di telemetria.
• InstrumentationKey: risorsa di Application Insights in Azure in cui sono visualizzati i dati di telemetria. In genere viene prelevato da ApplicationInsights.config.
• Posizione: posizione geografica del dispositivo.
• Operazione: nelle applicazioni web, la richiesta HTTP corrente. In altri tipi di app è possibile impostare questo valore per raggruppare gli eventi.
  • ID: valore generato che correla diversi eventi in modo che quando si esamina qualsiasi evento in Ricerca diagnostica, è possibile trovare elementi correlati.
  • Nome: identificatore, in genere l'URL della richiesta HTTP.
  • SyntheticSource: se non null o vuoto, una stringa che indica che l'origine della richiesta è stata identificata come un robot o un test Web. Per impostazione predefinita, viene esclusa dai calcoli in Esplora metriche.
• Sessione: sessione dell'utente. L'ID è impostato su un valore generato, che viene modificato quando l'utente non è stato attivo per un periodo di tempo.
• Utente: informazioni sull'utente.

Limits

Esistono alcuni limiti sul numero di metriche e eventi per applicazione, ovvero per chiave di strumentazione. I limiti dipendono dal piano tariffario scelto.

Per altre informazioni sui prezzi e sulle quote, vedere Fatturazione di Application Insights.

Per evitare di raggiungere il limite di velocità dei dati usare il campionamento.

Per determinare per quanto tempo vengono conservati i dati, vedere Conservazione e privacy dei dati.

Applicazioni di esempio

Applicazione console .NET Core: usare questo esempio se si usa un'applicazione console scritta in .NET Core (2.0 o versione successiva) o .NET Framework (4.7.2 o versione successiva).

Attività in background di ASP.NET Core con HostedServices: usate questo esempio se lavorate con ASP.NET Core e create attività in background seguendo le indicazioni ufficiali.

Servizio di lavoro .NET Core: usare questo esempio se si dispone di un'applicazione del servizio di lavoro .NET in conformità alle indicazioni ufficiali.

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 di rilascio

Per la versione 2.12 e successive: .NET Software Development Kit (SDK) inclusi ASP.NET, ASP.NET Core e adattatori di registrazione

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

Passaggi successivi

• Per esaminare le domande frequenti, vedere:
  • Domande frequenti su Applications Insights per ASP.NET
  • Domande frequenti su Application Insights per ASP.NET Core
  • Domande frequenti su applicazioni del servizio di lavoro
  • Domande frequenti sull'API di Application Insights per eventi personalizzati e metriche
• Verificare di eseguire una versione supportata di Application Insights SDK.
• Per informazioni sul modello di dati e sui tipi di Application Insights, vedere il modello di dati.
• Aggiungi transazioni sintetiche per verificare che il sito Web sia disponibile in tutto il mondo con il monitoraggio della disponibilità.
• Vedere System.Diagnostics.Activity User Guide (Guida dell'utente di System.Diagnostics.Activity) per informazioni su come correlare i dati di telemetria.
• Configurare una raccolta di snapshot per visualizzare lo stato del codice sorgente e delle variabili nel momento in cui viene generata un'eccezione.

Documentazione di riferimento

• Informazioni di riferimento per i tipi di dati per ASP.NET SDK e ASP.NET Core SDK.
• Codice SDK per ASP.NET SDK e ASP.NET Core SDK.