1
<?xml version="1.0" encoding="latin1" ?>
2
<!DOCTYPE chapter SYSTEM "chapter.dtd">
9
<holder>Ericsson AB, All Rights Reserved</holder>
12
The contents of this file are subject to the Erlang Public License,
13
Version 1.1, (the "License"); you may not use this file except in
14
compliance with the License. You should have received a copy of the
15
Erlang Public License along with this software. If not, it can be
16
retrieved online at http://www.erlang.org/.
18
Software distributed under the License is distributed on an "AS IS"
19
basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
20
the License for the specific language governing rights and limitations
23
The Initial Developer of the Original Code is Ericsson AB.
32
<marker id="here"></marker>
35
<title>Introduction</title>
36
<p>The process manager Pman is a tool for viewing processes executing
37
locally or on remote nodes. Its main purpose is to locate
38
erroneous code by inspecting the state of the processes and by tracing
39
events. Bottlenecks, unread messages, and bad memory handling are
40
some of the problems that can be solved with Pman.</p>
41
<p>Processes may be inspected individually in a process trace
42
window. There the user may dynamically follow the execution of a
43
process by getting trace output for sent and received messages
44
as well as for called functions and some other process
45
events. Information about source code modules executed by the
46
processes is also accessible. Note that Pman has some effect on
47
the real time behavior of a running system.</p>
51
<title>Getting Started with Pman</title>
52
<p>Start Pman by calling <c>pman:start()</c>. It will start
53
the <seealso marker="#main_win">Main Window</seealso>, showing an
54
overview of all processes running at the current node.</p>
55
<p>To trace a certain process, select it by clicking on its line and
56
then chose Trace->Selected Process, or simply double-click it. This
57
will open a <seealso marker="#trace_win">Trace Window</seealso>.
58
In the Trace Window, there is some information about the process
59
and traced events are added dynamically.</p>
60
<p>Which events to trace are selected in
61
the <seealso marker="#options_win">Options Window</seealso> which
62
is opened by chosing File->Options... in the Main Window or in a
63
Trace Window. Currently supported trace events are message sending,
64
message receiving, function calls and process events.</p>
65
<p>It is possible to by-pass the Main Window and open a Trace
66
Window directly for the process <c>Pid</c> by calling
67
<c>pman:proc(Pid)</c>.</p>
71
<marker id="main_win"></marker>
72
<title>The Main Window</title>
73
<p>The Main Window shows all processes running at the displayed node.
74
The window is automatically updated every 5 seconds.
75
Select which node to display in the window by chosing the node name
76
from the Nodes menu.</p>
77
<image file="main_window">
78
<icaption>The Main Window.</icaption>
80
<p>A process can be selected by clicking on its line. The selected
81
process is highlighted. Use the arrow keys to move up and down in
82
the process overview.</p>
83
<p>The following information is displayed for each process:</p>
84
<list type="bulleted">
85
<item>Pid - process identifier.</item>
86
<item>Current Function - the function (<c>Module:Function/Arity</c>)
87
the process is currently executing.</item>
88
<item>Name - registered name of the process, if any.</item>
89
<item>Msgs - number of messages in the process' mailbox.</item>
90
<item>Reds - number of reductions performed. Gives a rough estimate
91
of the process' work load.</item>
92
<item>Size - estimated size of the process, in words, calculated by
93
adding the stack size and the heap size.</item>
95
<p>At the bottom of the window the following functions and
96
information can be found:</p>
98
<tag><em>Hide System Processes</em></tag>
99
<item>This check button controls the display of what Pman consider
100
<em>system processes</em>, that is, processes Pman knows are part
101
of Erlang/OTP rather than the user's application.
102
If the button is selected, these system processes will not be
104
<tag><em>Auto-Hide New</em></tag>
105
<item>This check button controls the treatment of newly created
106
processes. If it is selected, new processes will not be shown.</item>
107
<tag><em># Hidden</em></tag>
108
<item>This label displays the number of processes currently
109
executing that are not shown in the process overview.</item>
113
<title>The File Menu</title>
115
<tag><em>Options...</em></tag>
116
<item>Open the <seealso marker="#options_win">Options Window</seealso>
117
which allows the user to set the trace options to use.</item>
118
<tag><em>Save Options</em></tag>
119
<item>Save the options set using the Options Window. The options are
120
stored to the file <c>HOME/.erlang_tools/pman.opts</c>, where
121
<c>HOME</c> is the user's home directory, and are automatically
122
loaded the next time Pman is started.</item>
123
<tag><em>Exit</em></tag>
124
<item>Stop Pman.</item>
129
<title>The View Menu</title>
130
<p>This menu mainly contains buttons for controlling what to
131
display in the Main Window. Note that the View Menu overrides
132
the settings of the check buttons (Hide System processes, Auto-Hide
133
new) in the Main Window.</p>
135
<tag><em>Hide All Processes</em></tag>
136
<item>Hide all processes.</item>
137
<tag><em>Hide Modules...</em></tag>
138
<item>Opens a dialog window with all loaded modules. If the user
139
selects a window and clicks OK, the process overview will not
140
show any processes running code from those modules.</item>
141
<tag><em>Hide Selected Processs</em></tag>
142
<item>Hide the selected process.</item>
143
<tag><em>Module Info...</em></tag>
144
<item>Given a selected process currently executing a function in
145
the module <c>Module</c>, this menu button opens a window
146
showing information about the module as returned from
147
<c>Module:module_info()</c>.</item>
148
<tag><em>Refresh</em></tag>
149
<item>Updates the process overview.</item>
150
<tag><em>Show All Processes</em></tag>
151
<item>Show all processes, except system processes and/or new
152
processes if <em>Hide System Processes</em> and/or
153
<em>Auto-Hide New</em> is selected.</item>
154
<tag><em>Show Processes...</em></tag>
155
<item>Opens a dialog window with all hidden processes. If
156
the user selects a process and clicks OK, the process
157
overview will show that process.</item>
162
<title>The Trace Menu</title>
164
<tag><em>Kill</em></tag>
165
<item>Terminates the selected process by calling
166
<c>exit(Pid,kill)</c>.</item>
167
<tag><em>Trace Selected Process</em></tag>
168
<item>Opens a Trace Window for the selected process. Tracing
169
will start immediately with the default trace flags set from
170
the Main Window.</item>
171
<tag><em>Shell Process</em></tag>
172
<item>Opens a Trace Window for the shell process of node Pman
173
was started at (not the displayed node). If the shell process
174
dies, the opened Trace Window will find the pid of
175
the automatically started new shell process, and continue to
176
trace that process.</item>
181
<title>The Nodes Menu</title>
182
<p>The Nodes menu contains one entry for each known node.
183
By selecting a node from the Nodes menu, the process overview
184
window will change its view, and display the processes running
189
<title>The Help Menu</title>
191
<tag><em>Help</em></tag>
192
<item>Selecting Help from the Help menu will cause the HTML
193
version of the Pman User's Guide (this document) to be
194
displayed. Currently this function requires Netscape to be up
201
<marker id="trace_win"></marker>
202
<title>The Trace Window</title>
203
<p>A Trace Window outputs trace information for a traced process.
204
A Trace Window automatically uses the trace options set in
205
the Main Window, but it is also possible to change the options for
206
each Trace Window individually.</p>
208
<icaption>The Trace Window.</icaption>
210
<p>There is no limit to how many Trace Windows can be open at the same
211
time. However, notice that if more processes are traced,
212
the performance degradation of the system will be more noticeable.</p>
213
<p>The following information is displayed, where applicable:</p>
214
<list type="bulleted">
215
<item>initial call - the function (<c>Module:Function/Arity</c>)
216
the process started executing in.</item>
217
<item>current function - the function (<c>Module:Function/Arity</c>)
218
the process is currently executing.</item>
219
<item>messages - the messages in the mailbox.</item>
220
<item>dictionary - the contents of the process dictionary.</item>
221
<item>heap size - heap size in words.</item>
222
<item>stack size - stack size in words.</item>
223
<item>reductions - number of reductions performed. Gives a rough
224
estimate of the process' work load.</item>
225
<item>links - list of pids the process is linked to.</item>
226
<item>trap_exit - <c>true</c> if the process trap exit signals,
227
<c>false</c> otherwise.</item>
229
<p>In the Trace Window, trace output is continuously added. First in
230
each trace message is the pid of the traced process.
231
Note that if the inheritance flags for tracing are set, the trace
232
output for the spawned/linked processes will be shown in the same
233
window as the spawning/linking process.</p>
234
<p>Each trace message also has a mnemonic tag:</p>
236
<tag><em>!</em></tag>
237
<item>This tag indicates that a message has been sent. Following
238
the <c>To:</c> tag will be a pid/name of the receiver. Next,
239
following the <c>Msg:</c> tag will be the sent message.</item>
240
<tag><em>rec</em></tag>
241
<item>This tag indicates that a message has been received.
242
Following this will be the received message.</item>
243
<tag><em>call</em></tag>
244
<item>This tag indicates a call to a function. Following this will be
245
the actual call, with all the arguments.</item>
246
<tag><em>link</em></tag>
247
<item>This tag indicates that a link between the traced process and
248
another process has been created. Following this will be the pid
249
of the other process.</item>
250
<tag><em>spawn</em></tag>
251
<item>This tag indicates that the traced process has spawned another
252
process. Following this will be the pid of the spawned process.</item>
253
<tag><em>exit</em></tag>
254
<item>This tag indicates that traced process has exited. Following
255
this will be the exit reason.</item>
259
<title>The File Menu</title>
261
<tag><em>Options...</em></tag>
262
<item>Opens the <seealso marker="#options_win">Options Window</seealso>
263
which allows the user to set the trace options to use for this
264
specific Trace Window.</item>
265
<tag><em>Save Buffer...</em></tag>
266
<item>Opens a dialog that prompts the user for a file name to
267
save the current Trace Window contents in.</item>
268
<tag><em>Close</em></tag>
269
<item>Stops tracing of the process, and closes the Trace Window.</item>
274
<title>The View Menu</title>
276
<tag><em>Clear Buffer</em></tag>
277
<item>Clears the contents of the Trace Window.</item>
278
<tag><em>Module Info</em></tag>
279
<item>Opens a window showing information about the module
280
the process is currently executing code from, as returned from
281
<c>Module:module_info()</c>.</item>
286
<title>The Trace Menu</title>
288
<tag><em>All Linked Processes</em></tag>
289
<item>Opens a Trace Window for each of the processes linked to the
290
process being traced in the current Trace Window.</item>
291
<tag><em>Linked Process -></em></tag>
292
<item>The Linked Process submenu has one entry for each process
293
linked to the process being traced in the current Trace Window.
294
Select one of the processes to open a new Trace Window for that
296
<tag><em>Kill</em></tag>
297
<item>Terminates the process being traced in the current Trace
298
Window by calling <c>exit(Pid,kill)</c>.</item>
303
<title>The Help Menu</title>
305
<tag><em>Help</em></tag>
306
<item>Selecting Help from the Help menu will cause the HTML version
307
of the Pman User's Guide (this document) to be displayed.
308
Currently this function requires Netscape to be up and running.</item>
314
<marker id="options_win"></marker>
315
<title>The Options Window</title>
316
<p>The Options Window allows the user to specify the amount of output,
317
and the destination of output for traced processes.</p>
318
<image file="options">
319
<icaption>The Options Window.</icaption>
321
<p>In the upper left corner of the Options Window, there are check
322
buttons for determining what to output in the Trace Window:</p>
324
<tag><em>Trace send</em></tag>
325
<item>Select this check button to display information about sent
327
<tag><em>Trace receive</em></tag>
328
<item>Select this check button to display information about received
330
<tag><em>Trace functions</em></tag>
331
<item>Select this check button to display information about
332
function calls.</item>
333
<tag><em>Trace events</em></tag>
334
<item>Select this check button to display information about process
335
events, such as spawn, link and exit.</item>
337
<p>In the upper right corner of the dialog, there are options for
338
controlling the behaviour of spawned or linked processes:</p>
340
<tag><em>Inherit on spawn</em></tag>
342
<p>The user may select if spawned processes shall also be traced.
343
And if so, if all spawned processes should be traced, or just
344
the first spawned process.</p>
345
<p>If a spawned process is traced, it will get the same trace
346
options that are set for the spawning process. And the output
347
will be shown in the same Trace Window as that of the spawning
351
<tag><em>Inherit on link</em></tag>
353
<p>The user may select if a process that is being linked to
354
shall be traced. And if so, if all linked processes shall be
355
traced, or just the first one linked to.</p>
356
<p>If a linked process is traced, it will get the same trace
357
options that are set for the linking process. And the output
358
will be shown in the same Trace Window as that of the linked
362
<p>In the lower part of the Options Dialog, the user may select
363
whether the trace information shall be output to a file, or appear in
364
the trace window.</p>
365
<p>Sending trace information to a file is more efficient than displaying
366
it in the Trace Window. Furthermore, if the amount of trace data is
367
large, it will not be lost if tracing to a file. The trace information
368
in the Trace Window has an upper limit (approx. 10,000 lines), after
369
which the output buffer will be cleared.</p>
added
removed
lib/pman/doc/src/pman_chapter.xml
