Application Insights SDK'sında telemetri verilerini filtreleme ve ön işlemeden geçirme

Telemetri verilerinin Application Analizler hizmetine gönderilmeden önce nasıl zenginleştirilebileceğini ve işlenebileceğini özelleştirmek için Application Analizler SDK'sı için eklentiler yazabilir ve yapılandırabilirsiniz.

  • Örnekleme , istatistiklerinizi etkilemeden telemetri hacmini azaltır. Bir sorunu tanıladığınızda bunlar arasında gezinebilmeniz için ilgili veri noktalarını bir arada tutar. Portalda, örneklemeyi telafi etmek için toplam sayımlar çarpılır.
  • Telemetri işlemcileriyle filtrelemek, SDK'daki telemetriyi sunucuya gönderilmeden önce filtrelemenize olanak tanır. Örneğin, robotlardan gelen istekleri dışlayarak telemetri hacmini azaltabilirsiniz. Filtreleme, trafiği azaltmak için örneklemeye göre daha temel bir yaklaşımdır. İletilenler üzerinde daha fazla denetime olanak tanır, ancak istatistiklerinizi etkiler. Örneğin, tüm başarılı istekleri filtreleyebilirsiniz.
  • Telemetri başlatıcıları, uygulamanızdan gönderilen ve standart modüllerden telemetri içeren telemetriye özellikler ekler veya bunları değiştirir. Örneğin, portaldaki verileri filtrelemek için hesaplanan değerler veya sürüm numaraları ekleyebilirsiniz.
  • SDK API'si özel olayları ve ölçümleri göndermek için kullanılır.

Başlamadan önce:

Filtreleme

Bu teknik, telemetri akışına dahil edilen veya dışlananlar üzerinde doğrudan denetim sağlar. Filtreleme, telemetri öğelerinin Uygulama Analizler gönderilmesini bırakmak için kullanılabilir. Filtrelemeyi örneklemeyle birlikte veya ayrı ayrı kullanabilirsiniz.

Telemetriyi filtrelemek için bir telemetri işlemcisi yazıp ile TelemetryConfigurationkaydedersiniz. Tüm telemetri işlemcinizden geçer. Akışı akıştan bırakmayı veya zincirdeki bir sonraki işlemciye vermeyi seçebilirsiniz. HTTP isteği toplayıcısı ve bağımlılık toplayıcısı gibi standart modüllerden alınan telemetri ve kendiniz izlendiğiniz telemetri dahildir. Örneğin, robotlardan gelen istekler veya başarılı bağımlılık çağrıları hakkındaki telemetri verilerini filtreleyebilirsiniz.

Uyarı

sdk'dan gönderilen telemetriyi işlemciler kullanarak filtrelemek, portalda gördüğünüz istatistikleri çarpıtabilir ve ilgili öğeleri izlemeyi zorlaştırabilir.

Bunun yerine örnekleme kullanmayı göz önünde bulundurun.

Telemetri işlemcisi oluşturma

C#

  1. Filtre oluşturmak için uygulayın ITelemetryProcessor.

    Telemetri işlemcileri bir işleme zinciri oluşturur. Bir telemetri işlemcisinin örneğini oluştururken zincirdeki bir sonraki işlemciye başvuru alırsınız. Bir telemetri veri noktası işlem yöntemine geçirildiğinde, işini yapar ve ardından zincirdeki sonraki telemetri işlemcisini çağırır (veya çağırmaz).

    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. İşlemcinizi ekleyin.

uygulamaları ASP.NET

Bu kod parçacığını ApplicationInsights.config ekleyin:

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

Sınıfınızda genel adlandırılmış özellikler sağlayarak dize değerlerini .config dosyasından geçirebilirsiniz.

Uyarı

Tür adını ve .config dosyasındaki tüm özellik adlarını koddaki sınıf ve özellik adları ile eşleştirmeye dikkat edin. .config dosyası var olmayan bir türe veya özelliğe başvuruda bulunursa SDK sessizce herhangi bir telemetri gönderemeyebilir.

Alternatif olarak, filtreyi kodda başlatabilirsiniz. Uygun bir başlatma sınıfında, örneğin içinde AppStart Global.asax.cs, işlemcinizi zincire ekleyin:

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

Bu noktadan sonra oluşturulan telemetri istemcileri işlemcilerinizi kullanır.

Çekirdek/Çalışan hizmeti uygulamalarını ASP.NET

Not

kullanarak işlemci ApplicationInsights.config ekleme veya TelemetryConfiguration.Active ASP.NET Core uygulamalar için geçerli değildir veya Microsoft.ApplicationInsights.WorkerService SDK kullanıyorsanız.

ASP.NET Core veya WorkerService kullanılarak yazılan uygulamalar için, yeni bir telemetri işlemcisi ekleme işlemi, gösterildiği gibi üzerinde IServiceCollectionuzantı yöntemi kullanılarak AddApplicationInsightsTelemetryProcessor gerçekleştirilir. Bu yöntem sınıfınızın Startup.cs yönteminde ConfigureServices çağrılır.

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

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

parametre gerektiren telemetri işlemcilerini ASP.NET Core kaydetmek için ITelemetryProcessorFactory uygulayan özel bir sınıf oluşturun. Oluşturucuyu Create yönteminde istenen parametrelerle çağırın ve addSingletonITelemetryProcessorFactory<, MyTelemetryProcessorFactory>() kullanın.

Örnek filtreler

Yapay istekler

Botları ve web testlerini filtreleyin. Ölçüm Gezgini yapay kaynakları filtreleme seçeneği sunar ancak bu seçenek trafiği ve alma boyutunu SDK'nın kendisinde filtreleyerek azaltır.

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

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

Başarısız kimlik doğrulaması

İstekleri "401" yanıtıyla filtreleyin.

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

Hızlı uzak bağımlılık çağrılarını filtreleme

Yalnızca yavaş olan çağrıları tanılamak istiyorsanız hızlı olanları filtreleyin.

Not

Bu filtreleme, portalda gördüğünüz istatistikleri çarpıtır.

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

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

Bağımlılık sorunlarını tanılama

Bu blogda , bağımlılıklara otomatik olarak düzenli ping göndererek bağımlılık sorunlarını tanılamaya yönelik bir proje açıklanmaktadır.

Java

Telemetri işlemcileri ve Bunların Java'daki uygulamaları hakkında daha fazla bilgi edinmek için lütfen Java telemetri işlemcileri belgelerine başvurun.

JavaScript web uygulamaları

ITelemetryInitializer kullanarak filtreleme

  1. Telemetri başlatıcı geri çağırma işlevi oluşturun. Geri çağırma işlevi, işlenen olay olan bir parametre olarak alır ITelemetryItem . Bu geri aramadan geri dönülerek false telemetri öğesinin filtreleneceği sonucuna varılır.

    var filteringFunction = (envelope) => {
      if (envelope.data.someField === 'tobefilteredout') {
          return false;
      }
    
      return true;
    };
    
  2. Telemetri başlatıcı geri aramanızı ekleyin:

    appInsights.addTelemetryInitializer(filteringFunction);
    

Özellikleri ekleme/değiştirme: ITelemetryInitializer

Telemetriyi ek bilgilerle zenginleştirmek veya standart telemetri modülleri tarafından ayarlanan telemetri özelliklerini geçersiz kılmak için telemetri başlatıcılarını kullanın.

Örneğin, web paketi için Uygulama Analizler HTTP istekleri hakkında telemetri toplar. Varsayılan olarak, =400 yanıt koduna >sahip tüm istekler başarısız olarak işaretlenir. Ancak 400 değerini başarılı olarak ele almak istiyorsanız, başarı özelliğini ayarlayan bir telemetri başlatıcısı sağlayabilirsiniz.

Telemetri başlatıcısı sağlarsanız, Track*() yöntemlerinden herhangi biri çağrıldığında çağrılır. Bu, standart telemetri modülleri tarafından çağrılan yöntemleri içerir Track() . Kural gereği, bu modüller bir başlatıcı tarafından önceden ayarlanmış bir özellik ayarlamaz. Telemetri başlatıcıları, telemetri işlemcileri çağrılmadan önce çağrılır. Bu nedenle başlatıcılar tarafından yapılan tüm zenginleştirmeler işlemciler tarafından görülebilir.

Başlatıcınızı tanımlama

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 uygulamaları: Başlatıcınızı yükleme

ApplicationInsights.config'da:

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

Alternatif olarak kodda başlatıcının örneğin Global.aspx.cs dosyasında örneği oluşturabilirsiniz:

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

Bu örneğin daha fazlasına bakın.

ASP.NET Çekirdek/Çalışan hizmet uygulamaları: Başlatıcınızı yükleme

Not

kullanarak ApplicationInsights.config başlatıcı ekleme veya TelemetryConfiguration.Active ASP.NET Core uygulamaları için geçerli değildir veya Microsoft.ApplicationInsights.WorkerService SDK kullanıyorsanız.

ASP.NET Core veya WorkerService kullanılarak yazılan uygulamalar için, gösterildiği gibi yeni bir telemetri başlatıcısı bağımlılık ekleme kapsayıcısına eklenerek gerçekleştirilir. Bu yöntemde Startup.ConfigureServices yapılır.

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

JavaScript telemetri başlatıcıları

JavaScript

OnInit geri çağırmada kod parçacığını kullanarak telemetri başlatıcısı ekleyin:

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

Telemetri öğesinde kullanılabilen özel olmayan özelliklerin özeti için bkz. Uygulama Analizler Veri Modelini Dışarı Aktarma.

İstediğiniz kadar başlatıcı ekleyebilirsiniz. Eklendikleri sırayla çağrılır.

OpenCensus Python telemetri işlemcileri

OpenCensus Python'daki telemetri işlemcileri, telemetriyi dışarı aktarmadan önce işlemek için çağrılan geri çağırma işlevleridir. Geri çağırma işlevi, parametresi olarak bir zarf veri türünü kabul etmelidir. Telemetri verilerinin dışarı aktarılmasını filtrelemek için geri çağırma işlevinin döndürdüğünden Falseemin olun. GitHub üzerindeki zarflarda Azure İzleyici veri türlerinin şemasını görebilirsiniz.

Not

alandaki özniteliğini ai.cloud.roletags değiştirerek değiştirebilirsinizcloud_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()

İstediğiniz kadar işlemci ekleyebilirsiniz. Eklendikleri sırayla çağrılır. Bir işlemci özel durum oluşturursa, aşağıdaki işlemcileri etkilemez.

Örnek TelemetryInitializers

Özel özellik ekleme

Aşağıdaki örnek başlatıcı, izlenen her telemetriye özel bir özellik ekler.

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

Bulut rolü adı ekleme

Aşağıdaki örnek başlatıcı, bulut rolü adını izlenen her telemetriye ayarlar.

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

HttpContext'ten bilgi ekleme

Aşağıdaki örnek başlatıcı verileri okur HttpContext ve bir RequestTelemetry örneğe ekler. IHttpContextAccessor oluşturucu bağımlılık ekleme yoluyla otomatik olarak sağlanır.

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

Telemetri işlemcileri ile telemetri başlatıcıları arasındaki fark nedir?

  • Bunlarla yapabileceklerinizde bazı çakışmalar vardır. Her ikisi de telemetri özelliklerini eklemek veya değiştirmek için kullanılabilir, ancak bu amaçla başlatıcıları kullanmanızı öneririz.
  • Telemetri başlatıcıları her zaman telemetri işlemcilerinden önce çalışır.
  • Telemetri başlatıcıları birden çok kez çağrılabilir. Kurala göre, önceden ayarlanmış bir özellik ayarlamaz.
  • Telemetri işlemcileri, bir telemetri öğesini tamamen değiştirmenize veya atmanıza olanak sağlar.
  • Tüm kayıtlı telemetri başlatıcılarının her telemetri öğesi için çağrılacağı garanti edilir. Telemetri işlemcileri için SDK, ilk telemetri işlemcisini çağırmayı garanti eder. Geri kalan işlemcilerin çağrılıp çağrılmayacağı, önceki telemetri işlemcileri tarafından belirlenir.
  • Telemetriyi ek özelliklerle zenginleştirmek veya var olan bir özelliği geçersiz kılmak için telemetri başlatıcılarını kullanın. Telemetriyi filtrelemek için telemetri işlemcisi kullanın.

Not

JavaScript'te yalnızca ITelemetryInitializer kullanarak olayları filtreleyen telemetri başlatıcıları vardır

ApplicationInsights.config sorunlarını giderme

  • Tam tür adının ve derleme adının doğru olduğunu onaylayın.
  • applicationinsights.config dosyasının çıkış dizininizde olduğunu ve son değişiklikleri içerdiğini onaylayın.

Başvuru belgeleri

SDK kodu

Sonraki adımlar