Condividi tramite

API di Application Insights per metriche ed eventi personalizzati

  • Articolo

Inserire alcune righe di codice nell'applicazione per scoprire come viene usato dagli utenti o per agevolare la diagnosi dei problemi. È possibile inviare i dati di telemetria dalle app desktop e per dispositivi, dai client Web e dai server Web. Usare l'API di telemetria principale di Application Insights per inviare metriche ed eventi personalizzati e le versioni personalizzate dei dati di telemetria standard. Questa API è la stessa utilizzata dagli agenti di raccolta dati di Application Insights standard.

Nota

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

Riepilogo delle API

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

metodo Utilizzo
TrackPageView Pagine, schermate, riquadri o moduli.
TrackEvent Azioni dell'utente e altri eventi. Usato per tenere traccia del comportamento dell'utente o per monitorare le prestazioni.
GetMetric Metriche multidimensionali e con dimensioni pari a zero, aggregazione configurata a livello centrale, solo C#.
TrackMetric Misurazioni delle prestazioni, ad esempio la lunghezza della coda, non correlate a eventi specifici.
TrackException Registrare le eccezioni per la diagnosi. Tenere traccia del punto in cui si verificano in relazione ad altri eventi ed esaminare le analisi dello stack.
TrackRequest Registrare la frequenza e la durata delle richieste del server per l'analisi delle prestazioni.
TrackTrace Messaggi del log di diagnostica delle risorse. È anche possibile acquisire log di terze parti.
TrackDependency Registrare la durata e la frequenza delle chiamate ai componenti esterni da cui dipende l'app.

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

Prima di iniziare

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

Ottenere un'istanza di TelemetryClient

Ottenere un'istanza di TelemetryClient (tranne che in JavaScript nelle pagine Web):

Per le app ASP.NET Core e non HTTP/ruolo di lavoro per .NET/.NET Core, ottenere un'istanza di TelemetryClient dal contenitore di inserimento delle dipendenze, come illustrato nella rispettiva documentazione.

Se si usa Funzioni di Azure v2 o Processi Web di Azure v3+, vedere Monitorare Funzioni di Azure.

C#

private TelemetryClient telemetry = new TelemetryClient();

Se viene visualizzato un messaggio che indica che questo metodo è obsoleto, vedere microsoft/ApplicationInsights-dotnet#1152 per altre informazioni.

Visual Basic

Private Dim telemetry As New TelemetryClient

Java

private TelemetryClient telemetry = new TelemetryClient();

Node.js

var telemetry = applicationInsights.defaultClient;

L'oggetto TelemetryClient è thread-safe.

Per i progetti ASP.NET e Java, vengono acquisite automaticamente le richieste HTTP in ingresso. Potrebbe essere necessario creare più istanze di TelemetryClient per altri moduli dell'app. Ad esempio potrebbe esserci un’istanza di TelemetryClient in una classe middleware per segnalare eventi di logica di business. È possibile impostare proprietà quali UserId e DeviceId per identificare il computer. Queste informazioni sono associate a tutti gli eventi inviati dall'istanza.

C#

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

Java

telemetry.getContext().getUser().setId("...");
telemetry.getContext().getDevice().setId("...");

Nei progetti Node.js è possibile usare new applicationInsights.TelemetryClient(instrumentationKey?) per creare una nuova istanza. Questo approccio è consigliato solo per gli scenari che richiedono una configurazione isolata dal singleton 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" del framework.

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 potrebbe essere utile sapere con quale frequenza raggiungono determinati obiettivi o commettono tipi specifici di errori.

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

JavaScript

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

C#

telemetry.TrackEvent("WinGame");

Visual Basic

telemetry.TrackEvent("WinGame")

Java

telemetry.trackEvent("WinGame");

Node.js

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

Eventi personalizzati in Log Analytics

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

Se il campionamento è attivo, la proprietà itemCount mostra un valore maggiore di 1. Ad esempio, itemCount==10 indica che, su 10 chiamate di trackEvent(), il processo di campionamento ne trasmette solo una. Per ottenere un conteggio corretto degli eventi personalizzati, usare codice come customEvents | summarize sum(itemCount).

Nota

itemCount ha un valore minimo di 1. Il record stesso rappresenta una voce.

GetMetric

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

TrackMetric

Nota

Microsoft.ApplicationInsights.TelemetryClient.TrackMetric non è il metodo preferito per l'invio di metriche. Le metriche devono essere sempre pre-aggregate per un periodo di tempo prima dell'invio. Usare uno degli overload GetMetric(..) per ottenere un oggetto metrica per l'accesso alle funzionalità di pre-aggregazione dell'SDK.

Se si implementa la propria logica di pre-aggregazione, è possibile usare il metodo TrackMetric() per inviare le aggregazioni risultanti. Se l'applicazione richiede ogni volta l'invio di un elemento di telemetria separato senza aggregazione nel tempo, è probabile che si tratti di un caso d'uso per la telemetria degli eventi. Vedere TelemetryClient.TrackEvent (Microsoft.ApplicationInsights.DataContracts.EventTelemetry).

Application Insights è in grado di creare grafici in base a metriche non associate a determinati eventi. Ad esempio, è possibile monitorare la lunghezza di una coda a intervalli regolari. Grazie alle metriche, le singole misurazioni sono meno interessanti rispetto alle variazioni e alle tendenze, i grafici statistici risultano pertanto utili.

Per inviare le metriche ad Application Insights, è possibile usare l'API TrackMetric(..). Per inviare le metriche è possibile procedere in due modi:

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

    Ad esempio, si supponga di avere una metrica che descrive il numero di elementi in un contenitore. Durante un periodo di tempo specifico, inserire prima tre elementi nel contenitore e poi rimuoverne due. Di conseguenza, è necessario chiamare TrackMetric due volte. Prima di tutto, passare il valore 3 e quindi passare il valore -2. Application Insights memorizza automaticamente entrambi i valori.

  • Aggregazione. Quando si usano le metriche non si considera quasi mai una sola misura. È importante invece il riepilogo delle operazioni eseguite in un periodo di tempo specifico. Tale riepilogo viene chiamato aggregazione.

    Nell'esempio precedente la somma della metrica di aggregazione per quel periodo di tempo è 1 e il conteggio dei valori della metrica è 2. Quando si usa l'approccio di aggregazione, si chiama TrackMetric solo una volta per periodo di tempo e si inviano i valori di aggregazione. Questo è l'approccio consigliato perché può ridurre notevolmente i costi e il sovraccarico per le prestazioni inviando meno punti dati ad Application Insights, raccogliendo comunque tutte le informazioni pertinenti.

Esempi di singolo valore

Per inviare un singolo valore di metrica:

JavaScript

appInsights.trackMetric({name: "queueLength", average: 42});

C#

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

Java

telemetry.trackMetric("queueLength", 42.0);

Node.js

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

Metriche personalizzate in Log Analytics

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

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

Nota

valueCount ha un valore minimo di 1. Il record stesso rappresenta una voce.

Visualizzazioni pagina

In un'app per dispositivo o pagine Web i dati di telemetria delle visualizzazioni pagina vengono inviati per impostazione predefinita quando viene caricata ogni schermata o pagina. È tuttavia possibile modificare l'impostazione predefinita per tenere traccia delle visualizzazioni di pagina in momenti diversi o aggiuntivi. 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 relativi a utente e sessione vengono inviati come proprietà insieme alle visualizzazioni di pagina, in modo che i grafici utente e di sessione si attivino in presenza dei dati di telemetria delle visualizzazioni di pagina.

Visualizzazioni pagina personalizzate

JavaScript

appInsights.trackPageView("tab1");

C#

telemetry.TrackPageView("GameReviewPage");

Visual Basic

telemetry.TrackPageView("GameReviewPage")

Java

telemetry.trackPageView("GameReviewPage");

Se sono presenti alcune schede in pagine HTML diverse, è possibile specificare anche l'URL:

appInsights.trackPageView("tab1", "http://fabrikam.com/page1.htm");

Temporizzazione delle visualizzazioni delle pagine

Per impostazione predefinita, gli intervalli di tempo indicati come Tempo di caricamento della visualizzazione pagina sono misurati dal momento in cui il browser invia la richiesta al momento della chiamata dell'evento di caricamento della pagina del browser.

In alternativa, è possibile:

  • Impostare una durata esplicita nella chiamata di trackPageView: appInsights.trackPageView("tab1", null, null, null, durationInMilliseconds);.
  • Usare le chiamate relative ai tempi di visualizzazione della pagina startTrackPage e stopTrackPage.

JavaScript

// To start timing a page:
appInsights.startTrackPage("Page1");

...

// To stop timing and log the page:
appInsights.stopTrackPage("Page1", url, properties, measurements);

Il nome che si usa come primo parametro associa le chiamate di avvio e arresto. Il valore predefinito corrisponde al nome della pagina corrente.

I tempi di caricamento delle pagine visualizzati in Esplora metriche sono calcolati in base all'intervallo tra la chiamata di avvio e la chiamata di arresto. È possibile specificare l'intervallo effettivo calcolato desiderato.

Dati di telemetria della pagina in Log Analytics

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

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

Per trovare il tempo necessario al browser per elaborare pagine diverse:

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

Per individuare la popolarità dei diversi browser:

pageViews
| summarize count() by client_Browser

Per associare le visualizzazioni di pagina alle chiamate AJAX, unirle alle 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 vogliono simulare le richieste in un contesto in cui il modulo del servizio Web non è in esecuzione.

Il modo consigliato per inviare dati di telemetria della richiesta è quello in cui la richiesta agisce come un contesto dell'operazione.

Contesto dell'operazione

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

Per altre informazioni sulla correlazione, vedere Correlazione di dati di telemetria in Application Insights.

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:

C#

// Establish an operation context and associated telemetry item:
using (var operation = telemetryClient.StartOperation<RequestTelemetry>("operationName"))
{
    // Telemetry sent in here will use 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.

Oltre a impostare un contesto operativo, 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 sua durata viene impostata sull'intervallo di tempo compreso tra l'avvio e l'arresto.

Gli elementi di telemetria segnalati in un ambito dell'operazione diventano elementi figlio di tale operazione. I contesti dell'operazione possono essere annidati.

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

Screenshot che mostra l'elenco Elementi correlati.

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

Richieste in Log Analytics

In Analytics di Application Insights le richieste vengono visualizzate nella tabella requests.

Se il campionamento è attivo, la proprietà itemCount mostra un valore maggiore di 1. Ad esempio, itemCount==10 indica che, su 10 chiamate di trackRequest(), il processo di campionamento ne trasmette solo una. Per ottenere un conteggio corretto delle richieste e della durata media segmentato in base ai nomi della richiesta, usare un codice, ad esempio:

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

TrackException

Inviare le eccezioni ad Application Insights:

I report includono le analisi dello stack.

C#

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

Java

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

JavaScript

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

Node.JS

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

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

({
    instrumentationKey: "your key",
    disableExceptionTracking: true
})

Eccezioni in Log Analytics

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

Se il campionamento è attivo, la proprietà itemCount mostra un valore maggiore di 1. Ad esempio, itemCount==10 indica che, su 10 chiamate di trackException(), il processo di campionamento ne trasmette solo una. Per ottenere un conteggio corretto delle eccezioni segmentate per tipo di eccezione, usare un codice, ad esempio:

exceptions
| summarize sum(itemCount) by type

La maggior parte delle informazioni importanti dello stack è già stata estratta in variabili distinte, ma è possibile separare la struttura details per ottenerne altre. Poiché si tratta di una struttura dinamica, è necessario eseguire il cast del risultato per il tipo previsto. Ad esempio:

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

Per associare le richieste alle eccezioni correlate, è possibile usare 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 e controllarli in Ricerca diagnostica.

In .NET gli adattatori di log usano questa API per inviare i log di terze parti al portale.

In Java, l'agente Java di Application Insights raccoglie automaticamente e invia i log al portale.

C#

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

Java

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

Node.js

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

JavaScript lato client/browser

trackTrace({
    message: string,
    properties?: {[string]:string},
    severityLevel?: SeverityLevel
})

Registrare un evento di diagnostica, ad esempio inserire o rimuovere un metodo.

Parametro Descrizione
message Dati di diagnostica. Possono essere molto più lunghi di un nome.
properties Mapping da stringa a stringa. Dati aggiuntivi usati per filtrare le eccezioni nel portale. Per impostazione predefinita è vuoto.
severityLevel Valori supportati: SeverityLevel.ts.

È possibile eseguire ricerche nel contenuto del messaggio, ma, a differenza dei valori delle proprietà, non è possibile applicare filtri.

Il limite delle dimensioni per message è molto superiore al limite per le proprietà. Un vantaggio di TrackTrace è la possibilità di inserire dati relativamente lunghi nel messaggio. Ad esempio è possibile codificare dati POST.

È anche possibile aggiungere al messaggio un livello di gravità. E come per altri tipi di dati di telemetria è possibile aggiungere valori di proprietà utili per filtrare o cercare set di tracce diversi. Ad esempio:

C#

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

Java

Map<String, Integer> properties = new HashMap<>();
properties.put("Database", db.ID);
telemetry.trackTrace("Slow Database response", SeverityLevel.Warning, properties);

In Ricerca sarà possibile filtrare facilmente tutti i messaggi di un determinato livello di gravità relativi a un database specifico.

Tracce in Log Analytics

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

Se il campionamento è attivo, la proprietà itemCount mostra un valore maggiore di 1. Ad esempio, itemCount==10 indica che, su 10 chiamate di trackTrace(), il processo di campionamento ne trasmette solo una. Per ottenere un conteggio corretto delle chiamate di traccia, usare codice come traces | summarize sum(itemCount).

TrackDependency

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

Nota

Per .NET e .NET Core, è possibile usare in alternativa il metodo TelemetryClient.StartOperation (estensione) che compila le proprietà DependencyTelemetry necessarie per la correlazione e altre proprietà come l'ora di inizio e la durata, quindi non è necessario creare un timer personalizzato come negli esempi seguenti. Per altre informazioni, vedere la sezione relativa al rilevamento delle dipendenze in uscita in Tenere traccia delle operazioni personalizzate con Application Insights .NET SDK.

C#

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

Java

boolean success = false;
Instant startTime = Instant.now();
try {
    success = dependency.call();
}
finally {
    Instant endTime = Instant.now();
    Duration delta = Duration.between(startTime, endTime);
    RemoteDependencyTelemetry dependencyTelemetry = new RemoteDependencyTelemetry("My Dependency", "myCall", delta, success);
    dependencyTelemetry.setTimeStamp(startTime);
    telemetry.trackDependency(dependencyTelemetry);
}

Node.js

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 server includono un modulo dipendenza che consente di individuare e tracciare alcune chiamate di dipendenza automaticamente, ad esempio a database e API REST. È necessario installare un agente nel server per consentire il funzionamento del modulo.

In Java, molte chiamate di dipendenza possono essere tracciate automaticamente usando l'agente Java di Application Insights.

Usare questa chiamata se si vuole tenere traccia di chiamate che il rilevamento automatico non intercetta.

Per disattivare il modulo standard per il rilevamento delle dipendenze in C#, modificare il file ApplicationInsights.config ed eliminare il riferimentoDependencyCollector.DependencyTrackingTelemetryModule. Per Java, vedere Eliminazione di dati di telemetria raccolti automaticamente specifici.

Dipendenze in Log Analytics

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

Se il campionamento è attivo, la proprietà itemCount mostra un valore maggiore di 1. Ad esempio, itemCount==10 indica che, su 10 chiamate di trackDependency(), il processo di campionamento ne trasmette solo una. Per ottenere un conteggio corretto delle dipendenze segmentate per componente di destinazione, usare un 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

Scaricamento dei dati

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

.NET

Quando si usa Flush(), è consigliabile usare questo modello:

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

Quando si usa FlushAsync(), è consigliabile usare questo modello:

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

È consigliabile eseguire sempre lo scaricamento come parte dell'arresto dell'applicazione per garantire che i dati di telemetria non vadano perduti.

Java

telemetry.flush();
//Allow some time for flushing before shutting down
Thread.sleep(5000);

Node.js

telemetry.flush();

La funzione è asincrona per il canale di telemetria del server.

Nota

  • Gli SDK Java e JavaScript prevedono lo scaricamento automatico all'arresto dell'applicazione.
  • Esaminare la configurazione di scaricamento automatico: l'abilitazione dello scaricamento automatico nel file web.config può causare una riduzione delle prestazioni nelle applicazioni .NET instrumentate con Application Insights. Con lo scaricamento automatico abilitato, ogni chiamata di metodi System.Diagnostics.Trace.Trace* comporta l'invio di singoli elementi di telemetria come richieste Web distinte al servizio di inserimento. Ciò può causare potenzialmente l'esaurimento delle risorse di rete e archiviazione nei server Web. Per migliorare le prestazioni, è consigliabile disabilitare lo scaricamento automatico e usare anche ServerTelemetryChannel, progettato per una trasmissione dei dati di telemetria più efficace.

Utenti autenticati

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

Se gli utenti accedono all'app, è possibile ottenere un conteggio più preciso impostando l'ID dell'utente autenticato nel codice del browser:

JavaScript

// Called when my app has identified the user.
function Authenticated(signInId) {
    var validatedId = signInId.replace(/[,;=| ]+/g, "_");
    appInsights.setAuthenticatedUserContext(validatedId);
    ...
}

In un'applicazione MVC Web ASP.NET, ad esempio:

Razor

@if (Request.IsAuthenticated)
{
    <script>
        appInsights.setAuthenticatedUserContext("@User.Identity.Name
            .Replace("\\", "\\\\")"
            .replace(/[,;=| ]+/g, "_"));
    </script>
}

Non è necessario usare il nome di accesso effettivo dell'utente. È sufficiente usare un ID univoco per l'utente. Non deve includere spazi o i caratteri ,;=|.

L'ID utente viene inoltre impostato in un cookie di sessione e inviato al server. Se l'SDK del server è installato, l'ID dell'utente autenticato viene inviato come parte delle proprietà contestuali della telemetria del client e del server. Quindi sarà possibile filtrarlo ed eseguire ricerche al suo interno.

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

appInsights.setAuthenticatedUserContext(validatedId, accountId);

In Esplora metriche è possibile creare un grafico che conta i valori Utenti, Autenticati e Account utente.

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

Nota

La proprietà EnableAuthenticationTrackingJavaScript nella classe ApplicationInsightsServiceOptions in .NET Core SDK semplifica la configurazione JavaScript necessaria per inserire il nome utente come ID di autenticazione per ogni traccia inviata da Application Insights JavaScript SDK.

Quando questa proprietà è impostata su true, il nome utente dell'utente in ASP.NET Core viene stampato insieme ai dati di telemetria lato client. Per questo motivo, l'aggiunta manuale di appInsights.setAuthenticatedUserContext non sarebbe più necessaria perché è già inserito dall'SDK per ASP.NET Core. Anche l'ID di autenticazione verrà inviato al server in cui l'SDK in .NET Core lo identificherà e lo userà per tutti i dati di telemetria lato server, come descritto nelle informazioni di riferimento per l'API JavaScript.

Per le applicazioni JavaScript che non funzionano allo stesso modo di ASP.NET Core MVC, ad esempio app Web SPA, è comunque necessario aggiungere appInsights.setAuthenticatedUserContext manualmente.

Filtrare, cercare e segmentare i dati usando le proprietà

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

proprietà sono valori di stringa che è possibile usare per filtrare i dati di telemetria nei report di utilizzo. Ad esempio, se l'app offre più giochi, è possibile associare il nome del gioco a ogni evento per vedere quali sono i giochi più diffusi.

Esiste un limite di 8.192 per la lunghezza della stringa. Se si vogliono inviare grandi blocchi di dati, usare il parametro del messaggio di TrackTrace.

metriche sono valori numerici che possono essere rappresentati graficamente. Ad esempio è possibile verificare se esiste un aumento graduale nei punteggi raggiunti dai giocatori. I grafici possono essere segmentati in base alle proprietà inviate con l'evento, in modo da 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 tuttavia alcuni limiti sul numero di proprietà, di valori delle proprietà e di metriche che è possibile usare.

JavaScript

appInsights.trackEvent({
  name: 'some event',
  properties: { // accepts any type
    prop1: 'string',
    prop2: 123.45,
    prop3: { nested: 'objects are okay too' }
  }
});

appInsights.trackPageView({
  name: 'some page',
  properties: { // accepts any type
    prop1: 'string',
    prop2: 123.45,
    prop3: { nested: 'objects are okay too' }
  }
});

C#

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

Node.JS

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

Visual Basic

' Set up some properties:
Dim properties = New Dictionary (Of String, String)
properties.Add("game", currentGame.Name)
properties.Add("difficulty", currentGame.Difficulty)

Dim metrics = New Dictionary (Of String, Double)
metrics.Add("Score", currentGame.Score)
metrics.Add("Opponents", currentGame.OpponentCount)

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

Java

Map<String, String> properties = new HashMap<String, String>();
properties.put("game", currentGame.getName());
properties.put("difficulty", currentGame.getDifficulty());

Map<String, Double> metrics = new HashMap<String, Double>();
metrics.put("Score", currentGame.getScore());
metrics.put("Opponents", currentGame.getOpponentCount());

telemetry.trackEvent("WinGame", properties, metrics);

Nota

Assicurarsi di non registrare informazioni personali nelle proprietà.

Metodo alternativo per impostare proprietà e metriche

Se si preferisce, è 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);

Avviso

Non riusare la stessa istanza dell'elemento di telemetria, event in questo esempio, per chiamare Track*() più volte. Questo approccio potrebbe causare l'invio della telemetria con una configurazione errata.

Misurazioni e proprietà personalizzate in Log Analytics

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

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

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

Si noti che:

  • Quando si estrae un valore da customDimensions o customMeasurements JSON, il tipo è dinamico, quindi è necessario eseguirne il cast in tostring o todouble.
  • Per tener conto della possibilità di campionamento, usare sum(itemCount) e non count().

Eventi di temporizzazione

A volte si vuole rappresentare in un grafico il tempo necessario per eseguire un'azione. Ad esempio si potrebbe voler sapere quanto tempo occorre agli utenti per scegliere tra le opzioni disponibili in un gioco. Per ottenere queste informazioni, usare il parametro di misurazione.

C#

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

Java

long startTime = System.currentTimeMillis();

// Perform timed action

long endTime = System.currentTimeMillis();
Map<String, Double> metrics = new HashMap<>();
metrics.put("ProcessingTime", (double)endTime-startTime);

// Setup some properties
Map<String, String> properties = new HashMap<>();
properties.put("signalSource", currentSignalSource.getName());

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

Proprietà predefinite per i dati di telemetria personalizzati

Se si vogliono impostare solo i valori di proprietà predefiniti per alcuni eventi personalizzati scritti, è possibile impostarli in un'istanza di TelemetryClient. Vengono associati a ogni elemento di telemetria inviato da quel client.

C#

using Microsoft.ApplicationInsights.DataContracts;

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

Visual Basic

Dim gameTelemetry = New TelemetryClient()
gameTelemetry.Context.GlobalProperties("Game") = currentGame.Name
' Now all telemetry will automatically be sent with the context property:
gameTelemetry.TrackEvent("WinGame")

Java

import com.microsoft.applicationinsights.TelemetryClient;
import com.microsoft.applicationinsights.TelemetryContext;
...

TelemetryClient gameTelemetry = new TelemetryClient();
TelemetryContext context = gameTelemetry.getContext();
context.getProperties().put("Game", currentGame.Name);

gameTelemetry.TrackEvent("WinGame");

Node.js

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

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

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

Per i client Web di JavaScript, usare gli inizializzatori di telemetria JavaScript.

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

Campionare, filtrare ed elaborare i dati di telemetria

Vedere Filtrare e pre-elaborare i dati di telemetria in Application Insights SDK.

Disabilitare telemetria

Per avviare e arrestare in modo dinamico la raccolta e la trasmissione di dati di telemetria:

C#

using  Microsoft.ApplicationInsights.Extensibility;

TelemetryConfiguration.Active.DisableTelemetry = true;

Java

telemetry.getConfiguration().setTrackingDisabled(true);

Per disabilitare gli agenti di raccolta standard selezionati, ad esempio contatori delle prestazioni, richieste HTTP o dipendenze, eliminare o impostare come commento le righe pertinenti in ApplicationInsights.config. Un esempio è se si vogliono inviare dati TrackRequest personalizzati.

Node.JS

telemetry.config.disableAppInsights = true;

Per disabilitare gli agenti di raccolta standard selezionati (ad esempio, i contatori delle prestazioni, le richieste HTTP o le dipendenze, in fase di inizializzazione), concatenare i metodi di configurazione con il codice di inizializzazione SDK.

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

Per disabilitare questi agenti di raccolta dopo l'inizializzazione, usare l'oggetto Configuration: applicationInsights.Configuration.setAutoCollectRequests(false).

Modalità sviluppatore

Durante il debug, è utile accelerare i dati di telemetria venga nella pipeline in modo da visualizzare immediatamente i risultati. Si ottengono anche altri messaggi che consentono di tracciare eventuali problemi con i dati di telemetria. Disattivare questa modalità in produzione poiché potrebbe rallentare l'app.

C#

TelemetryConfiguration.Active.TelemetryChannel.DeveloperMode = true;

Visual Basic

TelemetryConfiguration.Active.TelemetryChannel.DeveloperMode = True

Node.JS

Per Node.js, è possibile abilitare la modalità sviluppatore abilitando la registrazione interna tramite setInternalLogging e impostando maxBatchSize su 0, che fa sì che i dati di telemetria vengano inviati non appena vengono raccolti.

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

Impostare la chiave di strumentazione per la telemetria personalizzata selezionata

C#

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

Chiave di strumentazione dinamica

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

Invece di 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:

C#

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

JavaScript

appInsights.config.instrumentationKey = myKey;

Nelle pagine Web è possibile impostarla dallo stato del server Web anziché codificarla letteralmente nello script. Ad esempio, in una pagina Web generata in un'app ASP.NET:

JavaScript in Razor

<script type="text/javascript">
// Standard Application Insights webpage script:
var appInsights = window.appInsights || function(config){ ...
// Modify this part:
}({instrumentationKey:
    // Generate from server property:
    @Microsoft.ApplicationInsights.Extensibility.
        TelemetryConfiguration.Active.InstrumentationKey;
}) // ...

    String instrumentationKey = "00000000-0000-0000-0000-000000000000";

    if (instrumentationKey != null)
    {
        TelemetryConfiguration.getActive().setInstrumentationKey(instrumentationKey);
    }

TelemetryContext

TelemetryClient ha una proprietà Context contenente valori che vengono inviati insieme a tutti i dati di telemetria. Sono in genere impostati dai moduli di telemetria standard, ma è possibile anche impostarli manualmente. Ad esempio:

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

Se si imposta uno di questi valori manualmente, provare a rimuovere la riga pertinente da ApplicationInsights.config, in modo che i valori personali e quelli standard non si confondano.

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

Limiti

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

Conto risorse Limite predefinito Limite massimo Note
Totale dati al giorno 100 GB Contattare il supporto tecnico. È possibile impostare un limite per ridurre i dati. Se sono necessari più dati, è possibile aumentare il limite nel portale fino a 1.000 GB. Per capacità maggiori di 1.000 GB, inviare un messaggio di posta elettronica a AIDataCap@microsoft.com.
Limitazione 32.000 eventi/secondo Contattare il supporto tecnico. Il limite viene misurato nell'arco di un minuto.
Log di conservazione dati 30 - 730 giorni 730 giorni Questa risorsa è per i Log.
Metriche di conservazione dati 90 giorni 90 giorni Questa risorsa è pensata per Esplora metriche.
Conservazione dei risultati dettagliati di test di disponibilità in più passi 90 giorni 90 giorni Questa risorsa fornisce risultati dettagliati per ogni passaggio.
Dimensioni massime dei dati di telemetria 64 kB 64 kB
Numero massimo di dati di telemetria per batch 64.000 64.000
Lunghezza nomi di proprietà e metriche 150 150 Vedere gli schemi per tipo.
Lunghezza stringa valore di proprietà 8,192 8,192 Vedere gli schemi per tipo.
Lunghezza messaggio di traccia e di eccezione 32.768 32.768 Vedere gli schemi per tipo.
Numero di test di disponibilità per ogni risorsa di Application Insights 100 100
Numero di test di disponibilità per gruppo di risorse 800 800 Vedere Azure Resource Manager
Numero massimo di reindirizzamenti per test di disponibilità 10 10
Frequenza minima dei test di disponibilità 300 secondi Le frequenze di test personalizzate o le frequenze inferiori a 5 minuti richiedono implementazioni personalizzate di TrackAvailability.
Conservazione dati di Profiler e Snapshot Due settimane Contattare il supporto tecnico. Il limite massimo di conservazione è di sei mesi.
Dati profiler inviati al giorno Nessun limite Nessun limite.
Dati snapshot inviati al giorno 30 snapshot al giorno per ogni app monitorata Nessun limite. Il numero di snapshot raccolti per applicazione può essere modificato tramite la configurazione.

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 quanto tempo vengono conservati i dati, vedere Raccolta, conservazione e archiviazione di dati in Application Insights.

Documentazione di riferimento

Codice SDK

Domande frequenti

Questa sezione fornisce le risposte alle domande comuni.

Perché mancano i dati di telemetria?

Entrambi i TelemetryChannel perderanno i dati di telemetria memorizzati nel buffer se non vengono scaricati prima dell'arresto di un'applicazione.

Per evitare la perdita di dati, scaricare TelemetryClient quando un'applicazione viene arrestata.

Per altre informazioni, vedere Scaricamento dei dati.

Quali eccezioni potrebbero essere generate dalle chiamate Track_()?

Nessuno. Non è necessario eseguirne il wrapping in clausole try-catch. Se l'SDK rileva un problema, registrerà messaggi nell'output della console di debug e quindi in Ricerca diagnostica per approfondirne i dettagli.

Esiste un'API REST per ottenere dati dal portale?

Sì, l'API di accesso ai dati. Altri modi per estrarre i dati includono Power BI se è stata eseguita la migrazione a una risorsa basata sull'area di lavoro o l'esportazione continua se si usa ancora una risorsa classica.

Perché le chiamate alle API di metriche e eventi personalizzati vengono ignorate?

Application Insights SDK non è compatibile con la strumentazione automatica. Se la strumentazione automatica è abilitata, le chiamate a Track() e altre API di metriche e eventi personalizzati verranno ignorate.

Disattivare la strumentazione automatica nel portale di Azure nella scheda Application Insights della pagina Servizio app o impostare ApplicationInsightsAgent_EXTENSION_VERSION su disabled.

Perché i conteggi nei grafici di ricerca e di metrica non sono uguali?

Il campionamento riduce il numero di elementi di telemetria (richieste, eventi personalizzati e così via) inviati effettivamente dall'app al portale. In Ricerca viene visualizzato il numero di elementi ricevuti. Nei grafici di metrica che visualizzano un conteggio degli eventi, è possibile vedere il numero di eventi originali che si sono verificati.

Ogni elemento trasmesso include una proprietà itemCount che visualizza il numero di eventi originali rappresentati da questo elemento. Per osservare un campionamento in esecuzione, è possibile eseguire questa query in Log Analytics:

    requests | summarize original_events = sum(itemCount), transmitted_events = count()

Come è possibile impostare un avviso per un evento?

Gli avvisi di Azure si applicano solo alle metriche. Creare una metrica personalizzata che supera una soglia di valori ogni volta che si verifica l'evento. Impostare quindi un avviso per la metrica. Si riceve una notifica ogni volta che la metrica supera la soglia in entrambe le direzioni. Non si riceverà una notifica fino al primo superamento, indipendentemente dal fatto che il valore iniziale sia alto o basso. Esiste sempre una latenza di pochi minuti.

Passaggi successivi