aboutsummaryrefslogtreecommitdiffstats
path: root/lib/observer/doc/src/ttb.xml
blob: 2c8089192591f8269698750a267225bee0909f93 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
<?xml version="1.0" encoding="latin1" ?>
<!DOCTYPE erlref SYSTEM "erlref.dtd">

<erlref>
  <header>
    <copyright>
      <year>2002</year>
      <year>2011</year>
      <holder>Ericsson AB, All Rights Reserved</holder>
    </copyright>
    <legalnotice>
  The contents of this file are subject to the Erlang Public License,
  Version 1.1, (the "License"); you may not use this file except in
  compliance with the License. You should have received a copy of the
  Erlang Public License along with this software. If not, it can be
  retrieved online at http://www.erlang.org/.

  Software distributed under the License is distributed on an "AS IS"
  basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
  the License for the specific language governing rights and limitations
  under the License.

  The Initial Developer of the Original Code is Ericsson AB.
    </legalnotice>

    <title>ttb</title>
    <prepared>Siri hansen</prepared>
    <responsible></responsible>
    <docno>1</docno>
    <approved></approved>
    <checked></checked>
    <date>2002-02-25</date>
    <rev>PA1</rev>
    <file>ttb.sgml</file>
  </header>
  <module>ttb</module>
  <modulesummary>A base for building trace tools for distributed systems.</modulesummary>
  <description>
    <p>The Trace Tool Builder <c>ttb</c> is a base for building trace
      tools for distributed systems.
      </p>
    <p>When using <c>ttb</c>, <c>dbg</c> shall not be used in parallel.</p>
  </description>
  <funcs>
    <func>
      <name>tracer() -> Result</name>
      <fsummary>This is equivalent to tracer(node()).</fsummary>
      <desc>
        <p>This is equivalent to <c>tracer(node())</c>.</p>
      </desc>
    </func>
    <func>
      <name>tracer(Nodes) -> Result</name>
      <fsummary>This is equivalent to tracer(Nodes,[]).</fsummary>
      <desc>
        <p>This is equivalent to <c>tracer(Nodes,[])</c>.</p>
      </desc>
    </func>
    <func>
      <name>tracer(Nodes,Opts) -> Result</name>
      <fsummary>Start a trace port on each given node.</fsummary>
      <type>
        <v>Result = {ok, ActivatedNodes} | {error,Reason}</v>
        <v>Nodes   = atom() | [atom()] | all | existing | new</v>
        <v>Opts = [Opt]</v>
        <v>Opt = {file,Client} | {handler, FormatHandler} | {process_info,PI}</v>
        <v>Client = File | {local, File}</v>
        <v>File = Filename | Wrap</v>
        <v>Filename = string()</v>
        <v>Wrap = {wrap,Filename} | {wrap,Filename,Size,Count}</v>
        <v>FormatHandler = See format/2</v>
        <v>PI = true | false </v>
      </type>
      <desc>
        <p>This function starts a file trace port on all given nodes
          and also points the system tracer for sequential tracing to
          the same port.
          </p>
        <p>The given <c>Filename</c> will be prefixed with the node
          name. Default <c>Filename</c> is "ttb".
          </p>
        <p><c>File={wrap,Filename,Size,Count}</c> can be used if
          the size of the trace logs must be limited. Default values are
          <c>Size=128*1024</c> and <c>Count=8</c>.
          </p>
        <p>When tracing diskless nodes, <c>ttb</c> must be started
          from an external "trace control node" with disk access, and
          <c>Client</c> must be <c>{local, File}</c>. All
          trace information is then sent to the trace control node where
          it is written to file.
          </p>
        <p>The <c>process_info</c> option indicates if process
          information should be collected. If <c>PI = true</c> (which is
          default), each process identifier <c>Pid</c> is replaced by a
          tuple <c>{Pid,ProcessInfo,Node}</c>, where <c>ProcessInfo</c>
          is the process' registered name its globally registered name,
          or its initial function. It is possible to turn off this
          functionality by setting <c>PI = false</c>.
          </p>
      </desc>
    </func>
    <func>
      <name>p(Procs,Flags) -> Return</name>
      <fsummary>Sets the given trace flags on the given processes.</fsummary>
      <type>
        <v>Return = {ok,[{Procs,MatchDesc}]}</v>
        <v>Procs   = Process | [Process] | all | new | existing</v>
        <v>Process = pid() | atom() | {global,atom()}</v>
        <v>Flags   = Flag | [Flag]</v>
      </type>
      <desc>
        <p>This function sets the given trace flags on the given
          processes.
          </p>
        <p>Please turn to the Reference manual for module <c>dbg</c>
          for details about the possible trace flags. The parameter
          <c>MatchDesc</c> is the same as returned from <c>dbg:p/2</c></p>
        <p>Processes can be given as registered names, globally
          registered names or process identifiers. If a registered name
          is given, the flags are set on processes with this name on all
          active nodes.</p>
      </desc>
    </func>
    <func>
      <name>tp, tpl, ctp, ctpl, ctpg</name>
      <fsummary>Set and clear trace patterns.</fsummary>
      <desc>
        <p>These functions should be used in combination with the
          <c>call</c> trace flag for setting and clearing trace
          patterns. When the <c>call</c> trace flag is set on a process,
          function calls will be traced on that process if a trace
          pattern has been set for the called function. Trace patterns
          specifies how to trace a function by using match
          specifications. Match specifications are described in the
          User's Guide for the erlang runtime system <c>erts</c>.
          </p>
        <p>These functions are equivalent to the corresponding
          functions in <c>dbg</c>, but all calls are stored in the
          history. The history buffer makes it easy to create config
          files so that the same trace environment can be setup several
          times, e.g. if you want to compare two test runs. It also
          reduces the amount of typing when using <c>ttb</c> from the
          erlang shell.
          </p>
        <taglist>
          <tag><c>tp</c></tag>
          <item>Set trace pattern on global function calls</item>
          <tag><c>tpl</c></tag>
          <item>Set trace pattern on local and global function calls</item>
          <tag><c>ctp</c></tag>
          <item>Clear trace pattern on local and global function
           calls</item>
          <tag><c>ctpl</c></tag>
          <item>Clear trace pattern on local function calls</item>
          <tag><c>ctpg</c></tag>
          <item>Clear trace pattern on global function calls</item>
        </taglist>
      </desc>
    </func>
    <func>
      <name>list_history() -> History</name>
      <fsummary>Returns all calls stored in history</fsummary>
      <type>
        <v>History = [{N,Func,Args}]</v>
      </type>
      <desc>
        <p>All calls to <c>ttb</c> is stored in the history. This
          function returns the current content of the history. Any entry
          can be re-executed with <c>run_history/1</c> or stored in a
          config file with <c>write_config/2/3</c>.</p>
      </desc>
    </func>
    <func>
      <name>run_history(N) -> ok | {error, Reason}</name>
      <fsummary>Executes one entry of the history</fsummary>
      <type>
        <v>N = integer() | [integer()]</v>
      </type>
      <desc>
        <p>Executes the given entry or entries from the history
          list. History can be listed with <c>list_history/0</c>.</p>
      </desc>
    </func>
    <func>
      <name>write_config(ConfigFile,Config)</name>
      <fsummary>Equivalent to write_config(ConfigFile,Config,[]).</fsummary>
      <desc>
        <p>Equivalent to <c>write_config(ConfigFile,Config,[])</c>.</p>
      </desc>
    </func>
    <func>
      <name>write_config(ConfigFile,Config,Opt) -> ok | {error,Reason}</name>
      <fsummary>Creates a config file.</fsummary>
      <type>
        <v>ConfigFile = string()</v>
        <v>Config = all | [integer()] | [{Mod,Func,Args}]</v>
        <v>Mod = atom()</v>
        <v>Func = atom()</v>
        <v>Args = [term()]</v>
        <v>Opt = [] | [append]</v>
      </type>
      <desc>
        <p>This function creates or extends a config file which can be
          used for restoring a specific configuration later.
          </p>
        <p>The content of the config file can either be fetched from
          the history or given directly as a list of
          <c>{Mod,Func,Args}</c>.
          </p>
        <p>If the complete history is to be stored in the config file
          <c>Config</c> should be <c>all</c>. If only a selected number
          of entries from the history should be stored, <c>Config</c>
          should be a list of integers pointing out the entries to be
          stored.
          </p>
        <p>If <c>Opt</c> is not given or if it is <c>[]</c>,
          <c>ConfigFile</c> is deleted and a new file is created. If
          <c>Opt = [append]</c>, <c>ConfigFile</c> will not be deleted.
          The new information will be appended at the end of the file.</p>
      </desc>
    </func>
    <func>
      <name>run_config(ConfigFile) -> ok | {error,Reason}</name>
      <fsummary>Executes all entries in a config file.</fsummary>
      <type>
        <v>ConfigFile = string()</v>
      </type>
      <desc>
        <p>Executes all entries in the given config file.</p>
      </desc>
    </func>
    <func>
      <name>run_config(ConfigFile,NumList) -> ok | {error,Reason}</name>
      <fsummary>Executes selected entries from a config file.</fsummary>
      <type>
        <v>ConfigFile = string()</v>
        <v>NumList = [integer()]</v>
      </type>
      <desc>
        <p>Executes selected entries from the given config
          file. <c>NumList</c> is a list of integers pointing out the
          entries to be executed.
          </p>
        <p>The content of a config file can be listed with
          <c>list_config/1</c>.</p>
      </desc>
    </func>
    <func>
      <name>list_config(ConfigFile) -> Config | {error,Reason}</name>
      <fsummary>Lists all entries in a config file.</fsummary>
      <type>
        <v>ConfigFile = string()</v>
        <v>Config = [{N,Func,Args}]</v>
      </type>
      <desc>
        <p>Lists all entries in the given config file.</p>
      </desc>
    </func>
    <func>
      <name>write_trace_info(Key,Info) -> ok</name>
      <fsummary>Writes any information to the <c>.ti</c>file.</fsummary>
      <type>
        <v>Key = term()</v>
        <v>Info = Data | fun() -> Data</v>
        <v>Data = term()</v>
      </type>
      <desc>
        <p>The <c>.ti</c> file contains <c>{Key,ValueList}</c>
          tuples. This function adds <c>Data</c> to the ValueList
          associated with <c>Key</c>. All information written with this
          function will be included in the call to the format handler.</p>
      </desc>
    </func>
    <func>
      <name>seq_trigger_ms() -> MatchSpec</name>
      <fsummary>Equivalent to seq_trigger_ms(all)</fsummary>
      <desc>
        <p>Equivalent to <c>seq_trigger_ms(all)</c></p>
      </desc>
    </func>
    <func>
      <name>seq_trigger_ms(Flags) -> MatchSpec</name>
      <fsummary>Returns a match_spec() which starts sequential tracing</fsummary>
      <type>
        <v>MatchSpec = match_spec()</v>
        <v>Flags = all | SeqTraceFlag | [SeqTraceFlag]</v>
        <v>SeqTraceFlag = atom()</v>
      </type>
      <desc>
        <p>A match specification can turn on or off sequential
          tracing. This function returns a match specification which
          turns on sequential tracing with the given <c>Flags</c>.
          </p>
        <p>This match specification can be given as the last argument
          to <c>tp</c> or <c>tpl</c>. The activated <c>Item</c> will
          then become a <em>trigger</em> for sequential tracing. This
          means that if the item is called on a process with the
          <c>call</c> trace flag set, the process will be "contaminated"
          with the seq_trace token.
          </p>
        <p>If <c>Flags = all</c>, all possible flags are set.
          </p>
        <p>Please turn to the reference manual for the
          <em><c>seq_trace</c></em> module in the <em><c>kernel</c></em>
          application to see the possible values for
          <c>SeqTraceFlag</c>.  For a description of the match_spec()
          syntax, please turn to the <em>User's guide</em> for the
          runtime system (<em>erts</em>). The chapter <em>Match Specification in Erlang</em> explains the general match
          specification "language".
          </p>
        <note>
          <p>The <em>system tracer</em> for sequential tracing is
            automatically initiated by <c>ttb</c> when a trace port is
            started with <c>ttb:tracer/0/1/2</c>.</p>
        </note>
        <p>Example of how to use the <c>seq_trigger_ms/0/1</c> function:</p>
        <code type="none">
(tiger@durin)5> ttb:tracer().
{ok,[tiger@durin]}
(tiger@durin)6> ttb:p(all,call).
{ok,{[all],[call]}}
(tiger@durin)7> ttb:tp(mod,func,ttb:seq_trigger_ms()).
{ok,[{matched,1},{saved,1}]}
(tiger@durin)8>         </code>
        <p>Whenever <c>mod:func(...)</c> is called after this, the
          seq_trace token will be set on the executing process.</p>
      </desc>
    </func>
    <func>
      <name>stop()</name>
      <fsummary>Equivalent to stop([])</fsummary>
      <desc>
        <p>Equivalent to <c>stop([])</c>.</p>
      </desc>
    </func>
    <func>
      <name>stop(Opts) -> stopped</name>
      <fsummary>Stop tracing and fetch/format logs from all nodes</fsummary>
      <type>
        <v>Opts = [Opt]</v>
        <v>Opt = fetch | format</v>
      </type>
      <desc>
        <p>Stops tracing on all nodes.
          </p>
        <p>The <c>fetch</c> option indicates that trace logs shall be
          collected from all nodes after tracing is stopped. This option
          is useful if nodes on remote machines are traced. Logs and
          trace information files are then sent to the trace control
          node and stored in a directory named
          <c>ttb_upload-Timestamp</c>, where <c>Timestamp</c> is on the
          form <c>yyyymmdd-hhmmss</c>. Even logs from nodes on the same
          machine as the trace control node are moved to this directory.
          </p>
        <p>The <c>format</c> option indicates that the trace logs
          shall be formatted after tracing is stopped. Note that this
          option also implies the <c>fetch</c> option, i.e. logs are
          collected in a new directory on the trace control node before
          formatting. All logs in the directory will be merged.</p>
      </desc>
    </func>
    <func>
      <name>format(File)</name>
      <fsummary>Same as <c>format(File,[])</c>.</fsummary>
      <desc>
        <p>Same as <c>format(File,[])</c>.</p>
      </desc>
    </func>
    <func>
      <name>format(File,Options) -> ok | {error, Reason}</name>
      <fsummary>Format a binary trace log</fsummary>
      <type>
        <v>File = string() | [string()]</v>
        <d>This can be the name of a binary log, a list of such logs or the name of a directory containing one or more binary logs.</d>
        <v>Options = [Opt]</v>
        <v>Opt = {out,Out} | {handler,FormatHandler}</v>
        <v>Out = standard_io | string()</v>
        <v>FormatHandler = {Function, InitialState} | et</v>
        <v>Function = fun(Fd,Trace,TraceInfo,State) -> State</v>
        <v>Fd = standard_io | FileDescriptor</v>
        <d>This is the file descriptor of the destination file <c>Out</c></d>
        <v>Trace = tuple()</v>
        <d>This is the trace message. Please turn to the Reference manual for the <c>erlang</c>module for details.</d>
        <v>TraceInfo = [{Key,ValueList}]</v>
        <d>This includes the keys <c>flags</c>, <c>client</c>and <c>node</c>,  and if <c>handler</c>is given as option to the tracer function,  this is also included. In addition all information written with the <c>write_trace_info/2</c>function is included. </d>
      </type>
      <desc>
        <p>Reads the given binary trace log(s). If a directory or a
          list of logs is given and the <c>timestamp</c> flag was set
          during tracing, the trace messages from the different logs are
          merged according to the timestamps.
          </p>
        <p>If <c>FormatHandler = {Function,InitialState}</c>,
          <c>Function</c> will be called for each trace message. If
          <c>FormatHandler = et</c>, <c>et_viewer</c> in the <em>Event Tracer</em> application (<c>et</c>) is used for presenting the
          trace log graphically. <c>ttb</c> provides a few different
          filters which can be selected from the Filter menu in the
          <c>et_viewer</c>. If <c>FormatHandler</c> is not given, a
          default handler is used which presents each trace message as a
          line of text.
          </p>
        <p>If <c>Out</c> is given, <c>FormatHandler</c> gets the
          filedescriptor to <c>Out</c> as the first parameter.
          </p>
        <p><c>Out</c> is ignored if <c>FormatHandler = et</c>.
          </p>
        <p>Wrap logs can be formatted one by one or all in one go. To
          format one of the wrap logs in a set, give the exact name of
          the file. To format the whole set of wrap logs, give the name
          with '*' instead of the wrap count. See examples in the
          <c>ttb</c> User's Guide.</p>
      </desc>
    </func>
  </funcs>
</erlref>