Filtrowanie i wstępne przetwarzanie danych telemetrycznych w zestawie Application Insights SDK

Możesz pisać i konfigurować wtyczki dla zestawu SDK usługi Application Szczegółowe informacje, aby dostosować sposób wzbogacania i przetwarzania danych telemetrycznych przed ich wysłaniem do usługi Application Szczegółowe informacje Service.

  • Próbkowanie zmniejsza ilość danych telemetrycznych bez wpływu na statystyki. Przechowuje ona razem powiązane punkty danych, dzięki czemu można przechodzić między nimi podczas diagnozowania problemu. W portalu łączna liczba jest mnożona w celu kompensowania próbkowania.
  • Filtrowanie za pomocą procesorów telemetrii umożliwia odfiltrowanie danych telemetrycznych w zestawie SDK przed ich wysłaniem do serwera. Można na przykład zmniejszyć ilość danych telemetrycznych, wykluczając żądania z robotów. Filtrowanie jest bardziej podstawowym podejściem do zmniejszania ruchu niż próbkowanie. Pozwala to na większą kontrolę nad tym, co jest przesyłane, ale wpływa na statystyki. Można na przykład odfiltrować wszystkie żądania pomyślne.
  • Inicjatory telemetrii dodają lub modyfikują właściwości wszelkich danych telemetrycznych wysyłanych z aplikacji, w tym telemetrii z modułów standardowych. Można na przykład dodać wartości obliczeniowe lub numery wersji, według których można filtrować dane w portalu.
  • Interfejs API zestawu SDK służy do wysyłania niestandardowych zdarzeń i metryk.

Przed rozpoczęciem:

Filtrowanie

Ta technika zapewnia bezpośrednią kontrolę nad tym, co jest dołączone lub wykluczone ze strumienia telemetrii. Filtrowanie może służyć do upuszczania elementów telemetrii z wysyłanych do usługi Application Szczegółowe informacje. Filtrowania można używać w połączeniu z próbkowaniami lub oddzielnie.

Aby filtrować dane telemetryczne, należy napisać procesor telemetrii i zarejestrować go za pomocą usługi TelemetryConfiguration . Wszystkie dane telemetryczne są przechodzić przez procesor. Możesz usunąć go ze strumienia lub przekazać do następnego procesora w łańcuchu. Uwzględniane są dane telemetryczne z modułów standardowych, takich jak moduł zbierający żądania HTTP i moduł zbierający zależności, oraz dane telemetryczne śledzone samodzielnie. Można na przykład odfiltrować dane telemetryczne dotyczące żądań robotów lub pomyślne wywołania zależności.

Ostrzeżenie

Filtrowanie danych telemetrycznych wysyłanych z zestawu SDK przy użyciu procesorów może nieschemać statystyk, które są dostępne w portalu, i utrudnić obserwowanie powiązanych elementów.

Zamiast tego rozważ użycie próbkowania.

Tworzenie procesora telemetrii (C#)

  1. Aby utworzyć filtr, zaim implementuj . ITelemetryProcessor

    Procesory telemetrii konstruują łańcuch przetwarzania. Podczas wystąpienia procesora telemetrii jest nadane odwołanie do następnego procesora w łańcuchu. Gdy punkt danych telemetrycznych jest przekazywany do metody procesu, działa, a następnie wywołuje (lub nie wywołuje) następny procesor telemetrii w łańcuchu.

    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. Dodaj procesor.

ASP.NET aplikacji

Wstaw ten fragment kodu w ApplicationInsights.config:

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

Wartości ciągu można przekazać z pliku .config, podając publiczne nazwane właściwości w klasie.

Ostrzeżenie

Zadbaj o dopasowanie nazwy typu i wszystkich nazw właściwości w .config do nazw klas i właściwości w kodzie. Jeśli plik .config odwołuje się do nieistniejącego typu lub właściwości, zestaw SDK może dyskretnie nie wysyłać żadnych danych telemetrycznych.

Alternatywnie możesz zainicjować filtr w kodzie. W odpowiedniej klasie inicjowania, na przykład AppStart w Global.asax.cs klasie , wstaw procesor do łańcucha:

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

Klienci telemetrii utworzeni po tym punkcie będą używać procesorów.

ASP.NET Core/worker service apps

Uwaga

Dodawanie procesora przy użyciu lub nie jest prawidłowe dla aplikacji ASP.NET Core lub jeśli używasz zestawu ApplicationInsights.config TelemetryConfiguration.Active SDK Microsoft.ApplicationInsights.WorkerService.

W przypadku aplikacji napisanych przy użyciu ASP.NET Core lub WorkerServicedodawanie nowego procesora telemetrii odbywa się przy użyciu metody rozszerzenia w AddApplicationInsightsTelemetryProcessor metodzie , jak IServiceCollection pokazano. Ta metoda jest wywoływana ConfigureServices w metodzie Startup.cs klasy .

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

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

Przykładowe filtry

Żądania syntetyczne

Odfiltruj boty i testy internetowe. Chociaż Eksplorator metryk umożliwia filtrowanie źródeł syntetycznych, ta opcja zmniejsza ruch i rozmiar pozyskiwania przez filtrowanie ich w samym zestawie SDK.

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

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

Uwierzytelnianie nie powiodło się

Odfiltruj żądania z odpowiedzią "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);
}

Odfiltruj szybkie zdalne wywołania zależności

Jeśli chcesz zdiagnozować tylko wywołania, które są powolne, odfiltruj te szybkie.

Uwaga

Filtrowanie spowoduje niescytowanie statystyk wyświetlonych w portalu.

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

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

Diagnozowanie problemów z zależnościami

W tym blogu opisano projekt diagnozowania problemów z zależnościami przez automatyczne wysyłanie regularnych ping do zależności.

Aplikacje internetowe w języku JavaScript

Filtrowanie przy użyciu ITelemetryInitializer

  1. Utwórz funkcję wywołania zwrotnego inicjatora telemetrii. Funkcja wywołania zwrotnego ITelemetryItem przyjmuje jako parametr, czyli przetwarzane zdarzenie. Zwracanie false z tego wywołania zwrotnego powoduje odfiltrowanie elementu telemetrii.

    var filteringFunction = (envelope) => {
      if (envelope.data.someField === 'tobefilteredout') {
          return false;
      }
    
      return true;
    };
    
  2. Dodaj wywołanie zwrotne inicjatora telemetrii:

    appInsights.addTelemetryInitializer(filteringFunction);
    

Dodawanie/modyfikowanie właściwości: ITelemetryInitializer

Inicjatory telemetrii mogą wzbogacić telemetrię o dodatkowe informacje lub zastąpić właściwości telemetrii ustawione przez standardowe moduły telemetrii.

Na przykład program Application Szczegółowe informacje pakietu internetowego zbiera dane telemetryczne dotyczące żądań HTTP. Domyślnie flaguje jako nieudane dowolne żądanie z kodem odpowiedzi >=400. Jeśli jednak chcesz traktować wartość 400 jako powodzenie, możesz podać inicjator telemetrii, który ustawia właściwość success.

Jeśli udostępnisz inicjator telemetrii, jest on wywoływany za każdym razem, gdy wywoływana jest dowolna z metod Track*(). Obejmuje to Track() metody wywoływane przez standardowe moduły telemetrii. Według konwencji te moduły nie ustawiają żadnej właściwości, która została już ustawiona przez inicjator. Inicjatory telemetrii są wywoływane przed wywołaniem procesorów telemetrii. Dlatego wszelkie wzbogacenia wykonywane przez inicjatory są widoczne dla procesorów.

Definiowanie inicjatora

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 aplikacji: załaduj inicjator

W ApplicationInsights.config:

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

Alternatywnie możesz utworzyć wystąpienia inicjatora w kodzie, na przykład w global.aspx.cs:

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

Zobacz więcej tego przykładu.

ASP.NET Core/Worker Service: Załaduj inicjator

Uwaga

Dodawanie inicjatora przy użyciu lub nie jest prawidłowe dla aplikacji ASP.NET Core lub jeśli używasz zestawu ApplicationInsights.config TelemetryConfiguration.Active SDK Microsoft.ApplicationInsights.WorkerService.

W przypadku aplikacji napisanych przy użyciu ASP.NET Core lub WorkerServicedodawanie nowego inicjatora telemetrii odbywa się przez dodanie go do kontenera wstrzykiwania zależności, jak pokazano. Odbywa się to w Startup.ConfigureServices metodzie .

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

Inicjatory telemetrii języka JavaScript

JavaScript

Wstaw inicjator telemetrii przy użyciu wywołania zwrotnego fragmentu kodu 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>

Aby uzyskać podsumowanie właściwości innych niżcustom dostępne dla elementu telemetrii, zobacz Application Szczegółowe informacje Export Data Model (Eksportowanie modelu danychaplikacji).

Możesz dodać tyle inicjatorów, ile chcesz. Są one wywoływane w kolejności, w których zostały dodane.

Procesory telemetrii OpenCensus języka Python

Procesory telemetrii w środowisku OpenCensus Python to po prostu funkcje wywołania zwrotnego wywoływane w celu przetwarzania danych telemetrycznych przed ich wyeksportowaniem. Funkcja wywołania zwrotnego musi akceptować typ danych koperty jako parametr. Aby odfiltrować dane telemetryczne od eksportowanych danych, upewnij się, że funkcja wywołania zwrotnego zwraca wartość False . Schemat typów danych Azure Monitor w kopertach na GitHub.

Uwaga

Możesz cloud_RoleName modyfikować, zmieniając ai.cloud.role atrybut w polu 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()

Możesz dodać tyle procesorów, ile chcesz. Są one wywoływane w kolejności, w których zostały dodane. Jeśli jeden procesor zgłasza wyjątek, nie ma to wpływu na następujące procesory.

Przykładowe elementy TelemetryInitializers

Dodawanie właściwości niestandardowej

Poniższy przykładowy inicjator dodaje właściwość niestandardową do każdej śledzonej telemetrii.

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

Dodawanie nazwy roli w chmurze

Poniższy przykładowy inicjator ustawia nazwę roli w chmurze na każdą śledzone dane telemetryczne.

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

Dodawanie informacji z httpContext

Poniższy przykładowy inicjator odczytuje dane z i HttpContext dołącza je do RequestTelemetry wystąpienia. Właściwość IHttpContextAccessor jest automatycznie dostarczana za pośrednictwem wstrzykiwania zależności konstruktora.

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

Jaka jest różnica między procesorami telemetrii i inicjatorami telemetrii?

  • Niektóre z nich nakładają się na to, co można z nimi zrobić. Oba te elementy mogą służyć do dodawania lub modyfikowania właściwości telemetrii, chociaż w tym celu zalecamy używanie inicjatorów.
  • Inicjatory telemetrii są zawsze uruchamiane przed procesorami telemetrii.
  • Inicjatory telemetrii mogą być wywoływane więcej niż raz. Domyślnie nie ustawiają żadnej właściwości, która została już ustawiona.
  • Procesory telemetrii umożliwiają całkowite zastąpienie lub odrzucenie elementu telemetrii.
  • Gwarantowane jest wywoływanie wszystkich zarejestrowanych inicjatorów telemetrii dla każdego elementu telemetrii. W przypadku procesorów telemetrii zestaw SDK gwarantuje wywołanie pierwszego procesora telemetrii. O tym, czy pozostałe procesory są wywoływane, decyduje poprzednie procesory telemetrii.
  • Użyj inicjatorów telemetrii, aby wzbogacić telemetrię o dodatkowe właściwości lub zastąpić istniejącą. Odfiltruj dane telemetryczne za pomocą procesora telemetrii.

Uwaga

Język JavaScript ma tylko inicjatory telemetrii, które mogą filtrować zdarzenia przy użyciu interfejsu ITelemetryInitializer

Rozwiązywanie ApplicationInsights.config

  • Upewnij się, że w pełni kwalifikowana nazwa typu i nazwa zestawu są poprawne.
  • Upewnij się, applicationinsights.config znajduje się w katalogu wyjściowym i zawiera wszystkie ostatnie zmiany.

Dokumenty referencyjne

Kod zestawu SDK

Następne kroki