Telemetria szűrése és előfeldolgozása az Application Insights SDK-ban

Írhat és konfigurálhat beépülő modulokat az Application Elemzések SDK-hoz, hogy testre szabja a telemetria gazdagításának és feldolgozásának folyamatát, mielőtt elküldenék az Application Elemzések szolgáltatásnak.

  • A mintavételezés a statisztikák befolyásolása nélkül csökkenti a telemetria mennyiségét. Ez együtt tartja a kapcsolódó adatpontokat, így a problémák diagnosztizálásakor navigálhat közöttük. A portálon a rendszer megszorozza a teljes darabszámokat a mintavételezés kompenzálására.
  • A telemetriai processzorokkal való szűrés lehetővé teszi a telemetria kiszűrését az SDK-ban, mielőtt a rendszer elküldi őket a kiszolgálónak. Például csökkentheti a telemetria mennyiségét, ha kihagyja a robotoktól származó kéréseket. A szűrés egy alapszintű módszer a forgalom csökkentésére, mint a mintavételezésre. Így jobban szabályozhatja az átvitelt, de hatással van a statisztikáira. Például kiszűrheti az összes sikeres kérést.
  • A telemetria-inicializálók tulajdonságokat ad hozzá vagy módosítnak az alkalmazásból küldött összes telemetriában, beleértve a standard modulokból származó telemetriát is. Hozzáadhat például számított értékeket vagy verziószámokat a portálon az adatok szűréséhez.
  • Az SDK API-val egyéni események és metrikák küldhetőek.

Előkészületek:

Szűrés

Ezzel a technikával közvetlenül szabályozhatja, hogy mit tartalmaz vagy mit zár ki a telemetriastreamből. A szűrés segítségével eldobhatja a telemetriai elemeket az Application Elemzések. A szűrést mintavételezéssel vagy külön-külön is használhatja.

A telemetria szűréséhez telemetriafeldolgozót kell írnia, és regisztrálnia kell a TelemetryConfiguration segítségével. Minden telemetria a processzoron halad át. Dönthet úgy, hogy kiveszi a streamből, vagy átadhatja a lánc következő processzorának. Tartalmazza a standard modulok, például a HTTP-kérésgyűjtő és a függőséggyűjtő telemetriai adatokat, valamint a saját maga által nyomon követhető telemetriát. Kiszűrheti például a robotoktól vagy a sikeres függőségi hívásoktól származó kérésekkel kapcsolatos telemetriai adatokat.

Figyelmeztetés

Az SDK-ból küldött telemetria processzorokkal való szűrése eltűrheti a portálon látható statisztikákat, és megnehezítheti a kapcsolódó elemek nyomon követését.

Ehelyett érdemes megfontolni a mintavételezést.

Telemetriafeldolgozó létrehozása (C#)

  1. Szűrő létrehozásához implementálja a ITelemetryProcessor et.

    A telemetriai processzorok feldolgozási láncot építnek ki. Amikor példányosul egy telemetriafeldolgozót, kap egy hivatkozást, amely a láncban következő processzorra hivatkozik. Amikor a rendszer továbbít egy telemetriai adatpontot a folyamat metódusának, el is teszi a munkáját, majd a lánc következő telemetriafeldolgozóját hívja meg (vagy nem hívja meg).

    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. Adja hozzá a processzort.

ASP.NET alkalmazások

Szúrja be ezt a kódrészletet a ApplicationInsights.config:

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

A fájlból sztringértékeket ad .config, ha nyilvános elnevezett tulajdonságokat ad meg az osztályban.

Figyelmeztetés

A fájlban szereplő típusnévnek és .config meg kell egyeznie a kód osztály- és tulajdonságnevekkel. Ha a .config nem létező típusra vagy tulajdonságra hivatkozik, előfordulhat, hogy az SDK csendesen nem küld telemetriai adatokat.

Másik lehetőségként inicializálhatja a szűrőt a kódban. Egy megfelelő inicializálási osztályban, például az AppStartban, Global.asax.cs szúrja be a processzort a láncba:

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

Az ezt követően létrehozott telemetriai ügyfelek a processzorokat fogják használni.

ASP.NET/feldolgozói szolgáltatásalkalmazások használata

Megjegyzés

Processzor hozzáadása a vagy a használatával nem érvényes ASP.NET Core alkalmazásokhoz, vagy ha a ApplicationInsights.config TelemetryConfiguration.Active Microsoft.ApplicationInsights.WorkerService SDK-t használja.

Az ASP.NET Core vagy WorkerServicehasználatával írt alkalmazások esetében az új telemetriafeldolgozó hozzáadása a bővítmény metódusával történik az AddApplicationInsightsTelemetryProcessor ábrán látható IServiceCollection módon. Ezt a metódust az ConfigureServices osztály metódusában Startup.cs hívjuk meg.

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

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

Példaszűrők

Szintetikus kérések

Robotokat és webes teszteket kiszűrhet. Bár Metrikaböngésző lehetővé teszi a szintetikus források kiszűrése, ez a beállítás az SDK-ra szűrve csökkenti a forgalmat és a begesedés méretét.

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

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

Sikertelen hitelesítés

A 401-es válaszokkal kiszűrheti a kéréseket.

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

Gyors távoli függőségi hívások kiszűrés

Ha csak a lassú hívásokat szeretné diagnosztizálni, szűrje ki a gyors hívásokat.

Megjegyzés

Ez a szűrés eltűri a portálon látható statisztikákat.

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

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

Függőségi problémák diagnosztizálása

Ez a blog egy olyan projektet ismertet, amely a függőségi problémák diagnosztizálásához küld rendszeres pingeket a függőségek számára.

JavaScript-webalkalmazások

Szűrés az ITelemetryInitializer használatával

  1. Hozzon létre egy telemetriainicializáló visszahívási függvényt. A visszahívási függvény ITelemetryItem paraméterként veszi fel a függvényt, amely a feldolgozás alatt áll. A false visszahívásból való visszatérés a telemetriaelem kiszűrését adja vissza.

    var filteringFunction = (envelope) => {
      if (envelope.data.someField === 'tobefilteredout') {
          return false;
      }
    
      return true;
    };
    
  2. Adja hozzá a telemetriainicializáló visszahívási műveletét:

    appInsights.addTelemetryInitializer(filteringFunction);
    

Tulajdonságok hozzáadása/módosítása: ITelemetryInitializer

Telemetria-inicializálók használatával további információkkal gazdagíthatja a telemetriát, vagy felülbírálhatja a szabványos telemetriai modulok által beállított telemetriatulajdonságokat.

Például az Application Elemzések webcsomaghoz telemetriai adatokat gyűjt a HTTP-kérésekkel kapcsolatban. Alapértelmezés szerint sikertelennek jelöl minden olyan kérést, amely válaszkódja =400>van. Ha azonban a 400-as elemet sikerként szeretné kezelni, meg tud adni egy telemetria-inicializálót, amely beállítja a sikeresség tulajdonságot.

Ha telemetria-inicializálót ad meg, a rendszer minden alkalommal meg lesz hívva, amikor a Track*() metódusok bármelyike meg van hívva. Ide tartoznak Track() a szabványos telemetriai modulok által hívott metódusok is. Ezek a modulok konvenció szerint nem állítják be az inicializáló által már beállított tulajdonságot. A telemetria-inicializálókat a rendszer a telemetriafeldolgozók hívása előtt hívja meg. Így az inicializálók által végzett gazdagítások láthatók a processzorok számára.

Az inicializáló meghatározása

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 alkalmazások: Az inicializáló betöltése

A ApplicationInsights.config:

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

Alternatív megoldásként példányos is lehet az inicializáló a kódban, például a Global.aspx.cs fájlban:

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

További információ a mintából:.

ASP.NET Core/Worker service apps: Az inicializáló betöltése

Megjegyzés

Inicializáló hozzáadása a vagy a használatával nem érvényes ASP.NET Core alkalmazásokhoz, vagy ha a ApplicationInsights.config TelemetryConfiguration.Active Microsoft.ApplicationInsights.WorkerService SDK-t használja.

Az ASP.NET Core vagy WorkerServicehasználatával írt alkalmazások esetében az új telemetria-inicializáló hozzáadásához adja hozzá a függőséginjektáló tárolóhoz, ahogy az ábrán látható. Ez a metódusban Startup.ConfigureServices történik.

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

JavaScript telemetria-inicializálók

JavaScript

Szúrjon be egy telemetria-inicializálót közvetlenül a portálról kapott inicializálási kód után:

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

A telemetriaelemhez elérhető nem egyéni tulajdonságok összegzését lásd: Application Elemzések Export Data Model (Alkalmazás-exportálási adatmodell).

Annyi inicializálót adhat hozzá, amennyit csak szeretne. A hozzáadás sorrendjében lesz megadva.

OpenCensus Python telemetriai processzorok

Az OpenCensus Python telemetriai processzorai egyszerűen visszahívási függvények, amelyek az exportálás előtt feldolgoznak telemetriai adatokat. A visszahívási függvénynek egy boríték adattípust kell elfogadnia paraméterként. Ha ki akarja szűrni a telemetriát az exportálásból, győződjön meg arról, hogy a visszahívási függvény a értéket adja False vissza. A borítékok között a borítékok között Azure Monitor adatforrások sémája GitHub.

Megjegyzés

A cloud_RoleName mezőben az attribútum ai.cloud.role módosításával tags módosítható.

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

Annyi processzort adhat hozzá, amennyit csak szeretne. A hozzáadás sorrendjében lesz megadva. Ha egy processzor kivételt ad vissza, az nem befolyásolja a következő processzorokat.

Telemetriainitializálók – példa

Egyéni tulajdonság hozzáadása

A következő minta inicializáló egy egyéni tulajdonságot ad hozzá minden nyomonott telemetriához.

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

Felhőbeli szerepkör nevének hozzáadása

A következő minta inicializáló a felhőbeli szerepkör nevét minden nyomon követett telemetriára beállítja.

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

Információk hozzáadása a HttpContextből

A következő minta inicializáló beolvassa az adatokat a-ból, HttpContext és hozzáfűzi egy RequestTelemetry példányhoz. A IHttpContextAccessor automatikusan a konstruktor függőséginjektálásán keresztül lesz megszórva.

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 és ITelemetryInitializer

Mi a különbség a telemetriai processzorok és a telemetriainicializálók között?

  • Van néhány átfedés abban, hogy mit lehet velük tenni. Mindkettő használható a telemetria tulajdonságainak hozzáadására vagy módosítására, bár javasoljuk, hogy erre a célra inicializálókat használjon.
  • A telemetriainicializálók mindig a telemetriai processzorok előtt futnak.
  • A telemetriainicializálókat egynél több alkalommal is meg lehet hívni. Konvenció szerint nem állítják be a már beállított tulajdonságot.
  • A telemetriafeldolgozók lehetővé teszik egy telemetriaelem teljes cseréjét vagy elvetését.
  • Minden regisztrált telemetria-inicializáló garantáltan minden telemetriaelemhez meg lesz hívva. A telemetriafeldolgozók esetében az SDK garantálja az első telemetriafeldolgozó hívását. Azt, hogy a többi processzort meg kell-e hívni vagy sem, a fenti telemetriai processzorok ják el.
  • Telemetria-inicializálók használatával további tulajdonságokkal gazdagíthatja a telemetriát, vagy felülbírálhatja a meglévőket. Telemetriafeldolgozó használata a telemetria kiszűréséhez.

Hibaelhárítási ApplicationInsights.config

  • Győződjön meg arról, hogy a teljes típusnév és a szerelvénynév helyes.
  • Ellenőrizze, hogy applicationinsights.config fájl a kimeneti könyvtárban található-e, és tartalmazza-e a legutóbbi módosításokat.

Referencia-dokumentumok

SDK-kód

Következő lépések