1PG_TOP(1) General Commands Manual PG_TOP(1)
2
6 pg_top - display and update information about the top cpu PostgreSQL
7 processes
8
10 pg_top [ -ITWbcinqu ] [ -dDBNAME ] [ -hHOSTNAME ] [ -ofield ] [ -pPORT
11 ] [ -stime ] [ -UUSER ] [ -xcount ] [ -zusername ] [ number ]
12
14 pg_top displays the top processes on the system and periodically
15 updates this information. Raw cpu percentage is used to rank the pro‐
16 cesses. If number is given, then the top number processes will be dis‐
17 played instead of the default.
18 pg_top makes a distinction between terminals that support advanced
20 capabilities and those that do not. This distinction affects the
21 choice of defaults for certain options. In the remainder of this docu‐
22 ment, an "intelligent" terminal is one that supports cursor addressing,
23 clear screen, and clear to end of line. Conversely, a "dumb" terminal
24 is one that does not support such features. If the output of pg_top is
25 redirected to a file, it acts as if it were being run on a dumb termi‐
26 nal.
27
29 -C Turn off the use of color in the display.
30 -I Do not display idle processes. By default, pg_top displays both
32 active and idle processes.
33 -T List all available color tags and the current set of tests used
35 for color highlighting, then exit.
36 -W Forces pg_top to prompt for a password before connecting to a
38 database.
39 -b Use "batch" mode. In this mode, all input from the terminal is
41 ignored. Interrupt characters (such as ^C and ^\) still have an
42 effect. This is the default on a dumb terminal, or when the
43 output is not a terminal.
44 -c Show the command name for each process. Default is to show the
46 full command line. This option is not supported on all plat‐
47 forms.
48 -i Use "interactive" mode. In this mode, any input is immediately
50 read for processing. See the section on "Interactive Mode" for
51 an explanation of which keys perform what functions. After the
52 command is processed, the screen will immediately be updated,
53 even if the command was not understood. This mode is the
54 default when standard output is an intelligent terminal.
55 -n Use "non-interactive" mode. This is indentical to "batch" mode.
57 -q Renice pg_top to -20 so that it will run faster. This can be
59 used when the system is being very sluggish to improve the pos‐
60 sibility of discovering the problem. This option can only be
61 used by root.
62 -u Do not take the time to map uid numbers to usernames. Normally,
64 pg_top will read as much of the file "/etc/passwd" as is neces‐
65 sary to map all the user id numbers it encounters into login
66 names. This option disables all that, while possibly decreasing
67 execution time. The uid numbers are displayed instead of the
68 names.
69 -v Write version number information to stderr then exit immedi‐
71 ately. No other processing takes place when this option is
72 used. To see current revision information while pg_top is run‐
73 ning, use the help command "?".
74 -stime Set the delay between screen updates to time seconds. The
76 default delay between updates is 5 seconds.
77 -ofield
79 Sort the process display area on the specified field. The field
80 name is the name of the column as seen in the output, but in
81 lower case. Likely values are "cpu", "size", "res", and "time",
82 but may vary on different operating systems. Note that not all
83 operating systems support this option.
84 -xcount
86 Show only count displays, then exit. A display is considered to
87 be one update of the screen. This option allows the user to
88 select the number of displays he wants to see before pg_top
89 automatically exits. For intelligent terminals, no upper limit
90 is set. The default is 1 for dumb terminals.
91 -zusername
93 Show only those processes owned by username. This option cur‐
94 rently only accepts usernames and will not understand uid num‐
95 bers.
96 Both count and number fields can be specified as "infinite", indicating
98 that they can stretch as far as possible. This is accomplished by
99 using any proper prefix of the keywords "infinity", "maximum", or
100 "all". The default for count on an intelligent terminal is, in fact,
101 infinity.
102 The environment variable PG_TOP is examined for options before the com‐
104 mand line is scanned. This enables a user to set his or her own
105 defaults. The number of processes to display can also be specified in
106 the environment variable PG_TOP. The options -C, -I, and -u are actu‐
107 ally toggles. A second specification of any of these options will
108 negate the first. Thus a user who has the environment variable PG_TOP
109 set to "-I" may use the command "top -I" to see idle processes.
110
112 When pg_top is running in "interactive mode", it reads commands from
113 the terminal and acts upon them accordingly. In this mode, the termi‐
114 nal is put in "CBREAK", so that a character will be processed as soon
115 as it is typed. Almost always, a key will be pressed when pg_top is
116 between displays; that is, while it is waiting for time seconds to
117 elapse. If this is the case, the command will be processed and the
118 display will be updated immediately thereafter (reflecting any changes
119 that the command may have specified). This happens even if the command
120 was incorrect. If a key is pressed while pg_top is in the middle of
121 updating the display, it will finish the update and then process the
122 command. Some commands require additional information, and the user
123 will be prompted accordingly. While typing this information in, the
124 user's erase and kill keys (as set up by the command stty) are recog‐
125 nized, and a newline terminates the input.
126 These commands are currently recognized (^L refers to control-L):
128 ^L Redraw the screen.
130 A Display the actual query plan (EXPLAIN ANALYZE) of the currently
132 running SQL statement by re-running the SQL statement (prompt
133 for process id.)
134 C Toggle the use of color in the display.
136 c Toggle the display of the full command line.
138 d Change the number of displays to show (prompt for new number).
140 Remember that the next display counts as one, so typing d1 will
141 make pg_top show one final display and then immediately exit.
142 h or ? Display a summary of the commands (help screen). Version infor‐
144 mation is included in this display.
145 E Display re-determined execution plan (EXPLAIN) of the SQL state‐
147 ment by a backend process (prompt for process id.)
148 e Display a list of system errors (if any) generated by the last
150 kill or renice command.
151 i (or I) Toggle the display of idle processes.
153 k Send a signal ("kill" by default) to a list of processes. This
155 acts similarly to the command kill(1)).
156 L Display the currently held locks by a backend process (prompt
158 for process id.)
159 M Order by memory utilization.
161 N Sort by process id.
163 n or # Change the number of processes to display (prompt for new num‐
165 ber).
166 o Change the order in which the display is sorted. This command
168 is not available on all systems. The sort key names when view‐
169 ing processes vary fron system to system but usually include:
170 "cpu", "res", "size", "time". The default is cpu. When viewing
171 user table statistics: "seq_scan", "seq_tup_read", "idx_scan",
172 "idx_tup_fetch", "n_tup_ins", "n_tup_upd", "n_tup_del". The
173 default is seq_scan. When viewing user index statistics:
174 "idx_scan", "idx_tup_fetch", "idx_tup_read". The default is
175 idx_scan.
176 P Sort by processor utilization.
178 Q Display the currently running query of a backend process (prompt
180 for process id.)
181 q Quit pg_top.
183 R Display user table statistics.
185 r Change the priority (the "nice") of a list of processes. This
187 acts similarly to the command renice(8)).
188 s Change the number of seconds to delay between displays (prompt
190 for new number).
191 T Order by time.
193 t Toggle between cumulative or differential statistics when view‐
195 ing user table or user index statistics.
196 u Display only processes owned by a specific username (prompt for
198 username). If the username specified is simply "+", then pro‐
199 cesses belonging to all users will be displayed.
200 X Display user index statistics.
202
204 The actual display varies depending on the specific variant of Unix
205 that the machine is running. This description may not exactly match
206 what is seen by pg_top running on this particular machine. Differences
207 are listed at the end of this manual entry.
208 The top few lines of the display show general information about the
210 state of the system, including the last process id assigned to a
211 process (on most systems), the three load averages, the current time,
212 the number of existing processes, the number of processes in each state
213 (sleeping, running, starting, zombies, and stopped), and a percentage
214 of time spent in each of the processor states (user, nice, system, and
215 idle). It also includes information about physical and virtual memory
216 allocation.
217 The remainder of the screen displays information about individual pro‐
219 cesses. This display is similar in spirit to ps(1) but it is not
220 exactly the same. The columns displayed by pg_top will differ slightly
221 between operating systems. Generally, the following fields are dis‐
222 played:
223 PID The process id.
225 USERNAME
227 Username of the process's owner (if -u is specified, a UID col‐
228 umn will be substituted for USERNAME).
229 PRI Current priority of the process.
231 NICE Nice amount in the range -20 to 20, as established by the use of
233 the command nice.
234 SIZE Total size of the process (text, data, and stack) given in kilo‐
236 bytes.
237 RES Resident memory: current amount of process memory that resides
239 in physical memory, given in kilobytes.
240 STATE Current state (typically one of "sleep", "run", "idl", "zomb",
242 or "stop").
243 TIME Number of system and user cpu seconds that the process has used.
245 CPU Percentage of available cpu time used by this process.
247 COMMAND
249 Name of the command that the process is currently running.
250
252 pg_top supports the use of ANSI color in its output. By default, color
253 is available but not used. The environment variable TOPCOLORS speci‐
254 fies colors to use and conditions for which they should be used. At
255 the present time, only numbers in the summay display area can be col‐
256 ored. In a future version it will be possible to highlight numbers in
257 the process display area as well. The environment variable is the only
258 way to specify color: there is no equivalent command line option. Note
259 that the environment variable TOPCOLOURS is also understood. The
260 British spelling takes precedence. The use of color only works on ter‐
261 minals that understand and process ANSI color escape sequences.
262 The environment variable is a sequence of color specifications, sepa‐
264 rated by colons. Each specification takes the form tag=min,max#code
265 where tag is the name of the value to check, min and max specify a
266 range for the value, and code is an ANSI color code. Multiple color
267 codes can be listed and separated with semi-colons. A missing min
268 implies the lowest possible value (usually 0) and a missing max implies
269 infinity. The comma must always be present. When specifying numbers for
270 load averages, they should be multiplied by 100. For example, the
271 specification 1min=500,1000#31 indicates that a 1 minute load average
272 between 5 and 10 should be displayed in red. Color attributes can be
273 combined. For example, the specification 5min=1000,#37;41 indicates
274 that a 5 minute load average higher than 10 should be displayed with
275 white characters on a red background. A special tag named header is
276 used to control the color of the header for process display. It should
277 be specified with no lower and upper limits, specifically header=,#
278 followed by the ANSI color code.
279 You can see a list of color codes recognized by this installation of
281 pg_top with the -T option. This will also show the current set of
282 tests used for color highligting, as specified in the environment.
283
285 William LeFebvre Mark Wong
286
288 PG_TOP user-configurable defaults for options. PG_TOPCOL‐
289 ORS color specification
290
292 As with ps(1), things can change while pg_top is collecting information
293 for an update. The picture it gives is only a close approximation to
294 reality.
295
297 kill(1), ps(1), stty(1), mem(4), renice(8)
298
300 The Linux port was written by Richard Henderson <rth@tamu.edu>. The
301 CPU% calculation was brazenly stolen from the Solaris 2 port and should
302 be attributed to one of the many names listed in its man page.
303 The order support was stolen from SUNOS 5 port by Alexey Klimkin
305 <kad@klon.tme.mcst.ru>
306 Made to work under 2.4 by William LeFebvre.
3084th Berkeley Distribution Local PG_TOP(1)