dotnet-trace 效能分析公用程式

本文適用於： ✔️ dotnet-trace 9.0.661903 及之後版本

安裝

有兩種方法可下載並安裝 dotnet-trace：

概要

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

描述

dotnet-trace 工具：

  • 是一款跨平台的 .NET 診斷工具。

  • 啟用在不使用原生分析器的情況下，收集執行中的程序的 .NET 痕跡。

  • 它是建立在 EventPipe .NET 執行環境之上。

  • 支援兩種不同的追蹤收集方式：

    特徵 / 功能 collect collect-linux
    支援的OS 任意 僅限 Linux，kernel 版本 >= 6.4
    需要管理員/根權限 否 Yes
    同時追蹤所有程序 否 支持
    擷取原生函式庫與核心事件 否 支持
    事件呼叫堆疊包含原生框架 否 Yes

選項

  • -h|--help

    顯示命令列說明。

  • --version

    顯示 dotnet-trace 公用程式的版本。

命令

指令
dotnet-trace 收集
dotnet-trace collect-linux
dotnet-trace 轉換器
dotnet-trace ps
dotnet-trace 列表設定檔
dotnet-trace 報表

dotnet-trace 收集

從執行中的處理序收集診斷追蹤，或啟動子處理序並加以追蹤 (.NET 5 或更新版本)。 如要讓工具執行子處理序並從其啟動加以追蹤，請附加 -- 至收集命令。

概要

dotnet-trace collect
    [--buffering-mode <Drop|Block>]
    [--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>]

選項

  • --buffering-mode <Drop|Block>

    版本為 dotnet-trace 10.0.750501 及以上版本。

    設定執行時如何緩衝事件。 接受 Drop 或 Block （大小寫不區分），並預設為 Drop。

    • Drop （預設）：當緩衝區溢出時，事件會被丟棄。
    • Block： 執行緒會等到緩衝區有空間來儲存事件時。 在罕見錯誤情況下，例如記憶體耗盡，事件仍可能被丟棄。 Block需要 .NET 11+ 的目標執行時，且可能使追蹤應用程式變慢，因為事件發出執行緒會暫停，而緩衝區保持滿。

  • --buffersize <size>

    設定記憶體內部緩衝區的大小 (MB)。 預設為 256 MB。

    注意

    如果目標處理序發出事件的速度比寫入磁碟的速度還快，那麼此緩衝區可能會溢位，使部分事件受到卸除。 您可以藉由增加緩衝區大小或減少所記錄的事件數目，來減輕此問題。

  • --clreventlevel <clreventlevel>

    要發出之 CLR 事件的詳細程度。 此選項僅在 --clrevents 指定且未被 --profile--providers或 覆蓋時適用。 下表顯示可用的事件等級。

    [字串值] 數值
    logalways 0
    critical 1
    error 2
    warning 3
    informational 4
    verbose 5

  • --clrevents <clrevents>

    要以 + 符號分隔的 CLR 執行階段提供者關鍵字清單。 這是簡單的對應，可讓您透過字串別名指定事件關鍵字，而不是其十六進位值。 舉例來說，dotnet-trace collect --providers Microsoft-Windows-DotNETRuntime:3:4 會要求與 dotnet-trace collect --clrevents gc+gchandle --clreventlevel informational 相同的一組事件。 若 CLR 執行時提供者Microsoft-Windows-DotNETRuntime也透過 或 --providers啟用--profile，則忽略此選項。 下表顯示可用關鍵字列表：

    關鍵字串別名 關鍵字十六進位值
    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

    你可以在 .NET 執行時提供者參考文件中更詳細地閱讀 CLR 提供者。

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

    啟動 dotnet-dsrouter 並連線到它。 需要安裝 dotnet-dsrouter 。 如需詳細資訊，請執行 dotnet-dsrouter -h 。

  • --format {Chromium|NetTrace|Speedscope}

    設定追蹤檔案轉換的輸出格式。 預設值為 NetTrace。

  • -n, --name <name>

    要從中收集追蹤的處理序名稱。

    注意

    在 Linux 和 macOS 上，使用此選項需要目標應用程式並 dotnet-trace 共用相同的 TMPDIR 環境變數。 否則，命令將會逾時。

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

    設定用來與要追蹤的進程通訊的 診斷埠 。 目標進程內的 dotnet-trace 和 .NET 運行時間必須在埠地址上達成一致，其中一個接聽，另一個連接。 dotnet-trace 會在使用 --process-id 或 --name 選項附加時，或使用 選項啟動進程 -- <command> 時，自動判斷正確的埠。 通常只有在等候未來啟動的進程或與不在目前進程命名空間的容器內執行的進程通訊時，才需要明確指定埠。

    與 port-address OS 不同：

    • Linux 和 macOS - Unix 網域套接字的路徑，例如 /foo/tool1.socket。
    • Windows - 具名管道的路徑，例如 \\.\pipe\my_diag_port1。
    • Android、iOS 和 tvOS - IP：port，例如 127.0.0.1:9000。

    根據預設， dotnet-trace 會在指定的位址接聽。 您可以藉由在位址後面附加dotnet-trace來要求,connect連線。 例如， --diagnostic-port /foo/tool1.socket,connect 會連線到接聽 Unix 網域套接字的 /foo/tool1.socket .NET 運行時間進程。

    若要瞭解如何使用此選項從應用程式啟動收集追蹤，請參閱 使用診斷埠從應用程式啟動收集追蹤。

  • --duration <time-to-run>

    追蹤執行的時間。 使用 dd:hh:mm:ss 格式。 假如為 00:00:00:05，其執行時間將為 5 秒。

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

    所收集追蹤資料的輸出路徑。 如果未指定，則預設為 <appname>_<yyyyMMdd>_<HHmmss>.nettrace，例如 『myapp_20210315_111514.nettrace』。

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

    要從中收集追蹤的處理序識別碼。

    注意

    在 Linux 和 macOS 上，使用此選項需要目標應用程式並 dotnet-trace 共用相同的 TMPDIR 環境變數。 否則，命令將會逾時。

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

    設定檔是一組預先定義的提供者配置，用於常見追蹤情境。 可同時指定多個設定檔，並以逗號區分。 提供者透過 --providers 覆寫該設定檔的設定來設定。 同樣地，若任何設定檔配置 CLR 執行時提供者，將覆寫透過 --clrevents所規定的任何配置。

    當 、 、 全部省略時，預設值會--profile啟用設定檔--providers。--clreventsdotnet-trace collectdotnet-commondotnet-sampled-thread-time

    可用資料：

    設定檔 描述
    dotnet-common 輕量級的 .NET 執行時診斷，旨在保持低開銷。
    包含 GC、AssemblyLoader、Loader、JIT、Exceptions、Threading、JittedMethodILToNativeMap 以及編譯事件
    相當於 --providers "Microsoft-Windows-DotNETRuntime:0x100003801D:4"。
    dotnet-sampled-thread-time 取樣 .NET 執行緒以執行時預設速率堆疊（~1000 Hz，啟用多執行緒建置時每 1 毫秒）來估算牆鐘時間碼使用量。
    gc-verbose 追蹤 GC 集合和範例物件配置。
    gc-collect 僅在額外負荷非常低的條件下追蹤 GC 集合。
    database 擷取 ADO.NET 及 Entity Framework 資料庫指令。

    小提示

    所使用的 dotnet-sampled-thread-time 取樣率可透過 DOTNET_EventPipeThreadSamplingRate 環境變數（以毫秒為單位）來改變。 此設定為全域程序，影響所有 EventPipe 會話。 詳情請參見 使用 environment 變數追蹤 。

    注意

    在過去版本的 dotnet-trace 工具中，collect 動詞支援一個名為 cpu-sampling的設定檔。 這個帳號因為名稱具有誤導性而被移除。 它會取樣所有執行緒，不論 CPU 使用率如何。 你現在 --profile dotnet-sampled-thread-time,dotnet-common可以用 來達到類似的結果。 如果你需要完全匹配前者的 cpu-sampling 行為，可以使用 --profile dotnet-sampled-thread-time --providers "Microsoft-Windows-DotNETRuntime:0x14C14FCCBD:4"。

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

    要啟用的 EventPipe 提供者逗號分隔清單。 這些提供者會補足由 --profile <list-of-comma-separated-profile-names> 隱含的任何提供者。 若某個提供者存在不一致，此配置優先於隱--profile--clrevents含配置與。

    以下提供者名單格式為 Provider[,Provider]：

    • Provider 形式為： KnownProviderName[:Flags[:Level[:KeyValueArgs]]]
    • KeyValueArgs 形式為： [key1=value1][;key2=value2]

    如果要深入了解 .NET 中的某些已知提供者，請參閱已知的事件提供者 (部分機器翻譯)。

  • -- <command> (適用於執行 .NET 5 或更新版本的目標應用程式)

    使用者可以在收集設定參數之後附加 --，緊接著一個用於啟動最少具有 5.0 執行階段之 .NET 應用程式的命令。 在診斷於處理序中早期發生的問題時 (例如啟動效能問題或組件載入器和繫結器錯誤)，這可能很有幫助。

    注意

    使用此選項會監視第一個 .NET 進程，以傳回工具，這表示如果您的命令啟動多個 .NET 應用程式，它只會收集第一個應用程式。 因此，建議您在獨立應用程式上使用此選項，或使用 dotnet exec <app.dll> 選項。

  • --show-child-io

    顯示目前主控台中已啟動子處理序的輸入和輸出資料流。

  • --resume-runtime

    在工作階段初始化後繼續執行階段，預設為 true。 使用 --resume-runtime:false 停用執行階段繼續。

  • --stopping-event-provider-name

    依原樣剖析的字串會在命中具有相符提供者名稱的事件時停止追蹤。 如需更具體的停止事件，請另外提供 --stopping-event-event-name 和/或 --stopping-event-payload-filter。 例如， --stopping-event-provider-name Microsoft-Windows-DotNETRuntime 若要在達到事件提供者發出的 Microsoft-Windows-DotNETRuntime 第一個事件時停止追蹤。

  • --stopping-event-event-name

    依原樣剖析的字串會在命中具有相符事件名稱的事件時停止追蹤。 需要設定 --stopping-event-provider-name。 如需更具體的停止事件，請另外提供 --stopping-event-payload-filter。 例如，--stopping-event-provider-name Microsoft-Windows-DotNETRuntime --stopping-event-event-name Method/JittingStarted若要在達到事件提供者發出的Method/JittingStarted第一個Microsoft-Windows-DotNETRuntime事件時停止追蹤。

  • --stopping-event-payload-filter

    剖析為 [payload_field_name]:[payload_field_value] 組並以逗號分隔的字串，會在命中包含所有指定承載組的事件時停止追蹤。 需要設定 --stopping-event-provider-name 和 --stopping-event-event-name。 例如，--stopping-event-provider-name Microsoft-Windows-DotNETRuntime --stopping-event-event-name Method/JittingStarted --stopping-event-payload-filter MethodNameSpace:Program,MethodName:OnButtonClick若要在事件提供者所發出Method/JittingStarted之命名空間中OnButtonClick方法Program的第一個Microsoft-Windows-DotNETRuntime事件上停止追蹤。

注意

  • 對於大型應用程式，停止追蹤可能需要很長時間（甚至可能幾分鐘）。 執行階段必須針對在追蹤中擷取的所有受控程式碼，透過類型快取傳送。
  • 若要使用 dotnet-trace 收集追蹤，其執行身分必須與執行目標處理序的使用者或根使用者相同。 否則，此工具將無法與目標處理序建立連線。
  • 如果您在執行 dotnet-trace collect 時遇到未處理的例外狀況，這會導致追蹤不完整。 如果發現例外狀況的根本原因是您的優先順序，請巡覽至在損毀時收集傾印。 因為未處理的例外狀況，使得追蹤會在執行階段關閉時受到截斷，以避免發生其他非預期的行為，例如停止回應或資料損毀。 即使追蹤不完整，您仍然可以開啟它，查看導致失敗的原因。 不過，其將會缺少取消資訊 (這會發生在追蹤的結尾)，因此可能無法解析堆疊 (取決於開啟的提供者)。 在命令列使用 /ContinueOnError 旗標執行 PerfView 來開啟追蹤。 記錄也會包含引發例外狀況的位置。
  • 當你透過 --stopping-event-* 選項指定停止事件時，因為 EventStream 是非同步解析，從解析符合指定停止事件選項的追蹤事件到 EventPipeSession 停止之間，會有一些事件經過。

dotnet-trace collect-linux

利用 Linux 作業系統技術 perf_events 收集診斷痕跡。 collect-linux使得以下附加功能得以實現。collect

特徵 / 功能 collect collect-linux
支援的OS 任意 僅限 Linux，kernel 版本 >= 6.4
需要管理員/根權限 否 Yes
同時追蹤所有程序 否 支持
擷取原生函式庫與核心事件 否 支持
事件呼叫堆疊包含原生框架 否 Yes

先決條件

  • 支援 CONFIG_USER_EVENTS=y Linux 核心（核心 6.4+）
  • tracefs 已掛載（預設為 /sys/kernel/tracing）
  • 根權限
  • .NET 10+

注意

這個 collect-linux 動詞僅能在擁有 glibc 2.27 或更新版本的 Linux x64 和 Linux Arm64 環境中運行。 除了 Alpine 3.22 外，所有官方支援的 Linux 發行版.NET都支援此項要求。 快速檢查系統 libc 版本的方法是使用指令 ldd --version 或直接執行 libc 函式庫。

小提示

要檢查你的核心 user_events 是否有支援，請執行 zgrep CONFIG_USER_EVENTS /proc/config.gz。 你也可以在 tracefs 支架下方找找 user_events_data （預設為 /sys/kernel/tracing/user_events_data）。

概要

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]

預設收集行為

當 --providers、 --profile、 --clrevents和 --perf-events 未指定時，預設 collect-linux 啟用這些設定檔：

  • dotnet-common — 輕量級.NET執行時診斷。
  • cpu-sampling — 核心 CPU 取樣。

預設情況下，機器上的所有程序都會被追蹤。 若要只追蹤一個程序，請使用 -n, --name <name> 或 -p|--process-id <PID>。

選項

提供者/事件規範選項

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

    要啟用的 EventPipe 提供者逗號分隔清單。 這些提供者會補足由 --profile <list-of-comma-separated-profile-names> 隱含的任何提供者。 若某個提供者存在不一致，此配置優先於隱--profile--clrevents含配置與。

    以下提供者名單格式為 Provider[,Provider]：

    • Provider 形式為： KnownProviderName[:Flags[:Level[:KeyValueArgs]]]
    • KeyValueArgs 形式為： [key1=value1][;key2=value2]

    想了解更多關於 .NET 中一些知名的服務提供者，請參閱 「知名活動提供者」。

  • --clreventlevel <clreventlevel>

    要發出之 CLR 事件的詳細程度。 此選項僅在 --clrevents 指定且未被 --profile--providers或 覆蓋時適用。 下表顯示可用的事件等級。

    [字串值] 數值
    logalways 0
    critical 1
    error 2
    warning 3
    informational 4
    verbose 5

  • --clrevents <clrevents>

    要以 + 符號分隔的 CLR 執行階段提供者關鍵字清單。 這是簡單的對應，可讓您透過字串別名指定事件關鍵字，而不是其十六進位值。 舉例來說，dotnet-trace collect-linux --providers Microsoft-Windows-DotNETRuntime:3:4 會要求與 dotnet-trace collect-linux --clrevents gc+gchandle --clreventlevel informational 相同的一組事件。 若 CLR 執行時提供者Microsoft-Windows-DotNETRuntime也透過 或 --providers啟用--profile，則忽略此選項。 下表顯示可用關鍵字列表：

    關鍵字串別名 關鍵字十六進位值
    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

    你可以在 .NET 執行時提供者參考文件中更詳細地閱讀 CLR 提供者。

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

    一個逗號分隔的穿透事件清單，包含在追蹤中。 可用事件可在 tracefs 下找到，通常掛載於 /sys/kernel/tracing，所有可用事件則掛載於 ， available_events 或透過 events/ 子目錄（分類事件）找到。

    範例：--perf-events syscalls:sys_enter_execve,sched:sched_switch,sched:sched_wakeup

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

    設定檔是一組預先定義的提供者配置，用於常見追蹤情境。 可同時指定多個設定檔，並以逗號區分。 提供者透過 --providers 覆寫該設定檔的設定來設定。 同樣地，若任何設定檔配置 CLR 執行時提供者，將覆寫透過 --clrevents所規定的任何配置。

    當 、 、 、 全部省略時，預設會--profile啟用設定檔 --providers 和 --clrevents 。--perf-eventsdotnet-trace collect-linuxdotnet-commoncpu-sampling

    可用資料：

    設定檔 描述
    dotnet-common 輕量級的 .NET 執行時診斷，旨在保持低開銷。
    包含 GC、AssemblyLoader、Loader、JIT、Exceptions、Threading、JittedMethodILToNativeMap 以及編譯事件
    相當於 --providers "Microsoft-Windows-DotNETRuntime:0x100003801D:4"。
    cpu-sampling 核心 CPU 取樣（基於 perf），以 形式 輸出 Universal.Events/cpu，以精確的 CPU 上歸屬。
    thread-time 核心執行緒上下文切換，以 Universal.Events/cswitch表示，用於 CPU 開關及排程器分析。
    gc-verbose 追蹤 GC 集合和範例物件配置。
    gc-collect 僅在額外負荷非常低的條件下追蹤 GC 集合。
    database 擷取 ADO.NET 及 Entity Framework 資料庫指令。

追蹤收集選項

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

    所收集追蹤資料的輸出路徑。 若未指定，預設為全機追蹤，程序特定追蹤trace_<yyyyMMdd>_<HHmmss>.nettrace則預設為 <appname>_<yyyyMMdd>_<HHmmss>.nettrace （--name或--process-id）

  • --duration <time-to-run>

    追蹤執行的時間。 使用 dd:hh:mm:ss 格式。 假如為 00:00:00:05，其執行時間將為 5 秒。

.NET 程序目標選項

參見 預設收集行為

  • -n, --name <name>

    要從中收集追蹤的處理序名稱。

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

    要從中收集追蹤的處理序識別碼。

探測模式選項

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

    探測 .NET 程序，支援 collect-linux 使用的 EventPipe UserEvents IPC 指令，且不收集追蹤。 結果會先列出支援的流程。 用 '-o stdout' 列印 CSV（pid、processName、supportsCollectLinux）到主控台，或用「-o output-filename' 寫入 CSV。 探測一個單一程序，名稱為 -n|--name 或 -p|--process-id。

    由於以探測模式執行 collect-linux 不會收集追蹤，因此執行時不需要根權限。 它不提供前 置條件的驗證，且在 .NET 執行時 '10.0.0' 預覽版上運行的 .NET 程序被視為不被支援。

注意

要使用 ，必須以根權限dotnet-trace collect-linuxCAP_PERFMON/（）執行CAP_SYS_ADMIN追蹤。 否則，工具將無法收集事件。

dotnet-trace 轉換器

將 nettrace 追蹤轉換為替代格式，以搭配替代追蹤分析工具使用。

概要

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

引數

  • <input-filename>

    要轉換的輸入追蹤檔案。 預設為 trace.nettrace。

選項

  • --format <Chromium|NetTrace|Speedscope>

    設定追蹤檔案轉換的輸出格式。

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

    輸出檔案名稱。 將會新增目標格式的副檔名。

注意

將 nettrace 檔案轉換為 chromium 或 speedscope 檔案後，便無法復原。 speedscope 和 chromium 檔案沒有重新建構 nettrace 所需的所有資訊。 不過，convert 命令會保留原始的 nettrace 檔案，所以如果您打算日後開啟該檔案的話，請勿予以刪除。

dotnet-trace ps

列出可從中收集追蹤的 dotnet 處理序。 dotnet-trace 6.0.320703 和更新版本也會顯示啟動每個處理序時所用的命令列引數 (如果有的話)。

注意

要獲得完整列舉 64 位元程序的資訊，你需要使用該工具的 64 位元版本 dotnet-trace 。

概要

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

範例

假設您使用 dotnet run --configuration Release 命令，啟動了一個長時間執行的應用程式。 在另一個視窗中，您執行了 dotnet-trace ps 命令。 看到的輸出就會如下所示。 dotnet-trace 6.0.320703 和更新版本中會顯示命令列引數 (如可用)。

> dotnet-trace ps

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

dotnet-trace 列表設定檔

列出預先建置的追蹤設定檔，其中有每個設定檔中所包含提供者和篩選的描述。

概要

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

dotnet-trace 報表

從先前產生的追蹤在 stdout 中建立報告。

概要

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

引數

  • <tracefile>

    要分析之追蹤的檔案路徑。

命令

dotnet-trace 報表 topN

尋找已在呼叫堆疊上最長的前 N 個方法。

概要
dotnet-trace report <tracefile> topN [-n|--number <n>] [--inclusive] [-v|--verbose] [-h|--help]
選項
  • -n|--number <n>

提供呼叫堆疊上的前 N 個方法。

  • --inclusive

根據內含時間輸出前 N 個方法。 如果未指定，預設會使用專屬時間。

  • -v|--verbose

完整輸出每個方法的參數。 如果未指定，則會截斷參數。

使用 dotnet-trace 收集追蹤

如要使用 dotnet-trace collect 收集追蹤：

  • 取得 .NET 應用程式的程序識別碼（PID）來收集追蹤資料。

    • 在 Windows 上，可以使用工作管理員或像是 tasklist 這樣的命令。
    • 例如，在 Linux 上，可以使用 ps 命令。
    • dotnet-trace ps

  • 執行以下命令：

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

    上述命令產生的輸出，類似如下：

    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.

  • 按下 Enter 鍵停止收集。 dotnet-trace 會完成將事件記錄到檔案中 .nettrace 。

啟動子應用程式，並使用 dotnet-trace 從其啟動收集追蹤

有時候收集程序啟動時的痕跡可能會很有用。 對於執行 .NET 5 或更新版本的應用程式，可以透過使用 dotnet-trace 來達成這個功能。

以下指令以 hello.exearg1 和 arg2 作為其命令列參數啟動，並從執行時啟動時收集追蹤：

dotnet-trace collect -- hello.exe arg1 arg2

上述命令產生的輸出，類似如下：

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...

你可以按 Enter 或 Ctrl + C 停止收集追蹤。這樣做也會退出 hello.exe。

注意

透過 dotnet-trace 啟動 hello.exe 會重新導向它的輸入/輸出，預設情況下你無法在主控台上與它互動。 請用 --show-child-io 參數來與其 stdin/stdout 互動。 透過 Ctrl + C 或 SIGTERM 退出工具，可以安全地結束工具和子程序。 如果子程序在工具結束之前退出，則工具也會退出，並且追蹤應該可以安全地查看。

使用診斷連接埠從應用程式啟動收集追蹤

診斷連接埠是 .NET 5 中新增的執行階段功能，可讓您從應用程式啟動開始追蹤。 如要使用 dotnet-trace 這麼做，您可以使用如上述範例中所述的 dotnet-trace collect -- <command>，或是使用 --diagnostic-port 選項。

如要快速地從應用程式啟動加以追蹤，那麼使用 dotnet-trace <collect|monitor> -- <command> 將應用程式作為子處理序啟動是最簡單的方法。

不過，當您想更精細地控制受追蹤的應用程式存留期 (例如只監控應用程式前 10 分鐘並繼續執行)，或是需要使用 CLI 與應用程式互動時，使用 --diagnostic-port 選項可讓您同時控制監控的目標應用程式與 dotnet-trace。

  1. 下列命令會建立 dotnet-trace 名為 myport.sock 的診斷通訊端，並等候連線。

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

    輸出：

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

  2. 在另一個主控台中，使用環境變數 DOTNET_DiagnosticPorts (設定為 dotnet-trace 輸出中的值) 來啟動目標應用程式。

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

    這應該會接著啟用 dotnet-trace 以開始追蹤 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.

    重要

    啟動應用程式 dotnet run 時可能會有問題，因為 dotnet CLI 可能會產生許多非你應用程式的子程序，且這些子程序可能先於 dotnet-trace 你的應用程式連線，導致應用程式在執行時被暫停。 建議您直接使用獨立版本的應用程式，或是 dotnet exec 來啟動應用程式。

（僅限 Linux 平台）使用 dotnet-trace 收集全機器追蹤

取得原生執行時框架的符號

collect-linux 擷取呼叫堆疊中的原生框架。 要解析執行時函式庫的原生方法名稱（例如 libcoreclr.so），將對應的除錯符號檔案放在函式庫旁的磁碟上。 若無這些符號，原生框架在追蹤中會以未解析位址的形式出現。

collect-linux 當 trace 開始時，動態啟用 JIT 編譯程式碼的 perf map 產生，因此你不需要重新啟動任何 .NET 程序。

要下載原生執行時符號，請使用 dotnet-symbol：

  1. 安裝 dotnet-symbol：

    dotnet tool install -g dotnet-symbol

  2. 下載你執行時版本的除錯符號。 例如，如果你的執行環境安裝在 /usr/share/dotnet/shared/Microsoft.NETCore.App/10.0.0：

    dotnet-symbol --symbols /usr/share/dotnet/shared/Microsoft.NETCore.App/10.0.0/lib*.so

  3. 將下載的 .so.dbg 檔案放在它們對應的執行時函式庫旁邊（例如， libcoreclr.so.dbg 旁邊 libcoreclr.so）。 預設情況下，會在 dotnet-symbol 每個輸入檔案旁寫入符號檔案。 如果你的執行時函式庫存在於受保護路徑（如 /usr/share/dotnet/...，例如 ），請以提升權限執行dotnet-symbol（例如使用 sudo），或使用-o/--output寫入可寫目錄的選項，則複製執行時函式庫旁的.so.dbg檔案。

放置符號後， collect-linux 當它收集追蹤時會解析原生方法名稱。

此範例捕捉了機器上所有程序的 CPU 樣本。 任何執行 .NET 10+ 的程序也會包含一些描述 GC、JIT 和組合語言載入行為的輕量級事件。

$ sudo dotnet-trace collect-linux
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

對於安裝多個 .NET 版本的環境，以collect-linux執行有助於判斷 .NET 程序是否能被 collect-linux 追蹤。

$ dotnet-trace collect-linux --probe
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'

檢視從 dotnet-trace 擷取的追蹤

在 Windows 上，您可以檢視 Visual Studio 或 PerfView 中的 .nettrace 檔案以進行分析。

在 Linux 上，您可以將 dotnet-trace 的輸出格式變更為 speedscope 來檢視追蹤。 使用 -f|--format 選項變更輸出檔案格式。 您可以選擇 nettrace (預設選項) 和 speedscope。 選項 -f speedscope 會使 dotnet-trace 產生 speedscope 檔案。 您可在 Speedscope 開啟 https://www.speedscope.app 檔案。

如為不是在 Windows 平台上收集的追蹤，您也可以將追蹤檔案移動到 Windows 機器，並在 Visual Studio 或 PerfView 中加以檢視。

注意

.NET Core 執行階段會以 nettrace 格式產生追蹤。 如有指定，則追蹤會在完成後轉換為 speedscope 格式。 由於某些轉換可能會導致資料遺失，因此會保留已轉換檔案旁的原始檔案 nettrace。

請使用 .rsp 檔案以避免鍵入過長的命令

您可以使用包含所要傳遞之引數的 dotnet-trace 檔案來啟動 .rsp。 當您要啟用預期有長引數的提供者，或是要使用會刪除字元的殼層環境時，這會很有幫助。

舉例來說，每當您要追蹤以下提供者時，鍵入其名稱可能會很麻煩：

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

此外，上一個範例包含 " 作為引數的一部分。 因為每個殼層不會平均處理引號，所以在使用不同殼層時，可能會遇到各種問題。 舉例來說，要在 zsh 中輸入的命令會與要在 cmd 中輸入的命令不同。

您不需要每次都鍵入這些文字，而是將以下文字儲存到名為 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

儲存 myprofile.rsp 之後，您就能使用以下命令來以此組態啟動 dotnet-trace：

dotnet-trace @myprofile.rsp

另請參閱

  • 上次更新時間：