Bagikan melalui

Mulai Cepat TraceLogging C/C++

  • Artikel

Bagian berikut menjelaskan langkah-langkah dasar yang diperlukan untuk menambahkan TraceLogging ke kode mode pengguna C/C++.

Prasyarat

  • Microsoft Visual Studio 2013 atau yang lebih baru.
  • Windows 10 Software Development Kit (SDK) diperlukan untuk menulis penyedia mode pengguna.
  • Windows Driver Kit (WDK) untuk Windows 10 diperlukan untuk menulis penyedia mode kernel.

Penting

Untuk menghindari kesalahan linker untuk fungsi , , EventWriteTransferatau EventUnregister yang belum terselesaikan, tautkan EventRegisterdengan advapi32.lib saat mengkompilasi contoh-contoh ini.

Untuk mengumpulkan dan mendekode peristiwa dari contoh ini, Anda harus memulai jejak menggunakan alat seperti tracelog atau traceview, menjalankan contoh, menghentikan jejak menggunakan alat seperti tracelog atau traceview, dan mendekode jejak menggunakan alat decoding seperti tracefmt atau traceview. Misalnya, jika penyedia saya didefinisikan menggunakan GUID {0205c616-cf97-5c11-9756-56a2cee02ca7}, saya mungkin melihat peristiwa dari contoh ini menggunakan tracelog alat Windows SDK dan tracefmt sebagai berikut:

  • tracelog -start MyTraceSession -f MyTraceFile.etl -guid #0205c616-cf97-5c11-9756-56a2cee02ca7
  • Jalankan contoh.
  • tracelog -stop MyTraceSession
  • tracefmt -o MyTraceFile.txt MyTraceFile.etl
  • notepad MyTraceFile.txt

SimpleTraceLoggingExample.h

Contoh header ini mencakup API TraceLogging dan penerusan mendeklarasikan handel penyedia yang akan digunakan untuk mencatat peristiwa. Kelas apa pun yang ingin menggunakan TraceLogging akan menyertakan header ini dan kemudian dapat memulai pengelogan.

#pragma once

#include <windows.h> // Definitions required by TraceLoggingProvider.h
#include <TraceLoggingProvider.h> // The C/C++ TraceLogging API

// Forward-declare the g_hMyComponentProvider variable that you will use for tracing in this component
TRACELOGGING_DECLARE_PROVIDER(g_hMyComponentProvider);

File header mencakup TraceLoggingProvider.h yang menentukan API TraceLogging C/C++. Anda harus menyertakan windows.h terlebih dahulu karena mendefinisikan konstanta yang digunakan oleh TraceLoggingProvider.h.

Penerusan file header mendeklarasikan handel g_hMyComponentProvider penyedia yang akan Anda teruskan ke API TraceLogging untuk mencatat peristiwa. Handel ini harus dapat diakses oleh kode apa pun yang ingin menggunakan TraceLogging.

TRACELOGGING_DECLARE_PROVIDER adalah makro yang membuat extern const TraceLoggingHProvider handel menggunakan nama yang Anda berikan, yang dalam contoh di atas adalah g_hMyComponentProvider. Anda akan mengalokasikan variabel handel penyedia aktual dalam file kode.

SimpleTraceLoggingExample.cpp

Contoh berikut mendaftarkan penyedia, mencatat peristiwa, dan membatalkan pendaftaran penyedia.

#include "SimpleTraceLoggingExample.h"

// Define a handle to a TraceLogging provider
TRACELOGGING_DEFINE_PROVIDER(
    g_hMyComponentProvider,
    "SimpleTraceLoggingProvider",
    // {0205c616-cf97-5c11-9756-56a2cee02ca7}
    (0x0205c616,0xcf97,0x5c11,0x97,0x56,0x56,0xa2,0xce,0xe0,0x2c,0xa7));

void main()
{

    char sampleValue[] = "Sample value";

    // Register the provider
    TraceLoggingRegister(g_hMyComponentProvider);

    // Log an event
    TraceLoggingWrite(g_hMyComponentProvider, // handle to my provider
        "HelloWorldTestEvent",              // Event Name that should uniquely identify your event.
        TraceLoggingValue(sampleValue, "TestMessage")); // Field for your event in the form of (value, field name).

    // Stop TraceLogging and unregister the provider
    TraceLoggingUnregister(g_hMyComponentProvider);
}

Contoh di atas mencakup SimpleTraceLoggingExample.h yang berisi variabel penyedia global yang akan digunakan kode Anda untuk mencatat peristiwa.

Makro TRACELOGGING_DEFINE_PROVIDER mengalokasikan penyimpanan dan menentukan variabel handel penyedia. Nama variabel yang Anda berikan ke makro ini harus cocok dengan nama yang Anda gunakan di makro TRACELOGGING_DECLARE_PROVIDER dalam file header Anda.

Mendaftarkan handel penyedia

Sebelum Anda dapat menggunakan handel penyedia untuk mencatat peristiwa, Anda harus memanggil TraceLoggingRegister untuk mendaftarkan handel penyedia Anda. Ini biasanya dilakukan di main() atau DLLMain() tetapi dapat dilakukan kapan saja selama mendahului upaya untuk mencatat peristiwa. Jika Anda mencatat peristiwa sebelum mendaftarkan handel penyedia, tidak ada kesalahan yang akan terjadi tetapi peristiwa tidak akan dicatat. Kode berikut dari contoh di atas mendaftarkan handel penyedia.

// Define the GUID to use in TraceLoggingProviderRegister
TRACELOGGING_DEFINE_PROVIDER(
    g_hMyComponentProvider,
    "SimpleTraceLoggingProvider",
    // {0205c616-cf97-5c11-9756-56a2cee02ca7}
    (0x0205c616,0xcf97,0x5c11,0x97,0x56,0x56,0xa2,0xce,0xe0,0x2c,0xa7));

void main()
{
    char sampleValue[] = "Sample value";

    // Register the provider
    TraceLoggingRegister(g_hMyComponentProvider);

Mencatat peristiwa Pelacakan

Setelah penyedia terdaftar, kode berikut mencatat peristiwa sederhana.

    // Log an event
    TraceLoggingWrite(g_hMyComponentProvider, // handle to my provider
        "HelloWorldTestEvent",              // Event Name that should uniquely identify your event.
        TraceLoggingValue(sampleValue, "TestMessage")); // Field for your event in the form of (value, field name).

Makro TraceLoggingWrite menerima hingga sembilan puluh sembilan argumen. Nama peristiwa disimpan dalam format UTF-8. Anda tidak boleh menggunakan karakter yang disematkan '\0' dalam nama peristiwa atau nama bidang. Tidak ada batasan lain pada karakter yang diizinkan, meskipun beberapa dekode peristiwa atau prosesor peristiwa mungkin memiliki batasannya sendiri.

Setiap argumen yang mengikuti nama peristiwa harus dibungkus di dalam Makro Pembungkus TraceLogging. Jika Anda menggunakan C++, Anda dapat menggunakan TraceLoggingValue makro pembungkus untuk secara otomatis menyimpulkan jenis argumen. Jika Anda menulis di C atau jika Anda ingin kontrol lebih besar atas jenis bidang, Anda harus menggunakan makro bidang khusus jenis seperti TraceLoggingInt32, , TraceLoggingUnicodeStringTraceLoggingString, dll.

Selain mencatat peristiwa tunggal, Anda juga dapat mengelompokkan peristiwa berdasarkan aktivitas dengan menggunakan makro TraceLoggingWriteActivity atau TraceLoggingWriteStart/TraceLoggingWriteStop yang ditemukan di TraceLoggingActivity.h. Aktivitas menghubungkan peristiwa dan berguna untuk skenario yang memiliki awal dan akhir. Misalnya, Anda dapat menggunakan aktivitas untuk mengukur skenario yang dimulai dengan peluncuran aplikasi, termasuk waktu yang diperlukan untuk layar splash menjadi tersedia, dan berakhir ketika layar awal aplikasi menjadi terlihat.

Aktivitas menangkap peristiwa tunggal dan menumpuk aktivitas lain yang terjadi antara awal dan akhir aktivitas tersebut. Aktivitas memiliki cakupan per proses dan harus diteruskan dari utas ke utas untuk menumpuk peristiwa multi-utas dengan benar.

Cakupan handel penyedia terbatas pada modul (file DLL, EXE, atau SYS) tempatnya ditentukan. Handel tidak boleh diteruskan ke DLL lain. Jika makro TraceLoggingWrite dipanggil di A.DLL menggunakan handel penyedia yang ditentukan dalam B.DLL, itu dapat menyebabkan masalah. Cara paling aman dan paling efisien untuk memenuhi persyaratan ini adalah dengan selalu secara langsung mereferensikan handel penyedia global dan tidak pernah melewati handel penyedia sebagai parameter.

Membatalkan pendaftaran penyedia

Sebelum komponen dibongkar, Anda harus membatalkan pendaftaran penyedia TraceLogging. Ini sangat penting untuk DLL dan driver. Crash kemungkinan terjadi jika DLL atau driver dibongkar tanpa membatalkan pendaftaran penyedia.

Kode berikut membatalkan pendaftaran penyedia:

// Stop TraceLogging and unregister the provider
TraceLoggingUnregister(g_hMyComponentProvider);

Kompatibilitas

Tergantung pada konfigurasinya, TraceLoggingProvider.h dapat kompatibel mundur (program yang dihasilkan akan berjalan diWindows Vista atau yang lebih baru), atau dapat dioptimalkan untuk versi OS yang lebih baru. TraceLoggingProvider.h menggunakan WINVER (mode pengguna) dan NTDDI_VERSION (mode kernel) untuk menentukan apakah harus kompatibel dengan versi OS sebelumnya atau dioptimalkan untuk versi OS yang lebih baru.

Untuk mode pengguna, jika Anda menyertakan <windows.h> sebelum mengatur WINVER, <windows.h> mengatur WINVER ke versi OS target default SDK. Jika WINVER diatur ke 0x602 atau lebih tinggi, TraceLoggingProvider.h mengoptimalkan perilakunya untuk Windows 8 atau yang lebih baru dan aplikasi Anda tidak akan berjalan pada versi Windows yang lebih lama. Jika Anda memerlukan program untuk berjalan di Vista atau Windows 7, pastikan untuk mengatur WINVER ke nilai yang sesuai sebelum menyertakan <windows.h>.

Demikian pula, jika Anda menyertakan <wdm.h> sebelum mengatur NTDDI_VERSION, <wdm.h> mengatur NTDDI_VERSION ke nilai default. Jika NTDDI_VERSION diatur ke 0x06040000 atau lebih tinggi, TraceLoggingProvider.h mengoptimalkan perilakunya untuk Windows 10 dan driver Anda tidak akan berfungsi pada versi Windows sebelumnya.

Perilaku ini dapat dikontrol arah dengan mengatur TLG_HAVE_EVENT_SET_INFORMATION sebelum menyertakan TraceLoggingProvider.h. Lihat komentar di TraceLoggingProvider.h header untuk detail tentang TLG_HAVE_EVENT_SET_INFORMATION makro.

Ringkasan dan langkah berikutnya

Untuk melihat cara mengambil dan melihat data TraceLogging menggunakan Windows Performance Tools (WPT), lihat Peristiwa Rekaman dan Tampilkan TraceLogging.

Lihat Contoh Pelacakan C/C++ untuk contoh TraceLogging C++ lainnya.