dtrace.1
DTRACE(1)
DTRACE(1)
FreeBSD General Commands Manual
DTRACE(1)
dtrace —
动态跟踪编译器和跟踪实用程序
dtrace [-32 | -64] [-aACeFGhHlqSvVwZ] [-b bufsz] [-c cmd] [-D name [=value]] [-I path] [-L path] [-o output] [-s script] [-U name] [-x arg [=value]] [-X a | c | s | t] [-p pid] [-P provider [[predicate] action]] [-m [provider:] module [[predicate] action]] [-f [[provider:] module:] function [[predicate] action]] [-n [[[provider:] module:] function:] name [[predicate] action]] [-i probe-id [[predicate] action]]
DTrace 是从 Solaris 移植的综合动态跟踪框架。 DTrace 提供了一个强大的基础架构，允许管理员、开发人员和服务人员简明扼要地回答有关操作系统和用户程序行为的任意问题。
dtrace 命令为 DTrace 工具提供的基本服务提供通用接口，包括：
列出 DTrace 当前发布的探测器和提供程序集的选项
使用任何探针描述说明符（提供者、模块、功能、名称）直接启用探针的选项
运行 D 编译器并编译一个或多个 D 程序文件或直接在命令行上编写的程序的选项
生成匿名跟踪程序的选项
生成程序稳定性报告的选项
修改 DTrace 跟踪和缓冲行为并启用其他 D 编译器功能的选项
您可以使用 dtrace 来创建 D 脚本，方法是在 shebang 声明中使用它来创建解释器文件。 您还可以使用 dtrace 尝试编译 D 程序并确定它们的属性，而无需使用 -e 选项实际启用跟踪。
-P -、 -m -、 -f -、 -n 和 -i 选项接受的参数可以包括用 predicate 括起来的可选 D 语言谓词和用大括号括起来的可选 D 语言 action 语句列表。 必须适当引用命令行上指定的 D 程序代码以避免 shell 解释元字符。
支持以下选项：
D 编译器使用操作系统内核的本机数据模型生成程序。 如果指定了 -32 选项， dtrace 会强制 D 编译器使用 32 位数据模型编译 D 程序。 如果指定了 -64 选项， dtrace 将强制 D 编译器使用 64 位数据模型编译 D 程序。 这些选项通常不是必需的，因为 dtrace 选择本机数据模型作为默认值。 数据模型影响整数类型的大小和其他语言属性。 为任一数据模型编译的 D 程序可以在 32 位和 64 位内核上执行。 -32 和 -64 选项还确定由 -G 选项生成的 elf(5) 文件格式（ELF32 或 ELF64）。
声明匿名跟踪状态并显示跟踪数据。 您可以将 -a 选项与 -e 选项结合使用，以强制 dtrace 在使用匿名跟踪状态后立即退出，而不是继续等待新数据。
生成用于匿名跟踪的指令并将它们写入 /boot/dtrace.dof 。 此选项构造一组 dtrace 配置文件指令以启用指定的探针进行匿名跟踪，然后退出。 默认情况下， dtrace 尝试将指令存储到文件 /boot/dtrace.dof 。 可以使用 -o 选项修改此行为以指定备用输出文件。
-b bufsz
将主体跟踪缓冲区大小设置为 bufsz 。 跟踪缓冲区大小可以包括任何大小后缀 k、m、g 或 t。 如果无法分配缓冲区空间， dtrace 会根据 bufresize 属性的设置尝试减小缓冲区大小或退出。
-c cmd
运行指定的命令 cmd 并在完成后退出。 如果命令行上存在多个 -c 选项，则 dtrace 会在所有命令退出时退出，并在每个子进程终止时报告其退出状态。 第一个命令的进程 ID 可用于命令行上指定的任何 D 程序，或通过 $target 宏变量使用 -s 选项。
在编译 D 程序之前，对它们运行 C 预处理器 cpp(1) 。 您可以使用 -D -、 -U -、 -I 和 -H 选项将选项传递给 C 预处理器。 如果使用 -X 选项，则可以选择符合 C 标准的程度。 有关调用 C 预处理器时 D 编译器定义的标记集的描述，请参见 -X 。
-D name [=value]
调用 cpp(1) 时定义 name 使用 -C 选项启用）。 如果您指定附加 value, 则会为名称分配相应的值。 此选项将 -D 选项传递给每个 cpp(1) 调用。
在编译任何请求并使用匿名跟踪状态 (-a 选项）但在启用任何探测之前退出。 您可以将此选项与 -a 选项结合使用以打印匿名跟踪数据并退出。 您还可以将此选项与 D 编译器选项结合使用。 这种组合验证程序编译时没有实际执行它们并启用相应的检测。
-f [[provider:] module:] function [[predicate] action]
指定要跟踪或列出的函数名称 (-l 选项）。相应的参数可以包括任何探测描述形式 provider:module:function, module:function, 或 function 。 未指定的探测描述字段留空，并匹配任何探测，无论这些字段中的值如何。 如果描述中没有指定除 function 以外的限定符，则匹配具有相应 function 的所有探测器。 -f 参数可以以可选的 D 探测子句作为后缀。 您可以一次在命令行上指定多个 -f 选项。
通过识别函数入口和返回来合并跟踪输出。 函数入口探测报告是缩进的，它们的输出以 ‘->’ 为前缀。 函数返回探测报告是未缩进的，它们的输出以 ‘<-’ 为前缀。 系统调用入口探测报告是缩进的，它们的输出以 ‘=>’ 为前缀。 系统调用返回探测报告是未缩进的，它们的输出以 ‘<=’ 为前缀。
生成包含嵌入式 DTrace 程序的 ELF 文件。 程序中指定的 DTrace 探针保存在可重定位的 ELF 对象中，该对象可以链接到另一个程序中。 如果存在 -o 选项，则使用指定为此操作数的参数的路径名保存 ELF 文件。 如果 -o 选项不存在并且 DTrace 程序包含一个名为 filename.d 的文件，则使用名称 filename.o 保存 ELF 文件。 否则，ELF 文件将使用名称 d.out 保存。
生成一个头文件，其中包含与指定提供程序定义中的探针相对应的宏。 该选项应该用于生成包含在其他源文件中的头文件，以供以后与 -G 选项一起使用。 如果存在 -o 选项，则使用指定为该选项参数的路径名保存头文件。 如果 -o 选项不存在并且 DTrace 程序包含在名为 filename.d 的文件中，则使用名称 filename.h 保存头文件。
调用 cpp(1) 时打印包含文件的路径名（使用 -C 选项启用）。 此选项将 -H 选项传递给每个 cpp(1) 调用，使其显示路径名列表，每行一个，以显示标准错误。
-i probe-id [[predicate] action]
指定要跟踪或列出的探测标识符 (probe-id) (l 选项）。 您可以使用十进制整数指定探测 ID，如 `dtrace -l` 所示。 -i 参数可以以可选的 D 探测子句作为后缀。 您一次可以指定多个 -i 选项。
-I path
调用 cpp(1) 使用 -C 选项启用）时，将指定的目录 path 添加到 #include 文件的搜索路径。 此选项将 -I 选项传递给每个 cpp(1) 调用。 指定的 path 被插入到默认目录列表之前的搜索路径中。
列出探针而不是启用它们。 如果指定了 -l 选项，则 dtrace 会生成与使用 -P -、 -m -、 -f -、 -n -、 -i 和 -s 选项给出的描述相匹配的探测报告。 如果未指定这些选项，则此选项列出所有探测。
-L path
将指定的目录 path 添加到 DTrace 库的搜索路径中。 DTrace 库用于包含编写 D 程序时可以使用的通用定义。 指定 path 添加在默认库搜索路径之后。
-m [provider:] module [[predicate] action]
指定要跟踪或列出的模块名称 (-l 选项）。 相应的参数可以包括任何探测描述形式 provider:module 或 module 。 未指定的探测描述字段留空，并匹配任何探测，无论这些字段中的值如何。 如果描述中没有指定除 module 以外的限定符，则匹配具有相应 module 的所有探测器。 -m 参数可以以可选的 D 探测子句作为后缀。 一次可以在命令行上指定多个 -m 选项。
-n [[[provider:] module:] function:] name [[predicate] action]
指定要跟踪或列出的探测名称 (-l 选项）。 相应的参数可以包括任何探测描述形式 provider:module:function:name 、 module:function:name, function:name 或 name 。 未指定的探测描述字段留空，并匹配任何探测，无论这些字段中的值如何。 如果描述中没有指定除 name 之外的限定符，则匹配具有相应 name 的所有探测器。 -n 参数可以以可选的 D 探测子句作为后缀。 一次可以在命令行上指定多个 -n- 选项。
-o output
为 -A -、 -G 和 -l 选项或跟踪数据本身指定 output 文件。 如果存在 -A 选项但不存在 -o ，则默认输出文件为 /boot/dtrace.dof 。 如果存在 -G 选项并且 -s 选项的参数的格式为 filename.d 而 -o 不存在，则默认输出文件为 filename.o 。 否则默认输出文件是 d.out 。
-p pid
获取指定的进程 ID pid ，缓存其符号表，并在完成后退出。 如果命令行上存在多个 -p 选项，则 dtrace 会在所有命令退出后退出，并在每个进程终止时报告其退出状态。 第一个进程 ID 可用于在命令行上指定的任何 D 程序或通过 $target 宏变量使用 -s 选项。
-P provider [[predicate] action]
指定要跟踪或列出的提供程序名称 (-l 选项）。其余的探测描述字段模块、函数和名称留空，并匹配任何探测，无论这些字段中的值如何。 -P 参数可以以可选的 D 探测子句作为后缀。 您可以一次在命令行上指定多个 -P 选项。
设置静音模式。 dtrace 抑制消息，例如与指定选项和 D 程序匹配的探测器数量，并且不打印列标题、CPU ID、探测器 ID 或在输出中插入换行符。 只有由 D 程序语句（如 ‘dtrace()’ 和 ‘printf()’ 跟踪和格式化的数据才会显示到标准输出。
-s script
编译指定的 D 程序源文件。 如果存在 -e 选项，则编译程序但不启用检测。 如果存在 -l 选项，则编译程序并列出与其匹配的探针集，但不启用检测。 如果 -e -、 -l -、 -G 或 -A 都不存在，则启用 D 程序指定的检测并开始跟踪。
显示 D 编译器中间代码。 D 编译器生成为每个 D 程序生成的中间代码到标准错误的报告。
-U name
调用 cpp(1) 时取消定义指定的 name （使用 -C 选项启用）。 此选项将 -U 选项传递给每个 cpp(1) 调用。
设置详细模式。 如果指定了 -v 选项， dtrace 会生成一个程序稳定性报告，显示指定 D 程序的最低接口稳定性和依赖性级别。
报告 dtrace 支持的最高 D 编程接口版本。 版本信息被打印到标准输出并且 dtrace 命令退出。
允许在使用 -s -、 -P -、 -m -、 -f -、 -n 或 -i 选项指定的 D 程序中执行破坏性操作。 如果未指定 -w 选项，则 dtrace 不允许编译或启用包含破坏性操作的 D 程序。
-x arg [=value]
启用或修改 DTrace 运行时选项或 D 编译器选项。 布尔选项通过指定它们的名称来启用。 带有值的选项是通过用等号 (=) 分隔选项名称和值来设置的。
size 参数可以后缀为 K 、 M 、 G 或 T （大写或小写）之一，以分别表示千字节、兆字节、千兆字节或太字节的倍数。
time 参数可以以 ns 、 nsec 、 us 、 usec 、 ms 、 msec 、 s 、 sec 、 m 、 min 、 h 、 hour 、 d 、 day 、 hz 之一作为后缀。 如果没有指定后缀， hz 将用作单位。
aggrate=time
聚合读取率。
aggsize=size
聚合缓冲区的大小。
bufpolicy=fill|switch|ring
指定主体缓冲区的缓冲区策略。
bufresize=auto|manual
缓冲区大小调整策略。
bufsize=size
每个 CPU 主要缓冲区的大小。 与 -b 标志相同。
cleanrate=time
清洁率。 必须以 “hz” 后缀为每秒数指定。
cpu=scalar
指定启用跟踪的 CPU。
defaultargs
允许引用未指定的宏参数。
destructive
允许破坏性行为。 与 -w 标志相同。
dynvarsize=size
动态变量空间的大小。
flowindent
打开流动缩进。 与 -F 标志相同。
grabanon
声明匿名状态。 与 -a 标志相同。
jstackframes=scalar
jstack() 的默认堆栈帧数。
jstackstrsize=scalar
jstack() 的默认字符串空间大小。
nspec=scalar
推测的数量。
quiet
设置静音模式。 与 -q 标志相同。
specsize=size
推测缓冲区的大小。
strsize=size
字符串的最大大小。
stackframes=scalar
执行 stack() 操作时展开的最大内核空间堆栈帧数。
stackindent=scalar
缩进 stack() 和 ustack() 输出时使用的空白字符数。
statusrate=time
状态检查率。
switchrate=time
缓冲区切换速率。
ustackframes=scalar
执行 ustack() 操作时要展开的最大用户空间堆栈帧数。
指定调用 cpp(1) 时应选择的 ISO C 标准的符合程度（使用 -C 选项启用）。 -X 选项参数会根据参数字母的值影响 __STDC__ 宏的值和存在。
-X 选项支持以下参数：
a
默认。 ISO C 和 K&R 兼容性扩展，具有 ISO C 要求的语义更改。 如果未指定 -X ，这是默认模式。 当 cpp(1) 与 -Xa 选项一起调用时，预定义宏 __STDC__ 的值为 0。
c
一致性。 严格符合 ISO C，没有 K&R C 兼容性扩展。 当 cpp(1) 与 -Xc 选项一起调用时，预定义宏 __STDC__ 的值为 1。
s
仅限 K&R C。 结合 -Xs 选项调用 cpp(1) 时，未定义宏 __STDC__。
t
过渡。 ISO C 加 K&R C 兼容性扩展，无需 ISO C 要求的语义更改。 当 cpp(1) 与 -Xt 选项一起调用时，预定义宏 __STDC__ 的值为 0。
由于 -X 选项仅影响 D 编译器调用 C 预处理器的方式，因此 -Xa 和 -Xt 选项从 D 的角度来看是等效的，并且提供这两个选项只是为了便于重用来自 C 构建环境的设置。
无论 -X 模式如何，始终指定以下附加 C 预处理器定义并且在所有模式下都有效：
__sun
__unix
__SVR4
__sparc (仅在 SPARC 系统上)
__sparcv9 (仅在编译 64 位程序时在 SPARC 系统上)
__i386 (仅在 x86 系统上编译 32 位程序时)
__amd64 (仅在 x86 系统上编译 64 位程序时)
__`uname -s`_`uname -r` (例如， ‘
FreeBSD_9.2-RELEASE 。’__SUNW_D=1
__SUNW_D_VERSION=0xMMmmmuuu
其中 MM 是十六进制的主释放值， mmm 是十六进制的次释放值， uuu 是十六进制的微释放值。
允许与零个探测匹配的探测描述。 如果未指定 -Z 选项，如果在 D 程序文件 (-s 选项）或命令行 (-P -、 -m -、 -f -、 -n 或 -i ）中指定了任何探测描述，则 dtrace 将报告错误并退出 options) 包含与任何已知探测不匹配的描述。
可以在 dtrace 命令行上指定零个或多个附加参数来定义一组宏变量等）。 附加参数可以在使用 -s 选项或命令行指定的 D 程序中使用。
/boot/dtrace.dof
匿名跟踪指令的文件。
返回以下退出状态：
0
顺利完成。
对于 D 程序请求，退出状态 0 表示程序已成功编译、探测器已成功启用或匿名状态已成功检索。 即使指定的跟踪请求遇到错误或丢弃， dtrace 也会返回 0。
1
发生错误。
对于 D 程序请求，退出状态为 1 表示程序编译失败或无法满足指定的请求。
2
指定了无效的命令行选项或参数。
dtrace 实用程序首次出现在 FreeBSD 7.1 中。
cpp(1) 、 elf(5) 、 SDT(9) 动态跟踪指南.
February 25, 2020
FreeBSD 13.1-RELEASE
最后更新于