Filtrera och förbearbeta telemetri i Application Insights SDK

Du kan skriva och konfigurera plugin-program för Application Insights SDK för att anpassa hur telemetri kan berikas och bearbetas innan den skickas till Application Insights-tjänsten.

  • Sampling minskar mängden telemetri utan att påverka din statistik. Den håller ihop relaterade datapunkter så att du kan navigera mellan dem när du diagnostiserar ett problem. I portalen multipliceras det totala antalet för att kompensera för samplingen.
  • Genom att filtrera med telemetriprocessorer kan du filtrera bort telemetri i SDK:n innan den skickas till servern. Du kan till exempel minska mängden telemetri genom att exkludera begäranden från robotar. Filtrering är en mer grundläggande metod för att minska trafiken än sampling. Det ger dig större kontroll över vad som överförs, men det påverkar din statistik. Du kan till exempel filtrera bort alla lyckade begäranden.
  • Telemetriinitierare lägger till eller ändrar egenskaper för all telemetri som skickas från din app, vilket inkluderar telemetri från standardmodulerna. Du kan till exempel lägga till beräknade värden eller versionsnummer för att filtrera data i portalen.
  • SDK-API:et används för att skicka anpassade händelser och mått.

Innan du börjar:

Filtrering

Den här tekniken ger dig direkt kontroll över vad som ingår eller exkluderas från telemetriströmmen. Filtrering kan användas för att ta bort telemetriobjekt från att skickas till Program Insights. Du kan använda filtrering tillsammans med sampling eller separat.

Om du vill filtrera telemetri skriver du en telemetriprocessor och registrerar den med TelemetryConfiguration . All telemetri går igenom processorn. Du kan välja att släppa den från dataströmmen eller ge den till nästa processor i kedjan. Telemetri från standardmodulerna, till exempel HTTP-begärandeinsamlaren och beroendeinsamlaren, och telemetri som du spårade själv ingår. Du kan till exempel filtrera bort telemetri om begäranden från robotar eller lyckade beroendeanrop.

Varning

Om du filtrerar telemetri som skickas från SDK:n med hjälp av processorer kan du förvränga statistiken som visas i portalen och göra det svårt att följa relaterade objekt.

Överväg i stället att använda sampling.

Skapa en telemetriprocessor (C#)

  1. Om du vill skapa ett filter implementerar du ITelemetryProcessor .

    Telemetriprocessorer skapar en bearbetningskedja. När du instansierar en telemetriprocessor får du en referens till nästa processor i kedjan. När en telemetridatapunkt skickas till processmetoden gör den sitt arbete och anropar (eller anropar inte) nästa telemetriprocessor i kedjan.

    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. Lägg till din processor.

ASP.NET appar

Infoga det här kodfragmentet i ApplicationInsights.config:

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

Du kan skicka strängvärden från .config genom att ange offentliga namngivna egenskaper i klassen.

Varning

Se till att matcha typnamnet och eventuella egenskapsnamn i .config med klass- och egenskapsnamnen i koden. Om .config refererar till en icke-existerande typ eller egenskap kan SDK:n misslyckas med att skicka telemetri.

Du kan också initiera filtret i koden. I en lämplig initieringsklass, till exempel AppStart i Global.asax.cs , infogar du processorn i kedjan:

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

Telemetriklienter som skapas efter den här punkten använder dina processorer.

ASP.NET Core/Worker-tjänstappar

Anteckning

Att lägga till en processor med hjälp av eller är inte giltigt ASP.NET Core program eller om du använder ApplicationInsights.config TelemetryConfiguration.Active Microsoft.ApplicationInsights.WorkerService SDK.

För appar som skrivits med ASP.NET Core eller WorkerServicegörs tillägg av en ny telemetriprocessor med hjälp av AddApplicationInsightsTelemetryProcessor tilläggsmetoden på , som du ser IServiceCollection i bilden. Den här metoden anropas i ConfigureServices metoden i klassen Startup.cs .

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

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

Exempelfilter

Syntetiska begäranden

Filtrera bort robotar och webbtester. Även Metrics Explorer ger dig möjlighet att filtrera bort syntetiska källor, minskar det här alternativet trafik- och inmatningsstorleken genom att filtrera dem på själva SDK:n.

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

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

Autentiseringen misslyckades

Filtrera bort begäranden med svaret "401".

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

Filtrera bort snabba fjärranslutna beroendeanrop

Om du bara vill diagnostisera anrop som är långsamma filtrerar du bort de snabba.

Anteckning

Den här filtreringen förvränger den statistik som visas i portalen.

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

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

Diagnostisera beroendeproblem

Den här bloggen beskriver ett projekt för att diagnostisera beroendeproblem genom att automatiskt skicka regelbundna pingar till beroenden.

JavaScript-webbprogram

Filtrera med hjälp av ITelemetryInitializer

  1. Skapa en återanropsfunktion för telemetriinitiering. Återanropsfunktionen ITelemetryItem tar som en parameter, vilket är den händelse som bearbetas. När false du returnerar från det här återanropet resulterar det i att telemetriobjektet filtreras bort.

    var filteringFunction = (envelope) => {
      if (envelope.data.someField === 'tobefilteredout') {
          return false;
      }
    
      return true;
    };
    
  2. Lägg till återanropet för telemetriinitiatorn:

    appInsights.addTelemetryInitializer(filteringFunction);
    

Lägg till/ändra egenskaper: ITelemetryInitializer

Använd telemetriinitierare för att utöka telemetri med ytterligare information eller åsidosätta telemetriegenskaper som anges av standardtelemetrimodulerna.

Till exempel samlar Application Insights för ett webbpaket in telemetri om HTTP-begäranden. Som standard flaggar den som misslyckad begäran med en svarskod >=400. Men om du vill behandla 400 som en framgång kan du ange en telemetriinitiering som anger egenskapen success .

Om du anger en telemetriinitierare anropas den när någon av Track*()-metoderna anropas. Detta inkluderar Track() metoder som anropas av standardmodulerna för telemetri. Enligt konventionen anger dessa moduler inte någon egenskap som redan har angetts av en initierare. Telemetriinitierare anropas innan telemetriprocessorer anropas. Därför är alla berikande som görs av initierare synliga för processorer.

Definiera initieraren

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 appar: Läs in initieraren

I ApplicationInsights.config:

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

Du kan också instansiera initieraren i kod, till exempel i Global.aspx.cs:

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

Se mer av det här exemplet.

ASP.NET Core/Worker-tjänstappar: Läs in initieraren

Anteckning

Att lägga till en initierare med hjälp av eller är inte giltigt för ASP.NET Core program eller om du använder ApplicationInsights.config TelemetryConfiguration.Active Microsoft.ApplicationInsights.WorkerService SDK.

För appar som skrivits med ASP.NET Core eller WorkerServicegörs det genom att lägga till en ny telemetriinitiering genom att lägga till den i containern Dependency Injection enligt nedan. Detta görs i Startup.ConfigureServices metoden .

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

JavaScript-telemetriinitierare

JavaScript

Infoga en telemetriinitierare omedelbart efter initieringskoden som du fick från portalen:

<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>

En sammanfattning av de icke-kundanpassade egenskaperna som är tillgängliga för telemetriobjektet finns i Application Insights Export Data Model.

Du kan lägga till så många initierare som du vill. De anropas i den ordning som de läggs till.

OpenCensus Python-telemetriprocessorer

Telemetriprocessorer i OpenCensus Python är helt enkelt återanropsfunktioner som anropas för att bearbeta telemetri innan de exporteras. Motringningsfunktionen måste acceptera en kuvertdatatyp som parameter. Om du vill filtrera bort telemetri från att exporteras kontrollerar du att återanropsfunktionen returnerar False . Du kan se schemat för Azure Monitor datatyper i kuverten på GitHub.

Anteckning

Du kan ändra cloud_RoleName genom att ai.cloud.role ändra attributet i fältet tags .

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

Du kan lägga till så många processorer du vill. De anropas i den ordning som de läggs till. Om en processor kastar ett undantag påverkar det inte följande processorer.

Exempel på telemetriinitialiserare

Lägga till en anpassad egenskap

Följande exempelinitierare lägger till en anpassad egenskap i varje spårad telemetri.

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

Lägga till ett molnrollnamn

Följande exempelinitiering anger namnet på molnrollen till varje spårad telemetri.

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

Lägga till information från HttpContext

Följande exempel-initierare läser data från HttpContext och lägger till dem i en RequestTelemetry instans. tillhandahålls IHttpContextAccessor automatiskt via konstruktorberoende injection.

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 och ITelemetryInitializer

Vad är skillnaden mellan telemetriprocessorer och telemetriinitierare?

  • Det finns vissa överlappningar i vad du kan göra med dem. Båda kan användas för att lägga till eller ändra egenskaper för telemetri, men vi rekommenderar att du använder initierare för detta ändamål.
  • Telemetriinitierare körs alltid före telemetriprocessorer.
  • Telemetriinitierare kan anropas mer än en gång. Enligt konventionen anger de inte någon egenskap som redan har angetts.
  • Med telemetriprocessorer kan du helt ersätta eller ta bort ett telemetriobjekt.
  • Alla registrerade telemetriinitierare anropas garanterat för varje telemetriobjekt. För telemetriprocessorer garanterar SDK att den första telemetriprocessorn anropas. Om resten av processorerna anropas eller inte avgörs av föregående telemetriprocessorer.
  • Använd telemetriinitierare för att utöka telemetrin med ytterligare egenskaper eller åsidosätta en befintlig. Använd en telemetriprocessor för att filtrera bort telemetri.

Felsöka ApplicationInsights.config

  • Bekräfta att det fullständigt kvalificerade typnamnet och sammansättningsnamnet är korrekta.
  • Bekräfta att applicationinsights.config finns i utdatakatalogen och innehåller de senaste ändringarna.

Referensdokument

SDK-kod

Nästa steg