dotnet-trace 性能分析实用工具

本文适用于： ✔️ dotnet-trace 9.0.661903 及更高版本

安装

可采用两种方法来下载和安装 dotnet-trace：

摘要

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

描述

dotnet-trace 工具：

  • 是一种跨平台 .NET 诊断工具。

  • 启用在没有本机探查器的情况下运行进程的 .NET 跟踪的集合。

  • 基于 .NET 运行时生成 EventPipe 。

  • 支持两种不同的收集跟踪方法：

    • 动 collect 词 在任何 OS 上都提供一致的功能。
    • 谓 collect-linux 词 使用特定于 Linux 的 OS 功能来提供其他功能。
    功能 / 特点 collect collect-linux
    支持的 OS 任意 仅限 Linux，内核版本 >= 6.4
    需要管理员/根权限 否 是的
    同时跟踪所有进程 否 已支持
    捕获本机库和内核事件 否 已支持
    事件调用堆栈包括本机帧 否 是的

选项

  • -h|--help

    显示命令行帮助。

  • --version

    显示 dotnet-dump 实用工具的版本。

命令

命令
dotnet-trace collect
dotnet-trace collect-linux
dotnet-trace convert
dotnet-trace ps
dotnet-trace list-profiles
dotnet-trace 报表

dotnet-trace collect

从正在运行的进程中收集诊断跟踪，或者启动子进程并对其进行跟踪（.NET 5 或更高版本）。 若要让工具运行子进程并自其启动时对其进行跟踪，请将 -- 追加到 collect 命令。

摘要

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>时自动确定正确的端口。 通常需要在等待将来启动的进程或与不在当前进程命名空间的容器中运行的进程通信时显式指定端口。

    OS port-address 的不同之处在于：

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

    从中收集跟踪的进程 ID。

    注意

    在 Linux 和 macOS 上，使用此选项需要目标应用程序并 dotnet-trace 共享相同的 TMPDIR 环境变量。 否则，该命令将超时。

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

    配置文件是常见跟踪方案的预定义提供程序配置集。 一次可以指定多个配置文件，用逗号分隔。 通过 --providers 重写配置文件的配置配置的提供程序。 同样，如果任何配置文件配置 CLR 运行时提供程序，它将替代通过 --clrevents指定的任何配置。

    如果--profile忽略--providers配置文件，并且--clrevents全部被省略，dotnet-trace collect则默认启用配置文件dotnet-commondotnet-sampled-thread-time。

    可用配置文件：

    配置文件 描述
    dotnet-common 轻型 .NET 运行时诊断旨在保持较低的开销。
    包括 GC、AssemblyLoader、Loader、JIT、异常、线程处理、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 会话。 有关详细信息，请参阅 使用环境变量进行跟踪 。

    注意

    在以前版本的 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 OS 技术perf_events收集诊断跟踪。 collect-linux 启用以下附加 collect功能。

功能 / 特点 collect collect-linux
支持的 OS 任意 仅限 Linux，内核版本 >= 6.4
需要管理员/根权限 否 是的
同时跟踪所有进程 否 已支持
捕获本机库和内核事件 否 已支持
事件调用堆栈包括本机帧 否 是的

先决条件

  • 支持 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 之外，所有 .NET 10 正式支持的 Linux 发行版都支持此要求。 检查系统的 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-events全部省略，dotnet-trace collect-linux则启用配置文件，dotnet-common默认情况下启用配置文件cpu-sampling。

    可用配置文件：

    配置文件 描述
    dotnet-common 轻型 .NET 运行时诊断旨在保持较低的开销。
    包括 GC、AssemblyLoader、Loader、JIT、异常、线程处理、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>

    从中收集跟踪的进程 ID。

探测模式选项

  • --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-linux收集跟踪，需要使用根权限运行跟踪（CAP_PERFMON/CAP_SYS_ADMIN）。 否则，该工具将无法收集事件。

dotnet-trace convert

将 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 位进程的完整信息，需要使用该工具的 dotnet-trace 64 位版本。

摘要

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 list-profiles

列出预生成的跟踪配置文件，并描述每个配置文件中包含的提供程序和筛选器。

摘要

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

dotnet-trace 报表

将报表从以前生成的跟踪创建到 stdout 中。

摘要

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

自变量

  • <tracefile>

    要分析的跟踪的文件路径。

命令

dotnet-trace report 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.exe作为其命令行参数启动arg1arg2，并从运行时启动中收集跟踪：

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 在 callstacks 中捕获本机帧。 若要解析运行时库（如 libcoreclr.so）的本机方法名称，请将相应的调试符号文件放在库旁边的磁盘上。 如果没有这些符号，本机帧在跟踪中显示为未解析的地址。

collect-linux 在跟踪开始时动态启用 JIT 编译代码的 perf 映射生成，因此无需重启任何 .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。 当启用需要较长参数的提供程序时，或在使用可去除字符的 shell 环境时，这很有用。

例如，以下提供程序在每次要跟踪时都可能要繁琐地键入内容：

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

此外，前一个示例包含 " 作为参数的一部分。 由于每个 shell 对引号的处理不同，因此在使用不同的 shell 时可能会遇到各种问题。 例如，在 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

另请参阅

  • 上次更新时间为