Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
dyntrace(3)		   Erlang Module Definition		   dyntrace(3)

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 func-
       tions in	this module is usable or give any effect.

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

	 * Trigger  the	 user-probe  user_trace_i4s4  in  the NIF library dyn-
	   trace.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  de-
       veloper 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 in-
       cluded 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 in-
       clude any documentation about using the dynamic trace tools of  respec-
       tive  platform. The examples directory of the runtime_tools application
       however contains	comprehensive examples of both d  and  systemtap  pro-
       grams  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 trac-
	      ing is available.	Usually	calling	erlang:system_info/1 is	a bet-
	      ter 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 mes-
	      sage  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 mes-
	      sage 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 mes-
	      sage containing the user tag and the integer() or	 string()  pa-
	      rameters	as  the	first fields of	respective type. integer() pa-
	      rameters 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 mes-
	      sage  containing	the user tag and the integer() or string() pa-
	      rameters as the first fields of respective type.	integer()  pa-
	      rameters	should	be  put	 before	any string() parameters, as in
	      p/2.

       p(integer() | string(), integer() | string(), integer() | string(), in-
       teger() | 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 mes-
	      sage  containing	the user tag and the integer() or string() pa-
	      rameters as the first fields of respective type.	integer()  pa-
	      rameters	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 mes-
	      sage  containing	the user tag and the integer() or string() pa-
	      rameters as the first fields of respective type.	integer()  pa-
	      rameters	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 mes-
	      sage  containing	the user tag and the integer() or string() pa-
	      rameters as the first fields of respective type.	integer()  pa-
	      rameters	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 mes-
	      sage  containing	the user tag and the integer() or string() pa-
	      rameters as the first fields of respective type.	integer()  pa-
	      rameters	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 inte-
	      ger()'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 mes-
	      sage  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 mes-
	      sages. For an explanation	of how user tags  can  be  spread  to-
	      gether  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  re-
		 store_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  pre-
	      vious  information so the	state (including any previously	spread
	      user tags) will be completely restored by	a later	 call  to  re-
	      store_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).

Ericsson AB		     runtime_tools 1.13.2		   dyntrace(3)

NAME | DESCRIPTION | EXPORTS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=dyntrace&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help