Telemetrie filteren en voorverwerken in de Application Insights-SDK

U kunt in plug-ins schrijven en configureren voor de Application Insights SDK om aan te passen hoe telemetrie kan worden verrijkt en verwerkt voordat deze naar de Application Insights-service wordt verzonden.

  • Steekproeven verminderen het volume aan telemetrie zonder dat dit van invloed is op uw statistieken. Het houdt gerelateerde gegevenspunten bij elkaar, zodat u ertussen kunt navigeren wanneer u een probleem diagnosticeert. In de portal worden het totale aantal vermenigvuldigd om de steekproef te compenseren.
  • Door te filteren met telemetrieprocessors kunt u telemetrie in de SDK filteren voordat deze naar de server wordt verzonden. U kunt bijvoorbeeld de hoeveelheid telemetrie verminderen door aanvragen van robots uit te sluiten. Filteren is een basisbenadering om het verkeer te verminderen dan steekproeven. Hiermee hebt u meer controle over wat er wordt verzonden, maar dit is van invloed op uw statistieken. U kunt bijvoorbeeld alle geslaagde aanvragen wegfilteren.
  • Initialisaties voor telemetrie voegen eigenschappen toe aan of wijzigen deze aan telemetrie die vanuit uw app wordt verzonden, waaronder telemetrie van de standaardmodules. U kunt bijvoorbeeld berekende waarden of versienummers toevoegen waarmee u de gegevens in de portal kunt filteren.
  • De SDK-API wordt gebruikt voor het verzenden van aangepaste gebeurtenissen en metrische gegevens.

Voordat u begint:

Filteren

Deze techniek geeft u directe controle over wat er is opgenomen of uitgesloten van de telemetriestroom. Filteren kan worden gebruikt om telemetrie-items te verwijderen van gegevens die worden verzonden naar Application Insights. U kunt filteren gebruiken in combinatie met steekproeven of afzonderlijk.

Als u telemetrie wilt filteren, schrijft u een telemetrieprocessor en registreert u deze bij TelemetryConfiguration . Alle telemetrie gaat via uw processor. U kunt ervoor kiezen om deze uit de stream te halen of aan de volgende processor in de keten te geven. Telemetrie van de standaardmodules, zoals de HTTP-aanvraagverzamelaar en de afhankelijkheidsverzamelaar, en telemetrie die u zelf hebt bijgespoord, zijn opgenomen. U kunt bijvoorbeeld telemetrie over aanvragen van robots of geslaagde afhankelijkheidsaanvragen filteren.

Waarschuwing

Het filteren van de telemetrie die vanuit de SDK wordt verzonden met behulp van processors kan de statistieken die u in de portal ziet, scheeftrekken en het lastig maken om gerelateerde items te volgen.

Overweeg in plaats daarvan het gebruik van steekproeven.

Een telemetrieprocessor maken (C#)

  1. Als u een filter wilt maken, implementeert u ITelemetryProcessor .

    Telemetrieprocessors bouwen een verwerkingsketen op. Wanneer u een telemetrieprocessor instantit, krijgt u een verwijzing naar de volgende processor in de keten. Wanneer een telemetriegegevenspunt wordt doorgegeven aan de procesmethode, wordt de volgende telemetrieprocessor in de keten aanroepen (of niet aanroepen).

    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.

ASP.NET apps

Voeg dit fragment in ApplicationInsights.config:

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

U kunt tekenreekswaarden uit het .config door openbare benoemde eigenschappen op te geven in uw klasse.

Waarschuwing

Zorg dat de typenaam en eventuele eigenschapsnamen in het .config overeenkomen met de klasse en eigenschapsnamen in de code. Als het .config verwijst naar een niet-bestaand type of eigenschap, kan de SDK op de stille kracht geen telemetrie verzenden.

U kunt het filter ook initialiseren in code. Voeg in een geschikte initialisatieklasse, bijvoorbeeld AppStart in Global.asax.cs , uw processor in de keten in:

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();

Telemetrie-clients die na dit punt zijn gemaakt, gebruiken uw processors.

ASP.NET Core/Worker-service-apps

Notitie

Het toevoegen van een processor met of is niet geldig voor ASP.NET Core toepassingen of als u de ApplicationInsights.config TelemetryConfiguration.Active Microsoft.ApplicationInsights.WorkerService SDK gebruikt.

Voor apps die zijn geschreven met ASP.NET Core of WorkerService,wordt het toevoegen van een nieuwe telemetrieprocessor uitgevoerd met behulp van de extensiemethode op AddApplicationInsightsTelemetryProcessor , zoals wordt IServiceCollection weergegeven. Deze methode wordt aangeroepen in de ConfigureServices methode van uw Startup.cs klasse.

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

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

Voorbeeldfilters

Synthetische aanvragen

Bots en webtests eruit filteren. Hoewel Metrics Explorer de mogelijkheid biedt om synthetische bronnen uit te filteren, vermindert deze optie het verkeer en de opnamegrootte door ze te filteren op de SDK zelf.

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

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

Mislukte verificatie

Filter aanvragen uit met een 401-antwoord.

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 externe afhankelijkheidsoproepen filteren

Als u alleen aanroepen wilt diagnosticeren die traag zijn, filtert u de snelle.

Notitie

Met deze filtering worden de statistieken die u in de portal ziet, scheef scheef gestaan.

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

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

Afhankelijkheidsproblemen vaststellen

In dit blog wordt een project beschreven voor het diagnosticeren van afhankelijkheidsproblemen door automatisch regelmatige pings naar afhankelijkheden te verzenden.

JavaScript-webtoepassingen

Filteren met ITelemetryInitializer

  1. Maak een callback-functie voor telemetrie-initialisatie. De callback-functie ITelemetryItem gebruikt als parameter. Dit is de gebeurtenis die wordt verwerkt. Als false u terugkeert van deze callback, wordt het telemetrie-item uitgefilterd.

    var filteringFunction = (envelope) => {
      if (envelope.data.someField === 'tobefilteredout') {
          return false;
      }
    
      return true;
    };
    
  2. Voeg de callback van uw telemetrie-initialisatieprogramma toe:

    appInsights.addTelemetryInitializer(filteringFunction);
    

Eigenschappen toevoegen/wijzigen: ITelemetryInitializer

Gebruik initialisaties voor telemetrie om telemetrie te verrijken met aanvullende informatie of om telemetrie-eigenschappen te overschrijven die zijn ingesteld door de standaard telemetriemodules.

Application Insights voor een webpakket verzamelt bijvoorbeeld telemetrie over HTTP-aanvragen. Standaard wordt elke aanvraag als mislukt weergegeven met een antwoordcode >=400. Maar als u 400 als een succes wilt behandelen, kunt u een telemetrie-initialisatiemiddel bieden om de eigenschap geslaagd in te stellen.

Als u een initialisatiemethode voor telemetrie verstrekt, wordt deze aangeroepen wanneer een van de Track*()-methoden wordt aangeroepen. Dit omvat Track() methoden die worden aangeroepen door de standaard-telemetriemodules. Volgens de conventies stellen deze modules geen eigenschap in die al is ingesteld door een initialisatier. Initialisaties voor telemetrie worden aangeroepen voordat telemetrieprocessors worden aangeroepen. Alle verrijkingen die door initializers worden uitgevoerd, zijn dus zichtbaar voor processors.

Definieer uw initialisatie

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: uw initialisatie-app laden

In ApplicationInsights.config:

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

U kunt het initialisatiemiddel ook instantieren in code, bijvoorbeeld in Global.aspx.cs:

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

Bekijk meer van dit voorbeeld.

ASP.NET Core/Worker-service-apps: De initialisatie-app laden

Notitie

Het toevoegen van een initialisatiemiddel met behulp van of is niet geldig voor ASP.NET Core-toepassingen of als u de ApplicationInsights.config TelemetryConfiguration.Active Microsoft.ApplicationInsights.WorkerService SDK gebruikt.

Voor apps die zijn geschreven met ASP.NET Core of WorkerService,wordt het toevoegen van een nieuwe telemetrie-initialisatie uitgevoerd door deze toe te voegen aan de container Dependency Injection, zoals wordt weergegeven. Dit wordt gedaan in de Startup.ConfigureServices methode .

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

Initialisatie van JavaScript-telemetrie

JavaScript

Voeg een telemetrie-initialisatiemiddel in direct na de initialisatiecode die u hebt ontvangen via de 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.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 cloud role name / instance
        envelope.tags["ai.cloud.role"] = "your role name";
        envelope.tags["ai.cloud.roleInstance"] = "your role instance";
    });

    // End of inserted code.

    appInsights.trackPageView();
</script>

Zie Application Insights Export Data Model voor een samenvatting van de niet-aanaan-klanteigenschappen die beschikbaar zijn op het telemetrie-item.

U kunt zoveel initialisaties toevoegen als u wilt. Ze worden aangeroepen in de volgorde waarin ze worden toegevoegd.

OpenCensus Python-telemetrieprocessors

Telemetrieprocessors in OpenCensus Python zijn gewoon callback-functies die worden aangeroepen om telemetrie te verwerken voordat ze worden geëxporteerd. De callback-functie moet een envelopgegevenstype als parameter accepteren. Als u wilt filteren op telemetrie van het exporteren, moet u ervoor zorgen dat de callback-functie False retourneert. U ziet het schema voor Azure Monitor gegevenstypen in de enveloppen op GitHub.

Notitie

U kunt wijzigen cloud_RoleName door het kenmerk in het veld te ai.cloud.role tags wijzigen.

def callback_function(envelope):
    envelope.tags['ai.cloud.role'] = 'new_role_name'
# Example for log exporter
import logging

from opencensus.ext.azure.log_exporter import AzureLogHandler

logger = logging.getLogger(__name__)

# Callback function to append '_hello' to each log message telemetry
def callback_function(envelope):
    envelope.data.baseData.message += '_hello'
    return True

handler = AzureLogHandler(connection_string='InstrumentationKey=<your-instrumentation_key-here>')
handler.add_telemetry_processor(callback_function)
logger.addHandler(handler)
logger.warning('Hello, World!')
# Example for trace exporter
import requests

from opencensus.ext.azure.trace_exporter import AzureExporter
from opencensus.trace import config_integration
from opencensus.trace.samplers import ProbabilitySampler
from opencensus.trace.tracer import Tracer

config_integration.trace_integrations(['requests'])

# Callback function to add os_type: linux to span properties
def callback_function(envelope):
    envelope.data.baseData.properties['os_type'] = 'linux'
    return True

exporter = AzureExporter(
    connection_string='InstrumentationKey=<your-instrumentation-key-here>'
)
exporter.add_telemetry_processor(callback_function)
tracer = Tracer(exporter=exporter, sampler=ProbabilitySampler(1.0))
with tracer.span(name='parent'):
response = requests.get(url='https://www.wikipedia.org/wiki/Rabbit')
# Example for metrics exporter
import time

from opencensus.ext.azure import metrics_exporter
from opencensus.stats import aggregation as aggregation_module
from opencensus.stats import measure as measure_module
from opencensus.stats import stats as stats_module
from opencensus.stats import view as view_module
from opencensus.tags import tag_map as tag_map_module

stats = stats_module.stats
view_manager = stats.view_manager
stats_recorder = stats.stats_recorder

CARROTS_MEASURE = measure_module.MeasureInt("carrots",
                                            "number of carrots",
                                            "carrots")
CARROTS_VIEW = view_module.View("carrots_view",
                                "number of carrots",
                                [],
                                CARROTS_MEASURE,
                                aggregation_module.CountAggregation())

# Callback function to only export the metric if value is greater than 0
def callback_function(envelope):
    return envelope.data.baseData.metrics[0].value > 0

def main():
    # Enable metrics
    # Set the interval in seconds in which you want to send metrics
    exporter = metrics_exporter.new_metrics_exporter(connection_string='InstrumentationKey=<your-instrumentation-key-here>')
    exporter.add_telemetry_processor(callback_function)
    view_manager.register_exporter(exporter)

    view_manager.register_view(CARROTS_VIEW)
    mmap = stats_recorder.new_measurement_map()
    tmap = tag_map_module.TagMap()

    mmap.measure_int_put(CARROTS_MEASURE, 1000)
    mmap.record(tmap)
    # Default export interval is every 15.0s
    # Your application should run for at least this amount
    # of time so the exporter will meet this interval
    # Sleep can fulfill this
    time.sleep(60)

    print("Done recording metrics")

if __name__ == "__main__":
    main()

U kunt zoveel processors toevoegen als u wilt. Ze worden aangeroepen in de volgorde waarin ze worden toegevoegd. Als één processor een uitzondering west, heeft dit geen invloed op de volgende processors.

Voorbeeld van TelemetryInitializers

Een aangepaste eigenschap toevoegen

Met de volgende voorbeeld-initialisatie voegt u een aangepaste eigenschap toe aan elke bij te houden telemetrie.

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

Een naam voor een cloudrol toevoegen

Met het volgende voorbeeld van initialisatie stelt u de naam van de cloudrol in op elke bij te houden telemetrie.

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

Informatie toevoegen vanuit HttpContext

Met het volgende voorbeeld van initialisatie leest u gegevens uit en wordt deze HttpContext aan een exemplaar van de RequestTelemetry initialisatie-app toe te appen. De IHttpContextAccessor wordt automatisch geleverd via constructorafhankelijkheidsinjectie.

public class HttpContextRequestTelemetryInitializer : ITelemetryInitializer
{
    private readonly IHttpContextAccessor httpContextAccessor;

    public HttpContextRequestTelemetryInitializer(IHttpContextAccessor httpContextAccessor)
    {
        this.httpContextAccessor =
            httpContextAccessor ??
            throw new ArgumentNullException(nameof(httpContextAccessor));
    }

    public void Initialize(ITelemetry telemetry)
    {
        var requestTelemetry = telemetry as RequestTelemetry;
        if (requestTelemetry == null) return;

        var claims = this.httpContextAccessor.HttpContext.User.Claims;
        Claim oidClaim = claims.FirstOrDefault(claim => claim.Type == "oid");
        requestTelemetry.Properties.Add("UserOid", oidClaim?.Value);
    }
}

ITelemetryProcessor en ITelemetryInitializer

Wat is het verschil tussen telemetrieprocessors en initialisaties voor telemetrie?

  • Er zijn enkele overlappingen in wat u er mee kunt doen. Beide kunnen worden gebruikt om eigenschappen van telemetrie toe te voegen of te wijzigen, hoewel het raadzaam is om initialisaties voor dat doel te gebruiken.
  • Initialisaties van telemetrie worden altijd uitgevoerd vóór telemetrieprocessors.
  • Initialisaties van telemetrie kunnen meer dan één keer worden aangeroepen. Volgens de conventies wordt er geen eigenschap ingesteld die al is ingesteld.
  • Met telemetrieprocessors kunt u een telemetrie-item volledig vervangen of verwijderen.
  • Alle geregistreerde telemetrie-initialisaties worden gegarandeerd aangeroepen voor elk telemetrie-item. Voor telemetrieprocessors garandeert SDK dat de eerste telemetrieprocessor wordt aanroepen. Of de rest van de processors worden aangeroepen of niet, wordt bepaald door de voorgaande telemetrieprocessors.
  • Gebruik initialisaties voor telemetrie om telemetrie te verrijken met aanvullende eigenschappen of om een bestaande te overschrijven. Gebruik een telemetrieprocessor om telemetrie uit te filteren.

Problemen met ApplicationInsights.config

  • Controleer of de volledig gekwalificeerde typenaam en assemblynaam juist zijn.
  • Controleer of het applicationinsights.config zich in uw uitvoermap en recente wijzigingen bevat.

Naslagdocumentatie

SDK-code

Volgende stappen