Telemetrie filteren en voor verwerking in de Application Insights SDKFiltering and preprocessing telemetry in the Application Insights SDK

U kunt invoeg toepassingen schrijven en configureren voor de Application Insights SDK om aan te passen hoe telemetrie kan worden verrijkt en verwerkt voordat het naar de Application Insights-service wordt verzonden.You can write and configure plug-ins for the Application Insights SDK to customize how telemetry can be enriched and processed before it's sent to the Application Insights service.

  • Door steek proeven wordt het aantal telemetrie verminderd zonder dat dit van invloed is op uw statistieken.Sampling reduces the volume of telemetry without affecting your statistics. Het houdt gerelateerde gegevens punten bij zodat u ertussen kunt navigeren bij het vaststellen van een probleem.It keeps together related data points so that you can navigate between them when diagnosing a problem. In de portal worden de totale aantallen vermenigvuldigd om de steek proeven te compenseren.In the portal, the total counts are multiplied to compensate for the sampling.
  • Met filters met telemetrie-processors kunt u telemetrie in de SDK filteren voordat deze naar de server wordt verzonden.Filtering with Telemetry Processors lets you filter out telemetry in the SDK before it is sent to the server. U kunt bijvoorbeeld het volume van de telemetrie verminderen door aanvragen van robots uit te sluiten.For example, you could reduce the volume of telemetry by excluding requests from robots. Filteren is een meer algemene benadering van het verminderen van het verkeer dan de steek proef.Filtering is a more basic approach to reducing traffic than sampling. Hiermee hebt u meer controle over wat er wordt verzonden, maar u moet er rekening mee houden dat dit van invloed is op uw statistieken, bijvoorbeeld als u alle succes volle aanvragen filtert.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.
  • Met de initialisatie functies voor telemetrie kunt u eigenschappen toevoegen of wijzigen voor alle telemetrie die vanuit uw app worden verzonden, inclusief telemetrie uit de standaard modules.Telemetry Initializers add or modify properties to any telemetry sent from your app, including telemetry from the standard modules. U kunt bijvoorbeeld berekende waarden toevoegen. of de versie nummers waarmee de gegevens in de portal worden gefilterd.For example, you could add calculated values; or version numbers by which to filter the data in the portal.
  • De SDK-API wordt gebruikt voor het verzenden van aangepaste gebeurtenissen en metrische gegevens.The SDK API is used to send custom events and metrics.

Voordat u begint:Before you start:

FilterenFiltering

Met deze techniek hebt u direct controle over wat er wordt opgenomen of uitgesloten van de telemetrie-stroom.This technique gives you direct control over what is included or excluded from the telemetry stream. Filteren kan worden gebruikt om telemetriegegevens te verwijderen van verzen ding naar Application Insights.Filtering can be used to drop telemetry items from being sent to Application Insights. U kunt deze gebruiken in combi natie met steek proeven of afzonderlijk.You can use it in conjunction with Sampling, or separately.

Als u telemetrie wilt filteren, schrijft u een telemetrie-processor en registreert u deze bij de TelemetryConfiguration.To filter telemetry, you write a telemetry processor and register it with the TelemetryConfiguration. Alle telemetrie verloopt via uw processor en u kunt ervoor kiezen om deze te verwijderen uit de stroom of door te geven aan de volgende processor in de keten.All telemetry goes through your processor, and you can choose to drop it from the stream or give it to the next processor in the chain. Dit omvat telemetrie van de standaard modules, zoals de HTTP-aanvraag verzamelaar en de afhankelijkheids verzamelaar, en telemetrie die u zelf hebt gevolgd.This includes telemetry from the standard modules such as the HTTP request collector and the dependency collector, and telemetry you have tracked yourself. U kunt bijvoorbeeld telemetrie filteren op aanvragen van robots of geslaagde afhankelijkheids aanroepen.You can, for example, filter out telemetry about requests from robots, or successful dependency calls.

Waarschuwing

Filteren van de telemetrie die via de SDK is verzonden met behulp van processors, kunnen de statistieken die u in de portal ziet, worden schuingetrokken en kan het lastig zijn om verwante items te volgen.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.

Overweeg in plaats daarvan steek proevente gebruiken.Instead, consider using sampling.

Een telemetrie-processorC#maken ()Create a telemetry processor (C#)

  1. Als u een filter wilt maken, implementeert u ITelemetryProcessor.To create a filter, implement ITelemetryProcessor.

    U ziet dat telemetrie-processors een keten van verwerking bouwen.Notice that Telemetry Processors construct a chain of processing. Wanneer u een telemetrie-processor maakt, krijgt u een verwijzing naar de volgende processor in de keten.When you instantiate a telemetry processor, you are given a reference to the next processor in the chain. Wanneer een telemetrie-gegevens punt wordt door gegeven aan de proces methode, wordt het werk uitgevoerd en wordt vervolgens de volgende telemetrie-processor in de keten aangeroepen (of niet).When a telemetry data point is passed to the Process method, it does its work and then calls (or not 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; }
    
        // next will point to the next TelemetryProcessor in the chain.
        public SuccessfulDependencyFilter(ITelemetryProcessor next)
        {
            this.Next = next;
        }
    
        public void Process(ITelemetry item)
        {
            // To filter out an item, return without calling the next processor.
            if (!OKtoSend(item)) { return; }
    
            this.Next.Process(item);
        }
    
        // Example: replace with your own criteria.
        private bool OKtoSend (ITelemetry item)
        {
            var dependency = item as DependencyTelemetry;
            if (dependency == null) return true;
    
            return dependency.Success != true;
        }
    }
    
  2. Voeg uw processor toe.Add your processor.

ASP.net-apps Voeg dit fragment in ApplicationInsights. config in:ASP.NET apps Insert this snippet in ApplicationInsights.config:

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

U kunt teken reeks waarden uit het. config-bestand door geven door open bare benoemde eigenschappen in uw klasse op te geven.You can pass string values from the .config file by providing public named properties in your class.

Waarschuwing

Zorg ervoor dat u de naam van het type en de namen van eigenschappen in het. config-bestand overeenkomt met de klasse-en eigenschaps namen in de code.Take care to match the type name and any property names in the .config file to the class and property names in the code. Als het. config-bestand verwijst naar een niet-bestaand type of een ongeldige eigenschap, kan de SDK een telemetrie niet op de achtergrond verzenden.If the .config file references a non-existent type or property, the SDK may silently fail to send any telemetry.

U kunt het filter ook in code initialiseren.Alternatively, you can initialize the filter in code. In een geschikte initialisatie klasse: bijvoorbeeld AppStart in Global.asax.cs-Voeg uw processor in de keten in:In a suitable initialization class - for example AppStart in Global.asax.cs - insert your processor into the chain:

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

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

builder.Build();

TelemetryClients gemaakt na dit punt zullen uw processors gebruiken.TelemetryClients created after this point will use your processors.

ASP.NET Core/Worker-service-appsASP.NET Core/ Worker Service apps

Notitie

Het toevoegen van een processor met ApplicationInsights.config of het gebruik van TelemetryConfiguration.Active is niet geldig voor ASP.NET Core toepassingen of als u micro soft. ApplicationInsights. WorkerService SDK gebruikt.Adding processor using ApplicationInsights.config or using TelemetryConfiguration.Active is not valid for ASP.NET Core applications or if you are using Microsoft.ApplicationInsights.WorkerService SDK.

Voor apps die zijn geschreven met behulp van ASP.net core of WorkerService, wordt het toevoegen van een nieuwe TelemetryProcessor uitgevoerd met behulp van AddApplicationInsightsTelemetryProcessor extensie methode op IServiceCollection, zoals hieronder wordt weer gegeven.For apps written using ASP.NET Core or WorkerService, adding a new TelemetryProcessor is done by using AddApplicationInsightsTelemetryProcessor extension method on IServiceCollection, as shown below. Deze methode wordt aangeroepen in ConfigureServices methode van uw Startup.cs-klasse.This method is called in ConfigureServices method of your Startup.cs class.

    public void ConfigureServices(IServiceCollection services)
    {
        // ...
        services.AddApplicationInsightsTelemetry();
        services.AddApplicationInsightsTelemetryProcessor<SuccessfulDependencyFilter>();

        // If you have more processors:
        services.AddApplicationInsightsTelemetryProcessor<AnotherProcessor>();
    }

Voorbeeld filtersExample filters

Synthetische aanvragenSynthetic requests

Wegfilteren bots en webtests.Filter out bots and web tests. Hoewel Metrics Explorer u de mogelijkheid geeft om synthetische bronnen uit te filteren, vermindert deze optie het verkeer en de opname grootte door deze te filteren op de SDK zelf.Although Metrics Explorer gives you the option to filter out synthetic sources, this option reduces traffic and ingestion size by filtering them at the SDK itself.

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

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

Mislukte verificatieFailed authentication

Aanvragen filteren met een antwoord van het "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, return without calling the next processor.
        return;
    }

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

Snelle oproepen voor externe afhankelijkheid uitfilterenFilter out fast remote dependency calls

Als u alleen aanroepen wilt opsporen die langzaam zijn, filtert u de snelle verbindingen.If you only want to diagnose calls that are slow, filter out the fast ones.

Notitie

Hierdoor worden de statistieken in de portal scheefer.This will skew the statistics you see on the portal.

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

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

Problemen als gevolg van diagnoseafhankelijkheidDiagnose dependency issues

In deze blog wordt een project beschreven voor het vaststellen van afhankelijkheids problemen door automatisch pings naar afhankelijkheden te verzenden.This blog describes a project to diagnose dependency issues by automatically sending regular pings to dependencies.

Java script-webtoepassingenJavaScript Web applications

Filteren met behulp van ITelemetryInitializerFiltering using ITelemetryInitializer

  1. Een call back functie voor telemetrie initialiseren maken.Create a telemetry initializer callback function. De call back-functie neemt ITelemetryItem als para meter. Dit is de gebeurtenis die wordt verwerkt.The callback function takes ITelemetryItem as a parameter, which is the event that is being processed. false retour neren van deze retour aanroep resulteert in het telemetrische item dat moet worden gefilterd.Returning false from this callback results in the telemetry item to be filtered out.

    var filteringFunction = (envelope) => {
      if (envelope.data.someField === 'tobefilteredout') {
         return false;
      }
    
      return true;
    };
    
  2. De call back van de telemetrie-initialisatie functie toevoegen:Add your telemetry initializer callback:

    appInsights.addTelemetryInitializer(filteringFunction);
    

Eigenschappen toevoegen/wijzigen: ITelemetryInitializerAdd/modify properties: ITelemetryInitializer

Gebruik initialisatie functies voor telemetrie om telemetrie te verrijken met aanvullende informatie en/of om de telemetrie-eigenschappen te overschrijven die zijn ingesteld door de standaard-telemetrie modules.Use telemetry initializers to enrich telemetry with additional information and/or to override telemetry properties set by the standard telemetry modules.

Zo kan de Application Insights voor webpakket het verzamelen van telemetrie over HTTP-aanvragen.For example, the Application Insights for Web package collect telemetry about HTTP requests. Standaard wordt een aanvraag met een antwoord code > = 400 als mislukt.By default, it flags as failed any request with a response code >= 400. Als u 400 als een succes wilt behandelen, kunt u een telemetrie-initialisatie functie opgeven waarmee de eigenschap Success wordt ingesteld.But if you want to treat 400 as a success, you can provide a telemetry initializer that sets the Success property.

Als u een telemetrie-initialisatie functie opgeeft, wordt deze aangeroepen wanneer een van de methoden van de track * () wordt aangeroepen.If you provide a telemetry initializer, it is called whenever any of the Track*() methods are called. Dit omvat Track()-methoden die worden aangeroepen door de standaard-telemetrie-modules.This includes Track() methods called by the standard telemetry modules. Per Conventie stellen deze modules geen eigenschap in die al is ingesteld door een initialisatie functie.By convention, these modules do not set any property that has already been set by an initializer. Initialisatie functies voor telemetrie worden aangeroepen voordat telemetrie-processors worden aangeroepen.Telemetry initializers are called before calling telemetry processors. Verrijkingen die door initializers worden uitgevoerd, zijn dus zichtbaar voor processors.So any enrichments done by initializers are visible to processors.

De initialisatie functie definiërenDefine 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.Properties["Overridden400s"] = "true";
        }
        // else leave the SDK to set the Success property
    }
  }
}

ASP.NET-Apps: de initialisatie functie ladenASP.NET apps: Load your initializer

In ApplicationInsights. config:In ApplicationInsights.config:

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

U kunt ook een exemplaar van de initialisatie functie in code maken, bijvoorbeeld in 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());
}

Bekijk meer van dit voor beeld.See more of this sample.

ASP.NET Core/Worker-service-apps: de initialisatie functie ladenASP.NET Core/ Worker Service apps: Load your initializer

Notitie

Het toevoegen van initializer met behulp van ApplicationInsights.config of het gebruik van TelemetryConfiguration.Active is niet geldig voor ASP.NET Core toepassingen of als u micro soft. ApplicationInsights. WorkerService SDK gebruikt.Adding initializer using ApplicationInsights.config or using TelemetryConfiguration.Active is not valid for ASP.NET Core applications or if you are using Microsoft.ApplicationInsights.WorkerService SDK.

Voor apps die zijn geschreven met behulp van ASP.net core of WorkerService, moet u een nieuwe TelemetryInitializer toevoegen door het toe te voegen aan de container voor de injectie van afhankelijkheden, zoals hieronder wordt weer gegeven.For apps written using ASP.NET Core or WorkerService, adding a new TelemetryInitializer is done by adding it to the Dependency Injection container, as shown below. Dit doet u in Startup.ConfigureServices methode.This is done in Startup.ConfigureServices method.

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

Initialisatie functies voor Java-telemetrieJava telemetry initializers

Documentatie voor Java SDKJava SDK documentation

public interface TelemetryInitializer
{ /** Initializes properties of the specified object. * @param telemetry The {@link com.microsoft.applicationinsights.telemetry.Telemetry} to initialize. */

void initialize(Telemetry telemetry); }

Registreer vervolgens de aangepaste initialisatie functie in uw applicationinsights. XML-bestand.Then register the custom initializer in your applicationinsights.xml file.

<Add type="mypackage.MyConfigurableContextInitializer">
    <Param name="some_config_property" value="some_value" />
</Add>

Initialisatie functies van Java script-telemetrieJavaScript telemetry initializers

JavaScriptJavaScript

Voeg direct na de initialisatie code die u hebt ontvangen van de portal, een telemetrie-initialisatie functie toe: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 items 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>

Zie Application Insights-gegevens model exporterenvoor een samen vatting van de niet-aangepaste eigenschappen die beschikbaar zijn op de telemetryItem.For a summary of the non-custom properties available on the telemetryItem, see Application Insights Export Data Model.

U kunt zoveel initialisatie functies toevoegen als u wilt en ze worden aangeroepen in de volg orde waarin ze worden toegevoegd.You can add as many initializers as you like, and they are called in the order they are added.

Voor beeld TelemetryInitializersExample TelemetryInitializers

Aangepaste eigenschap toevoegenAdd custom property

De volgende voor beeld-initialisatie functie voegt een aangepaste eigenschap toe aan elke getraceerde telemetrie.The following sample initializer adds a custom property to every tracked telemetry.

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

Rolnaam van Cloud toevoegenAdd cloud role name

De volgende voor beeld-initialisatie functie stelt de naam van de Cloud functie in op elke getraceerde telemetrie.The following sample initializer sets cloud role name to every tracked telemetry.

public void Initialize(ITelemetry telemetry)
{
    if(string.IsNullOrEmpty(telemetry.Context.Cloud.RoleName))
    {
        telemetry.Context.Cloud.RoleName = "MyCloudRoleName";
    }
}

ITelemetryProcessor en ITelemetryInitializerITelemetryProcessor and ITelemetryInitializer

Wat is het verschil tussen telemetrie-processors en initialisatie functies voor telemetrie?What's the difference between telemetry processors and telemetry initializers?

  • Er zijn enkele overlap pingen in wat u ermee kunt doen: beide kunnen worden gebruikt om eigenschappen van telemetrie toe te voegen of te wijzigen, maar het wordt aanbevolen initialisatie functies voor dat doel te gebruiken.There are some overlaps in what you can do with them: both can be used to add or modify properties of telemetry, though it is recommended to use initializers for that purpose.
  • TelemetryInitializers altijd uitgevoerd vóór TelemetryProcessors.TelemetryInitializers always run before TelemetryProcessors.
  • TelemetryInitializers kan meer dan één keer worden aangeroepen.TelemetryInitializers may be called more than once. Per Conventie hebben ze geen eigenschap ingesteld die al is ingesteld.By convention, they do not set any property that has already been set.
  • Met TelemetryProcessors kunt u een telemetrie-item volledig vervangen of verwijderen.TelemetryProcessors allow you to completely replace or discard a telemetry item.
  • Alle geregistreerde TelemetryInitializers worden gegarandeerd aangeroepen voor elk telemetrie-item.All registered TelemetryInitializers are guaranteed to be called for every telemetry item. Voor telemetrie-processors wordt door SDK gegarandeerd de eerste telemetrie-processor aan te roepen.For Telemetry processors, SDK guarantees calling the very first telemetry processor. Of de rest van de processors worden aangeroepen of niet, wordt bepaald door de voor gaande telemetrie-processors.Whether the rest of the processors are called or not, is decided by the preceding telemetry processors.
  • Gebruik TelemetryInitializers om telemetrie te verrijken met aanvullende eigenschappen, of een bestaande te overschrijven.Use TelemetryInitializers to enrich telemetry with additional properties, or override existing one. Gebruik TelemetryProcessor om telemetrie te filteren.Use TelemetryProcessor to filter out telemetry.

Problemen met ApplicationInsights. config oplossenTroubleshooting ApplicationInsights.config

  • Controleer of de FQDN-naam en de naam van de assembly juist zijn.Confirm that the fully qualified type name and assembly name are correct.
  • Controleer of het bestand applicationinsights. config zich in de uitvoermap bevindt en of het recente wijzigingen bevat.Confirm that the applicationinsights.config file is in your output directory and contains any recent changes.

ReferentiedocumentenReference docs

SDK-codeSDK Code

Volgende stappenNext steps