ttrace - Administer trap tracing from the hypervisor layer
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 ...]
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.
The following options are supported:
Applies the command to the Oracle Solaris kernel trap tracing.
Applies the command to hypervisor trap tracing on sun4v platform.
The options –K and –H cannot be used together in one command.
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.
Lists the CPUs on which the actions apply. The sub-commands which can accept this option are enable, disable, and dump.
Sets the output file when dumping trace records. If this option is omitted, the default output is stdout.
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.
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.
The following subcommands are supported:
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.
Disables trap tracing on a list of CPUs. If no CPU is specified through the –p option, then all the traces will be disabled.
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.
Restores the traces on all CPUs to the status prior to the suspend. The suspend and resume subcommands operate on all CPUs.
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.
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.
The CPU supports the following trap trace statuses.
The trace buffer has been allocated therefore, the trace is ready to be enabled.
The trace buffer has been allocated and configured, but not enabled. Therefore, the trace is ready to be enabled.
The trap trace has been enabled, therefore the contents in the trace buffer is being updated with the trap activities on the CPU.
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.
The trace has been suspended on all CPUs.
The following exit values are returned:
An error occurred.
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 32768Example 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 65536Example 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 65536Example 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 -HExample 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).
See attributes(5) for descriptions of the following attributes: