Go to main content

man pages section 8: System Administration Commands

Exit Print View

Updated: Thursday, June 13, 2019
 
 

ttrace(8)

Name

ttrace - Administer trap tracing from the hypervisor layer

Synopsis

ttrace config 
ttrace config  -K 
ttrace config  -K [-b bufsz [k | m] ] 
ttrace enable  -K [-v verbose] 
ttrace enable  -K [-v verbose] [-p processor_id ...] 
ttrace disable -K 
ttrace disable -K [-p processor_id ...] 
ttrace suspend -K 
ttrace resume  -K 
ttrace dump    -K 
ttrace dump    -K [-t] [-o output] [-p processor_id ...]
ttrace config  -H 
ttrace config  -H [-b bufsz [k | m] ] 
ttrace enable  -H 
ttrace enable  -H [-p processor_id ...] 
ttrace disable -H 
ttrace disable -H [-p processor_id ...] 
ttrace suspend -H 
ttrace resume  -H 
ttrace dump    -H 
ttrace dump    -H [-t] [-o output] [-p processor_id ...]

Description

The ttrace utility is used to administer hypervisor and kernel level trap tracing. Privileged users can enable and disable tracing dynamically on demand, and configure the trace as needed.

ttrace without arguments displays the usage information.

Options

The following options are supported:

–K

Applies the command to the Oracle Solaris kernel trap tracing.

–H

Applies the command to hypervisor trap tracing on sun4v platform.

The options –K and –H cannot be used together in one command.

–b bufsz [k | m]

Sets the trace buffer size bufsz for all the CPUs in the system. The buffer size bufsz can include either of the suffixes k or m. By default, bufsz is 2 * PAGESIZE. If the buffer with the desired size is allocated, trap trace reconfiguration will also occur, with the new buffer replacing the old one. The upper limit size for HV trace buffer is 16M. For kernel trap trace, the buffer upper limit is 16M on sun4v, but 4M on OPL.

However, if the desired buffer cannot be allocated at the moment due to a lack of memory, ttrace will continue to use the previously allocated buffer. As a result, the actual bufsz on a particular CPU might be different from the global bufsz.

Trap trace reconfiguration is expensive, so it is not recommended to use this option too often on production machines.

–p processor_id processor_id...

Lists the CPUs on which the actions apply. The sub-commands which can accept this option are enable, disable, and dump.

–o output

Sets the output file when dumping trace records. If this option is omitted, the default output is stdout.

–t

Walks trace records across all CPUs in the order of time stamps. If this option is omitted, the trace records will be walked first by CPU.

–v

Specifies a verbose level for kernel trap tracing when the traces are being enabled. The level is a number between 1 and 7. The default level is 7.

Sub Commands

The following subcommands are supported:

enable

Enables trap tracing on a list of CPUs. If no CPU is specified through the –p option, then the traces will be enabled on all CPUs.

disable

Disables trap tracing on a list of CPUs. If no CPU is specified through the –p option, then all the traces will be disabled.

suspend

Suspends trap trace on all CPUs. A CPU that has tracing disabled may be suspended. When resumed, it will still be disabled. The subcommands, suspend and resume, generate less overhead than the subcommands disable and enable. If you wish to stop tracing on all CPUs temporarily, you should use the suspend and resume subcommands.

resume

Restores the traces on all CPUs to the status prior to the suspend. The suspend and resume subcommands operate on all CPUs.

config

Displays the trap trace status for all CPUs, without an option. If specified with the –b bufsz option, the trace buffer size will be set to the specified bufsz, and result in trap trace reconfiguration.

dump

Dumps trace records. Without any options, all trace records will be displayed on the terminal. If an output file and a list of CPUs are provided, only the traces from these CPUs will be dumped out to the specified output file.

The format of the output is subject to change in the future.

TRAP TRACE STATUS

The CPU supports the following trap trace statuses.

Ready

The trace buffer has been allocated therefore, the trace is ready to be enabled.

Config

The trace buffer has been allocated and configured, but not enabled. Therefore, the trace is ready to be enabled.

Enabled

The trap trace has been enabled, therefore the contents in the trace buffer is being updated with the trap activities on the CPU.

Disabled

The trap trace has been disabled. So the contents in the trace buffer will not be updated until re-enabled. The trap activities occurred between the status Disabled and Enabled will not be reflected in the trace buffer.

Suspended

The trace has been suspended on all CPUs.

Exit Status

The following exit values are returned:

0

Successful completion.

1

An error occurred.

Examples

Example 1 Displaying the Current Trap Trace Status on Each CPU and its Buffer Size

The following example shows how the config sub-command without argument displays the current kernel and hypervisor trap trace status and buffer size for each CPU. If either –K or –H option is specified, only the status for the corresponding object will be displayed.

# ttrace config -K 
Kernel trap trace status : 
CPU     Trace-Status      buffer             size           verbose 
0       Enabled           0x10046410         16320          7 
1       Enabled           0x410b4000         16320          7 
2       Enabled           0x410bc000         16320          1 
3       Enabled           0x410c4000         16320          1

# ttrace config -H
HV trap trace status :
CPU     Trace-Status      buffer             size
0       Ready             0x22e70000         32768
1       Ready             0x22950000         32768
2       Ready             0x22958000         32768
3       Ready             0x22960000         32768
Example 2 Setting the Trace Buffer Size

The following example shows how to set the trace buffer size by using the config subcommand with the –b <bufsz> option and resulting in trace reconfiguration:

# ttrace config -K -b 128k 
kernel ttrace buffer size has been set to 131072 

# ttrace config -K 
kernel trap trace status : 
CPU     Trace-Status      buffer             size           verbose 
0       Ready             0x3e680000         131072         - 
1       Ready             0x3e6a0000         131072         - 
2       Ready             0x3e6c0000         131072         - 
3       Ready             0x3e6e0000         131072         - 
  
# ttrace config -H -b 64k 
HV ttrace buffer size has been set to 65536 
  
# ttrace config -H 
HV trap trace status : 
CPU     Trace-Status      buffer             size 
0       Suspended         0x22e70000         65536 
1       Suspended         0x22950000         65536 
2       Suspended         0x22958000         65536 
3       Suspended         0x22960000         65536 
Example 3 Enabling Traces on all CPUs

The following example show how to enable traces on all CPUs by using the enable subcommand:

# ttrace enable -K 
# ttrace config -K 
kernel trap trace status : 
CPU     Trace-Status      buffer             size           verbose 
0       Enabled           0x3e680000         131072         7 
1       Enabled           0x3e6a0000         131072         7 
2       Enabled           0x3e6c0000         131072         7 
3       Enabled           0x3e6e0000         131072         7

# ttrace enable -H
# ttrace config -H
CPU     Trace-Status      buffer             size 
0       Enabled           0x22d30000         65536
1       Enabled           0x22d40000         65536
2       Enabled           0x22e70000         65536
3       Enabled           0x22950000         65536

The subcommand enable with option –p followed by a list of CPUs will enable the trace on the list of CPUs only if they are currently disabled.

Example 4 Disabling Traces on all CPUs

The following example shows how to disable the traces on all CPUs by using the disable subcommand without –p option. If –p option is provided, only traces on the list of CPUs will be disabled.

# ttrace disable -K -p 0 1 
# ttrace config -K 
kernel trap trace status : 
CPU     Trace-Status      buffer             size           verbose 
0       Disabled          0x3e680000         131072         - 
1       Disabled          0x3e6a0000         131072         - 
2       Enabled           0x3e6c0000         131072         7 
3       Enabled           0x3e6e0000         131072         7

# ttrace disable -H -p 2 3
# ttrace config -H
CPU     Trace-Status       buffer             size 
0       Enabled            0x22d30000         65536
1       Enabled            0x22d40000         65536
2       Disabled           0x22e70000         65536
3       Disabled           0x22950000         65536

Example 5 Suspending and Resuming Trap Traces on all CPUs

The following example shows how to suspend and resume trap traces on all CPUs. The suspend sub-command suspends trap traces on all CPUs. A CPU that has tracing disabled may be suspended. When they are resumed, they will be resumed to status prior to the suspend. The sub-commands suspend and resume are more efficient than the sub-commands disable and enable.

# ttrace suspend -K 
# ttrace suspend -H 
  
# ttrace resume -K 
# ttrace resume -H
Example 6 Displaying Trace Records

The following example shows how to display trace records. Without arguments, all the trace records will be displayed on the terminal. If –o option is presented followed by an output file, the records will be saved to the output file. If –p option is presented followed by a list of CPUs, only the records from these CPUs will be saved.

# ttrace dump -K -o ktrace.out -p 0 1 
# ttrace dump -H -o htrace.out -p 2 3

With –t option, the trace records will be saved across CPUs in the order of the time stamps, instead of CPU by CPU:

# ttrace dump -K -t -o kalltrace.out 
# ttrace dump -H -t -o halltrace.out

An alternative way to retrieve the trace data is with mdb(1).

<cpuid>::ttrace 
<cpuid>::httrace

Attributes

See attributes(7) for descriptions of the following attributes:

ATTRIBUTE TYPE
ATTRIBUTE VALUE
Availability
system/kernel/ttrace
Interface Stability
Committed

See Also

attributes(7)