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.