System Administration Commands pgstat(1M)
NAME
pgstat - report utilization statistics for Processor Groups
SYNOPSIS
pgstat [-A] [-C] [-p] [-s key | -S key] [-t number] [-T u | d] [-v]
[-r string] [-R string] [-P pg ...] [-c processor_id... ]
[interval [count]]pgstat -h
DESCRIPTION
The pgstat displays utilization statistics about Processor
Groups (PGs). A PG is a set of CPUs that are grouped together by a common characteristic. PGs are used by the operating system to represent CPUs that share performance relevant hardware, such as execution pipelines, caches, and so forth. These PGs are organized into a hierarchy that models the processor topology of the machine. In this hierarchy, each CPU (strand) has a leaf PG that represents the CPUs that share the most hardware withit. Each successive ancestor of the leaf PG shares progres-
sively less hardware with the CPU until the root PG is reached. The root PG contains all of the CPUs in the system and represents the group of CPUs sharing the least hardware with each other. (See "Examples" below for an example of PG hierarchy).If a machine does not have any performance-relevant hardware
sharing relationships, then pgstat displays only a root PG
that contains all of the CPUs in the system.By default, pgstat does the following:
o Measures the hardware and software utilization of all PGs in the PG hierarchy over a one second interval. o Displays the utilization of the PGs in depth first order using indentation to help show how the PGs relate to each other. o Displays the ID, sharing relationship, hardware load, software load, and online CPUs for each PG at the end of each interval.SunOS 5.11 Last change: 17 Aug 2010 1
System Administration Commands pgstat(1M)
The interval and count can be given as arguments to specify the number of seconds in the sampling interval and number oftimes to measure and display the utilization for the speci-
fied PGs.You can specify options to further tailor the output, organ-
ize the output a certain way, and specify PGs of interest (see "Options" below for details).A hyphen ("-") is displayed when the utilization for a given
PG is not supported and a question mark (?) is displayed when the utilization is not available. On systems where the CPU hardware performance counters are needed to measure thehardware utilization, the hardware utilization might be una-
vailable because the counters are being used by a cpc(3CPC) consumer such as cpustat(1M), cputrack(1), dtrace(1M), or another application that uses libcpc(3LIB). OPTIONS The following options are supported:-A
Display summary of utilization data when pgstat is run
over multiple intervals.-c processor_id...
Display utilization about PGs that contain the specified CPUs. The CPUs can be specified as a comma separatedlist of CPU IDs. A hyphen ("-") can be used to specify
contiguous ranges of CPU IDs (for example, 0-3).
-C
Display utilization of each CPU in each PG.-h
Display short help message and exit with exit status 0.-p
Display the physical relationship that corresponds to a PG. If a PG has the same CPUs as the whole system, a processor core, or a chip, system, core, or chip, asSunOS 5.11 Last change: 17 Aug 2010 2
System Administration Commands pgstat(1M)
appropriate, is displayed after the sharing relationship of the PG in square brackets ("[]").-P pg,...
Display utilization for specified PGs. Multiple PGs canbe specified as a comma-separated list of PG IDs. A
hyphen ("-") can be used to specify a contiguous range
of PG IDs (for example, 0-3).
-r string1,string2,...
Display utilization only for PGs with a sharing rela-
tionship name that matches any of the specified strings. The string can be a whole relationship name or a portion of one or more relationship names. The string matchingis case-insensitive.
Multiple -r options can be entered, which results in
matching all PGs with a relationship name that matches any of the specified strings.-R string1,string2,...
Display information only about PGs with a sharing rela-
tionship name other than the one(s) specified. String matching is the same as described above for the-r option. Multiple -R options can be entered.
-s key
Sort output lines by the specified key in descending order. The specified key can be one of the following: pg Sort by PG ID. hwload Sort by hardware utilization. swload Sort by software utilization.SunOS 5.11 Last change: 17 Aug 2010 3
System Administration Commands pgstat(1M)
user Sort by user time. sys Sort by system time. idle Sort by idle time. depth Sort by descending PG tree from root to leaves,depth-first (default).
breadth Sort by descending PG tree from root to leaves,breadth-first.
-S key
Sort output lines by the specified key in ascendingorder. Possible key values are the same as for the -s
option.-t number
Show the top number of PGs for the specified integer number.-T u | d
Display timestamp for each sampling interval in Unix time (see time(2)) or the standard date format used by date(1).-v
Display extra information about each PG including hardware utilization and capacity and software user,SunOS 5.11 Last change: 17 Aug 2010 4
System Administration Commands pgstat(1M)
system, and idle times.OUTPUT HEADINGS
pgstat displays the column headings, which are listed below,
along with the meanings of those headings. PG Processor Group ID. RELATIONSHIP Sharing relationship for PG. HWHardware load in percent (calculated as UTIL/CAP for interval). UTIL Hardware utilization of PG's shared hardware component over the interval. This can be a large number, so K, M,
B, and T are used for denoting thousand, million, bil-
lion, and trillion, respectively. CAP Approximate maximum possible utilization for PG's shared hardware component over the interval. This can be a large number, so K, M, B, and T are used for denoting thousand, million, billion, and trillion, respectively. SW Software load in percent (calculated as (USR + SYS) / (USR + SYS + IDLE)) USR Percentage of time that software threads ran in user mode on CPUs in PG during interval.SunOS 5.11 Last change: 17 Aug 2010 5
System Administration Commands pgstat(1M)
SYS Percentage of time that software threads ran in system mode on CPUs in PG during interval. IDLE Percentage of time that no software threads ran on CPUs in PG during interval. CPUS CPU IDs for CPUs in PG.EXAMPLES
In the following examples, the system contains one UltraSPARC T1 processor chip with 8 cores and 32 strands. Example 1 Displaying Utilization for Specified Period The following command displays utilization for all PGs over the last two seconds.$ pgstat 1 2
PG RELATIONSHIP HW SW CPUS0 System - 0.4% 0-31
3 Data_Pipe_to_memory - 0.4% 0-31
2 Floating_Point_Unit 0% 0.4% 0-31
1 Integer_Pipeline 0% 0% 0-3
4 Integer_Pipeline 0% 0% 4-7
5 Integer_Pipeline 0% 0% 8-11
6 Integer_Pipeline 0% 0.2% 12-15
7 Integer_Pipeline 0% 0% 16-19
8 Integer_Pipeline 2.8% 2.7% 20-23
9 Integer_Pipeline 0.1% 0.2% 24-27
10 Integer_Pipeline 0% 0% 28-31
PG RELATIONSHIP HW SW CPUS0 System - 0.4% 0-31
3 Data_Pipe_to_memory - 0.4% 0-31
2 Floating_Point_Unit 0% 0.4% 0-31
1 Integer_Pipeline 0% 0.2% 0-3
4 Integer_Pipeline 0% 0% 4-7
5 Integer_Pipeline 0% 0% 8-11
6 Integer_Pipeline 0% 0% 12-15
7 Integer_Pipeline 0% 0% 16-19
8 Integer_Pipeline 3.1% 2.5% 20-23
9 Integer_Pipeline 0% 0% 24-27
SunOS 5.11 Last change: 17 Aug 2010 6
System Administration Commands pgstat(1M)
10 Integer_Pipeline 0% 0.2% 28-31
Example 2 Displaying Information about Integer Pipeline The following command displays detailed information about the two most utilized integer pipelines over the last two seconds.$ pgstat -v -t 2 -r 'Integer_Pipeline' 1 2
PG RELATIONSHIP HW UTIL CAP SW USR SYS IDLE CPUS1 Integer_Pipeline 0.2% 2.2M 1.4B 0.2% 0.0% 0.2% 99.8% 0-3
4 Integer_Pipeline 13.1% 181M 1.4B 14.9% 0.0% 14.9% 85.1% 4-7
PG RELATIONSHIP HW UTIL CAP SW USR SYS IDLE CPUS1 Integer_Pipeline 0.2% 1.9M 1.2B 0.2% 0.0% 0.2% 99.8% 0-3
4 Integer_Pipeline 13.1% 163M 1.2B 14.9% 0.0% 14.9% 85.1% 4-7
Example 3 Displaying Core Utilization over Specified PeriodThe following command displays information about core utili-
zation over the last two minutes.$ pgstat -A 60 2
PG RELATIONSHIP HW SW CPUS0 System - 56.9% 0-31
3 Data_Pipe_to_memory - 56.9% 0-31
2 Floating_Point_Unit 0.0% 56.9% 0-31
1 Integer_Pipeline 36.7% 58.7% 0-3
4 Integer_Pipeline 41.9% 58.3% 4-7
5 Integer_Pipeline 31.0% 58.0% 8-11
6 Integer_Pipeline 30.7% 57.9% 12-15
7 Integer_Pipeline 30.1% 55.8% 16-19
8 Integer_Pipeline 40.2% 54.8% 20-23
9 Integer_Pipeline 35.0% 56.0% 24-27
10 Integer_Pipeline 40.3% 55.8% 28-31
PG RELATIONSHIP HW SW CPUS0 System - 10.7% 0-31
3 Data_Pipe_to_memory - 10.7% 0-31
2 Floating_Point_Unit 0.0% 10.7% 0-31
1 Integer_Pipeline 9.0% 10.7% 0-3
4 Integer_Pipeline 9.6% 10.8% 4-7
5 Integer_Pipeline 8.6% 9.9% 8-11
6 Integer_Pipeline 10.5% 11.9% 12-15
7 Integer_Pipeline 9.1% 10.4% 16-19
8 Integer_Pipeline 9.6% 10.9% 20-23
SunOS 5.11 Last change: 17 Aug 2010 7
System Administration Commands pgstat(1M)
9 Integer_Pipeline 8.9% 10.0% 24-27
10 Integer_Pipeline 9.5% 10.7% 28-31
SUMMARY: UTILIZATION OVER 120 SECONDS------HARDWARE------ ------SOFTWARE------
PG RELATIONSHIP MIN AVG MAX MIN AVG MAX CPUS0 System - - - 10.7% 10.7% 56.9% 0-31
3 Data_Pipe_to_memory - - - 10.7% 10.7% 56.9% 0-31
2 Floating_Point_Unit 0.0% 0.0% 0.0% 10.7% 10.7% 56.9% 0-31
1 Integer_Pipeline 9.0% 8.5% 36.7% 10.7% 10.7% 58.7% 0-3
4 Integer_Pipeline 9.6% 9.1% 41.9% 10.8% 10.8% 58.3% 4-7
5 Integer_Pipeline 8.6% 8.1% 31.0% 9.9% 9.9% 58.0% 8-11
6 Integer_Pipeline 10.5% 10.0% 30.7% 11.9% 11.9% 57.9% 12-15
7 Integer_Pipeline 9.1% 8.6% 30.1% 10.4% 10.4% 55.8% 16-19
8 Integer_Pipeline 9.6% 9.1% 40.2% 10.9% 10.9% 54.8% 20-23
9 Integer_Pipeline 8.9% 8.4% 35.0% 10.0% 10.0% 56.0% 24-27
10 Integer_Pipeline 9.5% 8.9% 40.3% 10.7% 10.7% 55.8% 28-31
EXIT STATUS The following exit values are returned: 0 Successful completion. 1 Unable to get PG information from the system. 2 Specified interval, count, or all CPUs, PGs, and sharing relationships invalid. 3 Invalid syntax.ATTRIBUTES
See attributes(5) for descriptions of the following attri-
butes:SunOS 5.11 Last change: 17 Aug 2010 8
System Administration Commands pgstat(1M)
____________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|_____________________________|_____________________________|
| Availability | SUNWesu ||_____________________________|_____________________________|
| Interface Stability | Uncommitted ||_____________________________|_____________________________|
The command line options and output are Uncommitted.SEE ALSO
cputrack(1), cpustat(1M), dtrace(1M), pginfo(1M), cpc(3CPC), libcpc(3LIB), attributes(5)SunOS 5.11 Last change: 17 Aug 2010 9