Provided by: erlang-manpages_20.2.2+dfsg-1ubuntu2_all bug

NAME

       dyntrace - Interface to dynamic tracing

DESCRIPTION

       This  module  implements  interfaces  to dynamic tracing, should such be compiled into the
       virtual machine. For a standard and/or commercial build, no dynamic tracing is  available,
       in which case none of the functions in this module is usable or give any effect.

       Should  dynamic  tracing  be  enabled  in  the  current  build, either by configuring with
       ./configure    --with-dynamic-trace=dtrace    or    with    ./configure    --with-dynamic-
       trace=systemtap, the module can be used for two things:

         * Trigger  the  user-probe  user_trace_i4s4  in  the  NIF library dyntrace.so by calling
           dyntrace:p/{1,2,3,4,5,6,7,8}.

         * Set a user specified tag that will be present  in  the  trace  messages  of  both  the
           efile_drv and the user-probe mentioned above.

       Both  building with dynamic trace probes and using them is experimental and unsupported by
       Erlang/OTP. It is included as an option for the developer to trace and  debug  performance
       issues in their systems.

       The  original  implementation  is mostly done by Scott Lystiger Fritchie as an Open Source
       Contribution and it should be viewed as such even though the source for dynamic tracing as
       well  as  this  module  is  included in the main distribution. However, the ability to use
       dynamic tracing of the virtual machine is a very valuable contribution which OTP has every
       intention to maintain as a tool for the developer.

       How  to  write d programs or systemtap scripts can be learned from books and from a lot of
       pages on the Internet. This manual page does not include any documentation about using the
       dynamic  trace  tools  of respective platform. The examples directory of the runtime_tools
       application however contains comprehensive examples of both d and systemtap programs  that
       will  help  you  get  started.  Another  source of information is the dtrace and systemtap
       chapters in the Runtime Tools Users' Guide.

EXPORTS

       available() -> boolean()

              This function uses the NIF library to determine if dynamic  tracing  is  available.
              Usually  calling  erlang:system_info/1 is a better indicator of the availability of
              dynamic tracing.

              The function will throw an exception if the  dyntrace  NIF  library  could  not  be
              loaded by the on_load function of this module.

       p() -> true | false | error | badarg

              Calling  this  function  will trigger the "user" trace probe user_trace_i4s4 in the
              dyntrace NIF module, sending a trace message  only  containing  the  user  tag  and
              zeroes/empty strings in all other fields.

       p(integer() | string()) -> true | false | error | badarg

              Calling  this  function  will trigger the "user" trace probe user_trace_i4s4 in the
              dyntrace NIF module, sending a trace  message  containing  the  user  tag  and  the
              integer or string parameter in the first integer/string field.

       p(integer() | string(), integer() | string()) -> true | false | error | badarg

              Calling  this  function  will trigger the "user" trace probe user_trace_i4s4 in the
              dyntrace NIF module, sending a trace  message  containing  the  user  tag  and  the
              integer()  or string() parameters as the first fields of respective type. integer()
              parameters should be put before any string() parameters. I.e. p(1,"Hello")  is  ok,
              as is p(1,1) and p("Hello","Again"), but not p("Hello",1).

       p(integer()  |  string(),  integer()  |  string(), integer() | string()) -> true | false |
       error | badarg

              Calling this function will trigger the "user" trace probe  user_trace_i4s4  in  the
              dyntrace  NIF  module,  sending  a  trace  message  containing the user tag and the
              integer() or string() parameters as the first fields of respective type.  integer()
              parameters should be put before any string() parameters, as in p/2.

       p(integer()  | string(), integer() | string(), integer() | string(), integer() | string())
       -> true | false | error | badarg

              Calling this function will trigger the "user" trace probe  user_trace_i4s4  in  the
              dyntrace  NIF  module,  sending  a  trace  message  containing the user tag and the
              integer() or string() parameters as the first fields of respective type.  integer()
              parameters should be put before any string() parameters, as in p/2.

       p(integer(),  integer()  | string(), integer() | string(), integer() | string(), string())
       -> true | false | error | badarg

              Calling this function will trigger the "user" trace probe  user_trace_i4s4  in  the
              dyntrace  NIF  module,  sending  a  trace  message  containing the user tag and the
              integer() or string() parameters as the first fields of respective type.  integer()
              parameters should be put before any string() parameters, as in p/2.

              There  can  be no more than four parameters of any type (integer() or string()), so
              the first parameter has to be an integer() and the last a string().

       p(integer(), integer(), integer() | string(), integer() | string(), string(), string()) ->
       true | false | error | badarg

              Calling  this  function  will trigger the "user" trace probe user_trace_i4s4 in the
              dyntrace NIF module, sending a trace  message  containing  the  user  tag  and  the
              integer()  or string() parameters as the first fields of respective type. integer()
              parameters should be put before any string() parameters, as in p/2.

              There can be no more than four parameters of any type (integer() or  string()),  so
              the first two parameters has to be integer()'s and the last two string()'s.

       p(integer(),  integer(), integer(), integer() | string(), string(), string(), string()) ->
       true | false | error | badarg

              Calling this function will trigger the "user" trace probe  user_trace_i4s4  in  the
              dyntrace  NIF  module,  sending  a  trace  message  containing the user tag and the
              integer() or string() parameters as the first fields of respective type.  integer()
              parameters should be put before any string() parameters, as in p/2.

              There  can  be no more than four parameters of any type (integer() or string()), so
              the first three parameters has to be integer()'s and the last three string()'s.

       p(integer(), integer(), integer(), integer(), string(), string(), string(),  string())  ->
       true | false | error | badarg

              Calling  this  function  will trigger the "user" trace probe user_trace_i4s4 in the
              dyntrace NIF module, sending a trace message containing  all  the  integer()'s  and
              string()'s provided, as well as any user tag set in the current process.

       get_tag() -> binary() | undefined

              This  function returns the user tag set in the current process. If no tag is set or
              dynamic tracing is not available, it returns undefined

       get_tag() -> binary() | undefined

              This function returns the user tag set in the current process or, if no user tag is
              present, the last user tag sent to the process together with a message (in the same
              way as sequential  trace  tokens  are  spread  to  other  processes  together  with
              messages. For an explanation of how user tags can be spread together with messages,
              see spread_tag/1. If no tag is found  or  dynamic  tracing  is  not  available,  it
              returns undefined

       put_tag(Item) -> binary() | undefined

              Types:

                 Item = iodata()

              This function sets the user tag of the current process. The user tag is a binary(),
              but can be specified as any iodata(), which is automatically converted to a  binary
              by this function.

              The   user   tag   is   provided   to  the  user  probes  triggered  by  calls  top
              dyntrace:p/{1,2,3,4,5,6,7,8} as well as probes in the efile_driver. In the  future,
              user tags might be added to more probes.

              The  old  user tag (if any) is returned, or undefined if no user tag was present or
              dynamic tracing is not enabled.

       spread_tag(boolean()) -> TagData

              Types:

                 TagData = opaque data that can be used as parameter to restore_tag/1

              This function controls if user tags are to be spread to other  processes  with  the
              next  message.  Spreading  of  user  tags  work  like spreading of sequential trace
              tokens, so that a received user tag will be active in the process  until  the  next
              message arrives (if that message does not also contain the user tag.

              This  functionality  is  used  when  a client process communicates with a file i/o-
              server to spread the user tag to the I/O-server and  then  down  to  the  efile_drv
              driver.  By  using  spread_tag/1  and  restore_tag/1,  one  can  enable  or disable
              spreading of user tags to other processes and then restore the  previous  state  of
              the user tag. The TagData returned from this call contains all previous information
              so the state (including  any  previously  spread  user  tags)  will  be  completely
              restored by a later call to restore_tag/1.

              The  file module already spread's tags, so there is noo need to manually call these
              function to get user tags spread to the efile driver through that module.

              The most use of this function would be if one for example uses  the  io  module  to
              communicate with an I/O-server for a regular file, like in the following example:

              f() ->
                 {ok, F} = file:open("test.tst",[write]),
                 Saved = dyntrace:spread_tag(true),
                 io:format(F,"Hello world!",[]),
                 dyntrace:restore_tag(Saved),
                 file:close(F).

              In this example, any user tag set in the calling process will be spread to the I/O-
              server when the io:format call is done.

       restore_tag(TagData) -> true

              Types:

                 TagData = opaque data returned by spread_tag/1

              Restores the previous state of user tags and their spreading as  it  was  before  a
              call  to  spread_tag/1. Note that the restoring is not limited to the same process,
              one can utilize this to turn off spreding in one process and restore it in a  newly
              created, the one that actually is going to send messages:

              f() ->
                  TagData=dyntrace:spread_tag(false),
                  spawn(fun() ->
                           dyntrace:restore_tag(TagData),
                           do_something()
                        end),
                  do_something_else(),
                  dyntrace:restore_tag(TagData).

              Correctly  handling user tags and their spreading might take some effort, as Erlang
              programs tend to send and receive messages so that sometimes the user tag gets lost
              due  to various things, like double receives or communication with a port (ports do
              not handle user tags, in the same way as they  do  not  handle  regular  sequential
              trace tokens).