Memfilter dan melakukan pra-proses telemetri di Application Insights SDK

Plug-in untuk Application Insights SDK dapat mengkostumisasi bagaimana telemetri diperkaya dan diproses sebelum dikirim ke layanan Application Insights.

• Pengambilan sampel mengurangi volume telemetri tanpa mempengaruhi statistik Anda. Proses ini membuat data titik terus berkaitan bersama-sama sehingga Anda dapat menavigasi di antara mereka ketika Anda mendiagnosis masalah. Di portal, jumlah total dikalikan untuk mengimbangi pengambilan sampel.
• Pemfilteran dengan prosesor telemetri memungkinkan Anda memfilter telemetri di SDK sebelum hasilnya dikirim ke server. Misalnya, Anda dapat mengurangi volume telemetri dengan mengecualikan permintaan dari robot. Pemfilteran adalah pendekatan yang lebih mendasar untuk mengurangi lalu lintas daripada pengambilan sampel. Ini memungkinkan Anda lebih mengontrol apa yang ditransmisikan, tetapi mempengaruhi statistik Anda. Misalnya, Anda dapat memfilter semua permintaan yang berhasil.
• Penginisialan telemetri menambahkan atau memodifikasi properti ke telemetri apa pun yang dikirim dari aplikasi Anda, yang mencakup telemetri dari modul standar. Misalnya, Anda dapat menambahkan nilai terhitung atau nomor versi untuk memfilter data di portal.
• API SDK digunakan untuk mengirim peristiwa dan metrik kustom.

Sebelum memulai:

• Pasang SDK yang sesuai untuk aplikasi Anda: ASP.NET, ASP.NET Core,Non HTTP / Worker untuk .NET / .NET Core, atau JavaScript.

Pemfilteran

Teknik ini memberi Anda kontrol langsung atas apa yang disertakan atau dikecualikan dari aliran telemetri. Pemfilteran dapat digunakan untuk menjatuhkan item telemetri agar tidak dikirim ke Application Insights. Anda dapat menggunakan pemfilteran dengan pengambilan sampel, atau secara terpisah.

Untuk memfilter telemetri, Anda tulis prosesor telemetri dan daftarkan itu dengan TelemetryConfiguration. Semua telemetri melewati prosesor Anda. Anda dapat memilih untuk menghilangkannya dari streaming atau memberikannya ke prosesor berikutnya dalam rantai. Telemetri dari modul standar, seperti kolektor permintaan HTTP dan kolektor dependensi, dan telemetri yang Anda lacak sendiri disertakan. Misalnya, Anda dapat memfilter telemetri tentang permintaan dari robot atau panggilan dependensi yang berhasil.

Peringatan

Memfilter telemetri yang dikirim dari SDK dengan menggunakan prosesor dapat mengubah statistik yang Anda lihat di portal dan membuatnya sulit untuk mengikuti item terkait.

Sebagai gantinya, pertimbangkan untuk menggunakan sampling.

Membuat prosesor telemetri

C#

1. Untuk membuat filter, terapkan ITelemetryProcessor.

   Prosesor telemetri membangun rantai pemrosesan. Saat Anda membuat contoh realisasi prosesor telemetri, Anda akan diberi referensi ke prosesor berikutnya dalam rantai. Ketika titik data telemetri diteruskan ke metode proses, proses melakukan pekerjaannya dan kemudian memanggil (atau tidak memanggil) prosesor telemetri berikutnya dalam rantai.

   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. Tambahkan prosesor Anda.

Aplikasi ASP.NET

Masukkan cuplikan ini dalam ApplicationInsights.config:

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

Anda dapat meneruskan nilai untai (karakter) dari file .config dengan menyediakan properti bernama publik di kelas Anda.

Peringatan

Berhati-hatilah untuk mencocokkan nama tipe dan nama properti apa pun dalam file .config ke nama kelas dan properti dalam kode. Jika file .config mereferensikan tipe atau properti yang tidak ada, SDK mungkin diam-diam gagal mengirim telemetri apa pun.

Atau, Anda dapat menginisialisasi filter dalam kode. Di kelas inisialisasi yang sesuai, sebagai contoh, AppStart di Global.asax.cs, masukkan prosesor Anda ke dalam rantai:

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

Klien telemetri yang dibuat setelah titik ini akan menggunakan prosesor Anda.

Aplikasi layanan Core/Worker ASP.NET

Catatan

Menambahkan prosesor dengan menggunakan ApplicationInsights.config atau TelemetryConfiguration.Active tidak valid untuk aplikasi ASP.NET Core atau jika Anda menggunakan SDK Microsoft.ApplicationInsights.WorkerService.

Untuk aplikasi yang ditulis dengan menggunakan ASP.NET Core atau WorkerService, menambahkan prosesor telemetri baru dilakukan dengan menggunakan AddApplicationInsightsTelemetryProcessormetode ekstensi pada IServiceCollection, seperti yang ditunjukkan. Metode ini disebut dalam metode ConfigureServices dari kelas Startup.cs Anda.

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

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

Untuk mendaftarkan prosesor telemetri yang membutuhkan parameter di ASP.NET Core, buat kelas kustom yang menerapkan ITelemetryProcessorFactory. Panggil konstruktor dengan parameter yang diinginkan dalam metode Buat lalu gunakan AddSingleton<ITelemetryProcessorFactory, MyTelemetryProcessorFactory>().

Filter contoh

Permintaan sintetis

Memfilter tes bot dan web. Meskipun Metrics Explorer memberi Anda opsi untuk memfilter sumber sintetis, opsi ini mengurangi lalu lintas dan ukuran konsumsi dengan memfilternya di SDK itu sendiri.

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

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

Autentikasi gagal

Filter permintaan dengan respons "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);
}

Memfilter panggilan dependensi jarak jauh cepat

Jika Anda hanya ingin mendiagnosis panggilan yang lambat, saring panggilan yang cepat.

Catatan

Pemfilteran ini akan mengubah statistik yang Anda lihat di portal.

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

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

Mendiagnosis masalah ketergantungan

Blog ini menjelaskan proyek untuk mendiagnosis masalah ketergantungan dengan secara otomatis mengirim ping reguler ke dependensi.

Java

Untuk mempelajari selengkapnya tentang prosesor telemetri dan implementasinya di Java, lihat dokumentasi prosesor telemetri Java.

Aplikasi web JavaScript

Filter dengan menggunakan ITelemetryInitializer

1. Buat fungsi callback inisializer telemetri. Fungsi callback mengambil ITelemetryItem sebagai parameter, yang mana merupakan peristiwa yang sedang diproses. Mengembalikan false dari callback ini menghasilkan item telemetri yang akan difilter.

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

2. Tambahkan callback penginisialan telemetri Anda:

   appInsights.addTelemetryInitializer(filteringFunction);
   

Menambah/memodifikasi properti: ITelemetryInitializer

Gunakan penginisialan telemetri untuk memperkaya telemetri Anda dengan informasi tambahan atau mengesampingkan set properti telemetri dengan modul telemetri standar.

Misalnya, Application Insights untuk paket web mengumpulkan telemetri tentang permintaan HTTP. Secara default, telemetri memberi bendera kegagalan memenuhi permintaan dengan kode respons >=400. Tetapi jika Anda ingin memperlakukan 400 sebagai sukses, Anda dapat menyediakan inisialisasi telemetri yang menetapkan properti sukses.

Jika Anda menyediakan inisialisasi telemetri, telemetri disebut setiap kali metode Track*() dipanggil. Inisialisasi ini mencakup metode Track() yang disebut oleh modul telemetri standar. Berdasarkan konvensi, modul-mocul ini tidak menetapkan properti apa pun yang sudah ditetapkan oleh inisialisasi. Inisialisasi telemetri dipanggil sebelum memanggil prosesor telemetri. Jadi setiap pengayaan yang dilakukan oleh inisializer itu terlihat oleh prosesor.

Tentukan inisialisasi Anda

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 aplikasi: Muat inisializer Anda

Pada ApplicationInsights.config:

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

Atau, Anda dapat membuat contoh realisasi penginisialan dalam kode, misalnya, di Global.aspx.cs:

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

Lihat lebih lanjut dari sampel ini.

ASP.NET aplikasi layanan Core/Worker: Muat inisializer Anda

Catatan

Menambahkan penginisialan dengan menggunakan ApplicationInsights.config atau TelemetryConfiguration.Active tidak valid untuk aplikasi ASP.NET Core atau jika Anda menggunakan SDK Microsoft.ApplicationInsights.WorkerService.

Untuk aplikasi yang ditulis menggunakan ASP.NET Core atau WorkerService, menambahkan penginisialan telemetri baru dilakukan dengan menambahkannya ke kontainer Injeksi Dependensi, seperti yang ditunjukkan. Selesaikan langkah ini dalam metode Startup.ConfigureServices.

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

Penginisialan telemetri JavaScript

JavaScript

Masukkan initializer telemetri menggunakan cuplikan panggilan balik 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>

Untuk ringkasan properti non-kustom yang tersedia pada item telemetri, lihat Model Data Ekspor Application Insights.

Anda dapat menambahkan inisialisasi sebanyak yang Anda mau. Mereka dipanggil berdasarkan urutan mereka ditambahkan.

Prosesor telemetri OpenCensus Python

Prosesor telemetri di OpenCensus Python hanyalah sebatas fungsi callback yang dipanggil untuk memproses telemetri sebelum diekspor. Fungsi callback harus menerima data tipe amplop sebagai parameternya. Untuk memfilter telemetri agar tidak diekspor, pastikan fungsi callback kembali False. Anda dapat melihat skema untuk tipe data Azure Monitor dalam tipe amplop di GitHub.

Catatan

Anda dapat memodifikasi cloud_RoleName dengan mengubah atribut ai.cloud.role di bidang 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()

Anda dapat menambahkan prosesor sebanyak yang Anda suka. Mereka dipanggil berdasarkan urutan mereka ditambahkan. Jika satu prosesor melontarkan pengecualian, itu tidak berdampak pada prosesor berikutnya.

Contoh TelemetryInitializers

Menambahkan properti kustom

Contoh penginisialan berikut menambahkan properti kustom ke setiap telemetri yang terlacak.

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

Tambahkan nama peran cloud

Contoh penginisialan berikut ini menetapkan nama peran awan ke setiap telemetri yang dilacak.

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

Mengontrol alamat IP klien yang digunakan untuk pemetaan geolokasi

Sampel penginisialisasi berikut mengatur IP klien yang akan digunakan untuk pemetaan geolokasi, alih-alih alamat IP soket klien, selama penyerapan telemetri.

public void Initialize(ITelemetry telemetry)
{
    var request = telemetry as RequestTelemetry;
    if (request == null) return true;
    request.Context.Location.Ip = "{client ip address}"; // Could utilize System.Web.HttpContext.Current.Request.UserHostAddress;   
    return true;
}

ITelemetryProcessor dan ITelemetryInitializer

Apa perbedaan antara prosesor telemetri dan inisialisasi telemetri?

• Ada beberapa tumpang tindih dalam apa yang dapat Anda lakukan dengan mereka. Keduanya dapat digunakan untuk menambahkan atau memodifikasi properti telemetri, meskipun kami menyarankan Anda menggunakan penginisialan untuk tujuan tersebut.
• Penginisialan telemetri selalu berjalan sebelum prosesor telemetri.
• Penginisialan telemetri dapat dipanggil lebih dari sekali. Secara konvensi, mereka tidak menetapkan properti mana pun yang sudah ditetapkan.
• Prosesor telemetri memungkinkan Anda untuk sepenuhnya mengganti atau membuang item telemetri.
• Semua penginisialan telemetri yang terdaftar dipanggil untuk setiap item telemetri. Untuk prosesor telemetri, SDK menjamin untuk memanggil prosesor telemetri pertama. Apakah prosesor lainnya dipanggil atau tidak diputuskan oleh prosesor telemetri sebelumnya.
• Gunakan penginisialan telemetri untuk memperkaya telemetri dengan lebih banyak properti atau mengganti yang sudah ada. Gunakan prosesor telemetri untuk menyaring telemetri.

Catatan

JavaScript hanya memiliki inisial telemetri yang dapatmemfilter peristiwa dengan menggunakan ITelemetryInitializer

Memecahkan ApplicationInsights.config

• Konfirmasikan bahwa nama tipe dan nama perakitan yang sepenuhnya memenuhi syarat sudah benar.
• Pastikan bahwa applicationinsights.config Anda berada di direktori output Anda dan berisi setiap perubahan terbaru.

Dokumen referensi

• Ringkasan API
• Referensi ASP.NET

Kode SDK

• ASP.NET Core SDK
• ASP.NET SDK
• JavaScript SDK

Langkah berikutnya

• Mencari peristiwa dan log
• mengambil sampel
• Pemecahan Masalah