PTT, in capital letters, is the Per-Thread Time Facility. It consists of kernel-mode and user-mode components that, when running, maintain on-thread statistics for time (cycles) or any of a number of pre-defined metrics. PTT is most often referred to in the context of java callflow analysis which uses the PTT facility to maintain on-thread, per-method counts. In that context, it is controlled programmatically by JProf as needed.
ptt, in lower-case letters, is a user-mode command that allows some control over the PTT facility. You can turn it on and off, read summary information, and dump information about threads (all or subsets) for which PTT data is available.
ptt [-? | -??]
ptt [ints | noints]
ptt [autoterm | noautoterm]
ptt init [metric [metric] [...]] <PrivLevel>
ptt term
ptt info
ptt dump <ProcList> <JtnmOpt> <SortOpt> <AutoOpt> <-t sec> <-f fn> <-cpi> <-x>
PrivLevel: <priv_kernel | priv_user | priv_any>
ProcList: <-pl [pid<,pid,...> | name<,name,...>]
JtnmOpt: <[-jtnm | -jtnm=<path\>prefix]> <-allnames>
SortOpt: <[-sm ## | -sp | -st | -sd | -si]> <[-a | -d]>
AutoOpt: <-s #sec> <r #sec>
* Arguments in "<>" (angle brackets) are OPTIONAL.
* Arguments in "[]" (square brackets) are REQUIRED.
* To get the most up-to-date information enter "swtrace ?" or "swtrace ??"
Where:
********** COMMAND VERBS **********
ints: Set up the Per-Thread Time (PTT) facility to account for
interrupt time in a separate (not on thread) bucket.
- The setting will remain in effect until reset (via noints
command, or until the device driver is unloaded.
- This command just sets a mode. Nothing happens until you
use (init) the PTT facility.
- The PTT default *IS* ints.
noints: Set up the PTT facility to account for interrupt time
as being on-thread - interrupt time is added to total
time on thread.
- The setting will remain in effect until reset (via ints
command, or until the device driver is unloaded.
- This command just sets a mode. Nothing happens until you
use (init) the PTT facility.
- The PTT default *IS NOT* noints.
autoterm: Automatically terminates PTT on process exit.
- This allows for cleaning up after processes that don't
terminate PTT or that don't exit cleanly.
- This command just sets a mode. Nothing happens until you
use (init) the PTT facility.
- The PTT default *IS* autoterm.
* That means that initializing PTT using 'ptt init' will
only be in effect for the duration of the ptt command.
If you want to issue other commands, such as dump, you
*MUST* first enter: 'ptt noautoterm'.
noautoterm: Does not automatically terminate PTT on process exit.
- This command just sets a mode. Nothing happens until you
use (init) the PTT facility.
- The PTT default *IS NOT* noautoterm.
* See comments in 'autoterm' above.
init: Initializes the Per-Thread Time (PTT) facility.
- On completion the PTT facility is ready to use.
* If you intend to issue other commands, such as dump,
then you *MUST* first enter: 'ptt noautoterm' or things
won't work as you expect them.
- If the PTT facility is currently initialized it will be
reset and re-initialized.
- The 'init' command accepts optional 'metrics' which
determine the units for measuring time on thread. If not
specified, the default metric is NONHALTED_CYCLES.
- Valid values for 'metric' on this machine are:
Note: The list displayed is unique to the machine. You may see a different list.
* NONHALTED_CYCLES
* INSTR
* UOPS
* ALL_UOPS
* BRANCH
* MISPRED_BRANCH
* CALLS
* ITLB_MISS
* TC_FLUSH
* TC_DELIVER_LP0
* TC_DELIVER_LP1
* TC_MISS
* L2_READ_MISS
* L2_READ_REFS
* L3_READ_MISS
* L3_READ_REFS
* MACHINE_CLEAR
* MACHINE_CLEAR_MO
* MACHINE_CLEAR_SM
* BRANCH_TAKEN
* PROC_BUS_ACCESS
* PROC_NONPREFETCH_BUS_ACCESS
* PROC_READS
* PROC_WRITES
* PROC_READS_NONPREFETCH
* PROC_BUS_ACCESS_UW
* PROC_BUS_READS_UW
* PROC_BUS_WRITES_UW
* PROC_READS_NONPREFETCH_UW
* CTR0 thru CTR17 (if HyperThreading disabled)
- Specifying an event as the metric(s) causes the performance
counter(s) to be set up automatically - you *DO NOT* have to
do it.
- Specifying a counter as the metric assumes you *HAVE* set up
the correct counter using JPcnt or MPCNT.
* Keep in mind that when HyperThreading is enabled you must
set up different counters on each logical processor in order
to separate the counts by processor.
* When HyperThreading is enabled it is much better, safer and
easier to use events.
- The 'init' command also accepts an optional privilege level
which determines at which privilege level counting will take
place for metrics *OTHER* than CYCLES.
- Valid privilege levels are:
* priv_kernel
- metrics will only count when executing code in kernel mode
(also known as ring 0).
* priv_user
- metrics will only count when executing code in user mode
(also known as ring 3).
* priv_any
- metrics always count (whether executing code in kernel mode
(ring 0) or in user mode (ring 3).
- This is the default if no privilege level is specified.
- If you need/want to count CYCLES at a particular privilege
level only then you must use the NONHALTED_CYCLES metric.
- If you specify more than one privilege level then the
last one specified (right-most) is used.
term: Terminates the Per-Thread Time (PTT) facility.
- On completion the PTT facility is no longer usable.
reset: Same as 'term'.
info: Displays state of the Per-Thread Time (PTT) facility.
- If the -cpi option is specified then CPI values are displayed
for BusyTime, IdleTime and IntrTime in the CPU and System
summaries, provided the Cycles NONHLATED_CYCLES) and
Instructions Retired (INSTR) metrics are used.
dump: Displays per-thread information about all threads or about
all threads in a given process or list of processes.
This is a snapshot of the PTT data at the instance of
time the dump is taken.
The 'dump' command accepts several modifier options.
********** PID/TID NUMBERS **********
-x Causes ptt to display PID/TID numbers in hex.
* You can use this option if you're attempting to match
PID/TID numbers to other output (log-jtnm for example)
which displays them in hex.
* If you DO NOT specify the -x option, PID/TID numbers
are displayed in decimal (same as Task Manager).
********** PROCESS SELECTION **********
-pl Allows you to specify one or more processes whose threads
will be dumped (displayed).
* Information for all threads in the specified process(es)
will be displayed.
* If requesting more than one process to be monitored,
specify them in a comma-separated list, no blank
space between names/PIDs.
* You can specify processes by PID, either in decimal
(no prefix) or hexadecimal form (0x prefix).
ex in decimal: -pl 345,1026,2830
ex in hexadecimal: -pl 0x159,0x402,0xb0e
* You can specify processes by name (without the .exe).
ex. -pl explorer,vsmon
* You can mix PIDs and names in the list.
ex. -pl explorer,1026,vsmon,0x2380
* Keep in mind that process names may not be unique -
there may be more than one instance of a process
running. In that case, information about all threads in
all instances of the process is displayed.
* If you only want information for one of the instances
then specify the PID for the one you want.
* Only names/PIDs for running processes are allowed.
* The maximum number of processes for which information
can be displayed is currently set at 32.
* If you *DO NOT* specify the -pl option, information for
all threads, in all currently running processes will be
displayed.
********** JAVA THREAD NAME DECORATION **********
-jtnm
-jtnm=path\prefix
Specifies the location of the log-jtnm file(s) used to
decorate java threads (if any of the processes specified
by the -pl option is a java process).
* jtnm files must have the PID appended to their names. In
other words, don't use the -pidx JProf option.
* It is assumed that you are running at least one java
process, instrumenting it with JProf (-Xrunjprof or
-agentlib:jprof) and that, at the very least, the
"threadinfo" option is specified (-Xrunjprof:threadinfo
or -agentlib:jprof=threadinfo).
* Using either form of the -jtnm option causes PTT to
attempt to resolve java thread names.
* -jtnm does not require the use of the -pl option.
* For java threads that are reused, the thread name
will be a string of all names the thread has had,
separated by " |++| ".
-jtnm
* Locate the log-jtnm files in the current directory and
with names beginning with the default of "log".
* If your files are in a directory other than the
current directory and/or have a name prefix other than
"log" then you must use the -jtnm= form of the option.
-jtnm=path\prefix
* Locate the log-jtnm files in directory "path" and with
names beginning with "prefix".
* Use the same string used with the "LOGPATH" and/or
"LOGPREFIX" JProf options.
* Only use this form of the -jtnm option if the log-jtnm
files are located somewhere other than the current
directory and/or are named with a prefix other than "log".
* Examples:
1) -jtnm=C:\results\run1
Your log-jtnm files are located in C:\results and
are named "run1-jtnm_####".
2) -jtnm=test
Your log-jtnm files are located in the current
directory and are named "test-jtnm_####".
3) -jtnm=.\test
Same as number 2.
-allnames Causes all java thread names associated with a native
thread to be displayed for the native thread name. Names
are separated by " |**| ", with the first name used
being the left-most name, and the last name used being
the right-most name.
* If the JVM's threading model is 1:1 (one java thread
to one native thread) then the data displayed by ptt
for the native thread will be that of the last java
thread name used.
* If the JVM's threading model is M:1 (many java threads
to 1 native thread - native thread pool) then the data
displayed by ptt for the native thread will be sum of
all the java thread instances, and ptt can't split
the results by java thread, so the name should be all
the java thread names used.
* This option requires the -jtnm option. Otherwise it has
no effect and is ignored.
********** DISPLAY INTERVAL **********
-t #sec Specifies a sampling interval (in seconds).
ptt will display information for monitored processes at
each interval.
* If you set the interval too short you will spend a lot
of CPU time displaying information, which may not be
what you want to do.
* If you DO NOT specify the -t option, information is
displayed once.
********** SAVE TO FILE **********
-f fn Specifies a filename to write results to.
ptt will write all output to the requested file and to
STDOUT.
* If you DO NOT specify the -f option, all output is
written to STDOUT.
********** DUMP START/STOP OPTIONS **********
-s #sec Causes ptt to automatically start displaying information
for the selected threads in approximately #sec seconds.
* If you *DO NOT* specify the -s option, or specify the
value 0 (zero), displaying starts immediately.
-r #sec Run (display) for approximately #sec seconds then stop.
* If you DO NOT specify the -r option, ptt will continue
displaying information (if -t is specified) until
stopped via Ctrl-C/Ctrl-Break.
********** DISPLAY SORT OPTIONS **********
-sp Causes results to be sorted by pid.
-st Causes results to be sorted by tid.
-sd Causes results to be sorted by dispatch count.
-si Causes results to be sorted by interrupt count.
-sm ## Causes results to be sorted by the given metric ##.
-a Sort in ascending order (smallest to largest)
-d Sort in descending order (largest to smallest)
* If you *DO NOT* specify a sort option, results will be
sorted by metric 1 in descending order.
********** DISPLAY ON-THREAD CPI **********
-cpi Display on-thread CPI
- CPI is displayed only if the Cycles (NONHALTED_CYCLES)
and Instructions Retired (INSTR) metrics are used.
Examples:
1) ptt noautoterm
2) ptt init instr nonhalted_cycles
3) ptt dump
4) ptt dump -pl vptray,rtvscan
5) ptt dump -pl vptray,rtvscan -t 5 -s 5 -r 60 -st -a
6) ptt dump -pl java,rdclip -jtnm -t 5
7) ptt dump -pl java,rdclip -jtnm=C:\ibmperf\data\log -t 5
8) ptt term
9) ptt autoterm
Sample output with java thread names:
* Per-Thread Time accounting was started with commands:
ptt noautoterm
ptt init instr
* Java was started with the following options:
-Xrunjprof:threadinfo,logpath=C:\ibmperf\data
- or -
-agentlib:jprof=threadinfo,logpath=C:\ibmperf\data
* Output is the result of the command:
ptt -pl java -jtnm=C:\ibmperf\data\log
* The java process was running when the PTT command was issued.
* Java thread names appear at the end of each line.
* Any unnamed thread is assigned the name "**JVM**".
PID TID Disp Intr INSTR
----- ----- -------- -------- ----------------
3240 3460 684 3075 6310805838 main
3240 3852 137 387 1230148611 Thread-1
3240 3604 156 367 555990975 Thread-0
3240 2016 223 994 429101787 Thread-2
3240 3292 145 163 174329495 GC_Helper_1
3240 4028 151 172 170420156 GC_Helper_3
3240 3296 168 493 168121361 GC_Helper_2
3240 3272 95 97 547494 Reference_Handler
3240 3288 98 99 319616 Finalizer
3240 3268 95 57 192060 Signal_dispatcher
3240 3260 96 97 149799 RtdriverListenerThread
3240 1828 4 6 91547 Secondary_finalizer
3240 3304 3 4 41269 DG_event_write_thread
3240 3300 3 4 20666 **JVM**
3240 3248 11 12 20009 **JVM**
3240 3244 3 4 9778 **JVM**
----------------
9040310461
Notes:
* PTT facility not supported if:
- Running on a P5 (Pentium) processor.
- Tools running in Limited Function Mode.