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ůžou přizpůsobit způsob rozšiřování a zpracování telemetrie před odesláním do služby Přehledy aplikace.

• Vzorkování snižuje objem telemetrie, aniž by to ovlivnilo vaše statistiky. Udržuje spolu související datové body, abyste mezi nimi mohli přecházet při diagnostice problému. Na portálu se celkový počet vynásobí, aby se vyrovnal vzorkování.
• Filtrování pomocí procesorů telemetrie umožňuje vyfiltrovat 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ám větší kontrolu nad tím, co se přenáší, ale ovlivňuje vaše statistiky. Můžete například vyfiltrovat všechny úspěšné požadavky.
• Inicializátory telemetrie přidávají nebo upravují vlastnosti do všech telemetrických dat odesílaných z vaší aplikace, která zahrnuje telemetrii ze standardních modulů. Můžete například přidat počítané hodnoty nebo čísla verzí, podle kterých chcete filtrovat data na portálu.
• Rozhraní API sady SDK slouží 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, ne HTTP/Worker pro .NET/.NET Core nebo JavaScript.

Filtrování

Tato technika poskytuje přímou kontrolu nad tím, co je součástí nebo vyloučeno ze streamu telemetrie. Filtrování je možné použít k vyřazení položek telemetrie odesílaných do Přehledy aplikace. Filtrování můžete použít se vzorkováním nebo samostatně.

K filtrování telemetrie zapíšete procesor telemetrie a zaregistrujete ho .TelemetryConfiguration Veškerá telemetrie prochází vaším procesorem. Můžete se rozhodnout, že ho z datového proudu vyhodíte nebo ho dáte dalšímu procesoru v řetězu. Telemetrie ze standardních modulů, jako je kolektor požadavků HTTP a kolektor závislostí, a telemetrie, kterou jste sledovali sami, je zahrnutá. Můžete například vyfiltrovat telemetrii o požadavcích z robotů nebo úspěšných volání závislostí.

Upozornění

Filtrování telemetrie odeslané ze sady SDK pomocí procesorů může zkosit statistiky, které vidíte na portálu, a ztěžovat sledování souvisejících položek.

Místo toho zvažte použití vzorkování.

Vytvoření procesoru telemetrie

C#

1. Chcete-li vytvořit filtr, implementujte ITelemetryProcessor.

   Procesory telemetrie vytváří řetěz zpracování. Když vytvoříte instanci procesoru telemetrie, dostanete odkaz na další procesor v řetězu. Když se datovému bodu telemetrie předá metoda procesu, funguje to a pak volá (nebo nevolá) další procesor telemetrie v řetězu.

   using Microsoft.ApplicationInsights.Channel;
   using Microsoft.ApplicationInsights.Extensibility;
   using Microsoft.ApplicationInsights.DataContracts;
   
   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í

Vložte tento fragment kódu do ApplicationInsights.config:

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

Řetězcové hodnoty můžete předat ze souboru .config zadáním veřejných pojmenovaných vlastností ve třídě.

Upozornění

Dbejte na to, aby odpovídal názvu typu a všem názvům vlastností v souboru .config s názvy tříd a vlastností v kódu. Pokud soubor .config odkazuje na neexistující typ nebo vlastnost, sada SDK může bezobslužně selhat odeslat telemetrii.

Alternativně můžete inicializovat filtr v kódu. V vhodné inicializační třídě, například AppStart in Global.asax.cs, vložte procesor do řetězu:

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 vytvořená po tomto bodu budou používat vaše procesory.

ASP.NET aplikace služby Core/Worker

Poznámka

Přidání procesoru pomocí ApplicationInsights.config nebo TelemetryConfiguration.Active není platné pro ASP.NET Core aplikace nebo pokud používáte sadu Microsoft.ApplicationInsights.WorkerService SDK.

Pro aplikace napsané pomocí ASP.NET Core nebo WorkerService se přidání nového procesoru telemetrie provádí pomocí AddApplicationInsightsTelemetryProcessor metody rozšíření, IServiceCollectionjak je znázorněno. Tato metoda se volá v ConfigureServices metodě vaší Startup.cs třídy.

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

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

Pokud chcete zaregistrovat procesory telemetrie, které potřebují parametry v ASP.NET Core, vytvořte vlastní třídu implementující ITelemetryProcessorFactory. Zavolejte konstruktor s požadovanými parametry v metodě Create a pak použijte AddSingleton<ITelemetryProcessorFactory, MyTelemetryProcessorFactory>().

Ukázkové filtry

Syntetické požadavky

Vyfiltrujte roboty a webové testy. I když Průzkumník metrik nabízí možnost odfiltrovat syntetické zdroje, tato možnost snižuje provoz a velikost příjmu dat filtrováním 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í

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

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

Pokud chcete diagnostikovat jenom volání, která jsou pomalá, vyfiltrujte rychlé volání.

Poznámka

Toto filtrování zkosí statistiky, které vidíte na portálu.

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ů s závislostmi

Tento blog popisuje projekt pro diagnostiku problémů závislostí tím, že automaticky odesílá pravidelné příkazy ping do závislostí.

Java

Další informace o procesorech telemetrie a jejich implementaci v Javě najdete v dokumentaci k procesorům telemetrie v Javě.

Webové aplikace JavaScriptu

Filtrování pomocí ITelemetryInitializer

1. Vytvořte funkci zpětného volání inicializátoru telemetrie. Funkce zpětného volání přebírá ITelemetryItem jako parametr, což je událost, která se zpracovává. Vrácení z tohoto zpětného false volání vede k vyfiltrování položky 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

Inicializátory telemetrie můžete použít k obohacení telemetrie o další informace nebo k přepsání vlastností telemetrie nastavených standardními moduly telemetrie.

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

Pokud zadáte inicializátor telemetrie, volá se pokaždé, když se volá jakákoli metoda Track*(). Tento inicializátor zahrnuje Track() metody volané standardními moduly telemetrie. Podle konvence tyto moduly nenastavují žádnou vlastnost, která již byla nastavena inicializátorem. Inicializátory telemetrie se volají před voláním procesorů telemetrie. Všechny rozšiřování provedené inicializátory jsou tedy viditelné pro procesory.

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 instanci v kódu, například v Global.aspx.cs:

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

Podívejte se na další část této ukázky.

ASP.NET aplikace služby Core/Worker: Načtěte inicializátor

Poznámka

Přidání inicializátoru pomocí ApplicationInsights.config nebo TelemetryConfiguration.Active není platné pro ASP.NET Core aplikace nebo pokud používáte sadu Microsoft.ApplicationInsights.WorkerService SDK.

Pro aplikace napsané pomocí ASP.NET Core nebo WorkerService je přidání nového inicializátoru telemetrie provedeno přidáním do kontejneru injektáže závislostí, jak je znázorněno. Tento krok proveďte 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í 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 k dispozici u položky telemetrie, najdete v tématu Aplikace Přehledy Export datového modelu.

Můžete přidat tolik inicializátorů, kolik chcete. Volají se v pořadí, ve kterém se přidávají.

Procesory telemetrie OpenCensus Pythonu

Procesory telemetrie v OpenCensus Pythonu jsou jednoduše funkce zpětného volání volané ke zpracování telemetrie před jejich exportem. Funkce zpětného volání musí jako parametr přijmout datový typ obálky . Pokud chcete vyfiltrovat telemetrii z exportu, ujistěte se, že funkce zpětného volání vrátí False. Schéma datových typů služby Azure Monitor můžete zobrazit v obálek na GitHub.

Poznámka

Úpravou atributu ai.cloud.roletags v poli můžete změnitcloud_RoleName.

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 libovolný počet procesorů. Volají se v pořadí, ve kterém se přidávají. Pokud jeden procesor vyvolá výjimku, nemá vliv na následující procesory.

Příklady telemetrickýchinitializátorů

Přidání vlastní vlastnosti

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

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

Přidání názvu cloudové role

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

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

ITelemetryProcessor a ITelemetryInitializer

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

• Existuje několik překrývajících se toho, co s nimi můžete dělat. Obojí lze použít k přidání nebo úpravě vlastností telemetrie, i když doporučujeme používat inicializátory pro tento účel.
• Inicializátory telemetrie se vždy spouští před procesory telemetrie.
• Inicializátory telemetrie se můžou volat vícekrát. Podle konvence nenastavují žádnou vlastnost, která už byla nastavena.
• Procesory telemetrie umožňují úplně nahradit nebo zahodit položku telemetrie.
• Všechny registrované inicializátory telemetrie se volají pro každou položku telemetrie. V případě procesorů telemetrie sada SDK zaručuje volání prvního procesoru telemetrie. Jestli se zbývající procesory volají nebo ne, rozhoduje předchozí procesory telemetrie.
• Inicializátory telemetrie můžete použít k obohacení telemetrie o více vlastností nebo přepsání existujícího. Pomocí procesoru telemetrie vyfiltrujte telemetrii.

Poznámka

JavaScript obsahuje pouze inicializátory telemetrie, které můžou filtrovat události pomocí ITelemetryInitializer.

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

• Ověřte správnost plně kvalifikovaného názvu typu a názvu sestavení.
• Ověřte, že soubor applicationinsights.config je ve výstupním adresáři a obsahuje všechny nedávné změny.

Referenční dokumenty

• Přehled rozhraní API
• referenční dokumentace k ASP.NET

Kód sady SDK

• Sada ASP.NET Core SDK
• sada ASP.NET SDK
• JavaScript SDK

Další kroky

• Vyhledávání událostí a protokolů
• Odběru vzorků
• Řešení potíží