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