API di Application Insights per metriche ed eventi personalizzatiApplication Insights API for custom events and metrics

Inserire alcune righe di codice nell'applicazione per scoprire come viene usato dagli utenti o per agevolare la diagnosi dei problemi.Insert a few lines of code in your application to find out what users are doing with it, or to help diagnose issues. È possibile inviare i dati di telemetria dalle app desktop e per dispositivi, dai client Web e dai server Web.You can send telemetry from device and desktop apps, web clients, and web servers. Usare l'API di telemetria principale di Azure Application Insights per inviare metriche ed eventi personalizzati e le versioni personalizzate dei dati di telemetria standard.Use the Azure Application Insights core telemetry API to send custom events and metrics, and your own versions of standard telemetry. Questa API è la stessa utilizzata dagli agenti di raccolta dati di Application Insights standard.This API is the same API that the standard Application Insights data collectors use.

Riepilogo dell'APIAPI summary

L'API è uniforme in tutte le piattaforme, a parte alcune variazioni di lieve entità.The API is uniform across all platforms, apart from a few small variations.

MetodoMethod Usato perUsed for
TrackPageView Pagine, schermate, pannelli o form.Pages, screens, blades, or forms.
TrackEvent Azioni dell'utente e altri eventi.User actions and other events. Usato per tenere traccia del comportamento dell'utente o per monitorare le prestazioni.Used to track user behavior or to monitor performance.
TrackMetric Misurazioni delle prestazioni, ad esempio la lunghezza della coda, non correlate a eventi specifici.Performance measurements such as queue lengths not related to specific events.
TrackException Registrare le eccezioni per la diagnosi.Logging exceptions for diagnosis. Tenere traccia del punto in cui si verificano in relazione ad altri eventi ed esaminare le analisi dello stack.Trace where they occur in relation to other events and examine stack traces.
TrackRequest Registrare la frequenza e la durata delle richieste del server per l'analisi delle prestazioni.Logging the frequency and duration of server requests for performance analysis.
TrackTrace Messaggi nei log di diagnostica.Diagnostic log messages. È anche possibile acquisire log di terze parti.You can also capture third-party logs.
TrackDependency Registrare la durata e la frequenza delle chiamate ai componenti esterni da cui dipende l'app.Logging the duration and frequency of calls to external components that your app depends on.

È possibile associare proprietà e metriche alla maggior parte di queste chiamate di telemetria.You can attach properties and metrics to most of these telemetry calls.

Prima di iniziareBefore you start

Se non si ha ancora un riferimento in Application Insights SDK:If you don't have a reference on Application Insights SDK yet:

  • Aggiungere Application Insights SDK al progetto:Add the Application Insights SDK to your project:

  • Nel dispositivo o nel codice del server Web includere:In your device or web server code, include:

    C#: using Microsoft.ApplicationInsights;C#: using Microsoft.ApplicationInsights;

    Visual Basic: Imports Microsoft.ApplicationInsightsVisual Basic: Imports Microsoft.ApplicationInsights

    Java:import com.microsoft.applicationinsights.TelemetryClient;Java: import com.microsoft.applicationinsights.TelemetryClient;

    Node.js: var applicationInsights = require("applicationinsights");Node.js: var applicationInsights = require("applicationinsights");

Ottenere un'istanza di TelemetryClientGet a TelemetryClient instance

Ottenere un'istanza di TelemetryClient (tranne che in JavaScript nelle pagine Web):Get an instance of TelemetryClient (except in JavaScript in webpages):

C#C#

private TelemetryClient telemetry = new TelemetryClient();

Visual BasicVisual Basic

Private Dim telemetry As New TelemetryClient

JavaJava

private TelemetryClient telemetry = new TelemetryClient();

Node.jsNode.js

var telemetry = applicationInsights.defaultClient;

TelemetryClient è thread-safe.TelemetryClient is thread-safe.

Per i progetti ASP.NET e Java è consigliabile creare un'istanza di TelemetryClient per ogni modulo dell'app.For ASP.NET and Java projects, we recommend that you create an instance of TelemetryClient for each module of your app. Ad esempio è possibile che il servizio Web includa un'istanza di TelemetryClient per segnalare le richieste HTTP in entrata e un altro oggetto in una classe middleware per segnalare gli eventi di logica di business.For instance, you may have one TelemetryClient instance in your web service to report incoming HTTP requests, and another in a middleware class to report business logic events. È possibile impostare proprietà quali TelemetryClient.Context.User.Id per tenere traccia degli utenti e delle sessioni o TelemetryClient.Context.Device.Id per identificare il computer.You can set properties such as TelemetryClient.Context.User.Id to track users and sessions, or TelemetryClient.Context.Device.Id to identify the machine. Queste informazioni sono associate a tutti gli eventi inviati dall'istanza.This information is attached to all events that the instance sends.

Nei progetti Node.js è possibile usare new applicationInsights.TelemetryClient(instrumentationKey?) per creare una nuova istanza, ma questo è consigliato solo per scenari che richiedono la configurazione isolata dal defaultClient singleton.In Node.js projects, you can use new applicationInsights.TelemetryClient(instrumentationKey?) to create a new instance, but this is recommended only for scenarios that require isolated configuration from the singleton defaultClient.

TrackEventTrackEvent

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.In Application Insights, a custom event is a data point that you can display in Metrics Explorer as an aggregated count, and in Diagnostic Search as individual occurrences. Non è correlato a MVC o ad altri "eventi" del framework.(It isn't related to MVC or other framework "events.")

Inserire chiamate TrackEvent nel codice per contare i vari eventi.Insert TrackEvent calls in your code to count various events. La frequenza d'uso di una particolare funzionalità, la frequenza di raggiungimento di obiettivi specifici o la frequenza di particolari tipi di errore.How often users choose a particular feature, how often they achieve particular goals, or maybe how often they make particular types of mistakes.

Ad esempio, in un'app di gioco è possibile inviare un evento ogni volta che un utente vince il gioco:For example, in a game app, send an event whenever a user wins the game:

JavaScriptJavaScript

appInsights.trackEvent("WinGame");

C#C#

telemetry.TrackEvent("WinGame");

Visual BasicVisual Basic

telemetry.TrackEvent("WinGame")

JavaJava

telemetry.trackEvent("WinGame");

Node.jsNode.js

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

Visualizzare gli eventi nel portale di Microsoft AzureView your events in the Microsoft Azure portal

Per visualizzare un conteggio degli eventi, aprire un pannello Esplora metriche , aggiungere un nuovo grafico e selezionare Eventi.To see a count of your events, open a Metrics Explorer blade, add a new chart, and select Events.

Visualizzare il conteggio degli eventi personalizzati

Per confrontare il conteggio di eventi diversi, impostare il tipo di grafico su Griglia e raggruppare in base al nome dell'evento:To compare the counts of different events, set the chart type to Grid, and group by event name:

Impostare il tipo di grafico e il raggruppamento

Nella griglia, fare clic su un nome di evento per visualizzare le singole occorrenze di quell'evento.On the grid, click through an event name to see individual occurrences of that event. Per altre informazioni, fare clic su qualsiasi occorrenza nell'elenco.To see more detail - click any occurrence in the list.

Eseguire il drill-through degli eventi

Per concentrarsi sugli eventi specifici in Ricerca o in Esplora metriche, impostare il filtro del pannello sui nomi degli eventi a cui si è interessati:To focus on specific events in either Search or Metrics Explorer, set the blade's filter to the event names that you're interested in:

Aprire i filtri, espandere il nome dell’evento e selezionare uno o più valori

Eventi personalizzati in AnalyticsCustom events in Analytics

I dati di telemetria sono disponibili nella tabella customEvents in Analytics di Application Insights.The telemetry is available in the customEvents table in Application Insights Analytics. Ogni riga rappresenta una chiamata a trackEvent(..) nell'app in uso.Each row represents a call to trackEvent(..) in your app.

Se il campionamento è attivo, la proprietà itemCount mostra un valore maggiore di 1.If sampling is in operation, the itemCount property shows a value greater than 1. Per esempio itemCount==10 indica che su 10 chiamate a trackEvent(), il processo di campionamento ne trasmette solo una.For example itemCount==10 means that of 10 calls to trackEvent(), the sampling process only transmitted one of them. Per ottenere un conteggio corretto degli eventi personalizzati, si consiglia di usare un codice, ad esempio customEvent | summarize sum(itemCount).To get a correct count of custom events, you should use therefore use code such as customEvent | summarize sum(itemCount).

TrackMetricTrackMetric

Application Insights è in grado di creare grafici in base a metriche non sono associate a determinati eventi.Application Insights can chart metrics that are not attached to particular events. Ad esempio, è possibile monitorare la lunghezza di una coda a intervalli regolari.For example, you could monitor a queue length at regular intervals. Grazie alle metriche, le singole misurazioni sono meno interessanti rispetto alle variazioni e alle tendenze, i grafici statistici risultano pertanto utili.With metrics, the individual measurements are of less interest than the variations and trends, and so statistical charts are useful.

Per inviare le metriche ad Application Insights, è possibile usare l'API TrackMetric(..).In order to send metrics to Application Insights, you can use the TrackMetric(..) API. Per inviare le metriche è possibile procedere in due modi:There are two ways to send a metric:

  • Valore singolo.Single value. Ogni volta che si esegue una misurazione nell'applicazione, si invia il valore corrispondente ad Application Insights.Every time you perform a measurement in your application, you send the corresponding value to Application Insights. Ad esempio, si supponga di avere una metrica che descrive il numero di elementi in un contenitore.For example, assume that you have a metric describing the number of items in a container. Durante un periodo di tempo specifico, inserire prima tre elementi nel contenitore e poi rimuoverne due.During a particular time period, you first put three items into the container and then you remove two items. Di conseguenza, è necessario chiamare TrackMetric due volte: prima passando il valore 3 e poi il valore -2.Accordingly, you would call TrackMetric twice: first passing the value 3 and then the value -2. Application Insights memorizza entrambi i valori per conto dell'utente.Application Insights stores both values on your behalf.

  • Aggregazione.Aggregation. Quando si usano le metriche non si considera mai una sola misura.When working with metrics, every single measurement is rarely of interest. È importante invece il riepilogo delle operazioni eseguite in un periodo di tempo specifico.Instead a summary of what happened during a particular time period is important. Tale riepilogo viene chiamato aggregazione.Such a summary is called aggregation. Nell'esempio precedente la somma della metrica di aggregazione per quel periodo di tempo è 1 e il conteggio dei valori della metrica è 2.In the above example, the aggregate metric sum for that time period is 1 and the count of the metric values is 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.When using the aggregation approach, you only invoke TrackMetric once per time period and send the aggregate values. Questo è l'approccio consigliato in quanto può ridurre notevolmente i costi e le prestazioni generali inviando meno punti dati ad Application Insights, durante la raccolta di tutte le informazioni pertinenti.This is the recommended approach since it can significantly reduce the cost and performance overhead by sending fewer data points to Application Insights, while still collecting all relevant information.

Esempi:Examples:

Valori singoliSingle values

Per inviare un singolo valore di metrica:To send a single metric value:

JavaScriptJavaScript

    appInsights.trackMetric("queueLength", 42.0);

C#, JavaC#, Java

    var sample = new MetricTelemetry();
    sample.Name = "metric name";
    sample.Value = 42.3;
    telemetryClient.TrackMetric(sample);

Node.jsNode.js

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

Aggregazione delle metricheAggregating metrics

È consigliabile aggregare le metriche prima di inviarle dall'app, al fine di ridurre la larghezza di banda, il costo e migliorare le prestazioni.It is recommended to aggregate metrics before sending them from your app, to reduce bandwidth, cost and to improve performance. Di seguito è riportato un esempio di codice di aggregazione:Here is an example of aggregating code:

C#C#

using System;
using System.Threading;
using System.Threading.Tasks;

using Microsoft.ApplicationInsights;
using Microsoft.ApplicationInsights.DataContracts;

namespace MetricAggregationExample
{
    /// <summary>
    /// Aggregates metric values for a single time period.
    /// </summary>
    internal class MetricAggregator
    {
        private SpinLock _trackLock = new SpinLock();

        public DateTimeOffset StartTimestamp    { get; }
        public int Count                        { get; private set; }
        public double Sum                       { get; private set; }
        public double SumOfSquares              { get; private set; }
        public double Min                       { get; private set; }
        public double Max                       { get; private set; }
        public double Average                   { get { return (Count == 0) ? 0 : (Sum / Count); } }
        public double Variance                  { get { return (Count == 0) ? 0 : (SumOfSquares / Count)
                                                                                  - (Average * Average); } }
        public double StandardDeviation         { get { return Math.Sqrt(Variance); } }

        public MetricAggregator(DateTimeOffset startTimestamp)
        {
            this.StartTimestamp = startTimestamp;
        }

        public void TrackValue(double value)
        {
            bool lockAcquired = false;

            try
            {
                _trackLock.Enter(ref lockAcquired);

                if ((Count == 0) || (value < Min))  { Min = value; }
                if ((Count == 0) || (value > Max))  { Max = value; }
                Count++;
                Sum += value;
                SumOfSquares += value * value;
            }
            finally
            {
                if (lockAcquired)
                {
                    _trackLock.Exit();
                }
            }
        }
    }   // internal class MetricAggregator

    /// <summary>
    /// Accepts metric values and sends the aggregated values at 1-minute intervals.
    /// </summary>
    public sealed class Metric : IDisposable
    {
        private static readonly TimeSpan AggregationPeriod = TimeSpan.FromSeconds(60);

        private bool _isDisposed = false;
        private MetricAggregator _aggregator = null;
        private readonly TelemetryClient _telemetryClient;

        public string Name { get; }

        public Metric(string name, TelemetryClient telemetryClient)
        {
            this.Name = name ?? "null";
            this._aggregator = new MetricAggregator(DateTimeOffset.UtcNow);
            this._telemetryClient = telemetryClient ?? throw new ArgumentNullException(nameof(telemetryClient));

            Task.Run(this.AggregatorLoopAsync);
        }

        public void TrackValue(double value)
        {
            MetricAggregator currAggregator = _aggregator;
            if (currAggregator != null)
            {
                currAggregator.TrackValue(value);
            }
        }

        private async Task AggregatorLoopAsync()
        {
            while (_isDisposed == false)
            {
                try
                {
                    // Wait for end end of the aggregation period:
                    await Task.Delay(AggregationPeriod).ConfigureAwait(continueOnCapturedContext: false);

                    // Atomically snap the current aggregation:
                    MetricAggregator nextAggregator = new MetricAggregator(DateTimeOffset.UtcNow);
                    MetricAggregator prevAggregator = Interlocked.Exchange(ref _aggregator, nextAggregator);

                    // Only send anything is at least one value was measured:
                    if (prevAggregator != null && prevAggregator.Count > 0)
                    {
                        // Compute the actual aggregation period length:
                        TimeSpan aggPeriod = nextAggregator.StartTimestamp - prevAggregator.StartTimestamp;
                        if (aggPeriod.TotalMilliseconds < 1)
                        {
                            aggPeriod = TimeSpan.FromMilliseconds(1);
                        }

                        // Construct the metric telemetry item and send:
                        var aggregatedMetricTelemetry = new MetricTelemetry(
                                Name,
                                prevAggregator.Count,
                                prevAggregator.Sum,
                                prevAggregator.Min,
                                prevAggregator.Max,
                                prevAggregator.StandardDeviation);
                        aggregatedMetricTelemetry.Properties["AggregationPeriod"] = aggPeriod.ToString("c");

                        _telemetryClient.Track(aggregatedMetricTelemetry);
                    }
                }
                catch(Exception ex)
                {
                    // log ex as appropriate for your application
                }
            }
        }

        void IDisposable.Dispose()
        {
            _isDisposed = true;
            _aggregator = null;
        }
    }   // public sealed class Metric
}

Metriche personalizzate in Esplora metricheCustom metrics in Metrics Explorer

Per visualizzare i risultati, aprire Esplora metriche e aggiungere un nuovo grafico.To see the results, open Metrics Explorer and add a new chart. Modificare il grafico per visualizzare la metrica.Edit the chart to show your metric.

Nota

Potrebbero essere necessari alcuni minuti per visualizzare la metrica personalizzata nell'elenco delle metriche disponibili.Your custom metric might take several minutes to appear in the list of available metrics.

Aggiungere un nuovo grafico o selezionare un grafico e selezionare le metriche in Personalizzato

Metriche personalizzate in AnalyticsCustom metrics in Analytics

I dati di telemetria sono disponibili nella tabella customMetrics in Analytics di Application Insights.The telemetry is available in the customMetrics table in Application Insights Analytics. Ogni riga rappresenta una chiamata a trackMetric(..) nell'app in uso.Each row represents a call to trackMetric(..) in your app.

  • valueSum: somma delle misurazioni.valueSum - This is the sum of the measurements. Per ottenere il valore medio, dividere per valueCount.To get the mean value, divide by valueCount.
  • valueCount: numero delle misurazioni aggregate nella chiamata trackMetric(..).valueCount - The number of measurements that were aggregated into this trackMetric(..) call.

Visualizzazioni paginaPage views

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.In a device or webpage app, page view telemetry is sent by default when each screen or page is loaded. È tuttavia possibile modificare questa impostazione per tenere traccia delle visualizzazioni pagina in momenti diversi o aggiuntivi.But you can change that to track page views at additional or different times. Ad esempio, in un'app che visualizza schede o pannelli, è possibile tenere traccia di una "pagina" ogni volta che l'utente apre un nuovo pannello.For example, in an app that displays tabs or blades, you might want to track a page whenever the user opens a new blade.

Sezione Utilizzo nel pannello Panoramica

I dati relativi a utente e sessione vengono inviati come proprietà insieme alle visualizzazioni pagina, in modo che i grafici utente e sessione si attivino in presenza dei dati di telemetria delle visualizzazioni pagina.User and session data is sent as properties along with page views, so the user and session charts come alive when there is page view telemetry.

Visualizzazioni pagina personalizzateCustom page views

JavaScriptJavaScript

appInsights.trackPageView("tab1");

C#C#

telemetry.TrackPageView("GameReviewPage");

Visual BasicVisual Basic

telemetry.TrackPageView("GameReviewPage")

Se sono presenti alcune schede in pagine HTML diverse, è possibile specificare anche l'URL:If you have several tabs within different HTML pages, you can specify the URL too:

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

Temporizzazione delle visualizzazioni delle pagineTiming page views

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 pagina del browser.By default, the times reported as Page view load time are measured from when the browser sends the request, until the browser's page load event is called.

In alternativa, è possibile:Instead, you can either:

  • Impostare una durata esplicita nella chiamata di trackPageView: appInsights.trackPageView("tab1", null, null, null, durationInMilliseconds);.Set an explicit duration in the trackPageView call: appInsights.trackPageView("tab1", null, null, null, durationInMilliseconds);.
  • Usare le chiamate relative ai tempi di visualizzazione della pagina startTrackPage e stopTrackPage.Use the page view timing calls startTrackPage and stopTrackPage.

JavaScriptJavaScript

// 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.The name that you use as the first parameter associates the start and stop calls. Il valore predefinito corrisponde al nome della pagina corrente.It defaults to the current page name.

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.The resulting page load durations displayed in Metrics Explorer are derived from the interval between the start and stop calls. È possibile specificare l'intervallo effettivo calcolato desiderato.It's up to you what interval you actually time.

Dati di telemetria della pagina in AnalyticsPage telemetry in Analytics

In Analytics due tabelle mostrano i dati delle operazioni del browser:In Analytics two tables show data from browser operations:

  • La tabella pageViews contiene i dati relativi al titolo della pagina e all'URLThe pageViews table contains data about the URL and page title
  • La tabella browserTimings contiene i dati sulle prestazioni del client, ad esempio il tempo impiegato per elaborare i dati in ingressoThe browserTimings table contains data about client performance, such as the time taken to process the incoming data

Per trovare il tempo necessario al browser per elaborare pagine diverse:To find how long the browser takes to process different pages:

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

Per individuare le popolarità dei diversi browser:To discover the popularities of different browsers:

pageViews | summarize count() by client_Browser

Per associare le visualizzazioni di pagina alle chiamate AJAX, unirle alle dipendenze:To associate page views to AJAX calls, join with dependencies:

pageViews | join (dependencies) on operation_Id 

TrackRequestTrackRequest

Il server SDK usa TrackRequest per registrare le richieste HTTP.The server SDK uses TrackRequest to log HTTP requests.

È anche possibile chiamarlo manualmente se si vogliono simulare le richieste in un contesto in cui il modulo del servizio Web non è in esecuzione.You can also call it yourself if you want to simulate requests in a context where you don't have the web service module running.

Il modo consigliato per inviare dati di telemetria della richiesta è quello in cui la richiesta agisce come un contesto dell'operazione.However, the recommended way to send request telemetry is where the request acts as an operation context.

Contesto dell'operazioneOperation context

È possibile associare gli elementi di telemetria tra loro mediante il collegamento di un ID operazione comune.You can associate telemetry items together by attaching to them a common operation ID. 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.The standard request-tracking module does this for exceptions and other events that are sent while an HTTP request is being processed. In Ricerca e Analisi è possibile usare l'ID per trovare facilmente gli eventi associati alla richiesta.In Search and Analytics, you can use the ID to easily find any events associated with the request.

Il modo più semplice per impostare l'ID è selezionare un contesto dell'operazione mediante questo modello:The easiest way to set the ID is to set an operation context by using this pattern:

C#C#

// Establish an operation context and associated telemetry item:
using (var operation = telemetry.StartOperation<RequestTelemetry>("operationName"))
{
    // Telemetry sent in here will use the same operation ID.
    ...
    telemetry.TrackTrace(...); // or other Track* calls
    ...
    // Set properties of containing telemetry item--for example:
    operation.Telemetry.ResponseCode = "200";

    // Optional: explicitly send telemetry item:
    telemetry.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.Along with setting an operation context, StartOperation creates a telemetry item of the type that you specify. Invia l'elemento di telemetria quando si elimina l'operazione o si chiama esplicitamente StopOperation.It sends the telemetry item when you dispose the operation, or if you explicitly call 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.If you use RequestTelemetry as the telemetry type, its duration is set to the timed interval between start and stop.

I contesti dell’operazione non possono essere annidati.Operation contexts can't be nested. Se è già presente un contesto dell'operazione, il suo ID corrispondente viene associato a tutti gli elementi contenuti, compreso l'elemento creato con StartOperation.If there is already an operation context, then its ID is associated with all the contained items, including the item created with StartOperation.

In Ricerca il contesto dell'operazione viene usato per creare l'elenco di elementi correlati:In Search, the operation context is used to create the Related Items list:

Elementi correlati

Per altre informazioni sulle operazioni di rilevamento personalizzate, vedere Tenere traccia delle operazioni personalizzate con Application Insights .NET SDK.See Track custom operations with Application Insights .NET SDK for more information on custom operations tracking.

Richieste in AnalyticsRequests in Analytics

In Analytics di Application Insights le richieste vengono visualizzate nella tabella requests.In Application Insights Analytics, requests show up in the requests table.

Se il campionamento è attivo, la proprietà itemCount mostrerà un valore maggiore di 1.If sampling is in operation, the itemCount property will show a value greater than 1. Per esempio itemCount==10 indica che su 10 chiamate a trackRequest(), il processo di campionamento ne trasmette solo una.For example itemCount==10 means that of 10 calls to trackRequest(), the sampling process only transmitted one of them. Per ottenere un conteggio corretto delle richieste e della durata media segmentato in base ai nomi della richiesta, usare un codice, ad esempio:To get a correct count of requests and average duration segmented by request names, use code such as:

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

TrackExceptionTrackException

Inviare le eccezioni ad Application Insights:Send exceptions to Application Insights:

I report includono le analisi dello stack.The reports include the stack traces.

C#C#

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

JavaScriptJavaScript

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

Node.jsNode.js

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

Gli SDK rilevano molte eccezioni automaticamente, quindi non è sempre necessario richiamare TrackException in modo esplicito.The SDKs catch many exceptions automatically, so you don't always have to call TrackException explicitly.

Eccezioni in AnalyticsExceptions in Analytics

In Analytics di Application Insights le eccezioni vengono visualizzate nella tabella exceptions.In Application Insights Analytics, exceptions show up in the exceptions table.

Se il campionamento è attivo, la proprietà itemCount mostra un valore maggiore di 1.If sampling is in operation, the itemCount property shows a value greater than 1. Per esempio itemCount==10 indica che su 10 chiamate a trackException(), il processo di campionamento ne trasmette solo una.For example itemCount==10 means that of 10 calls to trackException(), the sampling process only transmitted one of them. Per ottenere un conteggio corretto delle eccezioni segmentate per tipo di eccezione, usare un codice, ad esempio:To get a correct count of exceptions segmented by type of exception, use code such as:

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.Most of the important stack information is already extracted into separate variables, but you can pull apart the details structure to get more. Poiché si tratta di una struttura dinamica, è necessario eseguire il cast del risultato per il tipo previsto.Since this structure is dynamic, you should cast the result to the type you expect. ad esempio:For example:

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

Per associare le richieste alle eccezioni correlate, è possibile usare un join:To associate exceptions with their related requests, use a join:

exceptions
| join (requests) on operation_Id 

TrackTraceTrackTrace

Usare TrackTrace per diagnosticare i problemi mediante l'invio di una traccia di navigazione ad Application Insights.Use TrackTrace to help diagnose problems by sending a "breadcrumb trail" to Application Insights. È possibile inviare blocchi di dati di diagnostica e controllarli in Ricerca diagnostica.You can send chunks of diagnostic data and inspect them in Diagnostic Search.

Gli adattatori di log usano questa API per inviare i log di terze parti al portale.Log adapters use this API to send third-party logs to the portal.

C#C#

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

Node.jsNode.js

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

È possibile eseguire ricerche nel contenuto del messaggio, ma, a differenza dei valori delle proprietà, non è possibile filtrarlo.You can search on message content, but (unlike property values) you can't filter on it.

Il limite delle dimensioni per message è molto superiore al limite per le proprietà.The size limit on message is much higher than the limit on properties. Un vantaggio di TrackTrace è che è possibile inserire dati relativamente lunghi nel messaggio.An advantage of TrackTrace is that you can put relatively long data in the message. Ad esempio è possibile codificare dati POST.For example, you can encode POST data there.

È anche possibile aggiungere al messaggio un livello di gravità.In addition, you can add a severity level to your message. E come per altri tipi di dati di telemetria è possibile aggiungere valori di proprietà utili per filtrare o cercare set di tracce diversi.And, like other telemetry, you can add property values to help you filter or search for different sets of traces. Ad esempio:For example:

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

In Ricerca sarà possibile filtrare facilmente tutti i messaggi di un determinato livello di gravità relativi a un database specifico.In Search, you can then easily filter out all the messages of a particular severity level that relate to a particular database.

Tracce in AnalyticsTraces in Analytics

In Analytics di Application Insights le chiamate a TrackTrace vengono visualizzate nella tabella traces.In Application Insights Analytics, calls to TrackTrace show up in the traces table.

Se il campionamento è attivo, la proprietà itemCount mostra un valore maggiore di 1.If sampling is in operation, the itemCount property shows a value greater than 1. Per esempio itemCount==10 indica che, su 10 chiamate di trackTrace(), il processo di campionamento ne trasmette solo una.For example itemCount==10 means that of 10 calls to trackTrace(), the sampling process only transmitted one of them. Per ottenere un conteggio corretto delle chiamate delle tracce, si consiglia di usare un codice, ad esempio traces | summarize sum(itemCount).To get a correct count of trace calls, you should use therefore code such as traces | summarize sum(itemCount).

TrackDependencyTrackDependency

Usare la chiamata di TrackDependency per rilevare i tempi di risposta e le percentuali di successo delle chiamate a un frammento di codice esterno.Use the TrackDependency call to track the response times and success rates of calls to an external piece of code. I risultati vengono visualizzati nei grafici dipendenze nel portale.The results appear in the dependency charts in the portal.

var success = false;
var startTime = DateTime.UtcNow;
var timer = System.Diagnostics.Stopwatch.StartNew();
try
{
    success = dependency.Call();
}
finally
{
    timer.Stop();
    telemetry.TrackDependency("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 il server SDK include un modulo dipendenza che consente di individuare e tracciare alcune chiamate di dipendenza automaticamente, ad esempio a database e API REST.Remember that the server SDKs include a dependency module that discovers and tracks certain dependency calls automatically--for example, to databases and REST APIs. È necessario installare un agente nel server per consentire il funzionamento del modulo.You have to install an agent on your server to make the module work. Usare questa chiamata se si vuole tenere traccia di chiamate che il rilevamento automatico non intercetta o se non si vuole installare l'agente.You use this call if you want to track calls that the automated tracking doesn't catch, or if you don't want to install the agent.

Per disattivare il modulo standard per il rilevamento delle dipendenze, modificare il file ApplicationInsights.config ed eliminare il riferimento a DependencyCollector.DependencyTrackingTelemetryModule.To turn off the standard dependency-tracking module, edit ApplicationInsights.config and delete the reference to DependencyCollector.DependencyTrackingTelemetryModule.

Dipendenze in AnalyticsDependencies in Analytics

In Analytics di Application Insights le chiamate a trackDependency vengono visualizzate nella tabella dependencies.In Application Insights Analytics, trackDependency calls show up in the dependencies table.

Se il campionamento è attivo, la proprietà itemCount mostra un valore maggiore di 1.If sampling is in operation, the itemCount property shows a value greater than 1. Per esempio itemCount==10 indica che su 10 chiamate a trackDependency(), il processo di campionamento ne trasmette solo una.For example itemCount==10 means that of 10 calls to trackDependency(), the sampling process only transmitted one of them. Per ottenere un conteggio corretto delle dipendenze segmentate per componente di destinazione, usare un codice, ad esempio:To get a correct count of dependencies segmented by target component, use code such as:

dependencies | summarize sum(itemCount) by target

Per associare le dipendenze alle richieste correlate, è possibile usare un join:To associate dependencies with their related requests, use a join:

dependencies
| join (requests) on operation_Id 

Scaricamento dei datiFlushing data

In genere l'SDK invia i dati in momenti scelti per ridurre al minimo l'impatto sull'utente.Normally, the SDK sends data at times chosen to minimize the impact on the user. In alcuni casi tuttavia è possibile che si voglia scaricare il buffer, ad esempio se si sta usando l'SDK in un'applicazione che si arresta.However, in some cases, you might want to flush the buffer--for example, if you are using the SDK in an application that shuts down.

C#C#

telemetry.Flush();

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

Node.jsNode.js

telemetry.flush();

Si noti che la funzione è asincrona per il canale di telemetria del server.Note that the function is asynchronous for the server telemetry channel.

utenti autenticatiAuthenticated users

In un'app Web gli utenti sono identificati dai cookie per impostazione predefinita.In a web app, users are (by default) identified by cookies. Un utente può essere conteggiato più volte se accede all'app da un computer o da un browser diverso o se elimina i cookie.A user might be counted more than once if they access your app from a different machine or browser, or if they delete cookies.

Se gli utenti accedono all'app, è possibile ottenere un conteggio più preciso impostando l'ID dell'utente autenticato nel codice del browser:If users sign in to your app, you can get a more accurate count by setting the authenticated user ID in the browser code:

JavaScriptJavaScript

// 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:In an ASP.NET web MVC application, for example:

RazorRazor

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

Non è necessario usare il nome di accesso effettivo dell'utente.It isn't necessary to use the user's actual sign-in name. È sufficiente usare un ID univoco per l'utente.It only has to be an ID that is unique to that user. Non deve includere spazi o i caratteri ,;=|.It must not include spaces or any of the characters ,;=|.

L'ID utente viene inoltre impostato in un cookie di sessione e inviato al server.The user ID is also set in a session cookie and sent to the 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.If the server SDK is installed, the authenticated user ID is sent as part of the context properties of both client and server telemetry. Quindi sarà possibile filtrarlo ed eseguire ricerche al suo interno.You can then filter and search on it.

Se l'app raggruppa gli utenti in account, è anche possibile passare un identificatore per l'account, con le stesse limitazioni di caratteri.If your app groups users into accounts, you can also pass an identifier for the account (with the same character restrictions).

  appInsights.setAuthenticatedUserContext(validatedId, accountId);

In Esplora metriche è possibile creare un grafico che conta i valori Utenti, Autenticati e Account utente.In Metrics Explorer, you can create a chart that counts Users, Authenticated, and User accounts.

È anche possibile cercare i punti dati del client con account e nomi utente specifici.You can also search for client data points with specific user names and accounts.

Filtro, ricerca e segmentazione dei dati mediante le proprietàFiltering, searching, and segmenting your data by using properties

È possibile associare proprietà e misure agli eventi e anche a metriche, visualizzazioni pagine, eccezioni e altri dati di telemetria.You can attach properties and measurements to your events (and also to metrics, page views, exceptions, and other telemetry data).

proprietà sono valori di stringa che è possibile usare per filtrare i dati di telemetria nei report di utilizzo.Properties are string values that you can use to filter your telemetry in the usage reports. 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.For example, if your app provides several games, you can attach the name of the game to each event so that you can see which games are more popular.

Esiste un limite di 8192 per la lunghezza della stringa.There's a limit of 8192 on the string length. Se si vogliono inviare grandi quantità di dati, usare il parametro del messaggio di TrackTrace.(If you want to send large chunks of data, use the message parameter of TrackTrace.)

metriche sono valori numerici che possono essere rappresentati graficamente.Metrics are numeric values that can be presented graphically. Ad esempio è possibile verificare se esiste un aumento graduale nei punteggi raggiunti dai giocatori.For example, you might want to see if there's a gradual increase in the scores that your gamers achieve. 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.The graphs can be segmented by the properties that are sent with the event, so that you can get separate or stacked graphs for different games.

Affinché i valori metrici siano visualizzati correttamente, devono essere maggiori o uguali a 0.For metric values to be correctly displayed, they should be greater than or equal to 0.

Esistono tuttavia alcuni limiti sul numero di proprietà, di valori delle proprietà e di metriche che è possibile usare.There are some limits on the number of properties, property values, and metrics that you can use.

JavaScriptJavaScript

appInsights.trackEvent
  ("WinGame",
     // String properties:
     {Game: currentGame.name, Difficulty: currentGame.difficulty},
     // Numeric metrics:
     {Score: currentGame.score, Opponents: currentGame.opponentCount}
     );

appInsights.trackPageView
    ("page name", "http://fabrikam.com/pageurl.html",
      // String properties:
     {Game: currentGame.name, Difficulty: currentGame.difficulty},
     // Numeric metrics:
     {Score: currentGame.score, Opponents: currentGame.opponentCount}
     );

C#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.jsNode.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 BasicVisual 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)

JavaJava

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à.Take care not to log personally identifiable information in properties.

Se è stata usata la metrica, aprire Esplora metriche e selezionare la metrica dal gruppo personalizzato:If you used metrics, open Metrics Explorer and select the metric from the Custom group:

Aprire Esplora metrica, selezionare il grafico e selezionare la metrica

Nota

Se non viene visualizzata l'unità di misura o se l'intestazione personalizzata non è presente, chiudere il pannello di selezione e riprovare più tardi.If your metric doesn't appear, or if the Custom heading isn't there, close the selection blade and try again later. A volte potrebbe essere necessaria un'ora per l'aggregazione delle metriche attraverso la pipeline.Metrics can sometimes take an hour to be aggregated through the pipeline.

Se si usano proprietà e metriche, segmentare la metrica in base alla proprietà:If you used properties and metrics, segment the metric by the property:

Impostare il raggruppamento e quindi selezionare la proprietà in Raggruppa per

In Ricerca diagnostica è possibile visualizzare le proprietà e le metriche di singole occorrenze di un evento.In Diagnostic Search, you can view the properties and metrics of individual occurrences of an event.

Selezionare un'istanza e quindi scegliere "..."

Usare il campo Ricerca per visualizzare le occorrenze di eventi con un valore della proprietà particolare.Use the Search field to see event occurrences that have a particular property value.

Digitare un termine in Ricerca

Altre informazioni sulle espressioni di ricerca.Learn more about search expressions.

Metodo alternativo per impostare proprietà e metricheAlternative way to set properties and metrics

Se si preferisce, è possibile raccogliere i parametri di un evento in un oggetto separato:If it's more convenient, you can collect the parameters of an event in a separate object:

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.Don't reuse the same telemetry item instance (event in this example) to call Track() multiple times. Potrebbe causare l'invio della telemetria con una configurazione errata.This may cause telemetry to be sent with incorrect configuration.

Misure e proprietà personalizzate in AnalyticsCustom measurements and properties in Analytics

In Analytics le metriche e le proprietà personalizzate vengono mostrate negli attributi customMeasurements e customDimensions di ogni record di dati di telemetria.In Analytics, custom metrics and properties show in the customMeasurements and customDimensions attributes of each telemetry record.

Ad esempio, se è stata aggiunta 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" della metrica personalizzata:For example, if you have added a property named "game" to your request telemetry, this query counts the occurrences of different values of "game", and show the average of the custom metric "score":

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

Si noti che:Notice that:

  • Quando si estrae un valore dal JSON customDimensions o customMeasurements, questo è di tipo dinamico e pertanto è necessario eseguirne il cast in tostring o todouble.When you extract a value from the customDimensions or customMeasurements JSON, it has dynamic type, and so you must cast it tostring or todouble.
  • Per tener conto della possibilità di campionamento, si consiglia di usare sum(itemCount), non count().To take account of the possibility of sampling, you should use sum(itemCount), not count().

Temporizzazione degli eventiTiming events

A volte si vuole rappresentare in un grafico il tempo necessario per eseguire un'azione.Sometimes you want to chart how long it takes to perform an action. Ad esempio si potrebbe voler sapere quanto tempo occorre agli utenti per scegliere tra le opzioni disponibili in un gioco.For example, you might want to know how long users take to consider choices in a game. Per questo è possibile usare il parametro di misurazione.You can use the measurement parameter for this.

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

Proprietà predefinite per i dati di telemetria personalizzatiDefault properties for custom telemetry

Se si intende impostare solo i valori di proprietà predefiniti per alcuni degli eventi personalizzati scritti, è possibile impostarli in un'istanza di TelemetryClient.If you want to set default property values for some of the custom events that you write, you can set them in a TelemetryClient instance. Vengono associati a ogni elemento di telemetria inviato da quel client.They are attached to every telemetry item that's sent from that client.

C#C#

using Microsoft.ApplicationInsights.DataContracts;

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

Visual BasicVisual Basic

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

JavaJava

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.jsNode.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à.Individual telemetry calls can override the default values in their property dictionaries.

Per i client Web di JavaScript, usare gli inizializzatori di telemetria JavaScript.For JavaScript web clients, use JavaScript telemetry initializers.

Per aggiungere proprietà a tutti i dati di telemetria, inclusi i dati dei moduli di raccolta standard, implementare ITelemetryInitializer.To add properties to all telemetry, including the data from standard collection modules, implement ITelemetryInitializer.

Campionamento, filtri ed elaborazione dei dati di telemetriaSampling, filtering, and processing telemetry

È possibile scrivere il codice per elaborare i dati di telemetria prima che vengano inviati dall'SDK.You can write code to process your telemetry before it's sent from the SDK. L'elaborazione include i dati inviati dai moduli di telemetria standard, come la raccolta delle richieste HTTP e la raccolta delle dipendenze.The processing includes data that's sent from the standard telemetry modules, such as HTTP request collection and dependency collection.

Aggiungere proprietà ai dati di telemetria implementando ITelemetryInitializer.Add properties to telemetry by implementing ITelemetryInitializer. Ad esempio è possibile aggiungere numeri di versione o valori calcolati da altre proprietà.For example, you can add version numbers or values that are calculated from other properties.

L'applicazione di filtri consente di modificare o rimuovere i dati di telemetria prima che vengano inviati dall'SDK implementando ITelemetryProcesor.Filtering can modify or discard telemetry before it's sent from the SDK by implementing ITelemetryProcesor. È possibile controllare gli elementi inviati o eliminati, ma è necessario tenere conto dell'effetto sulle metriche.You control what is sent or discarded, but you have to account for the effect on your metrics. A seconda di come si eliminano gli elementi, si potrebbe perdere la possibilità di navigare tra elementi correlati.Depending on how you discard items, you might lose the ability to navigate between related items.

Il campionamento è una soluzione in pacchetto che consente di ridurre il volume dei dati inviati dall'app al portale.Sampling is a packaged solution to reduce the volume of data that's sent from your app to the portal. Lo fa senza influenzare le metriche visualizzateIt does so without affecting the displayed metrics. e senza influire sulla possibilità di diagnosticare i problemi navigando tra elementi correlati, come eccezioni, richieste e visualizzazioni di pagina.And it does so without affecting your ability to diagnose problems by navigating between related items such as exceptions, requests, and page views.

Altre informazioni.Learn more.

Disabilitazione della telemetriaDisabling telemetry

Per avviare e arrestare in modo dinamico la raccolta e la trasmissione di dati di telemetria:To dynamically stop and start the collection and transmission of telemetry:

C#C#


    using  Microsoft.ApplicationInsights.Extensibility;

    TelemetryConfiguration.Active.DisableTelemetry = 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. Ad esempio è possibile eseguire questa operazione se si desidera inviare i propri dati TrackRequest.To disable selected standard collectors--for example, performance counters, HTTP requests, or dependencies--delete or comment out the relevant lines in ApplicationInsights.config. You can do this, for example, if you want to send your own TrackRequest data.

Node.jsNode.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:To disable selected standard collectors--for example, performance counters, HTTP requests, or dependencies--at initialization time, chain configuration methods to your SDK initialization code:


    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)To disable these collectors after initialization, use the Configuration object: applicationInsights.Configuration.setAutoCollectRequests(false)

Modalità di sviluppoDeveloper mode

Durante il debug, è utile accelerare i dati di telemetria venga nella pipeline in modo da visualizzare immediatamente i risultati.During debugging, it's useful to have your telemetry expedited through the pipeline so that you can see results immediately. È possibile che vengano visualizzati anche altri messaggi che consentono di tracciare eventuali problemi con i dati di telemetria.You also get additional messages that help you trace any problems with the telemetry. Disattivare questa modalità in fase di produzione poiché potrebbe rallentare l'app.Switch it off in production, because it may slow down your app.

C#C#

TelemetryConfiguration.Active.TelemetryChannel.DeveloperMode = true;

Visual BasicVisual Basic

TelemetryConfiguration.Active.TelemetryChannel.DeveloperMode = True

Impostazione della chiave di strumentazione per la telemetria personalizzata selezionataSetting the instrumentation key for selected custom telemetry

C#C#

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

Chiave di strumentazione dinamicaDynamic instrumentation key

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.To avoid mixing up telemetry from development, test, and production environments, you can create separate Application Insights resources and change their keys, depending on the environment.

Invece di ottenere la chiave di strumentazione dal file di configurazione, è possibile impostarla nel codice.Instead of getting the instrumentation key from the configuration file, you can set it in your code. Impostare la chiave in un metodo di inizializzazione, ad esempio global.aspx.cs in un servizio ASP.NET:Set the key in an initialization method, such as global.aspx.cs in an ASP.NET service:

C#C#

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

JavaScriptJavaScript

appInsights.config.instrumentationKey = myKey;

Nelle pagine Web è possibile impostarla dallo stato del server Web anziché codificarla nello script.In webpages, you might want to set it from the web server's state, rather than coding it literally into the script. Ad esempio, in una pagina Web generata in un'app ASP.NET:For example, in a webpage generated in an ASP.NET app:

JavaScript in RazorJavaScript 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"
}) // ...

TelemetryContextTelemetryContext

TelemetryClient dispone di una proprietà Context contenente valori che vengono inviati insieme a tutti i dati di telemetria.TelemetryClient has a Context property, which contains values that are sent along with all telemetry data. Sono in genere impostati dai moduli di telemetria standard, ma è possibile anche impostarli manualmente.They are normally set by the standard telemetry modules, but you can also set them yourself. Ad esempio:For example:

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.If you set any of these values yourself, consider removing the relevant line from ApplicationInsights.config, so that your values and the standard values don't get confused.

  • Componente: l'app e la relativa versione.Component: The app and its version.
  • Dispositivo: dati relativi al dispositivo in cui l'applicazione è in esecuzione.Device: Data about the device where the app is running. Nelle App Web questo è il server o dispositivo client da cui sono inviati i dati di telemetria.(In web apps, this is the server or client device that the telemetry is sent from.)
  • InstrumentationKey: la risorsa di Application Insights in Azure dove sono visualizzati i dati di telemetria.InstrumentationKey: The Application Insights resource in Azure where the telemetry appear. Viene in genere presa dal file ApplicationInsights.config.It's usually picked up from ApplicationInsights.config.
  • Posizione: la posizione geografica del dispositivo.Location: The geographic location of the device.
  • Operazione: nelle App Web la richiesta HTTP corrente.Operation: In web apps, the current HTTP request. In altri tipi di app è possibile impostarla in modo da raggruppare gli eventi tra loro.In other app types, you can set this to group events together.
    • ID: un valore generato che mette in correlazione eventi diversi, in modo che quando si analizza qualsiasi evento in Ricerca diagnostica, è possibile trovare elementi correlati.Id: A generated value that correlates different events, so that when you inspect any event in Diagnostic Search, you can find related items.
    • Nome: un identificatore, in genere l'URL della richiesta HTTP.Name: An identifier, usually the URL of the HTTP request.
    • SyntheticSource: se non è null o vuota, una stringa indicante che l'origine della richiesta è stata identificata come un test Web o un robot.SyntheticSource: If not null or empty, a string that indicates that the source of the request has been identified as a robot or web test. Per impostazione predefinita viene esclusa dai calcoli in Esplora metriche.By default, it is excluded from calculations in Metrics Explorer.
  • Proprietà: proprietà che vengono inviate con tutti i dati di telemetria.Properties: Properties that are sent with all telemetry data. È possibile eseguire l'override di questo valore in singole chiamate di Track.It can be overridden in individual Track calls.
  • Sessione: la sessione dell'utente.Session: The user's session. L'ID viene impostato su un valore generato, che viene modificato quando l'utente non è stato attivo per un periodo di tempo specifico.The ID is set to a generated value, which is changed when the user has not been active for a while.
  • Utente: le informazioni dell'utente.User: User information.

LimitiLimits

Esistono alcuni limiti sul numero di metriche e eventi per applicazione (ovvero, per ogni chiave di strumentazione).There are some limits on the number of metrics and events per application (that is, per instrumentation key). I limiti dipendono dal piano tariffario scelto.Limits depend on the pricing plan that you choose.

RisorsaResource Limite predefinitoDefault limit NotaNote
Totale dati al giornoTotal data per day 100 GB100 GB È possibile ridurre i dati impostando un limite.You can reduce data by setting a cap. Se è necessario più spazio, è possibile aumentare il limite fino a 1.000 GB dal portale.If you need more, you can increase the limit up to 1,000 GB from the portal. Per capacità superiori a 1.000 GB, inviare un messaggio di posta elettronica a AIDataCap@microsoft.com.For capacities greater than 1,000 GB, send mail to AIDataCap@microsoft.com.
Dati gratuiti al meseFree data per month
(piano tariffario base)(Basic price plan)
1 GB1 GB Vengono applicati addebiti per ogni gigabyte di dati aggiuntivi.Additional data is charged per gigabyte.
LimitazioneThrottling 32.000 eventi/secondo32 k events/second Il limite viene misurato nell'arco di un minuto.The limit is measured over a minute.
Conservazione dei datiData retention 90 giorni90 days Questa risorsa è destinata a Ricerca, Analisi e Esplora metriche.This resource is for Search, Analytics, and Metrics Explorer.
Conservazione dei risultati dettagliati di test di disponibilità in più passiAvailability multi-step test detailed results retention 90 giorni90 days Questa risorsa fornisce risultati dettagliati per ogni passaggio.This resource provides detailed results of each step.
Dimensioni massime dell'eventoMaximum event size 64 K64 K
Lunghezza nomi di proprietà e metricheProperty and metric name length 150150 Vedere gli schemi per tipoSee type schemas
Lunghezza stringa valore di proprietàProperty value string length 8.1928,192 Vedere gli schemi per tipoSee type schemas
Lunghezza messaggio di traccia e di eccezioneTrace and exception message length 10.00010 k Vedere gli schemi per tipoSee type schemas
Numero di test di disponibilità per appAvailability tests count per app 1010
Conservazione dati profilerProfiler data retention 5 giorni5 days
Dati profiler inviati al giornoProfiler data sent per day 10 GB10GB

Per altre informazioni, vedere Informazioni su prezzi e quote in Application Insights.For more information, see About pricing and quotas in Application Insights.

Per evitare di raggiungere il limite di velocità dei dati usare il campionamento.To avoid hitting the data rate limit, use sampling.

Per determinare quanto tempo vengono conservati i dati, vedere Raccolta, conservazione e archiviazione di dati in Application Insights.To determine how long data is kept, see Data retention and privacy.

Documentazione di riferimentoReference docs

Codice SDKSDK code

DomandeQuestions

  • Quali eccezioni potrebbero essere generate dalle chiamate Track_()?What exceptions might Track_() calls throw?

    Nessuna.None. Non è necessario eseguirne il wrapping in clausole try-catch.You don't need to wrap them in try-catch clauses. Se l'SDK rileva un problema, registrerà messaggi nell'output della console di debug e quindi in Ricerca diagnostica per approfondirne i dettagli.If the SDK encounters problems, it will log messages in the debug console output and--if the messages get through--in Diagnostic Search.

  • Esiste un'API REST per ottenere dati dal portale?Is there a REST API to get data from the portal?

    Sì, l'API di accesso ai dati.Yes, the data access API. Altri modi per estrarre i dati sono l'esportazione da Analytics a Power BI e l'esportazione continua.Other ways to extract data include export from Analytics to Power BI and continuous export.

Passaggi successiviNext steps