Bagikan melalui

utilitas analisis performa dotnet-trace

Artikel ini berlaku untuk: ✔️ dotnet-trace 9.0.661903 dan versi yang lebih baru

Instal

Ada dua cara untuk mengunduh dan menginstal dotnet-trace:

Sinopsis

dotnet-trace [-h, --help] [--version] <command>

Deskripsi

Alat dotnet-trace:

  • Adalah alat .NET Core lintas platform.

  • Memungkinkan pengumpulan jejak .NET Core dari proses yang sedang berjalan tanpa profiler asli.

  • Dibangun pada EventPipe runtime bahasa umum .NET Core.

  • Mendukung dua cara berbeda untuk mengumpulkan jejak:

    Fitur collect collect-linux
    OS yang didukung Apa saja Hanya Linux, versi >kernel = 6.4
    Memerlukan Hak Istimewa Admin/Root Tidak. Yes
    Melacak semua proses secara bersamaan Tidak. Didukung
    Mengambil pustaka asli dan peristiwa kernel Tidak. Didukung
    Callstack peristiwa mencakup bingkai asli Tidak. Yes

Opsi

  • -h|--help

    Tampilkan bantuan baris perintah.

  • --version

    Menampilkan versi utilitas dotnet-trace.

Perintah

Perintah
dotnet-trace collect
dotnet-trace collect-linux
dotnet-trace convert
dotnet-trace ps
dotnet-trace list-profiles
laporan dotnet-trace

dotnet-trace collect

Mengumpulkan jejak diagnostik dari proses yang sedang berjalan atau meluncurkan proses anak dan melacaknya (.NET 5 atau yang lebih baru). Agar alat menjalankan proses anak dan melacaknya dari startup-nya, tambahkan -- ke perintah kumpulkan.

Sinopsis

dotnet-trace collect
    [--buffersize <size>]
    [--clreventlevel <clreventlevel>]
    [--clrevents <clrevents>]
    [--dsrouter <ios|ios-sim|android|android-emu>]
    [--format <Chromium|NetTrace|Speedscope>]
    [-h|--help]
    [--duration dd:hh:mm:ss]
    [-n, --name <name>]
    [--diagnostic-port]
    [-o|--output <trace-file-path>]
    [-p|--process-id <pid>]
    [--profile <list-of-comma-separated-profile-names>]
    [--providers <list-of-comma-separated-providers>]
    [-- <command>] (for target applications running .NET 5 or later)
    [--show-child-io]
    [--resume-runtime]
    [--stopping-event-provider-name <stoppingEventProviderName>]
    [--stopping-event-event-name <stoppingEventEventName>]
    [--stopping-event-payload-filter <stoppingEventPayloadFilter>]

Opsi

  • --buffersize <size>

    Mengatur ukuran buffer dalam memori, dalam megabyte. Default 256 MB.

    Catatan

    Jika proses target memancarkan peristiwa lebih cepat daripada yang dapat ditulis ke disk, buffer ini mungkin meluap dan beberapa peristiwa akan dihilangkan. Anda dapat mengurangi masalah ini dengan meningkatkan ukuran buffer atau mengurangi jumlah peristiwa yang direkam.

  • --clreventlevel <clreventlevel>

    Verbositas peristiwa CLR yang akan dipancarkan. Opsi ini hanya berlaku ketika --clrevents ditentukan dan tidak ditimpa oleh --profile atau --providers. Tabel berikut ini memperlihatkan tingkat peristiwa yang tersedia.

    Nilai untai (karakter) Nilai numerik
    logalways 0
    critical 1
    error 2
    warning 3
    informational 4
    verbose 5

  • --clrevents <clrevents>

    Daftar kata kunci penyedia runtime CLR untuk mengaktifkan dipisahkan oleh tanda +. Ini adalah pemetaan sederhana yang memungkinkan Anda menentukan kata kunci peristiwa melalui alias string daripada nilai heksanya. Misalnya, dotnet-trace collect --providers Microsoft-Windows-DotNETRuntime:3:4 meminta serangkaian peristiwa yang sama dengan dotnet-trace collect --clrevents gc+gchandle --clreventlevel informational. Jika penyedia Microsoft-Windows-DotNETRuntime runtime CLR juga diaktifkan melalui --providers atau --profile, opsi ini diabaikan. Tabel berikut ini memperlihatkan daftar kata kunci yang tersedia:

    Alias string kata kunci Nilai heksa kata kunci
    gc 0x1
    gchandle 0x2
    assemblyloader 0x4
    loader 0x8
    jit 0x10
    ngen 0x20
    startenumeration 0x40
    endenumeration 0x80
    security 0x400
    appdomainresourcemanagement 0x800
    jittracing 0x1000
    interop 0x2000
    contention 0x4000
    exception 0x8000
    threading 0x10000
    jittedmethodiltonativemap 0x20000
    overrideandsuppressngenevents 0x40000
    type 0x80000
    gcheapdump 0x100000
    gcsampledobjectallocationhigh 0x200000
    gcheapsurvivalandmovement 0x400000
    managedheapcollect 0x800000
    gcheapandtypenames 0x1000000
    gcsampledobjectallocationlow 0x2000000
    perftrack 0x20000000
    stack 0x40000000
    threadtransfer 0x80000000
    debugger 0x100000000
    monitoring 0x200000000
    codesymbols 0x400000000
    eventsource 0x800000000
    compilation 0x1000000000
    compilationdiagnostic 0x2000000000
    methoddiagnostic 0x4000000000
    typediagnostic 0x8000000000
    jitinstrumentationdata 0x10000000000
    profiler 0x20000000000
    waithandle 0x40000000000
    allocationsampling 0x80000000000

    Anda dapat membaca tentang penyedia CLR secara lebih rinci tentang dokumentasi referensi penyedia runtime .NET.

  • '--dsrouter {ios|ios-sim|android|android-emu}

    Memulai dotnet-dsrouter dan menyambungkannya. Memerlukan dotnet-dsrouter untuk diinstal. Jalankan dotnet-dsrouter -h untuk informasi selengkapnya.

  • --format {Chromium|NetTrace|Speedscope}

    Mengatur format output untuk konversi file pelacakan. Default adalah NetTrace.

  • -n, --name <name>

    Nama proses untuk mengumpulkan jejak.

    Catatan

    Di Linux dan macOS, menggunakan opsi ini memerlukan aplikasi target dan dotnet-trace untuk berbagi variabel lingkungan yang sama TMPDIR . Jika tidak, perintah akan kehabisan waktu.

  • --diagnostic-port <port-address[,(listen|connect)]>

    Mengatur port diagnostik yang digunakan untuk berkomunikasi dengan proses yang akan dilacak. dotnet-trace dan runtime .NET di dalam proses target harus menyetujui alamat port, dengan satu mendengarkan dan yang lainnya terhubung. dotnet-trace secara otomatis menentukan port yang benar saat melampirkan menggunakan --process-id opsi atau --name , atau saat meluncurkan proses menggunakan -- <command> opsi . Biasanya hanya perlu menentukan port secara eksplisit saat menunggu proses yang akan dimulai di masa depan atau berkomunikasi ke proses yang berjalan di dalam kontainer yang bukan bagian dari namespace proses saat ini.

    Perbedaannya port-address dengan OS:

    • Linux dan macOS - jalur ke soket domain Unix seperti /foo/tool1.socket.
    • Windows - jalur ke pipa bernama seperti \\.\pipe\my_diag_port1.
    • Android, iOS, dan tvOS - IP:port seperti 127.0.0.1:9000.

    Secara default, dotnet-trace mendengarkan di alamat yang ditentukan. Anda dapat meminta dotnet-trace untuk terhubung sebagai gantinya dengan menambahkan ,connect setelah alamat. Misalnya, --diagnostic-port /foo/tool1.socket,connect akan terhubung ke proses runtime .NET yang mendengarkan /foo/tool1.socket soket domain Unix.

    Untuk mempelajari cara menggunakan opsi ini untuk mengumpulkan jejak dari startup aplikasi, lihat Menggunakan port diagnostik untuk mengumpulkan jejak dari startup aplikasi.

  • --duration <time-to-run>

    Waktu untuk pelacakan berjalan. Gunakan format .dd:hh:mm:ss Misalnya 00:00:00:05 akan menjalankannya selama 5 detik.

  • -o|--output <trace-file-path>

    Jalur output untuk data pelacakan yang dikumpulkan. Jika tidak ditentukan, defaultnya adalah <appname>_<yyyyMMdd>_<HHmmss>.nettrace, misalnya, 'myapp_20210315_111514.nettrace''.

  • -p|--process-id <PID>

    ID proses untuk mengumpulkan jejak.

    Catatan

    Di Linux dan macOS, menggunakan opsi ini memerlukan aplikasi target dan dotnet-trace untuk berbagi variabel lingkungan yang sama TMPDIR . Jika tidak, perintah akan kehabisan waktu.

  • --profile <list-of-comma-separated-profile-names>

    Profil adalah sekumpulan konfigurasi penyedia yang telah ditentukan sebelumnya untuk skenario pelacakan umum. Beberapa profil dapat ditentukan pada satu waktu, dibatasi oleh koma. Penyedia yang dikonfigurasi melalui --providers mengambil alih konfigurasi profil. Demikian pula, jika ada profil yang mengonfigurasi penyedia runtime CLR, profil tersebut akan mengambil alih konfigurasi apa pun yang ditentukan melalui --clrevents.

    Ketika --profile, --providers, dan --clrevents semuanya dihilangkan, dotnet-trace collect mengaktifkan profil dotnet-common dan dotnet-sampled-thread-time secara default.

    Profil yang tersedia:

    Profil Deskripsi
    dotnet-common Diagnostik runtime .NET ringan yang dirancang untuk tetap overhead rendah.
    Termasuk peristiwa GC, AssemblyLoader, Loader, JIT, Exceptions, Threading, JittedMethodILToNativeMap, dan Kompilasi
    Setara dengan --providers "Microsoft-Windows-DotNETRuntime:0x100003801D:4".
    dotnet-sampled-thread-time Sampel tumpukan utas .NET (~100 Hz) untuk mengidentifikasi hotspot dari waktu ke waktu. Menggunakan profiler sampel runtime dengan tumpukan terkelola.
    gc-verbose Melacak koleksi pengumpulan sampah dan sampel alokasi objek.
    gc-collect Melacak koleksi pengumpulan sampah hanya pada overhead yang sangat rendah.
    database Menangkap perintah database ADO.NET dan Entity Framework.

    Catatan

    Dalam versi sebelumnya dari alat dotnet-trace, kata kerja kumpulkan didukung profil yang disebut cpu-sampling. Profil ini dihapus karena namanya menyesatkan. Ini mengambil sampel semua utas terlepas dari penggunaan CPU mereka. Anda dapat mencapai hasil serupa sekarang menggunakan --profile dotnet-sampled-thread-time,dotnet-common. Jika Anda perlu mencocokkan perilaku sebelumnya cpu-sampling dengan tepat, gunakan --profile dotnet-sampled-thread-time --providers "Microsoft-Windows-DotNETRuntime:0x14C14FCCBD:4".

  • --providers <list-of-comma-separated-providers>

    Daftar yang dipisahkan koma penyedia EventPipe untuk diaktifkan. Penyedia ini melengkapi penyedia apa pun yang tersirat oleh --profile <list-of-comma-separated-profile-names>. Jika ada ketidakkonsistensian untuk penyedia tertentu, konfigurasi ini lebih diutamakan daripada konfigurasi implisit dari --profile dan --clrevents.

    Daftar penyedia ini dalam bentuk Provider[,Provider]:

    • Provider dalam bentuk: KnownProviderName[:Flags[:Level[:KeyValueArgs]]]
    • KeyValueArgs dalam bentuk: [key1=value1][;key2=value2]

    Untuk mempelajari lebih lanjut tentang beberapa penyedia terkenal di .NET, lihat Penyedia Peristiwa terkenal.

  • -- <command> (untuk aplikasi target yang menjalankan .NET 5 atau yang lebih baru)

    Setelah parameter konfigurasi pengumpulan, pengguna dapat menambahkan -- diikuti dengan perintah untuk memulai aplikasi .NET dengan setidaknya runtime 5.0. Ini mungkin berguna saat mendiagnosis masalah yang terjadi di awal proses, seperti masalah performa startup atau pemuat rakitan dan kesalahan pengikat.

    Catatan

    Menggunakan opsi ini memantau proses .NET pertama yang berkomunikasi kembali ke alat, yang berarti jika perintah Anda meluncurkan beberapa aplikasi .NET, itu hanya akan mengumpulkan aplikasi pertama. Oleh karena itu, disarankan agar Anda menggunakan opsi ini pada aplikasi mandiri, atau menggunakan opsi dotnet exec <app.dll>.

  • --show-child-io

    Menampilkan aliran input dan output dari proses anak yang diluncurkan di konsol saat ini.

  • --resume-runtime

    Lanjutkan runtime setelah sesi diinisialisasi, default ke true. Nonaktifkan resume runtime menggunakan --resume-runtime:false.

  • --stopping-event-provider-name

    String, diurai apa adanya, yang akan menghentikan jejak setelah mencapai peristiwa dengan nama penyedia yang cocok. Untuk acara penghentian yang lebih spesifik, berikan --stopping-event-event-name dan/atau --stopping-event-payload-filter. misalnya, --stopping-event-provider-name Microsoft-Windows-DotNETRuntime untuk menghentikan jejak setelah mencapai peristiwa pertama yang dipancarkan oleh Microsoft-Windows-DotNETRuntime penyedia peristiwa.

  • --stopping-event-event-name

    String, diurai apa adanya, yang akan menghentikan jejak setelah mencapai peristiwa dengan nama peristiwa yang cocok. --stopping-event-provider-name Perlu diatur. Untuk acara penghentian yang lebih spesifik, berikan --stopping-event-payload-filterjuga . misalnya, --stopping-event-provider-name Microsoft-Windows-DotNETRuntime --stopping-event-event-name Method/JittingStarted untuk menghentikan jejak setelah mencapai peristiwa pertama Method/JittingStarted yang dipancarkan oleh Microsoft-Windows-DotNETRuntime penyedia peristiwa.

  • --stopping-event-payload-filter

    String, diurai sebagai pasangan [payload_field_name]:[payload_field_value] yang dipisahkan oleh koma, yang akan menghentikan jejak saat mencapai peristiwa yang berisi semua pasangan payload yang ditentukan. --stopping-event-provider-name Memerlukan dan --stopping-event-event-name untuk diatur. misalnya, --stopping-event-provider-name Microsoft-Windows-DotNETRuntime --stopping-event-event-name Method/JittingStarted --stopping-event-payload-filter MethodNameSpace:Program,MethodName:OnButtonClick untuk menghentikan jejak pada peristiwa pertama Method/JittingStarted untuk metode OnButtonClick di namespace yang dipancarkan Program oleh Microsoft-Windows-DotNETRuntime penyedia peristiwa.

Catatan

  • Menghentikan pelacakan mungkin memakan waktu lama (hingga menit) untuk aplikasi besar. Runtime perlu mengirim cache jenis untuk semua kode terkelola yang diambil dalam jejak.
  • Untuk mengumpulkan pelacakan menggunakan dotnet-trace, metrik perlu dijalankan sebagai pengguna yang sama dengan pengguna yang menjalankan proses target atau sebagai akar. Jika tidak, alat akan gagal membuat koneksi dengan proses target.
  • Jika Anda mengalami pengecualian yang tidak tertangani saat menjalankan dotnet-trace collect, ini menghasilkan jejak yang tidak lengkap. Jika menemukan akar penyebab pengecualian adalah prioritas Anda, navigasi ke Kumpulkan crash dump saat crash. Sebagai akibat dari pengecualian yang tidak tertangani, jejak dipotong ketika runtime dimatikan untuk mencegah perilaku lain yang tidak diinginkan seperti hang atau kerusakan data. Meskipun jejak tidak lengkap, Anda masih dapat membukanya untuk melihat apa yang terjadi menjelang kegagalan. Namun, itu akan kehilangan informasi Rundown (ini terjadi di akhir jejak) sehingga tumpukan mungkin tidak terselesaikan (tergantung pada penyedia apa yang diaktifkan). Buka jejak dengan mengeksekusi PerfView dengan bendera /ContinueOnError di baris perintah. Log juga akan berisi lokasi pengecualian dipicu.
  • Saat menentukan peristiwa penghentian melalui --stopping-event-* opsi, karena EventStream sedang diurai secara asinkron, akan ada beberapa peristiwa yang diteruskan di antara waktu peristiwa pelacakan yang cocok dengan opsi peristiwa penghentian yang ditentukan diurai dan EventPipeSession dihentikan.

dotnet-trace collect-linux

Catatan

Kata collect-linux kerja adalah fitur pratinjau baru dan bergantung pada versi format file .nettrace yang diperbarui. Rilis PerfView terbaru mendukung file pelacakan ini, tetapi cara lain untuk menggunakan file pelacakan, seperti convert dan report, mungkin belum berfungsi.

Mengumpulkan jejak diagnostik menggunakan perf_events, teknologi OS Linux. collect-linux mengaktifkan fitur tambahan berikut melalui collect.

Fitur collect collect-linux
OS yang didukung Apa saja Hanya Linux, versi >kernel = 6.4
Memerlukan hak istimewa Admin/Root Tidak. Yes
Melacak semua proses secara bersamaan Tidak. Didukung
Mengambil pustaka asli dan peristiwa kernel Tidak. Didukung
Callstack peristiwa mencakup bingkai asli Tidak. Yes

Prasyarat

  • Kernel Linux dengan CONFIG_USER_EVENTS=y dukungan (kernel 6.4+)
  • Izin akar
  • .NET 10+

Catatan

Kata collect-linux kerja hanya berjalan pada lingkungan linux x64 dan linux arm64 yang memiliki glibc versi 2.35 atau lebih tinggi. Semua distro Linux yang didukung secara resmi .NET 10 mendukung persyaratan ini kecuali Alpine 3.22, CentOS Stream 9, dan distro apa pun berdasarkan Red Hat Enterprise Linux 9. Cara cepat untuk memeriksa versi libc sistem adalah dengan perintah ldd --version atau dengan menjalankan pustaka libc secara langsung.

Sinopsis

dotnet-trace collect-linux
    [-h|--help]

    # Provider/Event Specification
    [--providers <list-of-comma-separated-providers>]
    [--clreventlevel <clreventlevel>]
    [--clrevents <clrevents>]
    [--perf-events <list-of-perf-events>]
    [--profile <list-of-comma-separated-profile-names>]

    # Trace Collection
    [-o|--output <trace-file-path>]
    [--duration dd:hh:mm:ss]

    # .NET Process Target (Optional)
    [-n, --name <name>]
    [-p|--process-id <pid>]

    # Probe mode
    [--probe]

Perilaku pengumpulan default

Ketika --providers, , --profile--clrevents, dan --perf-events tidak ditentukan, collect-linux mengaktifkan profil ini secara default:

  • dotnet-common — diagnostik runtime .NET yang ringan.
  • cpu-sampling — pengambilan sampel CPU kernel.

Secara default, semua proses pada komputer dilacak. Untuk melacak hanya satu proses, gunakan -n, --name <name> atau -p|--process-id <PID>.

Opsi

Opsi Spesifikasi Penyedia/Peristiwa

  • --providers <list-of-comma-separated-providers>

    Daftar yang dipisahkan koma penyedia EventPipe untuk diaktifkan. Penyedia ini melengkapi penyedia apa pun yang tersirat oleh --profile <list-of-comma-separated-profile-names>. Jika ada ketidakkonsistensian untuk penyedia tertentu, konfigurasi ini lebih diutamakan daripada konfigurasi implisit dari --profile dan --clrevents.

    Daftar penyedia ini dalam bentuk Provider[,Provider]:

    • Provider dalam bentuk: KnownProviderName[:Flags[:Level[:KeyValueArgs]]]
    • KeyValueArgs dalam bentuk: [key1=value1][;key2=value2]

    Untuk mempelajari selengkapnya tentang beberapa penyedia terkenal di .NET, lihat Penyedia Peristiwa terkenal.

  • --clreventlevel <clreventlevel>

    Verbositas peristiwa CLR yang akan dipancarkan. Opsi ini hanya berlaku ketika --clrevents ditentukan dan tidak ditimpa oleh --profile atau --providers. Tabel berikut ini memperlihatkan tingkat peristiwa yang tersedia.

    Nilai untai (karakter) Nilai numerik
    logalways 0
    critical 1
    error 2
    warning 3
    informational 4
    verbose 5

  • --clrevents <clrevents>

    Daftar kata kunci penyedia runtime CLR untuk mengaktifkan dipisahkan oleh tanda +. Ini adalah pemetaan sederhana yang memungkinkan Anda menentukan kata kunci peristiwa melalui alias string daripada nilai heksanya. Misalnya, dotnet-trace collect-linux --providers Microsoft-Windows-DotNETRuntime:3:4 meminta serangkaian peristiwa yang sama dengan dotnet-trace collect-linux --clrevents gc+gchandle --clreventlevel informational. Jika penyedia Microsoft-Windows-DotNETRuntime runtime CLR juga diaktifkan melalui --providers atau --profile, opsi ini diabaikan. Tabel berikut ini memperlihatkan daftar kata kunci yang tersedia:

    Alias string kata kunci Nilai heksa kata kunci
    gc 0x1
    gchandle 0x2
    assemblyloader 0x4
    loader 0x8
    jit 0x10
    ngen 0x20
    startenumeration 0x40
    endenumeration 0x80
    security 0x400
    appdomainresourcemanagement 0x800
    jittracing 0x1000
    interop 0x2000
    contention 0x4000
    exception 0x8000
    threading 0x10000
    jittedmethodiltonativemap 0x20000
    overrideandsuppressngenevents 0x40000
    type 0x80000
    gcheapdump 0x100000
    gcsampledobjectallocationhigh 0x200000
    gcheapsurvivalandmovement 0x400000
    managedheapcollect 0x800000
    gcheapandtypenames 0x1000000
    gcsampledobjectallocationlow 0x2000000
    perftrack 0x20000000
    stack 0x40000000
    threadtransfer 0x80000000
    debugger 0x100000000
    monitoring 0x200000000
    codesymbols 0x400000000
    eventsource 0x800000000
    compilation 0x1000000000
    compilationdiagnostic 0x2000000000
    methoddiagnostic 0x4000000000
    typediagnostic 0x8000000000
    jitinstrumentationdata 0x10000000000
    profiler 0x20000000000
    waithandle 0x40000000000
    allocationsampling 0x80000000000

    Anda dapat membaca tentang penyedia CLR secara lebih rinci tentang dokumentasi referensi penyedia runtime .NET.

  • --perf-events <list-of-perf-events>

    Daftar peristiwa perf yang dipisahkan koma untuk disertakan dalam jejak. Peristiwa yang tersedia dapat ditemukan di bawah jejak, yang biasanya dipasang di , melalui /sys/kernel/tracing untuk semua peristiwa yang tersedia atau melalui available_events subdirektori untuk peristiwa yang dikategorikanevents/.

    Contoh: --perf-events syscalls:sys_enter_execve,sched:sched_switch,sched:sched_wakeup

  • --profile <list-of-comma-separated-profile-names>

    Profil adalah sekumpulan konfigurasi penyedia yang telah ditentukan sebelumnya untuk skenario pelacakan umum. Beberapa profil dapat ditentukan pada satu waktu, dibatasi oleh koma. Penyedia yang dikonfigurasi melalui --providers mengambil alih konfigurasi profil. Demikian pula, jika ada profil yang mengonfigurasi penyedia runtime CLR, profil tersebut akan mengambil alih konfigurasi apa pun yang ditentukan melalui --clrevents.

    Ketika --profile, --providers, --clrevents, dan --perf-events semuanya dihilangkan, dotnet-trace collect-linux mengaktifkan profil dotnet-common dan cpu-sampling secara default.

    Profil yang tersedia:

    Profil Deskripsi
    dotnet-common Diagnostik runtime .NET ringan yang dirancang untuk tetap overhead rendah.
    Termasuk peristiwa GC, AssemblyLoader, Loader, JIT, Exceptions, Threading, JittedMethodILToNativeMap, dan Kompilasi
    Setara dengan --providers "Microsoft-Windows-DotNETRuntime:0x100003801D:4".
    cpu-sampling Pengambilan sampel CPU kernel (berbasis perf), dipancarkan sebagai Universal.Events/cpu, untuk atribusi CPU yang tepat.
    thread-time Sakelar konteks utas kernel, dipancarkan sebagai Universal.Events/cswitch, untuk analisis on/off-CPU dan scheduler.
    gc-verbose Melacak koleksi pengumpulan sampah dan sampel alokasi objek.
    gc-collect Melacak koleksi pengumpulan sampah hanya pada overhead yang sangat rendah.
    database Menangkap perintah database ADO.NET dan Entity Framework.

Opsi Koleksi Pelacakan

  • -o|--output <trace-file-path>

    Jalur output untuk data pelacakan yang dikumpulkan. Jika tidak ditentukan, defaultnya adalah trace_<yyyyMMdd>_<HHmmss>.nettrace untuk pelacakan seluruh komputer default dan untuk <appname>_<yyyyMMdd>_<HHmmss>.nettrace pelacakan khusus proses (--name atau --process-id)

  • --duration <time-to-run>

    Waktu untuk pelacakan berjalan. Gunakan format .dd:hh:mm:ss Misalnya 00:00:00:05 akan menjalankannya selama 5 detik.

Opsi Target Proses .NET

Lihat Perilaku pengumpulan default

  • -n, --name <name>

    Nama proses untuk mengumpulkan jejak.

  • -p|--process-id <PID>

    ID proses untuk mengumpulkan jejak.

Opsi mode probe

  • --probe [-n|--name] [-p|--process-id] [-o|--output <stdout|output-filename>]

    Proses Probe .NET untuk dukungan perintah IPC EventPipe UserEvents yang digunakan oleh collect-linux, tanpa mengumpulkan jejak. Hasil mencantumkan proses yang didukung terlebih dahulu. Gunakan '-o stdout' untuk mencetak CSV (pid,processName,supportsCollectLinux) ke konsol, atau '-o output-filename' untuk menulis CSV. Probe satu proses dengan -n|--name atau -p|--process-id.

    Karena berjalan collect-linux dalam mode pemeriksaan tidak mengumpulkan jejak, tidak memerlukan izin root untuk dijalankan. Ini tidak memberikan validasi prasyarat, dan proses .NET yang berjalan pada versi pratinjau .NET Runtime '10.0.0' dianggap tidak didukung.

Catatan

Untuk mengumpulkan jejak menggunakan dotnet-trace collect-linux, pelacakan perlu dijalankan dengan izin root (CAP_PERFMON/CAP_SYS_ADMIN). Jika tidak, alat akan gagal mengumpulkan peristiwa.

dotnet-trace convert

Mengonversi pelacakan nettrace ke format alternatif untuk digunakan dengan alat analisis jejak alternatif.

Sinopsis

dotnet-trace convert [<input-filename>] [--format <Chromium|NetTrace|Speedscope>] [-h|--help] [-o|--output <output-filename>]

Argumen

  • <input-filename>

    File pelacakan input yang akan dikonversi. Default ke trace.nettrace.

Opsi

  • --format <Chromium|NetTrace|Speedscope>

    Mengatur format output untuk konversi file pelacakan.

  • -o|--output <output-filename>

    Filename output. Ekstensi format target akan ditambahkan.

Catatan

Mengonversi file nettrace ke chromium atau file speedscope tidak dapat diubah. File speedscope dan chromium tidak memiliki semua informasi yang diperlukan untuk membuat ulang file nettrace. Namun, perintah convert mempertahankan file nettrace asli, jadi jangan hapus file ini jika Anda berencana untuk membukanya di masa mendatang.

dotnet-trace ps

Mencantumkan proses dotnet tempat pelacakan dapat dikumpulkan. dotnet-trace 6.0.320703 dan yang lebih baru, juga menampilkan argumen baris perintah yang dimulai setiap proses, jika tersedia.

Catatan

Untuk mendapatkan informasi lengkap untuk proses 64 bit yang dijumlahkan, Anda perlu menggunakan alat versi dotnet-trace 64-bit.

Sinopsis

dotnet-trace ps [-h|--help]

Contoh

Misalkan Anda memulai aplikasi yang berjalan lama menggunakan perintah dotnet run --configuration Release. Di jendela lain, Anda menjalankan perintah dotnet-trace ps. Output yang akan Anda lihat adalah sebagai berikut. Argumen baris perintah, jika ada, ditampilkan dalam dotnet-trace versi 6.0.320703 dan yang lebih baru.

> dotnet-trace ps

  21932 dotnet     C:\Program Files\dotnet\dotnet.exe   run --configuration Release
  36656 dotnet     C:\Program Files\dotnet\dotnet.exe

dotnet-trace list-profiles

Mencantumkan profil pelacakan bawaan dengan deskripsi penyedia dan filter apa yang ada di setiap profil.

Sinopsis

dotnet-trace list-profiles [-h|--help]

laporan dotnet-trace

Membuat laporan ke stdout dari jejak yang dihasilkan sebelumnya.

Sinopsis

dotnet-trace report [-h|--help] <tracefile> [command]

Argumen

  • <tracefile>

    Jalur file untuk pelacakan yang dianalisis.

Perintah

dotnet-trace report topN

Menemukan metode N teratas yang telah berada di callstack paling lama.

Sinopsis
dotnet-trace report <tracefile> topN [-n|--number <n>] [--inclusive] [-v|--verbose] [-h|--help]
Opsi
  • -n|--number <n>

Memberikan metode N teratas pada callstack.

  • --inclusive

Keluarkan metode N teratas berdasarkan waktu inklusif. Jika tidak ditentukan, waktu eksklusif digunakan secara default.

  • -v|--verbose

Keluarkan parameter dari setiap metode secara penuh. Jika tidak ditentukan, parameter akan dipotong.

Mengumpulkan jejak dengan dotnet-trace

Untuk mengumpulkan jejak menggunakan dotnet-trace collect:

  • Dapatkan pengidentifikasi proses (PID) dari aplikasi .NET Core untuk mengumpulkan jejak.

    • Di Windows, Anda dapat menggunakan Manajer Tugas atau perintah tasklist, misalnya.
    • Di Linux, misalnya, perintah ps.
    • dotnet-trace ps

  • Jalankan perintah berikut:

    dotnet-trace collect --process-id <PID>

    Perintah sebelumnya menghasilkan output yang mirip dengan berikut ini:

    No profile or providers specified, defaulting to trace profiles 'dotnet-common' + 'dotnet-sampled-thread-time'.

Provider Name                           Keywords            Level               Enabled By
Microsoft-Windows-DotNETRuntime         0x000000100003801D  Informational(4)    --profile
Microsoft-DotNETCore-SampleProfiler     0x0000F00000000000  Informational(4)    --profile

Process        : <full-path-to-process-being-trace>
Output File    : <process>_20251007_154557.nettrace
[00:00:00:02]   Recording trace 178.172  (KB)
Press <Enter> or <Ctrl+C> to exit...
Stopping the trace. This may take several minutes depending on the application being traced.

Trace completed.

  • Hentikan pengumpulan dengan menekan tombol Enter . dotnet-trace akan menyelesaikan peristiwa pengelogan ke .nettrace file.

Luncurkan aplikasi anak dan kumpulkan jejak dari startup-nya menggunakan dotnet-trace

Terkadang mungkin berguna untuk mengumpulkan jejak proses dari startup-nya. Untuk aplikasi yang menjalankan .NET 5 atau yang lebih baru, dimungkinkan untuk melakukan ini dengan menggunakan dotnet-trace.

Ini akan diluncurkan hello.exe dengan arg1 dan arg2 sebagai argumen baris perintahnya dan mengumpulkan jejak dari startup runtime-nya:

dotnet-trace collect -- hello.exe arg1 arg2

Perintah sebelumnya menghasilkan output yang mirip dengan berikut ini:

No profile or providers specified, defaulting to trace profiles 'dotnet-common' + 'dotnet-sampled-thread-time'.

Provider Name                           Keywords            Level               Enabled By
Microsoft-Windows-DotNETRuntime         0x000000100003801D  Informational(4)    --profile
Microsoft-DotNETCore-SampleProfiler     0x0000F00000000000  Informational(4)    --profile

Process        : E:\temp\gcperfsim\bin\Debug\net5.0\gcperfsim.exe
Output File    : E:\temp\gcperfsim\trace.nettrace


[00:00:00:05]   Recording trace 122.244  (KB)
Press <Enter> or <Ctrl+C> to exit...

Anda dapat berhenti mengumpulkan jejak dengan menekan tombol <Enter> atau <Ctrl + C>. Melakukan ini juga akan mengeluarkan hello.exe.

Catatan

Meluncurkan hello.exe melalui dotnet-trace akan mengalihkan input/output-nya dan Anda tidak akan dapat berinteraksi dengannya di konsol secara default. Gunakan sakelar --show-child-io untuk berinteraksi dengan stdin/stdout-nya. Keluar dari alat melalui CTRL+C atau SIGTERM akan dengan aman mengakhiri alat dan proses anak. Jika proses anak keluar sebelum alat, alat akan keluar juga dan jejak harus dapat dilihat dengan aman.

Menggunakan port diagnostik untuk mengumpulkan jejak dari startup aplikasi

Port diagnostik adalah fitur runtime bahasa umum yang ditambahkan di .NET 5 yang memungkinkan Anda memulai pelacakan dari startup aplikasi. Untuk melakukan ini menggunakan dotnet-trace, Anda dapat menggunakan dotnet-trace collect -- <command> seperti yang dijelaskan dalam contoh di atas, atau menggunakan opsi --diagnostic-port.

Menggunakan dotnet-trace <collect|monitor> -- <command> untuk meluncurkan aplikasi sebagai proses anak adalah cara paling sederhana untuk dengan cepat melacak aplikasi dari startup-nya.

Namun, ketika Anda ingin mendapatkan kontrol yang lebih baik selama masa pakai aplikasi yang dilacak (misalnya, pantau aplikasi selama 10 menit pertama saja dan lanjutkan eksekusi) atau jika Anda perlu berinteraksi dengan aplikasi menggunakan CLI, menggunakan opsi --diagnostic-port memungkinkan Anda mengontrol aplikasi target yang dipantau dan dotnet-trace.

  1. Perintah di bawah ini membuat soket dotnet-trace diagnostik bernama myport.sock dan menunggu koneksi.

    dotnet-trace collect --diagnostic-port myport.sock

    Keluaran:

    Waiting for connection on myport.sock
Start an application with the following environment variable: DOTNET_DiagnosticPorts=/home/user/myport.sock

  2. Di konsol terpisah, luncurkan aplikasi target dengan variabel lingkungan DOTNET_DiagnosticPorts yang diatur ke nilai dalam output dotnet-trace.

    export DOTNET_DiagnosticPorts=/home/user/myport.sock
./my-dotnet-app arg1 arg2

    Ini kemudian harus mengaktifkan dotnet-trace untuk memulai pelacakan my-dotnet-app:

    Waiting for connection on myport.sock
Start an application with the following environment variable: DOTNET_DiagnosticPorts=myport.sock
Starting a counter session. Press Q to quit.

    Penting

    Meluncurkan aplikasi dotnet run Anda dapat bermasalah karena CLI dotnet dapat menelurkan banyak proses anak yang bukan aplikasi Anda dan dapat terhubung ke dotnet-trace sebelum aplikasi Anda, sehingga aplikasi Anda ditangguhkan saat runtime. Disarankan Anda langsung menggunakan versi aplikasi mandiri atau menggunakan dotnet exec untuk meluncurkan aplikasi.

(Khusus Linux) Mengumpulkan jejak di seluruh komputer menggunakan dotnet-trace

Contoh ini menangkap sampel CPU untuk semua proses pada komputer. Setiap proses yang menjalankan .NET 10+ juga akan mencakup beberapa peristiwa ringan tambahan yang menjelaskan perilaku pemuatan GC, JIT, dan Assembly.

$ sudo dotnet-trace collect-linux
==========================================================================================
The collect-linux verb is a new preview feature and relies on an updated version of the
.nettrace file format. The latest PerfView release supports these trace files but other
ways of using the trace file may not work yet. For more details, see the docs at
https://learn.microsoft.com/dotnet/core/diagnostics/dotnet-trace.
==========================================================================================
No providers, profiles, ClrEvents, or PerfEvents were specified, defaulting to trace profiles 'dotnet-common' + 'cpu-sampling'.

Provider Name                           Keywords            Level               Enabled By
Microsoft-Windows-DotNETRuntime         0x000000100003801D  Informational(4)    --profile

Linux Perf Events                                                               Enabled By
cpu-sampling                                                                    --profile

Output File    : <path-to-nettrace>trace_20251008_181939.nettrace

[00:00:00:03]   Recording trace.
Press <Enter> or <Ctrl-C> to exit...

Recording stopped.
Resolving symbols.
Finished recording trace.
Trace written to <path-to-nettrace>trace_20251008_181939.nettrace

Untuk lingkungan dengan beberapa versi .NET yang diinstal, berjalan collect-linux dalam mode pemeriksaan membantu membedakan apakah proses .NET mampu dilacak dengan collect-linux.

$ dotnet-trace collect-linux --probe
==========================================================================================
The collect-linux verb is a new preview feature and relies on an updated version of the
.nettrace file format. The latest PerfView release supports these trace files but other
ways of using the trace file may not work yet. For more details, see the docs at
https://learn.microsoft.com/dotnet/core/diagnostics/dotnet-trace.
==========================================================================================
Probing .NET processes for support of the EventPipe UserEvents IPC command used by collect-linux. Requires runtime '10.0.0' or later.
.NET processes that support the command:
3802935 MyApp

.NET processes that do NOT support the command:
3809123 dotnet - Detected runtime: '10.0.0-rc.1.25451.107'

Melihat jejak yang diambil dari dotnet-trace

Di Windows, Anda dapat melihat file .nettrace di Visual Studio atau PerfView untuk analisis.

Di Linux, Anda dapat melihat jejak dengan mengubah format output dotnet-trace menjadi speedscope. Ubah format file output dengan menggunakan opsi -f|--format. Anda dapat memilih antara nettrace (opsi default) dan speedscope. Opsi -f speedscope ini akan membuat dotnet-trace menghasilkan file speedscope. File Speedscope dapat dibuka di https://www.speedscope.app.

Untuk jejak yang dikumpulkan pada platform non-Windows, Anda juga dapat memindahkan file jejak ke komputer Windows dan melihatnya di Visual Studio atau PerfView.

Catatan

Runtime bahasa umum .NET Core menghasilkan jejak dalam format nettrace. Jejak dikonversi menjadi speedscope (jika ditentukan) setelah pelacakan selesai. Karena beberapa konversi dapat mengakibatkan hilangnya data, file nettrace asli dipertahankan di samping file yang dikonversi.

Gunakan file .rsp untuk menghindari mengetik perintah panjang

Anda dapat meluncurkan dotnet-trace dengan file .rsp yang berisi argumen yang akan diteruskan. Ini dapat berguna saat mengaktifkan penyedia yang mengharapkan argumen panjang atau saat menggunakan lingkungan shell yang menghapus karakter.

Misalnya, penyedia berikut dapat rumit untuk mengetik setiap kali Anda ingin melacak:

dotnet-trace collect --providers Microsoft-Diagnostics-DiagnosticSource:0x3:5:FilterAndPayloadSpecs="SqlClientDiagnosticListener/System.Data.SqlClient.WriteCommandBefore@Activity1Start:-Command;Command.CommandText;ConnectionId;Operation;Command.Connection.ServerVersion;Command.CommandTimeout;Command.CommandType;Command.Connection.ConnectionString;Command.Connection.Database;Command.Connection.DataSource;Command.Connection.PacketSize\r\nSqlClientDiagnosticListener/System.Data.SqlClient.WriteCommandAfter@Activity1Stop:\r\nMicrosoft.EntityFrameworkCore/Microsoft.EntityFrameworkCore.Database.Command.CommandExecuting@Activity2Start:-Command;Command.CommandText;ConnectionId;IsAsync;Command.Connection.ClientConnectionId;Command.Connection.ServerVersion;Command.CommandTimeout;Command.CommandType;Command.Connection.ConnectionString;Command.Connection.Database;Command.Connection.DataSource;Command.Connection.PacketSize\r\nMicrosoft.EntityFrameworkCore/Microsoft.EntityFrameworkCore.Database.Command.CommandExecuted@Activity2Stop:",OtherProvider,AnotherProvider

Selain itu, contoh sebelumnya berisi " sebagai bagian dari argumen. Karena tanda kutip tidak ditangani secara merata oleh setiap shell, Anda mungkin mengalami berbagai masalah saat menggunakan shell yang berbeda. Misalnya, perintah untuk dimasukkan zsh berbeda dengan perintah di cmd.

Daripada mengetik ini setiap kali, Anda dapat menyimpan teks berikut ke dalam file yang disebut myprofile.rsp.

--providers
Microsoft-Diagnostics-DiagnosticSource:0x3:5:FilterAndPayloadSpecs="SqlClientDiagnosticListener/System.Data.SqlClient.WriteCommandBefore@Activity1Start:-Command;Command.CommandText;ConnectionId;Operation;Command.Connection.ServerVersion;Command.CommandTimeout;Command.CommandType;Command.Connection.ConnectionString;Command.Connection.Database;Command.Connection.DataSource;Command.Connection.PacketSize\r\nSqlClientDiagnosticListener/System.Data.SqlClient.WriteCommandAfter@Activity1Stop:\r\nMicrosoft.EntityFrameworkCore/Microsoft.EntityFrameworkCore.Database.Command.CommandExecuting@Activity2Start:-Command;Command.CommandText;ConnectionId;IsAsync;Command.Connection.ClientConnectionId;Command.Connection.ServerVersion;Command.CommandTimeout;Command.CommandType;Command.Connection.ConnectionString;Command.Connection.Database;Command.Connection.DataSource;Command.Connection.PacketSize\r\nMicrosoft.EntityFrameworkCore/Microsoft.EntityFrameworkCore.Database.Command.CommandExecuted@Activity2Stop:",OtherProvider,AnotherProvider

Setelah menyimpan myprofile.rsp, Anda dapat meluncurkan dotnet-trace dengan konfigurasi ini menggunakan perintah berikut:

dotnet-trace @myprofile.rsp

Lihat juga

  • Last updated on