API Application Insights untuk aktivitas dan metrik kustom

Artikel
01/31/2024

Sisipkan beberapa baris kode di aplikasi Anda untuk mengetahui apa yang dilakukan pengguna dengannya, atau untuk membantu mendiagnosis masalah. Anda dapat mengirim telemetri dari aplikasi perangkat dan desktop, klien web, dan server web. Gunakan API telemetri inti Application Insights untuk mengirim peristiwa dan metrik kustom, dan versi telemetri standar Anda sendiri. API ini adalah API yang sama dengan yang digunakan oleh kolektor data Application Insights standar.

Catatan

Pada tanggal 31 Maret 2025, dukungan untuk penyerapan kunci instrumentasi akan berakhir. Penyerapan kunci instrumentasi akan berjalan terus, namun kami tidak akan lagi menyediakan pembaruan atau dukungan terhadap fitur tersebut. Transisi ke string koneksi untuk memanfaatkan kemampuan baru.

Ringkasan API

API inti bersifat sama di semua platform, terlepas adanya beberapa variasi seperti GetMetric (.NET saja).

Metode	Digunakan untuk
`TrackPageView`	Halaman, layar, panel, atau formulir.
`TrackEvent`	Tindakan pengguna dan peristiwa lainnya. Digunakan untuk melacak perilaku pengguna atau untuk memantau performa.
`GetMetric`	Metrik nol dan multi-dimensi, agregasi yang dikonfigurasikan secara terpusat, hanya C#.
`TrackMetric`	Pengukuran performa seperti panjang antrean tidak terkait dengan peristiwa tertentu.
`TrackException`	Mencatat pengecualian untuk diagnosis. Lacak di mana mereka terjadi dalam kaitannya dengan peristiwa lain dan periksa jejak tumpukan.
`TrackRequest`	Mencatat frekuensi dan durasi permintaan server untuk analisis performa.
`TrackTrace`	Pesan log Diagnostik Sumber Daya. Anda juga dapat menangkap log pihak ketiga.
`TrackDependency`	Mencatat durasi dan frekuensi panggilan ke komponen eksternal tempat aplikasi Anda bergantung.

Anda dapat melampirkan properti dan metrik ke sebagian besar panggilan telemetri ini.

Sebelum memulai

Jika Anda belum memiliki referensi tentang Application Insights SDK:

Menambahkan Application Insights SDK ke proyek Anda:
Di perangkat atau kode server web Anda, sertakan:

C#using Microsoft.ApplicationInsights;:

Visual Basic:Imports Microsoft.ApplicationInsights

Java:import com.microsoft.applicationinsights.TelemetryClient;

Node.js:var applicationInsights = require("applicationinsights");

Dapatkan instans TelemetryClient

Dapatkan instans TelemetryClient (kecuali di JavaScript di halaman web):

Untuk aplikasi ASP.NET Core dan aplikasi Non HTTP/Worker untuk .NET/.NET Core, mendapatkan instans TelemetryClient dari kontainer injeksi dependensi seperti yang dijelaskan dalam dokumentasi masing-masing.

Jika Anda menggunakan Azure Functions v2+ atau Azure WebJobs v3+, lihat Memantau Azure Functions.

private TelemetryClient telemetry = new TelemetryClient();

Jika Anda melihat pesan yang memberi tahu Anda metode ini sudah usang, lihat microsoft/ApplicationInsights-dotnet#1152 untuk informasi selengkapnya.

Visual Basic

Private Dim telemetry As New TelemetryClient

Java

private TelemetryClient telemetry = new TelemetryClient();

Node.js

var telemetry = applicationInsights.defaultClient;

TelemetryClient adalah utas aman.

Untuk proyek ASP.NET dan Java, Permintaan HTTP yang masuk akan diambil secara otomatis. Anda mungkin ingin membuat instans dari TelemetryClient untuk modul lain dari aplikasi Anda. Misalnya, Anda mungkin memiliki satu instans TelemetryClient di kelas middleware untuk melaporkan peristiwa logika bisnis. Anda dapat mengatur properti seperti UserId dan DeviceId untuk mengidentifikasi komputer. Informasi ini dilampirkan ke semua peristiwa yang dikirim instans.

TelemetryClient.Context.User.Id = "...";
TelemetryClient.Context.Device.Id = "...";

Java

telemetry.getContext().getUser().setId("...");
telemetry.getContext().getDevice().setId("...");

Dalam proyek Node.js, Anda dapat menggunakan new applicationInsights.TelemetryClient(instrumentationKey?) untuk membuat instans baru. Kami merekomendasikan pendekatan ini hanya untuk skenario yang memerlukan konfigurasi terisolasi dari database tunggal defaultClient.

TrackEvent

Di Application Insights, peristiwa kustom adalah titik data yang dapat Anda tampilkan di Metrics Explorer sebagai jumlah agregat, dan di Pencarian Diagnostik sebagai kejadian individu. (Ini tidak terkait dengan MVC atau kerangka kerja “peristiwa” lainnya.)

Sisipkan panggilanTrackEvent dalam kode Anda untuk menghitung berbagai peristiwa. Misalnya, Anda mungkin ingin melacak seberapa sering pengguna memilih fitur tertentu. Atau Anda mungkin ingin tahu seberapa sering mereka mencapai tujuan tertentu atau membuat jenis kesalahan tertentu.

Misalnya, di aplikasi game, kirim peristiwa setiap kali pengguna memenangkan game:

JavaScript

appInsights.trackEvent({name:"WinGame"});

telemetry.TrackEvent("WinGame");

Visual Basic

telemetry.TrackEvent("WinGame")

Java

telemetry.trackEvent("WinGame");

Node.js

telemetry.trackEvent({name: "WinGame"});

Peristiwa kustom di Analitik Log

Telemetri tersedia dalam tabel customEvents di tab Log Application Insights atau pengalaman penggunaan. Peristiwa mungkin berasal dari trackEvent(..) atau Plug-in Pengumpulan Otomatis Click Analytics.

Jika pengambilan sampel sedang beroperasi, properti itemCountmenunjukkan nilai yang lebih besar dari 1. Misalnya, itemCount==10 berarti dari 10 panggilan ke trackEvent(), proses pengambilan sampel mengirimkan hanya salah satunya. Untuk mendapatkan jumlah peristiwa kustom yang benar, gunakan kode seperti customEvents | summarize sum(itemCount).

Catatan

itemCount memiliki nilai minimum satu; rekaman tersebut mewakili entri.

GetMetric

Untuk mempelajari cara menggunakan panggilan GetMetric() secara efektif untuk menangkap metrik pra-agregasi lokal untuk aplikasi .NET dan .NET Core, lihat kumpulan metrik kustom di .NET dan .NET Core.

TrackMetric

Catatan

Microsoft.ApplicationInsights.TelemetryClient.TrackMetric bukan metode yang disukai untuk mengirim metrik. Metrik harus selalu diagregasi selama periode waktu sebelum dikirim. Gunakan salah satu kelebihan beban GetMetric(..) untuk mendapatkan objek metrik untuk mengakses kapabilitas pra-agregasi SDK.

Jika Anda menerapkan logika pra-agregasi Anda sendiri, Anda dapat menggunakan metode TrackMetric() untuk mengirim agregat yang dihasilkan. Jika aplikasi Anda memerlukan pengiriman item telemetri terpisah di setiap kesempatan tanpa agregasi sepanjang waktu, Anda mungkin memiliki kasus penggunaan untuk telemetri peristiwa. Lihat TelemetryClient.TrackEvent (Microsoft.ApplicationInsights.DataContracts.EventTelemetry).

Application Insights dapat membuat bagan metrik yang tidak dilampirkan ke peristiwa tertentu. Misalnya, Anda dapat memantau panjang antrean secara berkala. Dengan metrik, pengukuran individu terkesan kurang menarik daripada variasi dan tren, sehingga grafik statistik akan berguna.

Untuk mengirim metrik ke Application Insights, Anda dapat menggunakan API TrackMetric(..). Ada dua cara untuk mengirim metrik:

Nilai tunggal. Setiap kali Anda melakukan pengukuran di aplikasi, Anda mengirim nilai yang sesuai ke Application Insights.

Misalnya, asumsikan Anda memiliki metrik yang menjelaskan jumlah item dalam kontainer. Selama periode waktu tertentu, Anda pertama kali memasukkan tiga item ke dalam kontainer dan kemudian Anda menghapus dua item. Dengan demikian, Anda akan menelepon TrackMetric dua kali. Pertama, Anda akan meneruskan nilai 3 dan kemudian meneruskan nilai -2. Application Insights menyimpan kedua nilai untuk Anda.
Agregasi. Ketika bekerja dengan metrik, setiap pengukuran jarang menarik. Sebaliknya ringkasan tentang apa yang terjadi selama periode waktu tertentu justru penting. Ringkasan semacam itu disebut agregasi.

Dalam contoh di atas, jumlah metrik agregat untuk periode waktu tersebut adalah 1 dan hitungan nilai metrik adalah 2. Saat menggunakan pendekatan agregasi, Anda hanya memanggil TrackMetric sekali per periode waktu dan mengirim nilai agregat. Ini adalah pendekatan yang direkomendasikan karena dapat secara signifikan mengurangi biaya dan performa overhead dengan mengirim lebih sedikit titik data ke Application Insights, sambil tetap mengumpulkan semua informasi yang relevan.

Contoh nilai tunggal

Untuk mengirim satu nilai metrik:

JavaScript

appInsights.trackMetric({name: "queueLength", average: 42});

var sample = new MetricTelemetry();
sample.Name = "queueLength";
sample.Sum = 42.3;
telemetryClient.TrackMetric(sample);

Java

telemetry.trackMetric("queueLength", 42.0);

Node.js

telemetry.trackMetric({name: "queueLength", value: 42.0});

Metrik kustom di Analitik Log

Telemetri tersedia dalam tabel customMetrics di Application Insights Analytics. Setiap baris mewakili panggilan trackMetric(..) ke aplikasi Anda.

valueSum: Jumlah total pengukuran. Untuk mendapatkan nilai rata-rata, bagilah dengan valueCount.
valueCount: Jumlah pengukuran yang diagregasi ke dalam panggilan trackMetric(..) ini.

Catatan

valueCount memiliki nilai minimum satu; rekaman tersebut mewakili entri.

Tampilan halaman

Di aplikasi perangkat atau halaman web, telemetri tampilan halaman dikirim secara default saat setiap layar atau halaman dimuat. Tetapi Anda dapat mengubah default untuk melacak tampilan halaman pada waktu tambahan atau berbeda. Misalnya, dalam aplikasi yang menampilkan tab atau panel, Anda mungkin ingin melacak halaman setiap kali pengguna membuka panel baru.

Data pengguna dan sesi dikirim sebagai properti bersama dengan tampilan halaman, sehingga bagan pengguna dan sesi menjadi hidup ketika ada telemetri tampilan halaman.

Tampilan halaman kustom

JavaScript

appInsights.trackPageView("tab1");

telemetry.TrackPageView("GameReviewPage");

Visual Basic

telemetry.TrackPageView("GameReviewPage")

Java

telemetry.trackPageView("GameReviewPage");

Jika Anda memiliki beberapa tab dalam halaman HTML yang berbeda, Anda juga dapat menentukan URL:

appInsights.trackPageView("tab1", "http://fabrikam.com/page1.htm");

Tampilan halaman waktu

Secara default, waktu yang dilaporkan sebagai Waktu muat tampilan halaman diukur dari saat browser mengirim permintaan, hingga peristiwa pemuatan halaman browser dipanggil.

Sebagai gantinya, Anda dapat:

Mengatur durasi eksplisit di panggilan trackPageView:appInsights.trackPageView("tab1", null, null, null, durationInMilliseconds);.
Gunakan tampilan halaman waktu panggilan startTrackPage dan stopTrackPage.

JavaScript

// To start timing a page:
appInsights.startTrackPage("Page1");

...

// To stop timing and log the page:
appInsights.stopTrackPage("Page1", url, properties, measurements);

Nama yang Anda gunakan sebagai parameter pertama mengaitkan panggilan mulai dan berhenti. Ini adalah default ke nama halaman saat ini.

Durasi pemuatan halaman yang dihasilkan yang ditampilkan di Metrics Explorer berasal dari interval antara panggilan mulai dan berhenti. Terserah Anda interval apa yang sebenarnya Anda ukur waktunya.

Telemetri halaman di Analitik Log

Di Analitik Log, dua tabel memperlihatkan data dari operasi browser:

pageViews: Berisi data tentang URL dan judul halaman.
browserTimings: Data tentang performa klien, seperti waktu yang digunakan untuk memproses data masuk.

Untuk menemukan berapa lama waktu yang dibutuhkan browser untuk memproses halaman yang berbeda:

browserTimings
| summarize avg(networkDuration), avg(processingDuration), avg(totalDuration) by name

Untuk menemukan popularitas browser yang berbeda:

pageViews
| summarize count() by client_Browser

Untuk mengaitkan tampilan halaman ke panggilan AJAX, bergabunglah dengan dependensi:

pageViews
| join (dependencies) on operation_Id

TrackRequest

SDK server menggunakan TrackRequest untuk mencatat permintaan HTTP.

Anda juga dapat menyebutnya sendiri jika Ingin mensimulasikan permintaan dalam konteks ketika Anda tidak memiliki modul layanan web yang berjalan.

Cara yang disarankan untuk mengirim permintaan telemetri adalah tempat permintaan bertindak sebagai konteks operasi.

Konteks operasi

Anda dapat menyambungkan item telemetri bersama-sama dengan mengaitkannya dengan konteks operasi. Modul pelacakan permintaan standar melakukan ini untuk pengecualian dan peristiwa lain yang dikirim saat permintaan HTTP sedang diproses. Di Penelusuran dan Analitik, Anda dapat dengan mudah menemukan peristiwa yang terkait dengan permintaan menggunakan ID operasinya.

Untuk informasi lebih lanjut pada korelasi, lihat Korelasi telemetri di Application Insights.

Saat Anda melacak telemetri secara manual, cara termudah untuk memastikan korelasi telemetri dengan menggunakan pola ini:

// Establish an operation context and associated telemetry item:
using (var operation = telemetryClient.StartOperation<RequestTelemetry>("operationName"))
{
    // Telemetry sent in here will use the same operation ID.
    ...
    telemetryClient.TrackTrace(...); // or other Track* calls
    ...

    // Set properties of containing telemetry item--for example:
    operation.Telemetry.ResponseCode = "200";

    // Optional: explicitly send telemetry item:
    telemetryClient.StopOperation(operation);

} // When operation is disposed, telemetry item is sent.

Bersamaan dengan pengaturan konteks operasi, StartOperation buat item telemetri dari jenis yang Anda tentukan. Ini mengirimkan item telemetri ketika Anda membuang operasi, atau jika Anda secara eksplisit memanggil StopOperation. Jika Anda menggunakan RequestTelemetry sebagai jenis telemetri. durasinya diatur ke interval waktu antara mulai dan berhenti.

Item telemetri yang dilaporkan dalam lingkup operasi menjadi elemen turunan dari operasi tersebut. Konteks operasi dapat disarangkan.

Dalam Pencarian, konteks operasi digunakan untuk membuat daftar Item Terkait.

Untuk informasi selengkapnya tentang pelacakan operasi kustom, lihat Melacak operasi kustom dengan Application Insights .NET SDK.

Permintaan di Analitik Log

Di Application Insights Analytics, permintaan muncul dalam tabel requests.

Jika pengambilan sampel sedang beroperasi, properti itemCountmenunjukkan nilai yang lebih besar dari 1. Misalnya, itemCount==10 berarti dari 10 panggilan ke trackRequest(), proses pengambilan sampel mengirimkan hanya salah satunya. Untuk mendapatkan jumlah permintaan dan durasi rata-rata yang disegmentasikan menurut nama permintaan, gunakan kode seperti:

requests
| summarize count = sum(itemCount), avgduration = avg(duration) by name

TrackException

Mengirim pengecualian ke Application Insights:

Untuk menghitungnya, sebagai indikasi frekuensi masalah.
Untuk memeriksa kemunculan individu.

Laporan mencakup jejak tumpukan.

try
{
    ...
}
catch (Exception ex)
{
    telemetry.TrackException(ex);
}

Java

try {
    ...
} catch (Exception ex) {
    telemetry.trackException(ex);
}

JavaScript

try
{
    ...
}
catch (ex)
{
    appInsights.trackException({exception: ex});
}

Node.js

try
{
    ...
}
catch (ex)
{
    telemetry.trackException({exception: ex});
}

SDK menangkap banyak pengecualian secara otomatis, sehingga Anda tidak selalu harus memanggil TrackException secara eksplisit:

ASP.NET: Menulis kode untuk menangkap pengecualian.
Java EE: Pengecualian ditangkap secara otomatis.
JavaScript: Pengecualian ditangkap secara otomatis. Jika Anda ingin menonaktifkan koleksi otomatis, tambahkan baris ke Skrip Pemuat SDK JavaScript (Web) yang Anda sisipkan di halaman web Anda:

({
    instrumentationKey: "your key",
    disableExceptionTracking: true
})

Pengecualian di Analitik Log

Di Application Insights Analytics, permintaan muncul dalam tabel exceptions.

Jika pengambilan sampel sedang beroperasi, properti itemCountmenunjukkan nilai yang lebih besar dari 1. Misalnya, itemCount==10 berarti dari 10 panggilan ke trackException(), proses pengambilan sampel mengirimkan hanya salah satunya. Untuk mendapatkan jumlah pengecualian yang benar yang disegmentasi berdasarkan jenis pengecualian, gunakan kode seperti:

exceptions
| summarize sum(itemCount) by type

Sebagian besar informasi tumpukan penting sudah diekstraksi ke dalam variabel terpisah, tetapi Anda dapat memisahkan struktur details untuk mendapatkan lebih banyak. Karena struktur ini dinamis, Anda harus mentransmisikan hasilnya ke jenis yang Anda harapkan. Contohnya:

exceptions
| extend method2 = tostring(details[0].parsedStack[1].method)

Untuk mengaitkan pengecualian dengan permintaan terkait, gunakan gabungan:

exceptions
| join (requests) on operation_Id

TrackTrace

Gunakan TrackTrace untuk membantu mendiagnosis masalah dengan mengirim "jejak remah roti" ke Application Insights. Anda dapat mengirim potongan data diagnostik dan memeriksanya di Pencarian Diagnostik.

Dalam Adaptor log .NET, gunakan API ini untuk mengirim log pihak ketiga ke portal.

Di Java, agen Application Insights Java secara otomatis mengumpulkan dan mengirim log ke portal.

telemetry.TrackTrace(message, SeverityLevel.Warning, properties);

Java

telemetry.trackTrace(message, SeverityLevel.Warning, properties);

Node.js

telemetry.trackTrace({
    message: message,
    severity: applicationInsights.Contracts.SeverityLevel.Warning,
    properties: properties
});

JavaScript sisi klien/browser

trackTrace({
    message: string,
    properties?: {[string]:string},
    severityLevel?: SeverityLevel
})

Catat kejadian diagnostik seperti memasukkan atau meninggalkan metode.

Parameter	Deskripsi
`message`	Data diagnostik. Bisa lebih lama dari sebuah nama.
`properties`	Peta string ke string. Lebih banyak data digunakan untuk memfilter pengecualian di portal. Default untuk kosong.
`severityLevel`	Nilai yang didukung: SeverityLevel.ts.

Anda dapat mencari konten pesan, tetapi (tidak seperti nilai properti) Anda tidak dapat memfilternya.

Batas ukuran pada message jauh lebih tinggi daripada batas properti. Keuntungan dari TrackTrace adalah Anda dapat memasukkan data yang relatif panjang ke dalam pesan. Misalnya, Anda dapat menyandikan data POST di sana.

Anda juga dapat menambahkan tingkat keparahan ke pesan Anda. Dan, seperti telemetri lainnya, Anda dapat menambahkan nilai properti untuk membantu memfilter atau mencari set jejak yang berbeda. Contohnya:

var telemetry = new Microsoft.ApplicationInsights.TelemetryClient();
telemetry.TrackTrace("Slow database response",
                SeverityLevel.Warning,
                new Dictionary<string,string> { {"database", db.ID} });

Java

Map<String, Integer> properties = new HashMap<>();
properties.put("Database", db.ID);
telemetry.trackTrace("Slow Database response", SeverityLevel.Warning, properties);

Di Cari, Anda dapat dengan mudah memfilter semua pesan dengan tingkat keparahan tertentu yang terkait dengan database tertentu.

Jejak di Analitik Log

Di Analitik Application Insights, panggilan ke TrackTrace muncul di tabel traces.

Jika pengambilan sampel sedang beroperasi, properti itemCountmenunjukkan nilai yang lebih besar dari 1. Misalnya, itemCount==10 berarti dari 10 panggilan ke trackTrace(), proses pengambilan sampel mengirimkan hanya salah satunya. Untuk mendapatkan jumlah melacak panggilan yang benar, gunakan kode seperti traces | summarize sum(itemCount).

TrackDependency

Gunakan panggilan TrackDependency untuk melacak waktu respons dan tingkat keberhasilan panggilan ke bagian kode eksternal. Hasilnya muncul di bagan dependensi di portal. Cuplikan kode berikut harus ditambahkan di mana pun panggilan dependensi dilakukan.

Catatan

Untuk .NET dan .NET Core Anda juga dapat menggunakan TelemetryClient.StartOperation metode (ekstensi) yang mengisi properti DependencyTelemetry yang diperlukan untuk korelasi dan beberapa properti lain seperti waktu mulai dan durasi sehingga Anda tidak perlu membuat timer kustom seperti dengan contoh berikut. Untuk informasi selengkapnya, lihat bagian tentang pelacakan dependensi keluar di Melacak operasi kustom dengan Application Insights .NET SDK.

var success = false;
var startTime = DateTime.UtcNow;
var timer = System.Diagnostics.Stopwatch.StartNew();
try
{
    success = dependency.Call();
}
catch(Exception ex)
{
    success = false;
    telemetry.TrackException(ex);
    throw new Exception("Operation went wrong", ex);
}
finally
{
    timer.Stop();
    telemetry.TrackDependency("DependencyType", "myDependency", "myCall", startTime, timer.Elapsed, success);
}

Java

boolean success = false;
Instant startTime = Instant.now();
try {
    success = dependency.call();
}
finally {
    Instant endTime = Instant.now();
    Duration delta = Duration.between(startTime, endTime);
    RemoteDependencyTelemetry dependencyTelemetry = new RemoteDependencyTelemetry("My Dependency", "myCall", delta, success);
    dependencyTelemetry.setTimeStamp(startTime);
    telemetry.trackDependency(dependencyTelemetry);
}

Node.js

var success = false;
var startTime = new Date().getTime();
try
{
    success = dependency.Call();
}
finally
{
    var elapsed = new Date() - startTime;
    telemetry.trackDependency({
        dependencyTypeName: "myDependency",
        name: "myCall",
        duration: elapsed,
        success: success
    });
}

Ingat bahwa SDK server menyertakan modul dependensi yang menemukan dan melacak panggilan dependensi tertentu secara otomatis, misalnya, ke database dan API REST. Anda harus memasang agen di server Anda untuk membuat modul berfungsi.

Di Java, banyak panggilan dependensi dapat secara otomatis dilacak dengan menggunakan agen Application Insights Java.

Anda menggunakan panggilan ini jika Anda ingin melacak panggilan yang tidak ditangkap oleh pelacakan otomatis.

Untuk menonaktifkan modul pelacakan dependensi standar di C#, edit ApplicationInsights.config dan hapus referensi ke DependencyCollector.DependencyTrackingTelemetryModule. Untuk Java, lihat Menekan telemetri tertentu yang dikumpulkan secara otomatis.

Dependensi di Analitik Log

Di Application Insights Analytics, trackDependency permintaan muncul dalam tabel dependencies.

Jika pengambilan sampel sedang beroperasi, properti itemCountmenunjukkan nilai yang lebih besar dari 1. Misalnya, itemCount==10 berarti dari 10 panggilan ke trackDependency(), proses pengambilan sampel mengirimkan hanya salah satunya. Untuk mendapatkan jumlah dependensi yang benar yang disegmentasikan oleh komponen target, gunakan kode seperti:

dependencies
| summarize sum(itemCount) by target

Untuk mengaitkan pengecualian dengan permintaan terkait, gunakan gabungan:

dependencies
| join (requests) on operation_Id

Menghapus data

Biasanya, SDK mengirimkan data pada interval tetap, biasanya 30 detik, atau setiap kali buffer penuh, biasanya 500 item. Dalam beberapa kasus, Anda mungkin ingin membersihkan buffer. Contohnya adalah jika Anda menggunakan SDK dalam aplikasi yang dimatikan.

.NET

Saat Anda menggunakan Flush(), kami merekomendasikan pola ini:

telemetry.Flush();
// Allow some time for flushing before shutdown.
System.Threading.Thread.Sleep(5000);

Saat Anda menggunakan FlushAsync(), kami merekomendasikan pola ini:

await telemetryClient.FlushAsync()
// No need to sleep

Kami merekomendasikan selalu siram sebagai bagian dari penutupan aplikasi untuk menjamin bahwa telemetri tidak hilang.

Java

telemetry.flush();
//Allow some time for flushing before shutting down
Thread.sleep(5000);

Node.js

telemetry.flush();

Fungsi ini asinkron untuk saluran telemetri server.

Catatan

SDK Java dan JavaScript secara otomatis menyiram saat aplikasi dimatikan.

Pengguna yang diautentikasi

Di aplikasi web, pengguna diidentifikasi oleh cookie secara default. Pengguna mungkin dihitung lebih dari sekali jika mereka mengakses aplikasi Anda dari mesin atau browser yang berbeda, atau jika mereka menghapus cookie.

Jika pengguna masuk ke aplikasi, Anda bisa mendapatkan hitungan yang lebih akurat dengan mengatur ID pengguna yang diautentikasi di kode browser:

JavaScript

// Called when my app has identified the user.
function Authenticated(signInId) {
    var validatedId = signInId.replace(/[,;=| ]+/g, "_");
    appInsights.setAuthenticatedUserContext(validatedId);
    ...
}

Dalam aplikasi MVC web ASP.NET, misalnya:

Razor

@if (Request.IsAuthenticated)
{
    <script>
        appInsights.setAuthenticatedUserContext("@User.Identity.Name
            .Replace("\\", "\\\\")"
            .replace(/[,;=| ]+/g, "_"));
    </script>
}

Anda tidak perlu menggunakan nama masuk pengguna yang sebenarnya. Nama masuk hanya harus berupa ID yang unik bagi pengguna tersebut. Nama pengguna tidak boleh mencakup spasi atau karakter ,;=| apa pun.

ID pengguna juga diatur dalam cookie sesi dan dikirim ke server. Jika SDK server dipasang, ID pengguna yang diautentikasi dikirim sebagai bagian dari properti konteks dari telemetri klien dan server. Anda kemudian dapat memfilter dan mencarinya.

Jika aplikasi Anda mengelompokkan pengguna ke akun, Anda juga dapat meneruskan pengidentifikasi untuk akun tersebut. Pembatasan karakter yang sama berlaku.

appInsights.setAuthenticatedUserContext(validatedId, accountId);

Di Metrics Explorer, Anda bisa membuat bagan yang menghitung Pengguna, Diautentikasi, dan Akun pengguna.

Anda juga dapat mencari poin data klien dengan nama pengguna dan akun tertentu.

Catatan

Properti EnableAuthenticationTrackingJavaScript di kelas ApplicationInsightsServiceOptions di SDK .NET Core menyederhanakan konfigurasi JavaScript yang diperlukan untuk menyuntikkan nama pengguna sebagai ID Auth untuk setiap jejak yang dikirim oleh Application Insights JavaScript SDK.

Ketika properti ini diatur ke true, nama pengguna dari pengguna di ASP.NET Core dicetak bersamaan dengan telemetri sisi klien. Untuk alasan ini, menambahkan appInsights.setAuthenticatedUserContext secara manual tidak akan diperlukan lagi karena sudah disuntikkan oleh SDK untuk ASP.NET Core. Id Auth juga akan dikirim ke server tempat SDK di .NET Core akan mengidentifikasinya dan menggunakannya untuk telemetri sisi server apa pun, seperti yang dijelaskan dalam referensi API JavaScript.

Untuk aplikasi JavaScript yang tidak berfungsi dengan cara yang sama seperti ASP.NET Core MVC (seperti aplikasi web SPA), Anda masih perlu menambahkan appInsights.setAuthenticatedUserContext secara manual.

Memfilter, mencari, dan mensegmentasi data Anda dengan menggunakan properti

Anda dapat melampirkan properti dan pengukuran ke peristiwa Anda, metrik, tampilan halaman, pengecualian, dan data telemetri lainnya.

Properti adalah nilai untai (karakter) yang bisa Anda gunakan untuk memfilter telemetri Anda dalam laporan penggunaan. Misalnya, jika aplikasi menyediakan beberapa game, Anda dapat melampirkan nama game ke setiap peristiwa sehingga Anda dapat melihat game mana yang lebih populer.

Ada batas 8.192 pada panjang untai. Jika Anda ingin mengirim potongan data yang besar, gunakan parameter pesan TrackTrace.

Metrik adalah nilai numerik yang dapat disajikan secara grafis. Misalnya, Anda mungkin ingin melihat apakah ada peningkatan skor yang dicapai gamer secara bertahap. Grafik dapat disegmentasi oleh properti yang dikirim dengan peristiwa, sehingga Anda bisa mendapatkan grafik terpisah atau tertumpuk untuk game yang berbeda.

Nilai metrik harus lebih besar dari atau sama dengan 0 untuk ditampilkan dengan benar.

Ada beberapa batasan jumlah properti, nilai properti, dan metrik yang bisa Anda gunakan.

JavaScript

appInsights.trackEvent({
  name: 'some event',
  properties: { // accepts any type
    prop1: 'string',
    prop2: 123.45,
    prop3: { nested: 'objects are okay too' }
  }
});

appInsights.trackPageView({
  name: 'some page',
  properties: { // accepts any type
    prop1: 'string',
    prop2: 123.45,
    prop3: { nested: 'objects are okay too' }
  }
});

// Set up some properties and metrics:
var properties = new Dictionary <string, string>
    {{"game", currentGame.Name}, {"difficulty", currentGame.Difficulty}};
var metrics = new Dictionary <string, double>
    {{"Score", currentGame.Score}, {"Opponents", currentGame.OpponentCount}};

// Send the event:
telemetry.TrackEvent("WinGame", properties, metrics);

Node.js

// Set up some properties and metrics:
var properties = {"game": currentGame.Name, "difficulty": currentGame.Difficulty};
var metrics = {"Score": currentGame.Score, "Opponents": currentGame.OpponentCount};

// Send the event:
telemetry.trackEvent({name: "WinGame", properties: properties, measurements: metrics});

Visual Basic

' Set up some properties:
Dim properties = New Dictionary (Of String, String)
properties.Add("game", currentGame.Name)
properties.Add("difficulty", currentGame.Difficulty)

Dim metrics = New Dictionary (Of String, Double)
metrics.Add("Score", currentGame.Score)
metrics.Add("Opponents", currentGame.OpponentCount)

' Send the event:
telemetry.TrackEvent("WinGame", properties, metrics)

Java

Map<String, String> properties = new HashMap<String, String>();
properties.put("game", currentGame.getName());
properties.put("difficulty", currentGame.getDifficulty());

Map<String, Double> metrics = new HashMap<String, Double>();
metrics.put("Score", currentGame.getScore());
metrics.put("Opponents", currentGame.getOpponentCount());

telemetry.trackEvent("WinGame", properties, metrics);

Catatan

Pastikan Anda tidak mencatat informasi pengidentifikasi pribadi di properti.

Cara alternatif untuk mengatur properti dan metrik

Jika lebih nyaman, Anda dapat mengumpulkan parameter peristiwa di objek terpisah:

var event = new EventTelemetry();

event.Name = "WinGame";
event.Metrics["processingTime"] = stopwatch.Elapsed.TotalMilliseconds;
event.Properties["game"] = currentGame.Name;
event.Properties["difficulty"] = currentGame.Difficulty;
event.Metrics["Score"] = currentGame.Score;
event.Metrics["Opponents"] = currentGame.Opponents.Length;

telemetry.TrackEvent(event);

Peringatan

Jangan gunakan kembali contoh item telemetri yang sama (event dalam contoh ini) untuk memanggil Track*() beberapa kali. Praktik ini dapat menyebabkan telemetri dikirim dengan konfigurasi yang salah.

Pengukuran dan properti kustom di Analitik Log

Di Analitik Log, metrik dan properti kustom ditampilkan di atribut customMeasurements dan customDimensions dari masing-masing rekaman telemetri.

Misalnya, jika Anda menambahkan properti bernama "game" ke telemetri permintaan Anda, kueri ini menghitung kemunculan nilai "game" yang berbeda, dan menunjukkan rata-rata metrik kustom "skor":

requests
| summarize sum(itemCount), avg(todouble(customMeasurements.score)) by tostring(customDimensions.game)

Perhatikan bahwa:

Ketika Anda mengekstrak nilai dari JSON customDimensions atau customMeasurements, nilai tersebut memiliki jenis dinamis, jadi Anda harus mentransmisikan tostring atau todouble.
Untuk memperhitungkan kemungkinan pengambilan sampel, gunakan sum(itemCount), bukan count().

Peristiwa pengaturan waktu

Terkadang Anda ingin membuat bagan berapa lama waktu yang diperlukan untuk melakukan tindakan. Misalnya, Anda mungkin ingin tahu berapa lama waktu yang dibutuhkan pengguna untuk mempertimbangkan pilihan dalam game. Untuk mendapatkan informasi ini, gunakan parameter pengukuran.

var stopwatch = System.Diagnostics.Stopwatch.StartNew();

// ... perform the timed action ...

stopwatch.Stop();

var metrics = new Dictionary <string, double>
    {{"processingTime", stopwatch.Elapsed.TotalMilliseconds}};

// Set up some properties:
var properties = new Dictionary <string, string>
    {{"signalSource", currentSignalSource.Name}};

// Send the event:
telemetry.TrackEvent("SignalProcessed", properties, metrics);

Java

long startTime = System.currentTimeMillis();

// Perform timed action

long endTime = System.currentTimeMillis();
Map<String, Double> metrics = new HashMap<>();
metrics.put("ProcessingTime", (double)endTime-startTime);

// Setup some properties
Map<String, String> properties = new HashMap<>();
properties.put("signalSource", currentSignalSource.getName());

// Send the event
telemetry.trackEvent("SignalProcessed", properties, metrics);

Properti default untuk telemetri kustom

Jika Anda ingin mengatur nilai properti default untuk beberapa peristiwa kustom yang Anda tulis, atur dalam instans TelemetryClient. Mereka melekat pada setiap item telemetri yang dikirim dari klien tersebut.

using Microsoft.ApplicationInsights.DataContracts;

var gameTelemetry = new TelemetryClient();
gameTelemetry.Context.GlobalProperties["Game"] = currentGame.Name;
// Now all telemetry will automatically be sent with the context property:
gameTelemetry.TrackEvent("WinGame");

Visual Basic

Dim gameTelemetry = New TelemetryClient()
gameTelemetry.Context.GlobalProperties("Game") = currentGame.Name
' Now all telemetry will automatically be sent with the context property:
gameTelemetry.TrackEvent("WinGame")

Java

import com.microsoft.applicationinsights.TelemetryClient;
import com.microsoft.applicationinsights.TelemetryContext;
...

TelemetryClient gameTelemetry = new TelemetryClient();
TelemetryContext context = gameTelemetry.getContext();
context.getProperties().put("Game", currentGame.Name);

gameTelemetry.TrackEvent("WinGame");

Node.js

var gameTelemetry = new applicationInsights.TelemetryClient();
gameTelemetry.commonProperties["Game"] = currentGame.Name;

gameTelemetry.TrackEvent({name: "WinGame"});

Panggilan telemetri individual dapat menggantikan nilai default dalam kamus properti mereka.

Untuk klien web JavaScript, gunakan inisialisasi telemetri JavaScript.

Untuk menambahkan properti ke semua telemetri, termasuk data dari modul pengumpulan standar, terapkan ITelemetryInitializer.

Telemetri sampel, filter, dan proses

Lihat Memfilter dan melakukan praproscesing telemetri di Application Insights SDK.

Nonaktifkan telemetri

Untuk secara dinamis menghentikan dan memulai pengumpulan dan transmisi telemetri dari server:

using  Microsoft.ApplicationInsights.Extensibility;

TelemetryConfiguration.Active.DisableTelemetry = true;

Java

telemetry.getConfiguration().setTrackingDisabled(true);

Untuk menonaktifkan kolektor standar yang dipilih, misalnya, penghitung kinerja, permintaan HTTP, atau dependensi, menghapus atau mengomentari baris yang relevan di ApplicationInsights.config. Misalnya, jika Anda ingin mengirimkan data TrackRequest Anda sendiri.

Node.js

telemetry.config.disableAppInsights = true;

Untuk menonaktifkan kolektor standar yang dipilih, misalnya, penghitung kinerja, permintaan HTTP, atau dependensi, pada waktu inisialisasi, metode konfigurasi rantai ke kode inisialisasi SDK Anda.

applicationInsights.setup()
    .setAutoCollectRequests(false)
    .setAutoCollectPerformance(false)
    .setAutoCollectExceptions(false)
    .setAutoCollectDependencies(false)
    .setAutoCollectConsole(false)
    .start();

Untuk menonaktifkan kolektor ini setelah inisialisasi, gunakan objek Konfigurasi: applicationInsights.Configuration.setAutoCollectRequests(false).

Mode pengembang

Selama debugging, perlu untuk mempercepat telemetri Anda melalui alur sehingga Anda dapat melihat hasilnya dengan segera. Anda juga mendapatkan pesan lain yang membantu Anda melacak masalah dengan telemetri. Matikan dalam produksi, karena dapat memperlambat aplikasi Anda.

TelemetryConfiguration.Active.TelemetryChannel.DeveloperMode = true;

Visual Basic

TelemetryConfiguration.Active.TelemetryChannel.DeveloperMode = True

Node.js

Misalnya Node.js, Anda dapat mengaktifkan mode pengembang dengan mengaktifkan pengelogan internal melalui setInternalLogging dan pengaturan maxBatchSize ke 0, yang menyebabkan telemetri Anda dikirim segera setelah dikumpulkan.

applicationInsights.setup("ikey")
  .setInternalLogging(true, true)
  .start()
applicationInsights.defaultClient.config.maxBatchSize = 0;

Atur tombol instrumentasi untuk telemetri kustom yang dipilih

var telemetry = new TelemetryClient();
telemetry.InstrumentationKey = "---my key---";
// ...

Kunci instrumentasi dinamis

Untuk menghindari pencampuran telemetri dari lingkungan pengembangan, pengujian, dan produksi, Anda dapat membuat sumber daya Application Insights terpisah dan mengubah kuncinya, tergantung pada lingkungannya.

Alih-alih mendapatkan kunci instrumentasi dari file konfigurasi, Anda dapat mengaturnya di kode Anda. Atur kunci dalam metode inisialisasi, seperti global.aspx.cs dalam layanan ASP.NET:

protected void Application_Start()
{
    Microsoft.ApplicationInsights.Extensibility.
    TelemetryConfiguration.Active.InstrumentationKey =
        // - for example -
        WebConfigurationManager.Settings["ikey"];
    ...
}

JavaScript

appInsights.config.instrumentationKey = myKey;

Di halaman web, Anda mungkin ingin mengaturnya dari status server web, daripada mengodekannya secara harfiah ke dalam skrip. Misalnya, di halaman web yang dibuat di ASP.NET aplikasi:

JavaScript dalam Razor

<script type="text/javascript">
// Standard Application Insights webpage script:
var appInsights = window.appInsights || function(config){ ...
// Modify this part:
}({instrumentationKey:
    // Generate from server property:
    @Microsoft.ApplicationInsights.Extensibility.
        TelemetryConfiguration.Active.InstrumentationKey;
}) // ...

    String instrumentationKey = "00000000-0000-0000-0000-000000000000";

    if (instrumentationKey != null)
    {
        TelemetryConfiguration.getActive().setInstrumentationKey(instrumentationKey);
    }

TelemetryContext

TelemetryClient memiliki properti Context, yang berisi nilai yang dikirim bersama dengan semua data telemetri. Biasanya ditetapkan oleh modul telemetri standar, tetapi Anda juga dapat mengaturnya sendiri. Contohnya:

telemetry.Context.Operation.Name = "MyOperationName";

Jika Anda menetapkan sendiri nilai-nilai ini, pertimbangkan untuk menghapus baris yang relevan dari ApplicationInsights.config, sehingga nilai dan nilai standar Anda tidak menjadi bingung.

Komponen: Aplikasi dan versinya.
Perangkat: Data tentang perangkat tempat aplikasi dijalankan. Di aplikasi web, ini adalah server atau perangkat klien tempat telemetri dikirim.
InstrumentationKey: Sumber daya Application Insights di Azure tempat telemetri muncul. Ini biasanya diambil dari ApplicationInsights.config.
Lokasi: Lokasi geografis perangkat.
Operasi: Di aplikasi web, permintaan HTTP saat ini. Di jenis aplikasi lainnya, Anda dapat mengatur nilai ini ke peristiwa grup bersamaan.
- ID: Nilai yang dihasilkan yang menghubungkan peristiwa yang berbeda, sehingga ketika Anda memeriksa peristiwa apa pun di Pencarian Diagnostik, Anda dapat menemukan item terkait.
- Nama: Pengidentifikasi, biasanya URL permintaan HTTP.
- SyntheticSource: Jika tidak null atau kosong, untai (karakter) yang menunjukkan bahwa sumber permintaan telah diidentifikasi sebagai robot atau tes web. Secara default, itu dikecualikan dari perhitungan di Penjelajah Metrik.
Sesi: Sesi pengguna. ID diatur ke nilai yang dihasilkan, yang diubah ketika pengguna belum aktif untuk sementara waktu.
Pengguna: Informasi Pengguna.

Batas

Ada beberapa batasan jumlah metrik dan acara per aplikasi, yaitu per kunci instrumentasi. Batasan tergantung pada paket harga yang Anda pilih.

Sumber daya	Batas default	Batas maksimum	Catatan
Total data per hari	100 GB	Hubungi dukungan.	Anda dapat mengatur batas untuk mengurangi data. Jika Anda membutuhkan lebih banyak data, Anda dapat meningkatkan batasan di portal, hingga 1.000 GB. Untuk kapasitas yang lebih besar dari 1.000 GB, kirim email ke AIDataCap@microsoft.com.
Pembatasan	32.000 acara/detik	Hubungi dukungan.	Batas diukur lebih dari satu menit.
Log retensi data	30 hingga 730 hari	730 hari	Sumber daya ini untuk Log.
Metrik retensi data	90 hari	90 hari	Sumber daya ini untuk Metrics Explorer.
Pengujian multi-langkah ketersediaan retensi hasil terperinci	90 hari	90 hari	Sumber daya ini memberikan hasil terperinci dari setiap langkah.
Ukuran item telemetri maksimum	64 KB	64 KB
Item telemetri maksimum per batch	64.000	64.000
Panjang nama properti dan metrik	150	150	Lihat skema jenis.
Panjang string nilai properti	8.192	8.192	Lihat skema jenis.
Panjang pesan pelacakan dan pengecualian	32.768	32.768	Lihat skema jenis.
Jumlah pengujian ketersediaan per sumber daya Application Insights	100	100
Retensi data Profiler dan Snapshot	Dua minggu	Hubungi dukungan. Batas maksimum retensi adalah enam bulan.
Data profiler yang dikirim per hari	Tidak ada batasan	Tidak ada batasan.
Data Snapshot dikirim per hari	30 snapshot per hari per aplikasi yang dipantau	Tidak ada batasan.	Jumlah snapshot yang dikumpulkan per aplikasi dapat dimodifikasi melalui konfigurasi.

Untuk informasi selengkapnya tentang harga dan kuota, lihat tagihan Application Insights.

Untuk menghindari mencapai batas laju data, gunakan pengambilan sampel.

Untuk menentukan berapa lama data disimpan, lihat Retensi dan privasi data.

Dokumen referensi

Kode SDK

Tanya jawab umum

Bagian ini menyediakan jawaban atas pertanyaan umum.

Mengapa saya kehilangan data telemetri?

Kedua TelemetryChannels akan kehilangan telemetri buffer jika tidak dihapus sebelum aplikasi dimatikan.

Untuk menghindari kehilangan data, bersihkan TelemetryClient saat aplikasi dimatikan.

Untuk informasi selengkapnya, lihat Menghapus data.

Pengecualian apa yang mungkin diberikan `Track_()` oleh panggilan?

Tidak ada. Anda tidak perlu membungkusnya dalam klausa try-catch. Jika SDK mengalami masalah, SDK akan mencatat pesan di output konsol debug dan, jika pesan berhasil masuk, di Pencarian Diagnostik.

Apakah ada REST API untuk mendapatkan data dari portal?

Ya, API akses data. Cara lain untuk mengekstrak data termasuk Power BI jika Anda telah bermigrasi ke sumber daya berbasis ruang kerja atau ekspor berkelanjutan jika Anda masih berada di sumber daya klasik.

Mengapa panggilan saya ke peristiwa kustom dan API metrik diabaikan?

Application Insights SDK tidak kompatibel dengan autoinstrumentasi. Jika autoinstrumentasi diaktifkan, panggilan ke Track() dan api peristiwa dan metrik kustom lainnya akan diabaikan.

Nonaktifkan autoinstrumentasi di portal Azure pada tab Application Insights dari halaman App Service atau atur ApplicationInsightsAgent_EXTENSION_VERSION ke disabled.

Mengapa hitungan di bagan Penelusuran dan Metrik tidak sama?

Pengambilan sampel mengurangi jumlah item telemetri (seperti permintaan dan peristiwa kustom) yang dikirim dari aplikasi Anda ke portal. Di Pencarian, Anda akan melihat jumlah item yang diterima. Dalam bagan metrik yang menampilkan hitungan peristiwa, Anda akan melihat jumlah peristiwa asli yang terjadi.

Setiap item yang dikirimkan membawa itemCount properti yang menunjukkan berapa banyak peristiwa asli yang diwakili item tersebut. Untuk mengamati pengambilan sampel dalam operasi, Anda dapat menjalankan kueri ini di Analitik Log:

    requests | summarize original_events = sum(itemCount), transmitted_events = count()

Bagaimana cara mengatur pemberitahuan pada peristiwa?

Pemberitahuan Azure hanya ada pada metrik. Buat metrik kustom yang melewati ambang nilai setiap kali peristiwa terjadi. Kemudian, atur pemberitahuan pada metrik. Anda mendapatkan pemberitahuan setiap kali metrik melewati ambang batas ke kedua arah. Anda tidak akan mendapatkan pemberitahuan hingga persimpangan pertama, tidak peduli apakah nilai awal tinggi atau rendah. Selalu ada latensi beberapa menit.

Langkah berikutnya

Mencari peristiwa dan log

API Application Insights untuk aktivitas dan metrik kustom

Ringkasan API

Sebelum memulai

Dapatkan instans TelemetryClient

TrackEvent

Peristiwa kustom di Analitik Log

GetMetric

TrackMetric

Contoh nilai tunggal

Metrik kustom di Analitik Log

Tampilan halaman

Tampilan halaman kustom

Tampilan halaman waktu

Telemetri halaman di Analitik Log

TrackRequest

Konteks operasi

Permintaan di Analitik Log

TrackException

Pengecualian di Analitik Log

TrackTrace

Jejak di Analitik Log

TrackDependency

Dependensi di Analitik Log

Menghapus data

Pengguna yang diautentikasi

Memfilter, mencari, dan mensegmentasi data Anda dengan menggunakan properti

Cara alternatif untuk mengatur properti dan metrik

Pengukuran dan properti kustom di Analitik Log

Peristiwa pengaturan waktu

Properti default untuk telemetri kustom

Telemetri sampel, filter, dan proses

Nonaktifkan telemetri

Mode pengembang

Atur tombol instrumentasi untuk telemetri kustom yang dipilih

Kunci instrumentasi dinamis

TelemetryContext

Batas

Dokumen referensi

Kode SDK

Tanya jawab umum

Mengapa saya kehilangan data telemetri?

Pengecualian apa yang mungkin diberikan Track_() oleh panggilan?

Apakah ada REST API untuk mendapatkan data dari portal?

Mengapa panggilan saya ke peristiwa kustom dan API metrik diabaikan?

Mengapa hitungan di bagan Penelusuran dan Metrik tidak sama?

Bagaimana cara mengatur pemberitahuan pada peristiwa?

Langkah berikutnya

Sumber Daya Tambahan:

Pengecualian apa yang mungkin diberikan `Track_()` oleh panggilan?