Filterung und Vorverarbeitung von Telemetriedaten im Application Insights-SDKFiltering and preprocessing telemetry in the Application Insights SDK

Sie können Plug-Ins für das Application Insights SDK schreiben und konfigurieren, um anzupassen, wie Telemetriedaten vor dem Senden an den Application Insights-Dienst angereichert und verarbeitet werden.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.

  • Erstellen von Stichproben verringert sich der Umfang der Telemetriedaten, ohne Statistiken zu verfälschen.Sampling reduces the volume of telemetry without affecting your statistics. Zusammengehörige Datenpunkte werden dabei zusammengehalten, sodass Sie bei der Diagnose von Problemen zwischen diesen navigieren können.It keeps together related data points so that you can navigate between them when diagnosing a problem. Im Portal wird die Gesamtanzahl multipliziert, um eine Kompensation der Stichproben zu erreichen.In the portal, the total counts are multiplied to compensate for the sampling.
  • Durch das Filtern mit Telemetrieprozessoren können Sie Telemetriedaten im SDK herausfiltern, bevor sie an den Server gesendet werden.Filtering with Telemetry Processors lets you filter out telemetry in the SDK before it is sent to the server. Sie können beispielsweise den Umfang der Telemetriedaten verringern, indem Sie Anforderungen von Robots ausschließen.For example, you could reduce the volume of telemetry by excluding requests from robots. Filtern stellt ein grundlegenderes Verfahren zur Senkung des Datenverkehrs dar als das Erstellen von Stichproben.Filtering is a more basic approach to reducing traffic than sampling. Sie können so besser steuern, was übertragen wird. Jedoch müssen Sie beachten, dass dies Auswirkungen auf die Statistik hat – wenn Sie z. B. alle erfolgreichen Anforderungen herausfiltern.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.
  • Telemetrieinitialisierer fügen Eigenschaften zu beliebigen von der App gesendeten Telemetriedaten hinzu oder ändern sie, einschließlich Telemetriedaten von Standardmodulen.Telemetry Initializers add or modify properties to any telemetry sent from your app, including telemetry from the standard modules. Sie könnten z. B. berechnete Werte hinzufügen oder Versionsnummern, nach denen Sie die Daten im Portal filtern.For example, you could add calculated values; or version numbers by which to filter the data in the portal.
  • SDK-API wird zum Senden benutzerdefinierter Ereignisse und Metriken verwendet.The SDK API is used to send custom events and metrics.

Vorbereitung:Before you start:

FilterungFiltering

Mit dieser Technik können Sie direkt kontrollieren, welche Daten in den Telemetriedatenstrom ein- oder daraus ausgeschlossen werden sollen.This technique gives you direct control over what is included or excluded from the telemetry stream. Filtern Sie Telemetrieelemente vor dem Senden an Application Insights heraus.Filtering can be used to drop telemetry items from being sent to Application Insights. Sie können sie zusammen mit der Stichprobenerstellung oder einzeln verwenden.You can use it in conjunction with Sampling, or separately.

Zum Filtern von Telemetriedaten schreiben Sie einen Telemetrieprozessor und registrieren ihn bei TelemetryConfiguration.To filter telemetry, you write a telemetry processor and register it with the TelemetryConfiguration. Alle Telemetriedaten durchlaufen den Prozessor. Dabei können Sie auswählen, welche Daten aus dem Datenstrom gelöscht und welche an den nächsten Prozessor in der Kette weitergegeben werden sollen.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. Dies schließt Telemetriedaten aus den Standardmodulen wie etwa dem HTTP-Anforderungssammler und der Abhängigkeitserfassung ein sowie von Ihnen selbst überwachte Telemetriedaten.This includes telemetry from the standard modules such as the HTTP request collector and the dependency collector, and telemetry you have tracked yourself. Sie können z. B. Telemetriedaten zu Anforderungen von Robots oder erfolgreiche Abhängigkeitsaufrufe herausfiltern.You can, for example, filter out telemetry about requests from robots, or successful dependency calls.

Warnung

Die Filterung der vom SDK gesendeten Telemetriedaten mithilfe von Prozessoren kann die im Portal angezeigten Statistiken verfälschen und die Nachverfolgung verwandter Elemente erschweren.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.

Verwenden Sie stattdessen Sampling.Instead, consider using sampling.

Erstellen eines Telemetrieprozessors (C#)Create a telemetry processor (C#)

  1. Implementieren Sie ITelemetryProcessor, um einen Filter zu erstellen:To create a filter, implement ITelemetryProcessor.

    Beachten Sie, dass Telemetrieprozessoren eine Verarbeitungskette erstellen.Notice that Telemetry Processors construct a chain of processing. Beim Instanziieren eines Telemetrieprozessors erhalten Sie einen Verweis auf den nächsten Prozessor in der Kette.When you instantiate a telemetry processor, you are given a reference to the next processor in the chain. Wenn ein Telemetriedatenpunkt an die Verarbeitungsmethode übergeben wird, führt er seine Aufgaben aus und ruft den nächsten Telemetrieprozessor in der Kette auf (oder nicht).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. Fügen Sie den Prozessor hinzu.Add your processor.

ASP.NET-Apps: Fügen Sie den folgenden Codeausschnitt in „ApplicationInsights.config“ ein:ASP.NET apps Insert this snippet in ApplicationInsights.config:

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

Sie können durch die Bereitstellung von öffentlich benannten Eigenschaften in Ihrer Klasse Zeichenfolgenwerte aus der .config-Datei übergeben.You can pass string values from the .config file by providing public named properties in your class.

Warnung

Achten Sie darauf, dass die Typnamen und sonstige Eigenschaftennamen in der .config-Datei mit den Klassen- und Eigenschaftennamen im Code übereinstimmen.Take care to match the type name and any property names in the .config file to the class and property names in the code. Wenn die .config-Datei auf einen nicht vorhandenen Typ oder eine nicht vorhandene Eigenschaft verweist, könnte das SDK möglicherweise automatisch keine Telemetriedaten mehr senden.If the .config file references a non-existent type or property, the SDK may silently fail to send any telemetry.

Alternativ können Sie den Filter im Code initialisieren.Alternatively, you can initialize the filter in code. Fügen Sie in einer geeigneten Initialisierungsklasse, z. B. AppStart in Global.asax.cs, Ihren Prozessor in die Kette ein: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();

Nach diesem Punkt erstellte TelemetryClients-Elemente verwenden Ihre Prozessoren.TelemetryClients created after this point will use your processors.

ASP.NET Core/Workerdienst-AppsASP.NET Core/ Worker Service apps

Hinweis

Das Hinzufügen eines Prozessors mithilfe von ApplicationInsights.config oder TelemetryConfiguration.Active ist für ASP.NET Core-Anwendungen sowie für das SDK „Microsoft.ApplicationInsights.WorkerService“ ungültig.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.

Bei Apps, die mit ASP.NET Core oder WorkerService geschrieben wurden, wird ein neuer TelemetryProcessor, wie im folgenden Beispiel veranschaulicht, durch Anwenden der Erweiterungsmethode AddApplicationInsightsTelemetryProcessor auf IServiceCollection hinzugefügt.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. Diese Methode wird in der Methode ConfigureServices Ihrer Startup.cs-Klasse aufgerufen.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>();
    }

BeispielfilterExample filters

Synthetische AnforderungenSynthetic requests

Filtern Sie Bots und Webtests heraus.Filter out bots and web tests. Mit dem Metrik-Explorer haben Sie die Möglichkeit, synthetische Quellen herauszufiltern. Dabei werden jedoch der Datenverkehr und der Umfang der erfassten Daten verringert, da die Quellen im SDK selbst gefiltert werden.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);
}

Fehler bei der AuthentifizierungFailed authentication

Filtern Sie Abfragen mit der Antwort „401“ heraus.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);
}

Herausfiltern schneller RemoteabhängigkeitsaufrufeFilter out fast remote dependency calls

Wenn Sie langsame Aufrufe diagnostizieren möchten, filtern Sie die schnellen Aufrufe heraus.If you only want to diagnose calls that are slow, filter out the fast ones.

Hinweis

Dadurch wird die im Portal angezeigte Statistik verfälscht.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);
}

Diagnostizieren von AbhängigkeitsproblemenDiagnose dependency issues

diesem Blog wird ein Projekt zur Diagnose von Abhängigkeitsproblemen beim automatischen Senden regulärer Pings an Abhängigkeiten beschrieben.This blog describes a project to diagnose dependency issues by automatically sending regular pings to dependencies.

JavaScript-WebanwendungenJavaScript Web applications

Filtern mithilfe von „ITelemetryInitializer“Filtering using ITelemetryInitializer

  1. Erstellen Sie eine Rückruffunktion für einen Telemetrieinitialisierer.Create a telemetry initializer callback function. Die Rückruffunktion akzeptiert ITelemetryItem als Parameter. Dies ist das Ereignis, das gerade verarbeitet wird.The callback function takes ITelemetryItem as a parameter, which is the event that is being processed. Wenn dieser Rückruf false zurückgibt, wird das Telemetrieelement herausgefiltert.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. Fügen Sie den Rückruf für den Telemetrieinitialisierer hinzu:Add your telemetry initializer callback:

    appInsights.addTelemetryInitializer(filteringFunction);
    

Hinzufügen/Ändern von Eigenschaften von: ITelemetryInitializerAdd/modify properties: ITelemetryInitializer

Verwenden Sie Telemetrieinitialisierer, um Telemetriedaten mit zusätzlichen Informationen anzureichern und/oder die von Standardtelemetriemodulen festgelegten Telemetrieeigenschaften zu überschreiben.Use telemetry initializers to enrich telemetry with additional information and/or to override telemetry properties set by the standard telemetry modules.

Das Application Insights for Web-Paket erfasst beispielsweise Telemetriedaten zu HTTP-Anforderungen.For example, the Application Insights for Web package collect telemetry about HTTP requests. Standardmäßig kennzeichnet es jede Anforderung mit einem Antwortcode >= 400 als fehlerhaft.By default, it flags as failed any request with a response code >= 400. Wenn 400 jedoch als erfolgreich behandelt werden soll, können Sie einen Telemetrieinitialisierer angeben, der die Success-Eigenschaft festlegt.But if you want to treat 400 as a success, you can provide a telemetry initializer that sets the Success property.

Wenn Sie einen Telemetrieinitialisierer angeben, wird dieser immer aufgerufen, wenn eine der Track*()-Methoden aufgerufen wird.If you provide a telemetry initializer, it is called whenever any of the Track*() methods are called. Dies umfasst auch Track()-Methoden, die von den Standardtelemetriemodulen aufgerufen werden.This includes Track() methods called by the standard telemetry modules. Nach Abmachung legen diese Module keine Eigenschaft fest, die bereits durch einen Initialisierer festgelegt wurde.By convention, these modules do not set any property that has already been set by an initializer. Telemetrieinitialisierer werden vor Telemetrieprozessoren aufgerufen.Telemetry initializers are called before calling telemetry processors. Daher sind alle von Initialisierern durchgeführten Anreicherungen für Prozessoren sichtbar.So any enrichments done by initializers are visible to processors.

Definieren des InitialisierersDefine 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: Laden des InitialisierersASP.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>

Alternativ können Sie den Initialisierer im Code instanziieren, z.B. 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());
}

Weitere Informationen zu diesem Beispiel anzeigen.See more of this sample.

ASP.NET Core/Workerdienst-Apps: Laden des InitialisierersASP.NET Core/ Worker Service apps: Load your initializer

Hinweis

Das Hinzufügen eines Initialisierers mithilfe von ApplicationInsights.config oder TelemetryConfiguration.Active ist für ASP.NET Core-Anwendungen sowie für das SDK „Microsoft.ApplicationInsights.WorkerService“ ungültig.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.

Wenn Sie bei Apps, die mithilfe von ASP.NET Core oder WorkerService geschrieben wurden, einen neuen TelemetryInitializer hinzufügen möchten, wird dieser wie unten gezeigt dem Container für die Abhängigkeitsinjektion hinzugefügt.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. Dies erfolgt in der Methode Startup.ConfigureServices.This is done in Startup.ConfigureServices method.

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

Java-TelemetrieinitialisiererJava telemetry initializers

Java SDK-DokumentationJava 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); }

Registrieren Sie anschließend den benutzerdefinierten Initialisierer in der Datei „applicationinsights.xml“.Then register the custom initializer in your applicationinsights.xml file.

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

JavaScript-TelemetrieinitialisiererJavaScript telemetry initializers

JavaScriptJavaScript

Fügen Sie einen Telemetrieinitialisierer unmittelbar nach dem Initialisierungscode ein, den Sie vom Portal abgerufen haben: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>

Eine Übersicht der für „telemetryItem“ verfügbaren nicht benutzerdefinierten Eigenschaften finden Sie im Application Insights-Datenmodell für den Export von Daten.For a summary of the non-custom properties available on the telemetryItem, see Application Insights Export Data Model.

Sie können beliebig viele Initialisierer hinzufügen. Diese werden in der Reihenfolge aufgerufen, in der sie hinzugefügt wurden.You can add as many initializers as you like, and they are called in the order they are added.

Beispiel: TelemetrieinitialisiererExample TelemetryInitializers

Hinzufügen einer benutzerdefinierten EigenschaftAdd custom property

Mit dem folgenden Beispielinitialisierer wird allen überwachten Telemetriedaten eine benutzerdefinierte Eigenschaft hinzugefügt: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";
    }
}

Hinzufügen eines CloudrollennamensAdd cloud role name

Mit dem folgenden Beispielinitialisierer wird für alle überwachten Telemetriedaten ein Cloudrollenname festgelegt: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 und ITelemetryInitializerITelemetryProcessor and ITelemetryInitializer

Was ist der Unterschied zwischen Telemetrieprozessoren und Telemetrieinitialisierern?What's the difference between telemetry processors and telemetry initializers?

  • Bei den Anwendungsmöglichkeiten gibt es einige Überschneidungen: Mit beiden können Sie Eigenschaften von Telemetriedaten hinzufügen oder ändern. Für diesen Zweck wird jedoch die Verwendung von Initialisierern empfohlen.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.
  • Telemetrieinitialisierer werden immer vor Telemetrieprozessoren ausgeführt.TelemetryInitializers always run before TelemetryProcessors.
  • Telemetrieinitialisierer können mehrmals aufgerufen werden.TelemetryInitializers may be called more than once. Laut Konvention legen sie keine Eigenschaften fest, die bereits festgelegt wurden.By convention, they do not set any property that has already been set.
  • Mit Telemetrieprozessoren können Sie ein Telemetrieelement vollständig ersetzen oder verwerfen.TelemetryProcessors allow you to completely replace or discard a telemetry item.
  • Alle registrierten Telemetrieinitialisierer werden für jedes Telemetrieelement garantiert aufgerufen.All registered TelemetryInitializers are guaranteed to be called for every telemetry item. Bei Telemetrieprozessoren wird mit dem SDK der erste Telemetrieprozessor garantiert aufgerufen.For Telemetry processors, SDK guarantees calling the very first telemetry processor. Je nach vorangehenden Telemetrieprozessoren werden die restlichen Prozessoren anschließend aufgerufen oder nicht.Whether the rest of the processors are called or not, is decided by the preceding telemetry processors.
  • Mit Telemetrieinitialisierern können Sie Telemetriedaten mit zusätzlichen Eigenschaften anreichern oder die vorhandenen Daten überschreiben.Use TelemetryInitializers to enrich telemetry with additional properties, or override existing one. Mit Telemetrieprozessoren können Telemetriedaten herausgefiltert werden.Use TelemetryProcessor to filter out telemetry.

Behandeln von Problemen mit „ApplicationInsights.config“Troubleshooting ApplicationInsights.config

  • Vergewissern Sie sich, dass der vollqualifizierte Typname und der Assemblyname korrekt sind.Confirm that the fully qualified type name and assembly name are correct.
  • Vergewissern Sie sich, dass sich die Datei „applicationinsights.config“ in Ihrem Ausgabeverzeichnis befindet und auf dem neuesten Stand ist.Confirm that the applicationinsights.config file is in your output directory and contains any recent changes.

ReferenzReference docs

SDK-CodeSDK Code

Nächste SchritteNext steps