Filtri e pre-elaborazione della telemetria in Application Insights SDKFiltering and preprocessing telemetry in the Application Insights SDK

È possibile scrivere e configurare plug-in per Application Insights SDK per personalizzare l'acquisizione e l'elaborazione della telemetria prima che venga inviata al servizio Application Insights.You can write and configure plug-ins for the Application Insights SDK to customize how telemetry is captured and processed before it is sent to the Application Insights service.

  • campionamento riduce il volume della telemetria senza effetti sulle statistiche.Sampling reduces the volume of telemetry without affecting your statistics. Tiene insieme i punti dati correlati per poter passare da uno all'altro quando si diagnostica un problema.It keeps together related data points so that you can navigate between them when diagnosing a problem. Nel portale i conteggi totali vengono moltiplicati per compensare il campionamento.In the portal, the total counts are multiplied to compensate for the sampling.
  • L'applicazione di filtri con processori di telemetria per ASP.NET o Java consente di selezionare o di modificare i dati di telemetria nell'SDK prima che vengano inviati al server.Filtering with Telemetry Processors for ASP.NET or Java lets you select or modify telemetry in the SDK before it is sent to the server. È possibile, ad esempio, ridurre il volume della telemetria escludendo le richieste dei robot.For example, you could reduce the volume of telemetry by excluding requests from robots. L'applicazione di filtri è però un approccio di riduzione del traffico più semplice rispetto al campionamento.But filtering is a more basic approach to reducing traffic than sampling. Offre un controllo maggiore su ciò che viene trasmesso, ma è necessario tenere presente che influisce sulle statistiche, ad esempio se si filtrano tutte le richieste riuscite.It allows you more control over what is transmitted, but you have to be aware that it affects your statistics - for example, if you filter out all successful requests.
  • inizializzatori di telemetria aggiungono proprietà a tutti i dati di telemetria inviati dall'app, inclusi quelli dei moduli standard.Telemetry Initializers add properties to any telemetry sent from your app, including telemetry from the standard modules. È possibile, ad esempio, aggiungere valori calcolati oppure i numeri di versione in base a cui filtrare i dati nel portale.For example, you could add calculated values; or version numbers by which to filter the data in the portal.
  • L'API SDK viene usata per inviare metriche ed eventi personalizzati.The SDK API is used to send custom events and metrics.

Prima di iniziare:Before you start:

Filtro: ITelemetryProcessorFiltering: ITelemetryProcessor

Questa tecnica offre un controllo più diretto su ciò che viene incluso o escluso dal flusso di telemetria.This technique gives you more direct control over what is included or excluded from the telemetry stream. È possibile usarla insieme al campionamento oppure separatamente.You can use it in conjunction with Sampling, or separately.

Per filtrare la telemetria, scrivere un processore di telemetria e registrarlo con l'SDK.To filter telemetry, you write a telemetry processor and register it with the SDK. Tutta la telemetria passa attraverso il processore ed è possibile scegliere di eliminarla dal flusso o di aggiungere le proprietà.All telemetry goes through your processor, and you can choose to drop it from the stream, or add properties. È inclusa la telemetria dei moduli standard, ad esempio l'agente di raccolta delle richieste HTTP e l'agente di raccolta delle dipendenze, oltre alla telemetria scritta manualmente.This includes telemetry from the standard modules such as the HTTP request collector and the dependency collector, as well as telemetry you have written yourself. È possibile, ad esempio, filtrare la telemetria sulle richieste dei robot o le chiamate di dipendenza riuscite.You can, for example, filter out telemetry about requests from robots, or successful dependency calls.

Avviso

Se si filtra la telemetria inviata dall'SDK usando i processori, le statistiche visualizzate nel portale possono essere alterate e può risultare difficile seguire gli elementi correlati.Filtering the telemetry sent from the SDK using processors can skew the statistics that you see in the portal, and make it difficult to follow related items.

In alternativa, valutare la possibilità di usare il campionamento.Instead, consider using sampling.

Creare un processore di telemetria (C#)Create a telemetry processor (C#)

  1. Verificare che la versione di Application Insights SDK usata nel progetto sia 2.0.0 o successiva.Verify that the Application Insights SDK in your project is version 2.0.0 or later. Fare clic con il pulsante destro del mouse sul progetto in Esplora soluzioni di Visual Studio e scegliere Gestisci pacchetti NuGet.Right-click your project in Visual Studio Solution Explorer and choose Manage NuGet Packages. In Gestione pacchetti NuGet selezionare Microsoft.ApplicationInsights.Web.In NuGet package manager, check Microsoft.ApplicationInsights.Web.
  2. Per creare un filtro, implementare ITelemetryProcessor,To create a filter, implement ITelemetryProcessor. un altro punto di estendibilità come il modulo di telemetria, l'inizializzatore di telemetria e il canale di telemetria.This is another extensibility point like telemetry module, telemetry initializer, and telemetry channel.

    Si noti che i processori di telemetria creano una catena di elaborazione.Notice that Telemetry Processors construct a chain of processing. Quando si crea un'istanza di un processore di telemetria, si passa un collegamento al processore successivo nella catena.When you instantiate a telemetry processor, you pass a link to the next processor in the chain. Quando un punto dati della telemetria viene passato al metodo Process, esegue le operazioni necessarie e quindi chiama il processore di telemetria successivo nella catena.When a telemetry data point is passed to the Process method, it does its work and then calls the next Telemetry Processor in the chain.

    
    using Microsoft.ApplicationInsights.Channel;
    using Microsoft.ApplicationInsights.Extensibility;
    
    public class SuccessfulDependencyFilter : ITelemetryProcessor
      {
    
        private ITelemetryProcessor Next { get; set; }
    
        // You can pass values from .config
        public string MyParamFromConfigFile { get; set; }
    
        // Link processors to each other in a chain.
        public SuccessfulDependencyFilter(ITelemetryProcessor next)
        {
            this.Next = next;
        }
        public void Process(ITelemetry item)
        {
            // To filter out an item, just return
            if (!OKtoSend(item)) { return; }
            // Modify the item if required
            ModifyItem(item);
    
            this.Next.Process(item);
        }
    
        // Example: replace with your own criteria.
        private bool OKtoSend (ITelemetry item)
        {
            var dependency = item as DependencyTelemetry;
            if (dependency == null) return true;
    
            return dependency.Success != true;
        }
    
        // Example: replace with your own modifiers.
        private void ModifyItem (ITelemetry item)
        {
            item.Context.Properties.Add("app-version", "1." + MyParamFromConfigFile);
        }
    }
    
  3. Inserirlo in ApplicationInsights.config:Insert this in ApplicationInsights.config:

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

È la stessa sezione in cui viene inizializzato un filtro di campionamento.(This is the same section where you initialize a sampling filter.)

È possibile passare i valori della stringa dal file .config fornendo proprietà denominate come pubbliche nella classe.You can pass string values from the .config file by providing public named properties in your class.

Avviso

Prestare attenzione a fare corrispondere il nome del tipo e i nomi delle proprietà nel file. config ai nomi di classe e di proprietà nel codice.Take care to match the type name and any property names in the .config file to the class and property names in the code. Se il file. config fa riferimento a un tipo inesistente o una proprietà, l’SDK potrebbe automaticamente non riuscire a inviare nessuna telemetria.If the .config file references a non-existent type or property, the SDK may silently fail to send any telemetry.

In alternativa , è possibile inizializzare il filtro nel codice.Alternatively, you can initialize the filter in code. In una classe di inizializzazione adatta, ad esempio AppStart in Global.asax.cs, inserire il processore nella catena:In a suitable initialization class - for example AppStart in Global.asax.cs - insert your processor into the chain:


    var builder = TelemetryConfiguration.Active.TelemetryProcessorChainBuilder;
    builder.Use((next) => new SuccessfulDependencyFilter(next));

    // If you have more processors:
    builder.Use((next) => new AnotherProcessor(next));

    builder.Build();

Gli elementi TelemetryClient creati dopo questo punto useranno i processori dell'utente.TelemetryClients created after this point will use your processors.

Il codice seguente illustra come aggiungere un inizializzatore di telemetria in ASP.NET Core.The following code shows how to add a telemetry initializer in ASP.NET Core.

public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
    var initializer = new SuccessfulDependencyFilter();
    var configuration = app.ApplicationServices.GetService<TelemetryConfiguration>();
    configuration.TelemetryInitializers.Add(initializer);
}

Filtri di esempioExample filters

Richieste sinteticheSynthetic requests

Filtrare i robot e i test Web.Filter out bots and web tests. Anche se Esplora metriche consente di filtrare le origini sintetiche, questa opzione riduce il traffico filtrandole nell'SDK.Although Metrics Explorer gives you the option to filter out synthetic sources, this option reduces traffic by filtering them at the SDK.


    public void Process(ITelemetry item)
    {
      if (!string.IsNullOrEmpty(item.Context.Operation.SyntheticSource)) {return;}

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

Autenticazione non riuscitaFailed authentication

Filtrare le richieste con una risposta "401".Filter out requests with a "401" response.


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

    if (request != null &&
    request.ResponseCode.Equals("401", StringComparison.OrdinalIgnoreCase))
    {
        // To filter out an item, just terminate the chain:
        return;
    }
    // Send everything else:
    this.Next.Process(item);
}

Filtrare le chiamate di dipendenza remote rapideFilter out fast remote dependency calls

Per diagnosticare solo le chiamate lente, filtrare quelle rapide.If you only want to diagnose calls that are slow, filter out the fast ones.

Nota

In questo modo le statistiche visualizzate nel portale verranno modificate.This will skew the statistics you see on the portal. Il grafico delle dipendenze apparirà come se tutte le chiamate di dipendenza fossero non riuscite.The dependency chart will look as if the dependency calls are all failures.


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

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

Diagnosticare i problemi di dipendenzaDiagnose dependency issues

Questo blog descrive un progetto per diagnosticare i problemi di dipendenza con l'invio automatico di ping regolari alle dipendenze.This blog describes a project to diagnose dependency issues by automatically sending regular pings to dependencies.

Aggiungere proprietà: ITelemetryInitializerAdd properties: ITelemetryInitializer

Utilizzare gli inizializzatori di telemetria per definire le proprietà globali che vengono inviate con tutti i dati di telemetria; eseguire l'override del comportamento selezionato dei moduli di telemetria standard.Use telemetry initializers to define global properties that are sent with all telemetry; and to override selected behavior of the standard telemetry modules.

Ad esempio, il pacchetto Application Insights per il Web raccoglie dati di telemetria relativi alle richieste HTTP e,For example, the Application Insights for Web package collects telemetry about HTTP requests. per impostazione predefinita, contrassegna come non riuscita qualsiasi richiesta con un codice di risposta > = 400.By default, it flags as failed any request with a response code >= 400. Tuttavia, se si vuole considerare 400 come un risultato positivo, è possibile fornire un inizializzatore di telemetria che imposti la proprietà Success.But if you want to treat 400 as a success, you can provide a telemetry initializer that sets the Success property.

In tal modo, verrà chiamato ogni volta che viene chiamato il metodo Track().If you provide a telemetry initializer, it is called whenever any of the Track() methods is called. Sono inclusi i metodi chiamati dai moduli di telemetria standard.This includes methods called by the standard telemetry modules. Per convenzione, questi moduli non impostano le proprietà che sono già state impostate da un inizializzatore.By convention, these modules do not set any property that has already been set by an initializer.

Definire l'inizializzatoreDefine your initializer

C#C#


    using System;
    using Microsoft.ApplicationInsights.Channel;
    using Microsoft.ApplicationInsights.DataContracts;
    using Microsoft.ApplicationInsights.Extensibility;

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

Caricare l'inizializzatoreLoad your initializer

In ApplicationInsights.config:In ApplicationInsights.config:

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

In alternativa, è possibile creare un'istanza dell'inizializzatore nel codice, ad esempio nel file Global.aspx.cs:Alternatively, you can instantiate the initializer in code, for example in Global.aspx.cs:

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

Vedere questo esempio nel dettaglio.See more of this sample.

Inizializzatori di telemetria JavaScriptJavaScript telemetry initializers

JavaScriptJavaScript

Inserire un inizializzatore di telemetria immediatamente dopo il codice di inizializzazione ottenuto dal portale:Insert a telemetry initializer immediately after the initialization code that you got from the portal:


    <script type="text/javascript">
        // ... initialization code
        ...({
            instrumentationKey: "your instrumentation key"
        });
        window.appInsights = appInsights;


        // Adding telemetry initializer.
        // This is called whenever a new telemetry item
        // is created.

        appInsights.queue.push(function () {
            appInsights.context.addTelemetryInitializer(function (envelope) {
                var telemetryItem = envelope.data.baseData;

                // To check the telemetry item’s type - for example PageView:
                if (envelope.name == Microsoft.ApplicationInsights.Telemetry.PageView.envelopeType) {
                    // this statement removes url from all page view documents
                    telemetryItem.url = "URL CENSORED";
                }

                // To set custom properties:
                telemetryItem.properties = telemetryItem.properties || {};
                telemetryItem.properties["globalProperty"] = "boo";

                // To set custom metrics:
                telemetryItem.measurements = telemetryItem.measurements || {};
                telemetryItem.measurements["globalMetric"] = 100;
            });
        });

        // End of inserted code.

        appInsights.trackPageView();
    </script>

Per un riepilogo delle proprietà non personalizzate disponibili in telemetryItem, vedere Modello di dati di esportazione di Application Insights.For a summary of the non-custom properties available on the telemetryItem, see Application Insights Export Data Model.

È possibile aggiungere tutti gli inizializzatori desiderati.You can add as many initializers as you like.

ITelemetryProcessor e ITelemetryInitializerITelemetryProcessor and ITelemetryInitializer

Qual è la differenza tra processori di telemetria e inizializzatori di telemetria?What's the difference between telemetry processors and telemetry initializers?

  • Alcune funzioni si sovrappongono: entrambi possono essere usati per aggiungere proprietà a dati di telemetria.There are some overlaps in what you can do with them: both can be used to add properties to telemetry.
  • Gli inizializzatori di telemetria vengono sempre eseguiti prima dei processori di telemetria.TelemetryInitializers always run before TelemetryProcessors.
  • I processori di telemetria consentono di sostituire o rimuovere completamente un elemento di telemetria.TelemetryProcessors allow you to completely replace or discard a telemetry item.
  • I processori di telemetria non elaborano dati di telemetria dei contatori delle prestazioni.TelemetryProcessors don't process performance counter telemetry.

Risoluzione dei problemi relativi a ApplicationInsights.configTroubleshooting ApplicationInsights.config

  • Verificare che il nome di tipo completo e il nome di assembly siano corretti.Confirm that the fully qualified type name and assembly name are correct.
  • Verificare che il file applicationinsights.config si trovi nella directory di output e includa le ultime modifiche apportate.Confirm that the applicationinsights.config file is in your output directory and contains any recent changes.

Documentazione di riferimentoReference docs

Codice SDKSDK Code

Passaggi successiviNext steps