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 di base di Application Insights per inviare metriche e eventi personalizzati e 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 di chiavi di strumentazione continuerà a funzionare, ma non forniamo più aggiornamenti o supporto per la funzionalità. Passare alle stringa di connessione per sfruttare le nuove funzionalità.

Riepilogo delle API

L'API principale è uniforme in tutte le piattaforme, a parte alcune varianti come 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 zero e multidimensionali, aggregazione configurata centralmente, 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 ASP.NET app Core e Non-HTTP/Worker per le app .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, le richieste HTTP in ingresso vengono acquisite automaticamente. Potrebbe essere necessario creare più istanze di TelemetryClient per altri moduli dell'app. Ad esempio, potrebbe essere presente un'istanza TelemetryClient della classe middleware per segnalare gli eventi della logica di business. È possibile impostare proprietà come 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. È consigliabile questo approccio 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 potresti voler 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 customEvents tabella nella scheda Log di Application Insights o nell'esperienza di utilizzo. Gli eventi possono provenire da trackEvent(..) o dal plug-in Click Analytics Auto collection.

Se il campionamento è in funzione, la itemCount proprietà 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).

Nota

itemCount ha un valore minimo di uno; il record stesso rappresenta una voce.

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

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 GetMetric(..) overload per ottenere un oggetto metrica per accedere alle funzionalità di pre-aggregazione dell'SDK.

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

Application Insights può creare un grafico delle metriche non associate a eventi specifici. 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 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.

    Si supponga, ad esempio, 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, si chiamerebbe 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. Tale riepilogo viene chiamato 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 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 di misurazioni aggregate in questa trackMetric(..) chiamata.

Nota

valueCount ha un valore minimo di uno; 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 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 sessione vengono inviati come proprietà insieme alle visualizzazioni pagina, in modo che i grafici utente e sessione vengano attivati quando sono presenti dati di telemetria della visualizzazione 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, i tempi segnalati come tempo di caricamento della visualizzazione pagina vengono misurati da quando il browser invia la richiesta fino a quando non viene chiamato l'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.

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 il tempo necessario al browser 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, 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 i dati di telemetria delle richieste è la posizione in cui la richiesta funge da contesto operativo.

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 tutti gli eventi associati alla richiesta usando il relativo ID operazione.

Per altre informazioni sulla correlazione, vedere Correlazione dei 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 se si chiama StopOperationin modo esplicito . 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 all'interno di un ambito di 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 sul rilevamento delle operazioni 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 è in funzione, la itemCount proprietà 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 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 automaticamente molte eccezioni, quindi non è sempre necessario chiamare 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 è in funzione, la itemCount proprietà 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 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é questa struttura è dinamica, è necessario eseguire il cast del risultato al 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 inviando un "percorso di navigazione" ad Application Insights. È possibile inviare blocchi di dati di diagnostica e controllarli in Ricerca diagnostica.

Negli adattatori di log .NET usare questa API per inviare log di terze parti al portale.

In Java, l'agente Java di Application Insights esegue automaticamente la raccolta 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 Mappa della stringa alla stringa. Altri dati vengono usati per filtrare le eccezioni nel portale. Per impostazione predefinita è vuoto.
severityLevel Valori supportati: SeverityLevel.ts.

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

Il limite delle dimensioni per message è molto superiore al limite per le proprietà. Un vantaggio di TrackTrace è che è possibile 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 Application Insights Analytics le chiamate da TrackTrace visualizzare nella traces tabella.

Se il campionamento è in funzione, la itemCount proprietà 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 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 TelemetryClient.StartOperation metodo (estensione) che riempie le DependencyTelemetry proprietà 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 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 consentire il funzionamento del modulo.

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

Questa chiamata viene usata se si desidera tenere traccia delle 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 Suppressing specific autocollected telemetry .For Java, see Suppressing specific autocollected telemetry.

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

.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 scaricare sempre come parte dell'arresto dell'applicazione per garantire che i dati di telemetria non vengano persi.

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 vengono scaricati automaticamente all'arresto dell'applicazione.

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 nel ASP.NET Core viene stampato insieme ai dati di telemetria lato client. Per questo motivo, l'aggiunta appInsights.setAuthenticatedUserContext manuale non sarebbe più necessaria perché è già inserita dall'SDK per ASP.NET Core. L'ID di autenticazione verrà inviato anche al server in cui l'SDK in .NET Core lo identificherà e lo userà per tutti i dati di telemetria lato server, come descritto nella guida di riferimento all'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 agli eventi, alle metriche, alle visualizzazioni di pagina, alle eccezioni e ad 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 sulla lunghezza della stringa. Per inviare blocchi di dati di grandi dimensioni, usare il parametro message 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 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 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 riutilizzare la stessa istanza dell'elemento di telemetria (event in questo esempio) per chiamare Track*() più volte. Questa procedura potrebbe causare l'invio dei dati di telemetria con una configurazione non corretta.

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 da customDimensions o customMeasurements JSON, ha un tipo dinamico, quindi è necessario eseguirne il tostring cast o todouble.
  • Per tenere conto della possibilità di campionamento, usare sum(itemCount) non count().

Eventi di intervallo

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 desidera impostare i valori predefiniti delle proprietà per alcuni degli eventi personalizzati scritti, impostarli in un'istanza TelemetryClient di . Sono collegati a ogni elemento di telemetria inviato da tale 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.

Dati di telemetria di esempio, filtro ed elaborazione

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 personalizzati TrackRequest .

Node.JS

telemetry.config.disableAppInsights = true;

Per disabilitare gli agenti di raccolta standard selezionati, ad esempio contatori delle prestazioni, richieste HTTP o dipendenze, in fase di inizializzazione, concatenare i metodi di configurazione al codice di inizializzazione dell'SDK.

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

Per disabilitare questi agenti di raccolta dopo l'inizializzazione, utilizzare 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. Disattivarlo nell'ambiente di produzione perché 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 maxBatchSize0su , 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 i dati di telemetria personalizzati selezionati

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 potrebbe essere necessario impostarlo dallo stato del server Web invece di codificarlo 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 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. Ad 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 relativi al dispositivo in cui l'applicazione è in esecuzione. 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: la posizione geografica del dispositivo.
  • Operazione: nelle App 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: 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 è impostato su un valore generato, che viene modificato quando l'utente non è stato attivo per un periodo di tempo.
  • 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 dei dati Da 30 a 730 giorni 730 giorni Questa risorsa è per i log.
Metriche di conservazione dei dati 90 giorni 90 giorni Questa risorsa è per Esplora metriche.
Conservazione dettagliata dei risultati dei test a più passaggi di disponibilità 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
Conservazione dei dati di snapshot e profiler 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 canali di telemetria 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 possono Track_() generare?

Nessuno. Non è necessario eseguirne il wrapping in clausole try-catch. Se l'SDK rileva problemi, registra i messaggi nell'output della console di debug e, se i messaggi vengono visualizzati, in Ricerca diagnostica.

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 è ancora in una risorsa classica.

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

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

Disattivare la strumentazione automatica nella portale di Azure nella scheda Application Insights della pagina servizio app o impostare su ApplicationInsightsAgent_EXTENSION_VERSIONdisabled.

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

Il campionamento riduce il numero di elementi di telemetria,ad esempio richieste ed eventi personalizzati, inviati dall'app al portale. In Cerca 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 contiene una itemCount proprietà che mostra il numero di eventi originali rappresentato dall'elemento. Per osservare il campionamento nell'operazione, è 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 riceverai una notifica fino al primo incrocio, indipendentemente dal fatto che il valore iniziale sia alto o basso. C'è sempre una latenza di alcuni minuti.

Passaggi successivi