struktur EVENT_TRACE_LOGFILEA (evntrace.h)
Struktur EVENT_TRACE_LOGFILE menyimpan informasi tentang sumber data pelacakan.
Struktur EVENT_TRACE_LOGFILE digunakan saat memanggil OpenTrace. Pengguna menyediakan struktur EVENT_TRACE_LOGFILE dengan informasi tentang sumber data pelacakan (baik nama file ETL atau nama sesi pencatat real-time aktif), bendera pemrosesan pelacakan, dan fungsi panggilan balik yang akan menerima data pelacakan. Setelah berhasil, OpenTrace mengisi bidang struktur yang tersisa untuk mengembalikan detail tentang sumber data pelacakan.
Ketika ProcessTrace memproses buffer, ProcessTrace memanggil BufferCallback yang ditentukan pengguna dengan struktur EVENT_TRACE_LOGFILE untuk memberikan informasi tentang sesi pemrosesan peristiwa dan buffer.
Sintaks
typedef struct _EVENT_TRACE_LOGFILEA {
LPSTR LogFileName;
LPSTR LoggerName;
LONGLONG CurrentTime;
ULONG BuffersRead;
union {
ULONG LogFileMode;
ULONG ProcessTraceMode;
} DUMMYUNIONNAME;
EVENT_TRACE CurrentEvent;
TRACE_LOGFILE_HEADER LogfileHeader;
PEVENT_TRACE_BUFFER_CALLBACKA BufferCallback;
ULONG BufferSize;
ULONG Filled;
ULONG EventsLost;
union {
PEVENT_CALLBACK EventCallback;
PEVENT_RECORD_CALLBACK EventRecordCallback;
} DUMMYUNIONNAME2;
ULONG IsKernelTrace;
PVOID Context;
} EVENT_TRACE_LOGFILEA, *PEVENT_TRACE_LOGFILEA;
Anggota
LogFileName
Nama file log yang sedang diproses, atau NULL jika memproses data dari sesi pelacakan real time. Tentukan nilai untuk anggota ini jika Anda memanggil OpenTrace untuk menggunakan data dari file log.
Saat memanggil OpenTrace, jika LoggerNamenon-NULL maka LogFileName harus NULL.
Saat memanggil OpenTrace, pengguna yang menggunakan peristiwa harus memiliki izin untuk membaca file.
Catatan
Nama file yang disediakan untuk OpenTrace melalui bidang LogFileName harus berupa nama file lengkap, termasuk akhiran apa pun. Beberapa API pembuatan file jejak dapat secara diam-diam menambahkan akhiran ke nama file yang ditentukan pengguna. Misalnya, jika pengontrol mencatat peristiwa ke sesi privat (pengontrol mengatur anggota EVENT_TRACE_PROPERTIES LogFileMode ke EVENT_TRACE_PRIVATE_LOGGER_MODE saat memanggil StartTrace), file ETL yang dihasilkan akan menyertakan akhiran ID proses, misalnya mytrace.etl_123.
Ini juga dapat terjadi jika file dibuat menggunakan mode EVENT_TRACE_FILE_MODE_NEWFILE , dalam hal ini file ETL yang dihasilkan akan menyertakan nomor urutan.
LoggerName
Nama sesi pelacakan peristiwa real time, atau NULL jika memproses data dari file log. Tentukan nilai untuk anggota ini jika Anda memanggil OpenTrace untuk menggunakan data dari sesi real-time.
Saat memanggil OpenTrace, jika LogFileNamenon-NULL maka LoggerName harus NULL.
Anda hanya dapat menggunakan peristiwa secara real time jika pengontrol jejak telah mengatur anggota logFileModeEVENT_TRACE_PROPERTIES untuk menyertakan bendera EVENT_TRACE_REAL_TIME_MODE .
Hanya pengguna dengan hak istimewa administratif, pengguna di grup Pengguna Log Performa, dan aplikasi yang berjalan sebagai LocalSystem, LocalService, NetworkService yang dapat mengonsumsi peristiwa secara real time. Untuk memberi pengguna terbatas kemampuan untuk menggunakan peristiwa secara real time, tambahkan ke grup Pengguna Log Performa atau panggil EventAccessControl.
Windows XP dan Windows 2000: Siapa pun dapat mengonsumsi peristiwa real time.
CurrentTime
Pada output, waktu saat ini, dalam interval 100 nanodetik sejak tengah malam, 1 Januari 1601.
BuffersRead
Pada output, jumlah buffer yang diproses.
DUMMYUNIONNAME
DUMMYUNIONNAME.LogFileMode
Dicadangkan. Jangan gunakan.
DUMMYUNIONNAME.ProcessTraceMode
Mode untuk memproses peristiwa. Mode didefinisikan dalam evntcons.h file header. Anda dapat menentukan satu atau beberapa mode berikut:
PROCESS_TRACE_MODE_EVENT_RECORD
Tentukan mode ini jika Anda ingin menerima peristiwa dalam format EVENT_RECORD baru (sangat disarankan). Untuk menerima peristiwa dalam format baru, Anda harus menentukan panggilan balik di anggota EventRecordCallback . Jika Anda tidak menentukan mode ini, Anda akan menerima peristiwa dalam format lama melalui panggilan balik yang ditentukan dalam anggota EventCallback .
Sebelum Windows Vista: Tidak didukung.
PROCESS_TRACE_MODE_RAW_TIMESTAMP
Secara default, ProcessTrace mengonversi TimeStamp peristiwa dari format mentah asli (waktu sistem, waktu QPC, atau penghitung siklus CPU) menjadi waktu sistem (interval 100 nanodetik sejak tengah malam, 1 Januari 1601).
Tentukan bendera PROCESS_TRACE_MODE_RAW_TIMESTAMP jika Anda tidak ingin nilai stempel waktu di anggota TimeStampEVENT_HEADER dan EVENT_TRACE_HEADER dikonversi ke waktu sistem. Jika bendera ini ditentukan, ProcessTrace akan meninggalkan nilai stempel waktu dalam format asli yang ditentukan pengontrol dalam anggota Wnode.ClientContextdari EVENT_TRACE_PROPERTIES.
Sebelum Windows Vista: Tidak didukung.
PROCESS_TRACE_MODE_REAL_TIME
Tentukan mode ini untuk menerima peristiwa secara real time. Anda harus menentukan mode ini jika LoggerName bukan NULL.
CurrentEvent
Pada output, struktur EVENT_TRACE yang berisi peristiwa terakhir yang diproses.
LogfileHeader
Pada output, struktur TRACE_LOGFILE_HEADER yang berisi informasi umum tentang sesi dan komputer tempat sesi berjalan.
BufferCallback
Arahkan ke fungsi BufferCallback yang menerima statistik terkait buffer untuk setiap buffer flush ETW. ETW memanggil panggilan balik ini setelah mengirimkan semua peristiwa di buffer. Panggilan balik ini bersifat opsional.
BufferSize
Pada output, berisi ukuran setiap buffer, dalam byte.
Filled
Pada output, berisi jumlah byte dalam buffer yang berisi informasi yang valid.
EventsLost
Tidak digunakan.
DUMMYUNIONNAME2
DUMMYUNIONNAME2.EventCallback
Arahkan ke fungsi EventCallback yang dipanggil ETW untuk setiap peristiwa di buffer. Bidang ini hanya digunakan jika bidang ProcessTraceMode tidak menyertakan PROCESS_TRACE_MODE_EVENT_RECORD bendera .
Catatan
Bidang EventCallback akan diperlakukan sebagai EventRecordCallback jika bidang ProcessTraceMode menyertakan PROCESS_TRACE_MODE_EVENT_RECORD bendera . Jika EventCallback Anda menerima data yang tidak rusak dari ProcessTrace, verifikasi bahwa bidang ProcessTraceMode tidak menyertakan PROCESS_TRACE_MODE_EVENT_RECORD bendera .
Tip
Kode baru harus menggunakan EventRecordCallback alih-alih EventCallback. EventRecordCallback menerima EVENT_RECORD yang berisi informasi peristiwa yang lebih lengkap, dapat digunakan dengan API pendekodean seperti TdhGetEventInformation, dan memiliki penunjuk konteks yang dapat digunakan oleh panggilan balik Anda.
DUMMYUNIONNAME2.EventRecordCallback
Arahkan ke fungsi EventRecordCallback yang dipanggil ETW untuk setiap peristiwa di buffer. Bidang ini hanya digunakan jika bidang ProcessTraceMode menyertakan PROCESS_TRACE_MODE_EVENT_RECORD bendera .
Catatan
Bidang EventRecordCallback akan diperlakukan sebagai EventCallback jika bidang ProcessTraceMode tidak menyertakan PROCESS_TRACE_MODE_EVENT_RECORD bendera. Jika EventRecordCallback Anda menerima data yang kacau dari ProcessTrace, verifikasi bahwa bidang ProcessTraceMode menyertakan PROCESS_TRACE_MODE_EVENT_RECORD bendera .
Sebelum Windows Vista: Tidak didukung.
IsKernelTrace
Pada output, jika anggota ini TRUE, sesi pelacakan peristiwa adalah NT Kernel Logger. Jika tidak, ini adalah sesi pelacakan peristiwa lain.
Context
Data konteks yang dapat ditentukan konsumen saat memanggil OpenTrace. Jika konsumen menggunakan EventRecordCallback untuk menggunakan peristiwa, ETW menetapkan anggota UserContext dari struktur EVENT_RECORD ke nilai ini.
Sebelum Windows Vista: Tidak didukung.
Keterangan
Konsumen peristiwa harus:
- Inisialisasi memori untuk struktur ini ke nol.
- Jika membaca dari file ETL, atur LogFileName ke jalur ke file.
Jika tidak (yaitu jika membaca dari sesi real-time), atur LoggerName ke nama sesi dan atur ProcessTraceMode ke
PROCESS_TRACE_MODE_REAL_TIME. - Jika menggunakan EventRecordCallback (disarankan), atur EventRecordCallback ke alamat fungsi panggilan balik rekaman peristiwa Anda, atur Konteks ke nilai yang akan diberikan ke panggilan balik Anda, dan tambahkan
PROCESS_TRACE_MODE_EVENT_RECORDke ProcessTraceMode. Jika tidak (yaitu jika menggunakan EventCallback), atur EventCallback ke alamat fungsi panggilan balik peristiwa Anda. - Jika Anda memerlukan panggilan balik setelah setiap buffer diproses, atur BufferCallback ke alamat fungsi panggilan balik buffer Anda.
- Jika Anda menginginkan data tanda waktu mentah asli alih-alih tanda waktu yang diproses, tambahkan
PROCESS_TRACE_MODE_RAW_TIMESTAMPke ProcessTraceMode. - Hubungi OpenTrace. Perhatikan bahwa jika berhasil, fungsi OpenTrace akan mengisi anggota struktur ini dengan informasi dari sumber data pelacakan.
- Panggil ProcessTrace dengan handel yang dikembalikan oleh OpenTrace.
- ProcessTrace akan memanggil fungsi panggilan balik peristiwa Anda untuk setiap peristiwa.
- ProcessTrace akan memanggil fungsi panggilan balik buffer Anda (jika disediakan) setelah menyelesaikan setiap buffer dan akan menyertakan instans struktur EVENT_TRACE_LOGFILE dengan informasi status pemrosesan jejak.
- Setelah pemrosesan jejak selesai, panggil CloseTrace untuk menutup handel yang dikembalikan oleh OpenTrace.
Catatan
Header evntrace.h mendefinisikan EVENT_TRACE_LOGFILE sebagai alias yang secara otomatis memilih versi ANSI atau Unicode dari fungsi ini berdasarkan definisi konstanta pra-prosesor UNICODE. Mencampur penggunaan alias encoding-netral dengan kode yang tidak mengodekan-netral dapat menyebabkan ketidakcocokan yang mengakibatkan kesalahan kompilasi atau runtime. Untuk informasi selengkapnya, lihat Konvensi untuk Prototipe Fungsi.
Persyaratan
| Klien minimum yang didukung | Windows 2000 Professional [hanya aplikasi desktop] |
| Server minimum yang didukung | Windows 2000 Server [hanya aplikasi desktop] |
| Header | evntrace.h |
Lihat juga
Saran dan Komentar
Segera hadir: Sepanjang tahun 2024 kami akan menghentikan penggunaan GitHub Issues sebagai mekanisme umpan balik untuk konten dan menggantinya dengan sistem umpan balik baru. Untuk mengetahui informasi selengkapnya, lihat: https://aka.ms/ContentUserFeedback.
Kirim dan lihat umpan balik untuk