1dyntrace(3)                Erlang Module Definition                dyntrace(3)
2
3
4

NAME

6       dyntrace - Interface to dynamic tracing
7

DESCRIPTION

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
14       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
19         * 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
22         * 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
25       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
29       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
36       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

EXPORTS

45       available() -> boolean()
46
47              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
51              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
54       p() -> true | false | error | badarg
55
56              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
61       p(integer() | string()) -> true | false | error | badarg
62
63              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
68       p(integer() | string(), integer() | string()) -> true | false | error |
69       badarg
70
71              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
79       p(integer() | string(), integer() | string(), integer() | string())  ->
80       true | false | error | badarg
81
82              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
89       p(integer() | string(), integer() | string(), integer() | string(), in‐
90       teger() | string()) -> true | false | error | badarg
91
92              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
99       p(integer(), integer() | string(), integer() |  string(),  integer()  |
100       string(), string()) -> true | false | error | badarg
101
102              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
109              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
113       p(integer(), integer(), integer() |  string(),  integer()  |  string(),
114       string(), string()) -> true | false | error | badarg
115
116              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
123              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
127       p(integer(), integer(),  integer(),  integer()  |  string(),  string(),
128       string(), string()) -> true | false | error | badarg
129
130              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
137              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
141       p(integer(),  integer(),  integer(),  integer(),  string(),   string(),
142       string(), string()) -> true | false | error | badarg
143
144              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
149       get_tag() -> binary() | undefined
150
151              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
155       get_tag() -> binary() | undefined
156
157              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
165       put_tag(Item) -> binary() | undefined
166
167              Types:
168
169                 Item = iodata()
170
171              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
175              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
180              The  old  user tag (if any) is returned, or undefined if no user
181              tag was present or dynamic tracing is not enabled.
182
183       spread_tag(boolean()) -> TagData
184
185              Types:
186
187                 TagData = opaque data that can be used as  parameter  to  re‐
188                 store_tag/1
189
190              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
196              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
206              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
210              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
214              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
221
222              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
225       restore_tag(TagData) -> true
226
227              Types:
228
229                 TagData = opaque data returned by spread_tag/1
230
231              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
237              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
246
247              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).
253
254
255
256Ericsson AB                    runtime_tools 2.0                   dyntrace(3)
Impressum