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

FreeBSD Manual Pages

  
 
  

home | help
SDT(9)			   Kernel Developer's Manual			SDT(9)

NAME
       SDT -- a	DTrace framework for adding statically-defined tracing probes

SYNOPSIS
       #include	<sys/param.h>
       #include	<sys/queue.h>
       #include	<sys/sdt.h>

       SDT_PROVIDER_DECLARE(prov);

       SDT_PROVIDER_DEFINE(prov);

       SDT_PROBE_DECLARE(prov, mod, func, name);

       SDT_PROBE_DEFINE(prov, mod, func, name);

       SDT_PROBE_DEFINE0(prov, mod, func, name);

       SDT_PROBE_DEFINE1(prov, mod, func, name,	arg0);

       SDT_PROBE_DEFINE2(prov, mod, func, name,	arg0, arg1);

       SDT_PROBE_DEFINE3(prov, mod, func, name,	arg0, arg1, arg2);

       SDT_PROBE_DEFINE4(prov, mod, func, name,	arg0, arg1, arg2, arg3);

       SDT_PROBE_DEFINE5(prov, mod, func, name,	arg0, arg1, arg2, arg3,	arg4);

       SDT_PROBE_DEFINE6(prov,	mod, func, name, arg0, arg1, arg2, arg3, arg4,
	   arg5);

       SDT_PROBE_DEFINE7(prov, mod, func, name,	arg0, arg1, arg2, arg3,	 arg4,
	   arg5, arg6);

       SDT_PROBE_DEFINE0_XLATE(prov, mod, func,	name);

       SDT_PROBE_DEFINE1_XLATE(prov, mod, func,	name, arg0, xarg0);

       SDT_PROBE_DEFINE2_XLATE(prov,  mod,  func,  name,  arg0,	 xarg0,	 arg1,
	   xarg1);

       SDT_PROBE_DEFINE3_XLATE(prov,  mod,  func,  name,  arg0,	 xarg0,	 arg1,
	   xarg1, arg2,	xarg2);

       SDT_PROBE_DEFINE4_XLATE(prov,  mod,  func,  name,  arg0,	 xarg0,	 arg1,
	   xarg1, arg2,	xarg2, arg3, xarg3);

       SDT_PROBE_DEFINE5_XLATE(prov,  mod,  func,  name,  arg0,	 xarg0,	 arg1,
	   xarg1, arg2,	xarg2, arg3, xarg3, arg4, xarg4);

       SDT_PROBE_DEFINE6_XLATE(prov,  mod,  func,  name,  arg0,	 xarg0,	 arg1,
	   xarg1, arg2,	xarg2, arg3, xarg3, arg4, xarg4, arg5, xarg5);

       SDT_PROBE_DEFINE7_XLATE(prov,  mod,  func,  name,  arg0,	 xarg0,	 arg1,
	   xarg1,  arg2,  xarg2,  arg3,	xarg3, arg4, xarg4, arg5, xarg5, arg6,
	   xarg6);

       SDT_PROBE0(prov,	mod, func, name);

       SDT_PROBE1(prov,	mod, func, name, arg0);

       SDT_PROBE2(prov,	mod, func, name, arg0, arg1);

       SDT_PROBE3(prov,	mod, func, name, arg0, arg1, arg2);

       SDT_PROBE4(prov,	mod, func, name, arg0, arg1, arg2, arg3);

       SDT_PROBE5(prov,	mod, func, name, arg0, arg1, arg2, arg3, arg4);

       SDT_PROBE6(prov,	mod, func, name, arg0, arg1, arg2, arg3, arg4, arg5);

       SDT_PROBE7(prov,	mod, func, name, arg0, arg1, arg2, arg3,  arg4,	 arg5,
	   arg6);

DESCRIPTION
       The  SDT	macros allow programmers to define static trace	points in ker-
       nel code.  These	trace points are used by the SDT framework  to	create
       DTrace  probes,	allowing  the code to be instrumented using dtrace(1).
       By default, SDT trace points are	disabled and have  no  effect  on  the
       surrounding  code.   When a DTrace probe	corresponding to a given trace
       point is	enabled, threads that execute the trace	point will call	a han-
       dler and	cause the probe	to fire.  Moreover, trace points can take  ar-
       guments,	 making	 it possible to	pass data to the DTrace	framework when
       an enabled probe	fires.

       Multiple	trace points may correspond to a single	DTrace probe, allowing
       programmers to create DTrace probes that	correspond to  logical	system
       events  rather than tying probes	to specific code execution paths.  For
       instance, a DTrace probe	corresponding to the arrival of	an  IP	packet
       into  the  network stack	may be defined using two SDT trace points: one
       for IPv4	packets	and one	for IPv6 packets.

       In addition to defining DTrace probes, the SDT macros allow programmers
       to define new DTrace providers, making it possible to  namespace	 logi-
       cally-related  probes.	An  example  is	FreeBSD's sctp provider, which
       contains	SDT probes for FreeBSD's sctp(4) implementation.

       The SDT_PROVIDER_DECLARE() and SDT_PROVIDER_DEFINE()  macros  are  used
       respectively  to	 declare  and define a DTrace provider named prov with
       the SDT framework.  A provider need only	be defined once; however,  the
       provider	 must  be declared before defining any SDT probes belonging to
       that provider.

       Similarly, the SDT_PROBE_DECLARE() and SDT_PROBE_DEFINE*()  macros  are
       used to declare and define DTrace probes	using the SDT framework.  Once
       a  probe	 has been defined, trace points	for that probe may be added to
       kernel code.  DTrace probe identifiers consist of a  provider,  module,
       function	and name, all of which may be specified	in the SDT probe defi-
       nition.	 Note that probes should not specify a module name: the	module
       name of a probe is used to determine whether or not it  should  be  de-
       stroyed	when  a	 kernel	 module	 is unloaded.  See the "BUGS" section.
       Note in particular that probes must not be defined across multiple ker-
       nel modules.

       If `-' character	(dash) is wanted in a probe name, then	it  should  be
       represented  as	`__'  (double  underscore) in the probe	name parameter
       passed to various SDT_*() macros, because of technical reasons (a  dash
       is not valid in C identifiers).

       The  SDT_PROBE_DEFINE*()	 macros	 also allow programmers	to declare the
       types of	the arguments that are passed to probes.  This is optional; if
       the argument types are omitted (through use of  the  SDT_PROBE_DEFINE()
       macro),	users  wishing to make use of the arguments will have to manu-
       ally cast them to the correct types in their D scripts.	It is strongly
       recommended that	probe definitions include a declaration	of their argu-
       ment types.

       The SDT_PROBE_DEFINE*_XLATE() macros are	used for probes	whose argument
       types are to be dynamically translated to the types  specified  by  the
       corresponding xarg arguments.  This is mainly useful when porting probe
       definitions  from  other	 operating systems.  As	seen by	dtrace(1), the
       arguments of a probe defined using these	macros will have  types	 which
       match  the  xarg	types in the probe definition.	However, the arguments
       passed in at the	trace point will have types matching the native	 argu-
       ment types in the probe definition, and thus the	native type is dynami-
       cally  translated  to  the  translated type.  So	long as	an appropriate
       translator is defined in	/usr/lib/dtrace, scripts  making  use  of  the
       probe  need  not	concern	themselves with	the underlying type of a given
       SDT probe argument.

       The SDT_PROBE*()	macros are used	to create SDT trace points.  They  are
       meant  to be added to executable	code and can be	used to	instrument the
       code in which they are called.

PROVIDERS
       A number	of kernel DTrace providers are available.  In  general,	 these
       providers  define  stable interfaces and	should be treated as such: ex-
       isting D	scripts	may be broken if a probe is renamed or	its  arguments
       are  modified.  However,	it is often useful to define ad-hoc SDT	probes
       for debugging a subsystem or driver.  Similarly,	a developer  may  wish
       to  provide  a  group  of SDT probes without committing to their	future
       stability.  Such	probes should be added to the `sdt'  provider  instead
       of defining a new provider.

EXAMPLES
       The DTrace providers available on the current system can	be listed with

	     dtrace -l | sed 1d	| awk '{print $2}' | sort -u

       A  detailed  list  of the probes	offered	by a given provider can	be ob-
       tained by specifying the	provider using the -P flag.  For  example,  to
       view the	probes and argument types for the `sched' provider, run

	     dtrace -lv	-P sched

       The  following  probe  definition  will	create	a  DTrace probe	called
       `icmp:::receive-unreachable', which would hypothetically	 be  triggered
       when  the  kernel  receives an ICMP packet of type Destination Unreach-
       able:

	     SDT_PROVIDER_DECLARE(icmp);

	     SDT_PROBE_DEFINE1(icmp, , , receive__unreachable,
		 "struct icmp *");

       This particular probe would take	a single argument: a  pointer  to  the
       struct containing the ICMP header for the packet.  Note that the	module
       name of this probe is not specified.

       Consider	 a DTrace probe	which fires when the network stack receives an
       IP packet.  Such	a probe	would be defined by multiple tracepoints:

	     SDT_PROBE_DEFINE3(ip, , , receive,	"struct	ifnet *",
		 "struct ip *",	"struct	ip6_hdr	*");

	     int
	     ip_input(struct mbuf *m)
	     {
		     struct ip *ip;
		     ...
		     ip	= mtod(m, struct ip *);
		     SDT_PROBE3(ip, , ,	receive, m->m_pkthdr.rcvif, ip,	NULL);
		     ...
	     }

	     int
	     ip6_input(struct mbuf *m)
	     {
		     struct ip6_hdr *ip6;
		     ...
		     ip6 = mtod(m, struct ip6_hdr *);
		     SDT_PROBE3(ip, , ,	receive, m->m_pkthdr.rcvif, NULL, ip6);
		     ...
	     }

       In particular, the probe	should fire when the kernel receives either an
       IPv4 packet or an IPv6 packet.

       Consider	the ICMP probe discussed above.	 We note that its second argu-
       ment is of type struct icmp, which is a type  defined  in  the  FreeBSD
       kernel  to  represent the ICMP header of	an ICMP	packet,	defined	in RFC
       792.  Linux has a corresponding type, struct icmphdr, for the same pur-
       pose, but its field names differ	from  FreeBSD's	 struct	 icmp.	 Simi-
       larly,  illumos	defines	 the  icmph_t type, again with different field
       names.  Even with the `icmp:::pkt-receive' probes defined in all	 three
       operating systems, one would still have to write	OS-specific scripts to
       extract	a  given  field	out of the ICMP	header argument.  Dynamically-
       translated types	solve this problem: one	can define  an	OS-independent
       c(7)  struct  to	 represent an ICMP header, say struct icmp_hdr_dt, and
       define translators from each of the three OS-specific types  to	struct
       icmp_hdr_dt, all	in the dtrace(1) library path.	Then the FreeBSD probe
       above can be defined with:

	     SDT_PROBE_DEFINE1_XLATE(ip, , , receive, "struct icmp *",
		 "struct icmp_hdr_dt *");

SEE ALSO
       dtrace(1), dtrace_io(4),	dtrace_ip(4), dtrace_proc(4), dtrace_sched(4),
       dtrace_tcp(4), dtrace_udp(4)

AUTHORS
       DTrace and the SDT framework were originally ported to FreeBSD from So-
       laris  by  John Birrell <jb@FreeBSD.org>.  This manual page was written
       by Mark Johnston	<markj@FreeBSD.org>.

BUGS
       The SDT macros allow the	module and function names of  a	 probe	to  be
       specified as part of a probe definition.	 The DTrace framework uses the
       module  name  of	 probes	 to determine which probes should be destroyed
       when a kernel module is unloaded, so the	module name of a probe	should
       match  the  name	 of the	module in which	its defined.  SDT will set the
       module name properly if it is left unspecified in the probe definition;
       see the "EXAMPLES" section.

       One of the goals	of the original	SDT implementation (and	by  extension,
       of  FreeBSD's  port) is that inactive SDT probes	should have no perfor-
       mance impact.  This is unfortunately not	the  case;  SDT	 trace	points
       will  add  a  small but non-zero	amount of latency to the code in which
       they are	defined.  A more sophisticated implementation  of  the	probes
       will help alleviate this	problem.

FreeBSD	14.3			April 18, 2015				SDT(9)

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

home | help