test

Oracle Solaris Studio 12.2：性能分析器

使用 collect 命令收集数据

要从命令行使用 collect 命令运行收集器，请键入以下内容。


% collect collect-options program program-arguments

其中，collect-options 是 collect 命令选项，program 是要收集其数据的程序的名称，program-arguments 是该程序的参数。目标程序通常是二进制可执行文件。但是，如果设置环境变量 SP_COLLECTOR_SKIP_CHECKEXEC，可以将脚本指定为目标。

如果未提供 collect-options，则缺省情况下会打开分析间隔大约为 10 毫秒的基于时钟的分析。

要获取可用于分析的选项列表和所有硬件计数器的名称列表，请键入不带参数的 collect 命令。


% collect

有关对硬件计数器列表的描述，请参见硬件计数器溢出分析数据。另请参见硬件计数器溢出分析的限制。

数据收集选项

这些选项控制所收集数据的类型。有关对数据类型的介绍，请参见收集器收集何种数据。

如果未指定数据收集选项，则缺省值为 -p on，这会启用缺省分析间隔大约为 10 毫秒的基于时钟的分析。该缺省值由 -h 选项关闭，而不是由任何其他数据收集选项关闭。

如果您明确禁用了基于时钟的分析，而且未启用跟踪或硬件计数器溢出分析，则 collect 命令会列显一条警告消息，并且只收集全局数据。

-p option

收集基于时钟的分析数据。option 的允许值包括：

collect 命令的缺省操作是收集基于时钟的分析数据。

-h counter_definition_1...[, counter_definition_n]

收集硬件计数器溢出分析数据。计数器定义的数量与处理器有关。

如果安装了 perfctr 修补程序（可以从 http://user.it.uu.se/~mikpe/linux/perfctr/2.6/ 下载），该选项在运行 Linux 操作系统的系统上是可用的。安装说明包含在 tar 文件中。使用 LD_LIBRARY_PATH 环境变量的值搜索用户级 libperfctr.so 库，即：对于 32 位版本，在 /usr/local/lib、/usr/lib 和 /lib 中进行搜索；对于 64 位版本，在 /usr/local/lib64、/usr/lib64 和 /lib64 中进行搜索。

要获取可用计数器的列表，请在终端窗口中键入不带参数的 collect。硬件计数器列表一节提供了对计数器列表的介绍。在大多数系统上，即使未列出计数器，仍可以使用数值（十六进制或十进制）对其进行指定。

计数器定义可以采用下列形式之一，具体取决于处理器是否支持硬件计数器的属性。

[+]counter_name[/ register_number][,interval ]

[+]counter_name[~ attribute_1=value_1]...[~attribute_n =value_n][/ register_number][,interval ]

特定于处理器的 counter_name 可以为下列名称之一：

如果指定了多个计数器，则它们必须使用不同的寄存器。如果它们未使用不同的寄存器，则 collect 命令会列显一条错误消息并退出。

如果硬件计数器对与内存访问有关的事件进行计数，可以在计数器名称前添加 + 符号，以针对引起计数器溢出的指令打开对其真实程序计数器地址 (counter address, PC) 的搜索。这种回溯功能适用于 SPARC 处理器，并且仅适用于类型为 load、store 或 load-store 的计数器。如果搜索成功，则所引用的虚拟 PC、物理 PC 和有效地址将存储在事件数据包中。

在某些处理器上，可以将多个属性选项与一个硬件计数器关联。如果某个处理器支持多个属性选项，则运行不带参数的 collect 命令会列出计数器定义（包括属性名）。可以使用十进制或十六进制格式来指定属性值。

间隔（溢出值）是事件计数或循环计数的数量，在达到该数量时，硬件计数器将溢出并且将记录溢出事件。间隔可以设置为下列值之一：

缺省值是为每个计数器预定义的正常阈值，它出现在计数器列表中。另请参见硬件计数器溢出分析的限制。

如果在使用 -h 选项时未明确指定 -p 选项，则基于时钟的分析功能将处于关闭状态。要同时收集硬件计数器数据和基于时钟的数据，必须同时指定 -h 选项和 -p 选项。

-s option

收集同步等待跟踪数据。option 的允许值包括：

对于 Java 程序，不能记录同步等待跟踪数据；如果指定它，将视为错误。

在 Solaris 上，跟踪以下函数：

mutex_lock()

rw_rdlock()

rw_wrlock()

cond_wait()

cond_timedwait()

cond_reltimedwait()

thr_join()

sema_wait()

pthread_mutex_lock()

pthread_rwlock_rdlock()

pthread_rwlock_wrlock()

pthread_cond_wait()

pthread_cond_timedwait()

pthread_cond_reltimedwait_np()

pthread_join()

sem_wait()

在 Linux 上，跟踪以下函数：

pthread_mutex_lock()

pthread_cond_wait()

pthread_cond_timedwait()

pthread_join()

sem_wait()

-H option

收集堆跟踪数据。option 的允许值包括：

缺省情况下，堆跟踪功能处于关闭状态。对于 Java 程序，不支持堆跟踪；如果指定堆跟踪，将被视为错误。

-M option

指定对 MPI 实验的收集。collect 命令的目标必须为 mpirun 命令，必须使用 ‐‐ 选项将 mpirun 的选项与要使用 mpirun 命令运行的目标程序分开。（始终将 -- 选项和 mpirun 命令一起使用，以便可以通过将 collect 命令及其选项前置于 mpirun 命令行来收集实验。）实验按惯常方式命名且称为创始实验，其目录包含每个 MPI 进程的子实验，按等级进行命名。

option 的允许值包括：

缺省情况下，MPI 实验的收集功能是关闭的。打开 MPI 实验的收集功能时，-m 选项的缺省设置更改为 on。

键入不带选项的 collect 命令时，或者如果使用 -M 选项指定无法识别的版本，将会列显受支持的 MPI 版本。

-m option

收集 MPI 跟踪数据。option 的允许值包括：

缺省情况下关闭 MPI 跟踪，除非启用了 -M 选项，在这种情况下会缺省打开 MPI 跟踪。通常使用 -M 选项收集 MPI 实验，无需用户对 MPI 跟踪进行控制。如果要收集 MPI 实验，但不收集 MPI 跟踪数据，请使用显式选项 -M MPI-version -m off。

有关其调用被跟踪的 MPI 函数以及根据跟踪数据计算的度量的更多信息，请参见MPI 跟踪数据。

-S option

定期记录样本包。option 的允许值包括：

缺省情况下，启用间隔为 1 秒的定期抽样功能。

-c option

记录计数数据，仅针对 Solaris 系统。

注 –

此功能要求您安装 Binary Interface Tool (BIT)，它是 Add-on Cool Tools for OpenSPARC（适用于 OpenSPARC 的附加酷类工具）的一部分（可从 http://cooltools.sunsource.net/ 获取）。BIT 是用来度量 Solaris 二进制代码的性能或测试套件适用范围的工具。

option 的允许值包括：

缺省情况下，关闭对计数数据的收集。计数数据不能和任何其他类型的数据一起收集。

-I directory

为 bit 检测指定目录。该选项仅在 Solaris 系统上可用，且仅当指定了 -c 选项时才有意义。

-N library_name

指定要从 bit 检测中排除的库，不管该库是链接到可执行文件还是使用 dlopen() 装入。该选项仅在 Solaris 系统上可用，且仅当指定了 -c 选项时才有意义。可以指定多个 -N 选项。

-r option

为线程分析器收集数据争用检测或死锁检测数据。允许的值包括：

有关 collect -r 命令和线程分析器的更多信息，请参见《Oracle Solaris Studio 12.2：线程分析器用户指南》和 tha(1) 手册页。

实验控制选项

这些选项控制如何收集实验数据。

-F option

控制是否应当记录子孙进程的数据。option 的允许值包括：

缺省情况下设置 -F on 选项，这样收集器将跟踪通过调用函数 fork(2)、fork1(2)、fork(3F)、vfork(2) 和 exec(2) 及其变体而创建的进程。对 vfork 的调用已在内部被替换为对 fork1 的调用。

对于 MPI 实验，缺省情况下还跟踪子孙进程。

如果指定 -F all 选项，收集器将跟踪所有子孙进程，其中包括那些通过调用 system(3C)、system(3F)、sh(3F)、posix_spawn(3p)、posix_spawnp(3p) 和 popen(3C) 以及类似函数而创建的子孙进程以及与其相关的子孙进程。

如果指定 -F '= regexp ' 选项，收集器将跟踪所有子孙进程。当子孙进程的名称或子实验的名称与指定的正则表达式匹配时，收集器将创建子实验。有关正则表达式的信息，请参见 regexp(5) 手册页。

当您在子孙进程上收集数据时，收集器会针对创始实验中的每个子孙进程打开一个新实验。这些新实验是通过向实验后缀添加一个下划线、一个字母和一个数字来命名的，如下所示：

例如，如果初始进程的实验名称是 test.1.er，则由它的第三个派生创建的子进程的实验是 test.1.er/_f3.er。如果该子进程针对新映像执行 exec 操作，则相应的实验名称为 test.1.er/_f3_x1.er。如果该子进程使用 popen 调用创建另一个进程，则实验名称为 test.1.er/_f3_x1_c1.er。

读取创始实验时，分析器和 er_print 实用程序将自动读取子孙进程的实验，并在数据显示中显示子孙进程。

要从命令行中选择要显示的数据，请明确指定 er_print 或 analyzer 的路径名。所指定的路径必须包含创始实验的名称以及创始目录中后续实验的名称。

例如，要查看 test.1.er 实验的第三个派生的数据，需要指定以下内容：

er_print test.1.er/_f3.er

analyzer test.1.er/_f3.er

或者，可以使用感兴趣的后续实验的显式名称来准备实验组文件。

要在分析器中检查子孙进程，请装入创始实验并从“视图”菜单中选择“过滤数据”。此时将显示一个实验列表，其中只有创始实验处于选中状态。取消选中初始实验并选中感兴趣的后续实验。

注 –

如果正在跟踪子孙进程时创始进程退出，将继续从仍然在运行的子孙进程中收集数据。创始实验目录会相应地继续变大。

您还可以收集脚本上的数据并跟踪脚本的子孙进程。有关更多信息，请参见从脚本收集数据。

-j option

当目标程序是 JVM 时，启用 Java 分析。option 的允许值包括：

如果要收集 .class 文件或 .jar 文件中的数据，则不需要 -j 选项，但前提是 java 可执行文件的路径在 JDK_HOME 环境变量或 JAVA_PATH 环境变量中。随后可以在 collect 命令行上将目标 program 指定为具有或不具有扩展名的 .class 文件或 .jar 文件。

如果无法在 JDK_HOME 或 JAVA_PATH 环境变量中定义 java 可执行文件的路径，或者要禁用对 Java HotSpot 虚拟机所编译的方法的识别，则可以使用 -j 选项。如果使用此选项，在 collect 命令行上指定的 program 必须为版本不低于 JDK 6 Update 18 的 Java 虚拟机。collect 命令验证 program 是否为 JVM 且是 ELF 可执行文件，如果不是，collect 命令将列显一条错误消息。

如果要使用 64 位 JVM 收集数据，则不得对 32 位 JVM 的 java 命令使用 -d64 选项。否则，将收集不到任何数据。而是，必须在 collect 命令的 program 参数中或者在 JDK_HOME 或 JAVA_PATH 环境变量中指定 64 位 JVM 的路径。

-J java_argument

指定要传递到用于分析的 JVM 的其他参数。如果您指定了 -J 选项但未指定 Java 分析，则会生成一个错误并且不运行实验。如果 java_argument 包含多个参数，则必须使用括号将其括起来。它必须包括一组由空格或制表符分隔的令牌。每个令牌作为单独的参数传递给 JVM。JVM 的大多数参数必须以 "-" 字符开头。

-l signal

当名为 signal 的信号传递到进程时，记录样本包。

可以通过全信号名、不带开始的几个字母 SIG 的信号名或信号编号来指定信号。请不要使用程序所使用的信号或会终止执行的信号。建议的信号为 SIGUSR1 和 SIGUSR2。即使指定时钟分析，也可以使用 SIGPROF。可通过 kill 命令将信号传递到进程。

如果同时使用 -l 和 -y 选项，则必须针对每个选项使用不同的信号。

如果您使用该选项而程序具有其自己的信号处理程序，则应当确保使用 -l 指定的信号会传递到收集器的信号处理程序，而不是被截获或忽略。

有关信号的更多信息，请参见 signal(3HEAD) 手册页。

-t duration

指定数据收集的时间范围。

可以将 duration 指定为单个数字（可以选择添加 m 或 s 后缀）以指示实验在该时间（单位为分钟或秒）终止。缺省情况下，持续时间以秒为单位。也可以将 duration 指定为用连字符分隔的两个这样的数字，这会导致数据收集暂停，直到经过第一个时间之后才开始收集数据。当到达第二个时间时，数据收集终止。如果第二个数字为零，则在初次暂停之后收集数据，直到该程序运行结束。即使该实验已经终止，也允许目标进程运行至结束。

-x

在从 exec 系统调用退出时使目标进程停止，以便允许调试器附加到目标进程。如果将 dbx 附加到目标进程，请使用 dbx 命令 ignore PROF 和 ignore EMT 来确保收集信号传递到 collect 命令。

-y signal[ ,r]

控制对包含名为 signal 的信号的数据的记录。无论何时将信号传递到进程，它都在暂停状态（在此期间不记录任何数据）和记录状态（在此期间记录数据）之间切换。无论切换状态如何，都将始终记录样本点。

可以通过全信号名、不带开始的几个字母 SIG 的信号名或信号编号来指定信号。请不要使用程序所使用的信号或会终止执行的信号。建议的信号为 SIGUSR1 和 SIGUSR2。即使指定时钟分析，也可以使用 SIGPROF。可通过 kill 命令将信号传递到进程。

如果同时使用 -l 和 -y 选项，则必须针对每个选项使用不同的信号。

使用 -y 选项时，如果已提供可选的 r 参数，则收集器将在记录状态下启动，否则将在暂停状态下启动。如果未使用 -y 选项，则收集器将在记录状态下启动。

如果您使用该选项而程序具有其自己的信号处理程序，则应当确保使用 -y 指定的信号会传递到收集器的信号处理程序，而不是被截获或忽略。

有关信号的更多信息，请参见 signal(3HEAD) 手册页。

输出选项

这些选项控制收集器生成实验的各个方面。

-o experiment_name

使用 experiment_name 作为要记录的实验的名称。experiment_name 字符串必须以字符串 ".er" 结尾；否则 collect 实用程序会列显一条错误消息并退出。

如果不指定 -o 选项，则为实验提供一个格式为 stem.n.er 的名称，其中 stem 是字符串，n 是数字。如果使用 -g 选项指定了组名称，则将 stem 设置为不带 .erg 后缀的组名称。如果未指定组名称，则将 stem 设置为字符串 test。

如果您要从用于运行 MPI 作业的命令之一（例如 mpirun，但不带 -M MPI-version 选项和 -o 选项）调用 collect 命令，则采用用于定义该进程的 MPI 等级的环境变量的名称中使用的值 n。否则，将 n 设置为比当前使用的最大整数还要大的值。

如果没有使用 stem.n.er 格式指定名称，而正在使用给定名称，将显示一条错误消息且实验不会运行。如果名称采用 stem.n.er 格式且正在使用提供的名称，将在与比当前使用的最大值 n 还要大的值对应的名称下记录实验。如果名称已更改，则会显示一条警告。

-d directory-name

将实验置于 directory-name 目录中。此选项仅适用于个别实验，而不适用于实验组。如果该目录不存在，则 collect 实用程序会列显一则错误消息并退出。如果使用 -g 选项指定了某个组，则该组文件也将写入 directory-name 中。

对于最轻量的数据收集，最好使用 -d 选项指定存放数据的目录，以便将数据记录到本地文件。但是，对于群集上的 MPI 实验，创始实验必须在相同的路径下可用，以便所有进程将所有数据记录到创始实验中。

写入长延迟文件系统的实验问题尤为突出，可能进行非常缓慢，特别是在收集样本数据时（缺省采用 -S on 选项）。如果必须通过长延迟连接来进行记录，请禁用样本数据。

-g group-name

使实验成为实验组 group-name 的一部分。如果 group-name 不以 .erg 结尾，则 collect 实用程序会列显一条错误消息并退出。如果该组存在，则会将实验添加到该组中。如果 group-name 不是绝对路径并且使用 -d 指定了一个目录，则实验组将被置于 directory-name 目录中，否则，将被置于当前目录中。

-A option

控制是否应将目标进程所使用的装入对象归档或复制到已记录的实验中。option 的允许值包括：

如果您希望将实验从记录的位置复制到另一台计算机，或者从另一台计算机读取实验，请指定 - A copy。使用该选项不会将任何源文件或目标 (.o) 文件复制到实验中。确保可从在其上检查实验的计算机访问这些文件且这些文件未发生更改。

-L size

将所记录的分析数据量限制在 size 兆字节。该限制适用于基于时钟的分析数据量、硬件计数器溢出分析数据量和同步等待跟踪数据量之和，但不适用于样本点。该限制只是近似值，可以被超出。

当达到该限制时，不再记录分析数据，但实验会一直保持打开状态，直到目标进程终止。如果启用了定期抽样，则会继续写入样本点。

例如，要将限制确定为约 2 GB，请指定 -L 2000。指定的大小必须大于零。

缺省情况下，记录的数据量不存在限制。

-O file

将 collect 本身的所有输出附加到名称 file，但是不重定向所产生的目标的输出。如果该文件设置为 /dev/null，则禁止 collect 的所有输出（包括任何错误消息）。

其他选项

这些 collect 命令选项用于其他目的。

-P process_id

编写 dbx 脚本以附加到具有给定 process_id 的进程，从中收集数据，然后在脚本中调用 dbx。可以仅指定分析数据而不指定跟踪数据，且不支持定时运行（-t 选项）。

-C comment

将注释放在实验的 notes 文件中。最多可以提供十个 -C 选项。该 notes 文件的内容会置于实验标题的前面。

-n

不运行目标，但列显在运行目标时要生成的实验的详细信息。此选项是模拟运行选项。

-R

在终端窗口中显示性能分析器自述文件的文本版本。如果未找到自述文件，则列显一条警告。不再检查任何参数，也不执行进一步的处理。

-V

列显 collect 命令的当前版本。不再检查任何参数，也不执行进一步的处理。

-v

列显 collect 命令的当前版本和正在运行的实验的详细信息。

使用 collect 实用程序从正在运行的进程中收集数据

仅在 Solaris OS 中，可以将 -P pid 选项与 collect 实用程序一起使用来附加到具有指定 PID 的进程并从该进程收集数据。collect 命令的其他选项被转换为 dbx 脚本，系统会调用该脚本来收集数据。只能收集基于时钟的分析数据（-p 选项）和硬件计数器溢出分析数据（-h 选项）。不支持跟踪数据。

如果在使用 -h 选项时未明确指定 -p 选项，则基于时钟的分析功能将处于关闭状态。要同时收集硬件计数器数据和基于时钟的数据，必须同时指定 -h 选项和 -p 选项。

Procedure使用 collect 实用程序从正在运行的进程中收集数据

  1. 确定程序的进程 ID (process ID, PID)。

    如果从命令行启动了程序并将其置于后台，shell 将在标准输出中列显其 PID。否则，可以通过键入以下内容来确定程序的 PID。


    % ps -ef | grep program-name

  2. 使用 collect 命令对该进程启用数据收集，并设置任何可选参数。


    % collect -P pid collect-options

    数据收集选项中对收集器选项进行了说明。有关基于时钟的分析的信息，请参见-p option。有关硬件时钟分析的信息，请参见 -h option。