Filtrování a předběžné zpracování telemetrických dat v sadě Application Insights SDK

Moduly plug-in pro sadu Application Přehledy SDK můžete napsat a nakonfigurovat tak, aby bylo možné přizpůsobit, jak lze telemetrii rozšířit a zpracovat před odesláním do služby Application Přehledy.

• Vzorkování snižuje objem telemetrie, aniž by to ovlivnilo vaše statistiky. Udržuje pohromadě související datové body, abyste mezi nimi mohli procházet při diagnostice problému. Na portálu se celkový počet vynásobí, aby se vykompenzoval vzorkování.
• Filtrování pomocí procesorů telemetrie umožňuje odfiltrovat telemetrii v sadě SDK před odesláním na server. Můžete například snížit objem telemetrie vyloučením požadavků z robotů. Filtrování je základní přístup ke snížení provozu než vzorkování. Umožňuje větší kontrolu nad tím, co se přenáší, ale ovlivňuje vaše statistiky. Můžete například odfiltrovat všechny úspěšné požadavky.
• Inicializátory telemetrie přidávají nebo upravujte vlastnosti jakékoli telemetrie odesílané z vaší aplikace, což zahrnuje telemetrii ze standardních modulů. Můžete například přidat počítané hodnoty nebo čísla verzí, podle kterých se mají data na portálu filtrovat.
• Rozhraní SDK API se používá k odesílání vlastních událostí a metrik.

Než začnete, potřebujete:

• Nainstalujte příslušnou sadu SDK pro vaši aplikaci: ASP.NET, ASP.NET Core, Non HTTP/Worker pro .NET/.NET Corenebo JavaScript.

Filtrování

Tato technika vám poskytuje přímou kontrolu nad tím, co je zahrnuto nebo vyloučeno z datového proudu telemetrie. Filtrování lze použít k vynětí telemetrických položek z odeslání do služby Application Přehledy. Filtrování můžete použít ve spojení se vzorkováním nebo samostatně.

Pokud chcete filtrovat telemetrii, napíšete procesor telemetrie a zaregistrujete ho v TelemetryConfiguration . Veškerá telemetrie prochází procesorem. Můžete se rozhodnout ho z datového proudu vypustit nebo ho dát dalšímu procesoru v řetězci. Součástí je telemetrie ze standardních modulů, jako je kolektor požadavků HTTP a kolektor závislostí, a telemetrie, kterou jste sami sledovali. Můžete například odfiltrovat telemetrii žádostí od robotů nebo úspěšná volání závislostí.

Vytvoření procesoru telemetrie (C#)

1. Pokud chcete vytvořit filtr, implementujte ITelemetryProcessor .

   Procesory telemetrie sestaví řetěz zpracování. Když vytváříte instanci procesoru telemetrie, budete mít odkaz na další procesor v řetězci. Když se datový bod telemetrie předá metodě procesu, udělá svou práci a pak zavolá (nebo nevolá) další procesor telemetrie v řetězci.

   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. Přidejte procesor.

ASP.NET aplikací

Do souboru vložte ApplicationInsights.config:

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

Řetězcové hodnoty můžete předat z .config souboru tak, že ve své třídě zadáte veřejné pojmenované vlastnosti.

Případně můžete filtr inicializovat v kódu. Do vhodné inicializační třídy, například AppStart v Global.asax.cs souboru , vložte procesor do řetězce:

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

Klienti telemetrie, kteří se vytvořili po tomto bodu, budou používat vaše procesory.

ASP.NET aplikací služby Core nebo Worker

U aplikací napsaných pomocí ASP.NET Core nebo WorkerServicese přidání nového procesoru telemetrie provádí pomocí metody rozšíření v , jak AddApplicationInsightsTelemetryProcessor je IServiceCollection znázorněno na obrázku. Tato metoda je volána ConfigureServices v metodě vaší Startup.cs třídy.

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

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

Příklady filtrů

Syntetické požadavky

Odfiltrujte roboty a webové testy. Přestože Průzkumník metrik umožňuje odfiltrovat syntetické zdroje, tato možnost snižuje provoz a velikost příjmu dat tím, že je filtruje v samotné sadě SDK.

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

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

Neúspěšné ověřování

Odfiltrujte požadavky s odpovědí 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);
}

Odfiltrování rychlých vzdálených volání závislostí

Pokud chcete diagnostikovat pouze pomalá volání, odfiltrujte rychlá volání.

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

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

Diagnostika problémů se závislostmi

Tento blog popisuje projekt pro diagnostiku problémů se závislostmi automatickým odesíláním běžných příkazu ping do závislostí.

Webové aplikace v JavaScriptu

Filtrování pomocí iniciallizéru ITelemetryInitializer

1. Vytvořte funkci zpětného volání inicializátoru telemetrie. Funkce zpětného volání ITelemetryItem přebírá jako parametr, což je událost, která se zpracovává. Výsledkem vrácení false z tohoto zpětného volání je vyfiltrovaná položka telemetrie.

   var filteringFunction = (envelope) => {
     if (envelope.data.someField === 'tobefilteredout') {
         return false;
     }
   
     return true;
   };
   

2. Přidejte zpětné volání inicializátoru telemetrie:

   appInsights.addTelemetryInitializer(filteringFunction);
   

Přidání nebo úprava vlastností: ITelemetryInitializer

Pomocí inicializátorů telemetrie můžete rozšířit telemetrii o další informace nebo přepsat vlastnosti telemetrie nastavené standardními moduly telemetrie.

Například funkce Application Přehledy pro webový balíček shromažďuje telemetrii o požadavcích HTTP. Ve výchozím nastavení označí jako neúspěšný jakýkoli požadavek s kódem odpovědi >=400. Pokud ale chcete s 400 zacházet jako s úspěchem, můžete zadat inicializátor telemetrie, který nastaví vlastnost success.

Pokud poskytnete inicializátor telemetrie, volá se vždy, když se volá kterákoli z metod Track*(). To zahrnuje Track() metody vytyčované standardními moduly telemetrie. Podle konvence tyto moduly nestaví žádnou vlastnost, která už byla nastavena inicializátorem. Inicializátory telemetrie se volají před voláním procesorů telemetrie. Proto jsou pro procesory viditelná jakákoli rozšíření prováděná inicializátory.

Definování inicializátoru

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 aplikací: Načtení inicializátoru

V ApplicationInsights.config:

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

Případně můžete inicializátor vytvořit v kódu, například v souboru Global.aspx.cs:

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

Další informace o této ukázce najdete tady:.

ASP.NET služby Core/Worker: Načtení inicializátoru

U aplikací napsaných pomocí ASP.NET Core nebo WorkerServicese přidání nového inicializátoru telemetrie provádí přidáním do kontejneru injektáže závislostí, jak je znázorněno níže. To se provádí v Startup.ConfigureServices metodě .

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

Inicializátory telemetrie JavaScriptu

JavaScript

Vložte inicializátor telemetrie pomocí fragmentu zpětného volání onInit:

<script type="text/javascript">
!function(T,l,y){<!-- Removed the Snippet code for brevity -->}(window,document,{
src: "https://js.monitor.azure.com/scripts/b/ai.2.min.js",
crossOrigin: "anonymous",
onInit: function (sdk) {
  sdk.addTelemetryInitializer(function (envelope) {
    envelope.data.someField = 'This item passed through my telemetry initializer';
  });
}, // Once the application insights instance has loaded and initialized this method will be called
cfg: { // Application Insights Configuration
    instrumentationKey: "YOUR_INSTRUMENTATION_KEY"
}});
</script>

Souhrn vlastností, které nejsou v položce telemetrie k dispozici, najdete v tématu Application Přehledy Export Data Model.

Můžete přidat tolik inicializátorů, kolik chcete. Jsou volány v pořadí, v pořadí, ve které jsou přidány.

Procesory telemetrie Pythonu OpenCensus

Procesory telemetrie v OpenCensus Pythonu jsou jednoduše funkce zpětného volání volané pro zpracování telemetrie před jejich exportem. Funkce zpětného volání musí jako parametr přijmout datový typ obálky. Pokud chcete odfiltrovat export telemetrie, ujistěte se, že funkce zpětného volání vrací False . Schéma pro datové typy Azure Monitor vidíte v obálce na GitHub.

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

Můžete přidat tolik procesorů, kolik chcete. Jsou volány v pořadí, v pořadí, ve které jsou přidány. Pokud jeden procesor vyvolá výjimku, nemá vliv na následující procesory.

Příklady telemetrických inicializovaných zařízení

Přidání vlastní vlastnosti

Následující ukázkový inicializátor přidá do každé sledované telemetrie vlastní vlastnost.

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

Přidat název cloudové role

Následující ukázkový inicializátor nastaví název cloudové role na každou sledovanou telemetrii.

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

Přidat informace z HttpContext

Následující ukázkový inicializátor načte data z HttpContext a připojí je k RequestTelemetry instanci. IHttpContextAccessorJe automaticky zajištěn vložením závislosti konstruktoru.

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

Jaký je rozdíl mezi procesory telemetrie a Inicializátory telemetrie?

• Existuje několik překrývajících se v tom, co můžete s nimi dělat. Obojí lze použít k přidání nebo úpravě vlastností telemetrie, i když doporučujeme pro tento účel použít inicializátory.
• Inicializátory telemetrie se vždycky spouštějí před procesory telemetrie.
• Inicializátory telemetrie mohou být volány více než jednou. Podle konvence nenastaví žádnou vlastnost, která již byla nastavena.
• Procesory telemetrie umožňují zcela nahradit nebo zrušit položku telemetrie.
• Všechny registrované Inicializátory telemetrie jsou zaručené pro každou položku telemetrie. Pro procesory telemetrie sada SDK garantuje volání prvního procesoru telemetrie. Určuje, zda jsou ostatní procesory volány nebo nikoli, o základě předchozích procesorů telemetrie.
• Použijte Inicializátory telemetrie k obohacení telemetrie o další vlastnosti nebo přepište existující. K odfiltrování telemetrie použijte procesor telemetrie.

Řešení potíží s ApplicationInsights.config

• Potvrďte, že plně kvalifikovaný název typu a název sestavení jsou správné.
• Potvrďte, že je soubor applicationinsights.config ve výstupním adresáři a obsahuje nedávné změny.

Referenční dokumenty

• Přehled rozhraní API
• odkaz na ASP.NET

Kód sady SDK

• Sada ASP.NET Core SDK
• ASP.NET SADĚ
• JavaScript SDK

Další kroky

• Hledat události a protokoly
• kontrol
• Řešení potíží