1dyntrace(3) Erlang Module Definition dyntrace(3)
2
6 dyntrace - Interface to dynamic tracing
7
9 This module implements interfaces to dynamic tracing, should such be
10 compiled into the virtual machine. For a standard and/or commercial
11 build, no dynamic tracing is available, in which case none of the func‐
12 tions in this module is usable or give any effect.
13 Should dynamic tracing be enabled in the current build, either by con‐
15 figuring with ./configure --with-dynamic-trace=dtrace or with ./config‐
16 ure --with-dynamic-trace=systemtap, the module can be used for two
17 things:
18 * Trigger the user-probe user_trace_i4s4 in the NIF library dyn‐
20 trace.so by calling dyntrace:p/{1,2,3,4,5,6,7,8}.
21 * Set a user specified tag that will be present in the trace messages
23 of both the efile_drv and the user-probe mentioned above.
24 Both building with dynamic trace probes and using them is experimental
26 and unsupported by Erlang/OTP. It is included as an option for the de‐
27 veloper to trace and debug performance issues in their systems.
28 The original implementation is mostly done by Scott Lystiger Fritchie
30 as an Open Source Contribution and it should be viewed as such even
31 though the source for dynamic tracing as well as this module is in‐
32 cluded in the main distribution. However, the ability to use dynamic
33 tracing of the virtual machine is a very valuable contribution which
34 OTP has every intention to maintain as a tool for the developer.
35 How to write d programs or systemtap scripts can be learned from books
37 and from a lot of pages on the Internet. This manual page does not in‐
38 clude any documentation about using the dynamic trace tools of respec‐
39 tive platform. The examples directory of the runtime_tools application
40 however contains comprehensive examples of both d and systemtap pro‐
41 grams that will help you get started. Another source of information is
42 the dtrace and systemtap chapters in the Runtime Tools Users' Guide.
43
45 available() -> boolean()
46 This function uses the NIF library to determine if dynamic trac‐
48 ing is available. Usually calling erlang:system_info/1 is a bet‐
49 ter indicator of the availability of dynamic tracing.
50 The function will throw an exception if the dyntrace NIF library
52 could not be loaded by the on_load function of this module.
53 p() -> true | false | error | badarg
55 Calling this function will trigger the "user" trace probe
57 user_trace_i4s4 in the dyntrace NIF module, sending a trace mes‐
58 sage only containing the user tag and zeroes/empty strings in
59 all other fields.
60 p(integer() | string()) -> true | false | error | badarg
62 Calling this function will trigger the "user" trace probe
64 user_trace_i4s4 in the dyntrace NIF module, sending a trace mes‐
65 sage containing the user tag and the integer or string parameter
66 in the first integer/string field.
67 p(integer() | string(), integer() | string()) -> true | false | error |
69 badarg
70 Calling this function will trigger the "user" trace probe
72 user_trace_i4s4 in the dyntrace NIF module, sending a trace mes‐
73 sage containing the user tag and the integer() or string() pa‐
74 rameters as the first fields of respective type. integer() pa‐
75 rameters should be put before any string() parameters. I.e.
76 p(1,"Hello") is ok, as is p(1,1) and p("Hello","Again"), but not
77 p("Hello",1).
78 p(integer() | string(), integer() | string(), integer() | string()) ->
80 true | false | error | badarg
81 Calling this function will trigger the "user" trace probe
83 user_trace_i4s4 in the dyntrace NIF module, sending a trace mes‐
84 sage containing the user tag and the integer() or string() pa‐
85 rameters as the first fields of respective type. integer() pa‐
86 rameters should be put before any string() parameters, as in
87 p/2.
88 p(integer() | string(), integer() | string(), integer() | string(), in‐
90 teger() | string()) -> true | false | error | badarg
91 Calling this function will trigger the "user" trace probe
93 user_trace_i4s4 in the dyntrace NIF module, sending a trace mes‐
94 sage containing the user tag and the integer() or string() pa‐
95 rameters as the first fields of respective type. integer() pa‐
96 rameters should be put before any string() parameters, as in
97 p/2.
98 p(integer(), integer() | string(), integer() | string(), integer() |
100 string(), string()) -> true | false | error | badarg
101 Calling this function will trigger the "user" trace probe
103 user_trace_i4s4 in the dyntrace NIF module, sending a trace mes‐
104 sage containing the user tag and the integer() or string() pa‐
105 rameters as the first fields of respective type. integer() pa‐
106 rameters should be put before any string() parameters, as in
107 p/2.
108 There can be no more than four parameters of any type (integer()
110 or string()), so the first parameter has to be an integer() and
111 the last a string().
112 p(integer(), integer(), integer() | string(), integer() | string(),
114 string(), string()) -> true | false | error | badarg
115 Calling this function will trigger the "user" trace probe
117 user_trace_i4s4 in the dyntrace NIF module, sending a trace mes‐
118 sage containing the user tag and the integer() or string() pa‐
119 rameters as the first fields of respective type. integer() pa‐
120 rameters should be put before any string() parameters, as in
121 p/2.
122 There can be no more than four parameters of any type (integer()
124 or string()), so the first two parameters has to be integer()'s
125 and the last two string()'s.
126 p(integer(), integer(), integer(), integer() | string(), string(),
128 string(), string()) -> true | false | error | badarg
129 Calling this function will trigger the "user" trace probe
131 user_trace_i4s4 in the dyntrace NIF module, sending a trace mes‐
132 sage containing the user tag and the integer() or string() pa‐
133 rameters as the first fields of respective type. integer() pa‐
134 rameters should be put before any string() parameters, as in
135 p/2.
136 There can be no more than four parameters of any type (integer()
138 or string()), so the first three parameters has to be inte‐
139 ger()'s and the last three string()'s.
140 p(integer(), integer(), integer(), integer(), string(), string(),
142 string(), string()) -> true | false | error | badarg
143 Calling this function will trigger the "user" trace probe
145 user_trace_i4s4 in the dyntrace NIF module, sending a trace mes‐
146 sage containing all the integer()'s and string()'s provided, as
147 well as any user tag set in the current process.
148 get_tag() -> binary() | undefined
150 This function returns the user tag set in the current process.
152 If no tag is set or dynamic tracing is not available, it returns
153 undefined
154 get_tag() -> binary() | undefined
156 This function returns the user tag set in the current process
158 or, if no user tag is present, the last user tag sent to the
159 process together with a message (in the same way as sequential
160 trace tokens are spread to other processes together with mes‐
161 sages. For an explanation of how user tags can be spread to‐
162 gether with messages, see spread_tag/1. If no tag is found or
163 dynamic tracing is not available, it returns undefined
164 put_tag(Item) -> binary() | undefined
166 Types:
168 Item = iodata()
170 This function sets the user tag of the current process. The user
172 tag is a binary(), but can be specified as any iodata(), which
173 is automatically converted to a binary by this function.
174 The user tag is provided to the user probes triggered by calls
176 top dyntrace:p/{1,2,3,4,5,6,7,8} as well as probes in the
177 efile_driver. In the future, user tags might be added to more
178 probes.
179 The old user tag (if any) is returned, or undefined if no user
181 tag was present or dynamic tracing is not enabled.
182 spread_tag(boolean()) -> TagData
184 Types:
186 TagData = opaque data that can be used as parameter to re‐
188 store_tag/1
189 This function controls if user tags are to be spread to other
191 processes with the next message. Spreading of user tags work
192 like spreading of sequential trace tokens, so that a received
193 user tag will be active in the process until the next message
194 arrives (if that message does not also contain the user tag.
195 This functionality is used when a client process communicates
197 with a file i/o-server to spread the user tag to the I/O-server
198 and then down to the efile_drv driver. By using spread_tag/1 and
199 restore_tag/1, one can enable or disable spreading of user tags
200 to other processes and then restore the previous state of the
201 user tag. The TagData returned from this call contains all pre‐
202 vious information so the state (including any previously spread
203 user tags) will be completely restored by a later call to re‐
204 store_tag/1.
205 The file module already spread's tags, so there is no need to
207 manually call these function to get user tags spread to the
208 efile driver through that module.
209 The most use of this function would be if one for example uses
211 the io module to communicate with an I/O-server for a regular
212 file, like in the following example:
213 f() ->
215 {ok, F} = file:open("test.tst",[write]),
216 Saved = dyntrace:spread_tag(true),
217 io:format(F,"Hello world!",[]),
218 dyntrace:restore_tag(Saved),
219 file:close(F).
220 In this example, any user tag set in the calling process will be
223 spread to the I/O-server when the io:format call is done.
224 restore_tag(TagData) -> true
226 Types:
228 TagData = opaque data returned by spread_tag/1
230 Restores the previous state of user tags and their spreading as
232 it was before a call to spread_tag/1. Note that the restoring is
233 not limited to the same process, one can utilize this to turn
234 off spreding in one process and restore it in a newly created,
235 the one that actually is going to send messages:
236 f() ->
238 TagData=dyntrace:spread_tag(false),
239 spawn(fun() ->
240 dyntrace:restore_tag(TagData),
241 do_something()
242 end),
243 do_something_else(),
244 dyntrace:restore_tag(TagData).
245 Correctly handling user tags and their spreading might take some
248 effort, as Erlang programs tend to send and receive messages so
249 that sometimes the user tag gets lost due to various things,
250 like double receives or communication with a port (ports do not
251 handle user tags, in the same way as they do not handle regular
252 sequential trace tokens).
253Ericsson AB runtime_tools 2.0 dyntrace(3)