dtrace

- DTrace 动态跟踪编译器和跟踪实用程序

用法概要

dtrace [-32 | -64] [-aACeFGHhlqSvVwZ] [-b bufsz] [-c cmd] 
     [-D name [=value]] [-I path] [-L path] [-o output] 
     [-s script] [-U name] [-x arg [=val]] 
     [-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 提供一个强大的基础结构，使管理员、开发者和服务人员能简明地回答有关操作系统和用户程序行为的任意问题。

《Solaris Dynamic Tracing Guide》介绍如何使用 DTrace 观察、调试和调优系统行为。请参见此书以详细了解 DTrace 功能，包括随附的 DTrace 监测工具、检测过程提供器以及 D 编程语言。

dtrace 命令提供了一个可访问 DTrace 工具提供的基本服务的通用界面，包括：

• 用于列出 DTrace 当前发布的探测器和提供器集的选项

• 允许使用任何探测器说明符（提供器、模块、函数和名称）直接启用探测器的选项

• 用于运行 D 编译器并编译一个或多个直接在命令行上编写的 D 程序文件或程序的选项

• 用于生成匿名跟踪程序的选项

• 用于生成程序稳定性报告的选项

• 用于修改 DTrace 跟踪和缓冲行为并启用其他 D 编译器功能的选项

可以使用 dtrace 创建 D 脚本，方式是在 #! 声明中使用它来创建解释程序文件。还可在不使用 -e 选项实际启用跟踪的情况下，使用 dtrace 尝试编译 D 程序并确定其属性。请参见“选项”部分。 请参见《Solaris Dynamic Tracing Guide》，获得如何使用 dtrace 实用程序执行这些任务的详细示例。

选项

-P、-m、-f、-n 以及 -i 选项接受的参数可包括括在斜杠 // 中的可选 D 语言 predicate 与括在大括号 {} 中的 D 语言 action 语句列表。在命令行上指定的 D 程序代码必须适当用引号括起，以避免 Shell 进行元字符解释。

所支持的选项如下：

-32 | -64

D 编译器使用操作系统内核的本机数据模型生成程序。可使用 isainfo - b 命令确定当前操作系统的数据模型。如果指定了 -32 选项，则 dtrace 将强制 D 编译器使用 32 位数据模型编译 D 程序。如果指定了 -64 选项，则 dtrace 将强制 D 编译器使用 64 位数据模型编译 D 程序。通常这些选项不是必需的，因为 dtrace 会选择本机数据模型作为缺省数据模型。数据模型会影响整数类型的大小和其他语言属性。对任一数据模型编译的 D 程序可在 32 位和 64 位内核上执行。-32 和 -64 选项还可确定 -G 选项生成的 ELF 文件格式（ELF32 或 ELF64）。

-a

声明匿名跟踪状态并显示跟踪数据。可将 -a 选项与 -e 选项组合在一起，以强制 dtrace 在使用匿名跟踪状态后立即退出，而不是继续等待新数据。有关匿名跟踪的更多信息，请参见《Solaris Dynamic Tracing Guide》。

-A

生成 driver.conf(4) 指令以进行匿名跟踪。该选项将构造一组 dtrace(7D) 配置文件指令，为匿名跟踪启用指定探测器，然后退出。缺省情况下，dtrace 尝试将指令存储到文件 /kernel/drv/dtrace.conf 中。如果使用 -o 选项指定备用输出文件，则可修改此行为。

-b bufsz

设置主体跟踪缓冲区大小 (bufsz)。 跟踪缓冲区大小可以使用任何大小后缀 k、m、g 或 t。如果不能分配缓冲区空间，则 dtrace 将根据 bufresize 属性的设置减小缓冲区大小或退出。

-c cmd

运行指定的命令 cmd，并在完成时退出。如果命令行上有多个 -c 选项，dtrace 将在所有命令退出后退出，并报告每个子进程终止时的退出状态。第一个命令的进程 ID 可供在命令行上（或者使用 -s 选项通过 $target 宏变量）指定的任何 D 程序使用。有关宏变量的更多信息，请参见《Solaris Dynamic Tracing Guide》。

-C

在编译 D 程序之前对它们运行 C 预处理程序 cpp(1)。可使用 -D、-U、-I 和 -H 选项将这些选项传递到 C 预处理程序。如果使用 -X 选项，则可选择 C 标准的符合程度。有关调用 C 预处理程序时由 D 编译器定义的一组令牌的说明，请参见 -X。

-D name [=value]

调用 cpp(1)（使用 -C 选项启用）时定义 name。如果指定等号 (=) 和其他 value，则 name 将赋予相应的值。此选项将 -D 选项传递到每个 cpp 调用。

-e

在编译所有请求并使用匿名跟踪状态（-a 选项）之后、启用任何探测器之前退出。可以结合使用该选项与 -a 选项以列出匿名跟踪数据，然后退出。还可将该选项与 D 编译器选项结合使用。此结合使用将验证无需真正执行程序并启用相应检测过程验就对程序进行编译。

-f[[provider:]module:]function[[predicate]action ]]

指定要跟踪或列出的函数名称（-l 选项）。相应参数可以包括下列任何探测器说明形式：provider:module:function、module:function 或 function。未指定的探测器说明字段将留为空白，并且与任何探测器相匹配，无论这些字段中的值是什么。如果说明中仅指定了 function 限定符，则会匹配所有包含相应 function 的探测器。可将可选 D 探测器子句用作 -f 参数的后缀。在命令行上，可以一次指定多个 -f 选项。

-F

通过标识函数的入口和返回位置来合并跟踪输出。对函数入口的探测报告将进行缩进，并在其输出内容前附带 -> 前缀。对函数返回的探测报告将不进行缩进，并在其输出内容前附带 <- 前缀。系统调用进入探测器报告将进行缩进，并在其输出内容前附带 => 前缀。系统调用返回探测器报告将不进行缩进，并在其输出内容前附带 <= 前缀。

-G

生成包含嵌入式 DTrace 程序的 ELF 文件。在程序中指定的 DTrace 探测器将保存在可与其他程序链接的可重定位 ELF 对象中。如果 -o 选项存在，则会使用指定为此操作数参数的路径名来保存 ELF 文件。如果 -o 选项不存在，且 DTrace 程序随附有名称为 filename.d 的文件，则 ELF 文件将使用名称 filename.o 进行保存。 否则，ELF 文件将使用名称 d.out 进行保存。

-H

在调用 cpp(1)（使用 -C 选项启用）时列出所包含文件的路径名。此选项会将 -H 选项传递到每个 cpp 调用，从而使调用将路径名的列表显示到 stderr，每个路径名显示为一行。

-h

以指定的提供器定义生成包含与探测器对应的宏的头文件。该选项应用于生成由其他源文件包含以备稍后与 -G 选项结合使用的头文件。如果 -o 选项存在，则会使用指定为此选项参数的路径名来保存头文件。如果 -o 选项不存在，且 DTrace 程序随附有名称为 filename.d 的文件，则头文件将使用名称 filename.h 进行保存。

-i probe-id[[predicate] action]

指定要跟踪或列出的探测器标识符 (probe-id) （-l 选项）。可以使用十进制整数指定探测器 ID，如 dtrace -l 所示。 可将可选 D 探测器子句用作 -i 参数的后缀。一次可以指定多个 -i 选项。

-I path

在调用 cpp(1)（使用 -C 选项启用）时，将指定的目录 path 添加到 #include 文件的搜索路径。此选项将 -I 选项传递到每个 cpp 调用。指定的 path 将插入到缺省目录列表之前的搜索路径中。

-L path

将指定的目录 path 添加到 DTrace 库的搜索路径。DTrace 库用于包含可在编写 D 程序时使用的常见定义。指定的 path 将添加到缺省库搜索路径后面。

-l

列出探测器而不是启用它们。如果指定了 -l 选项，dtrace 将生成与使用 -P、-m、-f、-n、-i 和 -s 选项指定的说明相匹配的探测器报告。如果未指定这些选项中的任何一个，该选项将列出所有探测器。

-m [[provider:] module: [[predicate] action]]

指定要跟踪或列出的模块名称（-l 选项）。相应参数可以包括下列任何探测器说明形式：provider:module 或 module。未指定的探测器说明字段将留为空白，并且与任何探测器相匹配，无论这些字段中的值是什么。如果说明中仅指定了 module 限定符，则会匹配所有包含相应 module 的探测器。可将可选 D 探测器子句用作 -m 参数的后缀。在命令行上，一次可以指定多个 -m 选项。

-n [[[provider:] module:] function:] name [[predicate] action]

指定要跟踪或列出的探测器名称（-l 选项）。相应参数可以包括下列任何探测器说明形式：provider:module:function:name、module:function:name、function:name 或 name。未指定的探测器说明字段将留为空白，并且与任何探测器相匹配，无论这些字段中的值是什么。如果说明中仅指定了 name 限定符，则会匹配所有包含相应 name 的探测器。可将可选 D 探测器子句用作 -n 参数的后缀。在命令行上，一次可以指定多个 -n 选项。

-o output

针对 -A、-G、-h 以及 -l 选项或跟踪的数据本身指定 output 文件。如果 -A 选项存在而 -o 不存在，则缺省输出文件为 /kernel/drv/dtrace.conf。如果 -G 选项存在并且 -s 选项的参数为 filename.d 形式，而 -o 不存在，则缺省输出文件为 filename.o。否则，缺省输出文件为 d.out。

请注意，随着使用 -o 选项连续调用 dtrace，dtrace 不会覆盖输出文件，而是附加到输出文件。

-p pid

获取指定的进程 ID pid，高速缓存其符号表，然后在完成时退出。如果命令行上有多个 -p 选项，dtrace 将在所有命令退出后退出，并报告每个进程终止时的退出状态。第一个进程 ID 可供在命令行上（或使用 -s 选项通过 $target 宏变量）指定的任何 D 程序使用。有关宏变量的更多信息，请参见《Solaris Dynamic Tracing Guide》。

-P provider [[predicate] action]

指定要跟踪或列出的提供器名称（-l 选项）。其余的探测器说明字段（模块、函数和名称）将留为空白，并且与任何探测器相匹配，无论这些字段中的值是什么。可将可选 D 探测器子句用作 -P 参数的后缀。在命令行上，可以一次指定多个 -P 选项。

-q

设置静默模式。dtrace 将取消显示消息（如与指定选项和 D 程序相匹配的探测器数目），并且将不列出列标题、CPU ID、探测器 ID，也不会在输出中插入新行。只有 D 程序语句（如 trace() 和 printf()）跟踪并格式化的数据才会显示在 stdout 中。

-s

编译指定的 D 程序源文件。如果 -e 选项存在，则将编译该程序，但不会启用检测过程。如果 -l 选项存在，则将编译该程序，并且会列出与其相匹配的一组探测器，但不会启用检测过程。如果 -e、-l、-G 或 -A 均不存在，则启用 D 程序指定的检测过程并开始跟踪。

-S

显示 D 编译器中间代码。对于为每个 D 程序生成的中间代码，D 编译器会将它的报告生成到 stderr。

-U name

在调用 cpp(1)（使用 -C 选项启用）时取消定义指定的 name。此选项将 -U 选项传递到每个 cpp 调用。

-v

设置详细模式。如果指定了 -v 选项，dtrace 将生成程序稳定性报告，说明所指定 D 程序的最低接口稳定性和相关性级别。DTrace 稳定性级别在《Solaris Dynamic Tracing Guide》中进行了详细阐述。

-V

报告 dtrace 支持的最高 D 编程接口版本。版本信息将列显到 stdout，然后 dtrace 命令将退出。有关 DTrace 版本控制功能的更多信息，请参见《Solaris Dynamic Tracing Guide》。

-w

允许使用 -s、-P、-m、-f、-n 或 -i 选项在指定的 D 程序中执行破坏性操作。如果未指定 -w 选项，dtrace 将不允许编译或启用包含破坏性操作的 D 程序。

-x arg [=val]

启用或修改 DTrace 运行时选项或 D 编译器选项。选项列表可在《Solaris Dynamic Tracing Guide》中找到。 将通过指定名称来启用布尔选项。将通过使用等号（=）分隔选项名称和值来设置包含值的选项。

-X a | c | s | t

指定在调用 cpp(1)（使用 -C 选项启用）时应选择的 ISO C 标准的符合程度。根据参数字母的值，-X 选项参数会影响 __STDC__ 宏的值和存在性。

-X 选项支持以下参数：

a

缺省。ISO C 及 K&R 兼容性扩展，包含 ISO C 所需的语义更改。如果未指定 -X，则此模式为缺省模式。在将 cpp 与 -Xa 选项一起调用时，预定义宏 __STDC__ 具有值 0。

c

一致性。严格符合 ISO C（不包含 K&R C 兼容性扩展）。将 cpp 与 -Xc 选项一起调用时，预定义宏 __STDC__ 具有值 1。

s

仅 K&R C。将 cpp 与 -Xs 选项一起调用时，不会定义宏 __STDC__。

t

转换。ISO C 及 KR C 兼容性扩展，不包含 ISO C 所需的语义更改。将 cpp 与 -Xt 选项一起调用时，预定义宏 __STDC__ 具有值 0。

因为 -X 选项仅影响 D 编译器调用 C 预处理程序的方式，所以从 D 的角度看来，-Xa 和 -Xt 选项是等同的，提供这两个选项都是为了简化 C 生成环境中设置的重复使用。

无论 -X 模式如何，始终会指定下列附加 C 预处理程序定义，并且它们在所有模式中有效：

• __sun

• __unix

• __SVR4

• __sparc（仅在 SPARC 系统上）

• __sparcv9（仅当在 SPARC 系统上编译 64 位程序时）

• __i386（仅当在 x86 系统上编译 32 位程序时）

• __amd64（仅当在 x86 系统上编译 64 位程序时）

• __`uname -s`_`uname -r`（例如，__SunOS_5_10）

• __SUNW_D=1

• __SUNW_D_VERSION=0xMMmmmuuu

  其中，MM 是以十六进制表示的主要发行版值，mmm 是以十六进制表示的次要发行版值，而 uuu 是以十六进制表示的微发行版值。有关 DTrace 版本控制的更多信息，请参见《Solaris Dynamic Tracing Guide》。

-Z

允许与任何探测器都不匹配的探测器说明。在未指定 -Z 选项时，如果在 D 程序文件中（使用 -s 选项）或在命令行上（使用 -P、-m、-f、-n 或 -i 选项）指定的任何探测器说明中包含不与任何已知探测器匹配的说明，则 dtrace 会报告错误并退出。

操作数

可以在 dtrace 命令上指定零或多个附加参数，以定义一组宏变量（$1、$2 等等）。附加参数可以用于使用 -s 选项指定的 D 程序中或命令行上。宏变量的使用在《Solaris Dynamic Tracing Guide》中有进一步的描述。

退出状态

将返回下列退出值：

0

成功完成。

对于 D 程序请求，退出状态 0 指示已成功编译程序，并且已成功启用探测器，或者已成功检索匿名状态。即使指定的跟踪请求遇到错误或删除，dtrace 也会返回 0。

1

出现错误。

对于 D 程序请求，退出状态 1 指示程序编译失败或者无法满足指定的请求。

2

指定的命令行选项或参数无效。

属性

有关以下属性的说明，请参见 attributes(5)：

命令行语法是 Committed（已确定）。人可阅读的输出是 Uncommitted（未确定）。

另请参见

cpp(1)、isainfo(1)、ssh(1)、libdtrace(3LIB)、driver.conf(4)、attributes(5)、dtrace(7D)

《《Solaris Dynamic Tracing Guide》》

用法

使用 -p 标志后，dtrace 将在检查目标进程并报告结果时停止这些进程。进程被停止后将无法执行任何操作。这意味着，例如，如果 X 服务器由在 X 服务器控制下的窗口中运行的 dtrace 进行检查，则整个窗口系统可能会出现死锁现象，因为 proc 工具将尝试将其结果显示到无法刷新的窗口。在此情况下，使用 ssh(1) 从另一个系统登录，中止违例 proc 工具以清除死锁。