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

FreeBSD Manual Pages

  
 
  

home | help
SDT(9)		       FreeBSD 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 kernel
     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 sur-
     rounding code.  When a DTrace probe corresponding to a given trace	point
     is	enabled, threads that execute the trace	point will call	a handler and
     cause the probe to	fire.  Moreover, trace points can take arguments, mak-
     ing 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 con-
     tains 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 ker-
     nel code.	DTrace probe identifiers consist of a provider,	module,	func-
     tion and name, all	of which may be	specified in the SDT probe definition.
     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 destroyed when a
     kernel module is unloaded.	 See the BUGS section.	Note in	particular
     that probes must not be defined across multiple kernel modules.

     If	`-' character (dash) is	wanted in a probe name,	then it	should be rep-
     resented 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 manually
     cast them to the correct types in their D scripts.	 It is strongly	recom-
     mended that probe definitions include a declaration of their argument
     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 cor-
     responding	xarg arguments.	 This is mainly	useful when porting probe def-
     initions from other operating systems.  As	seen by	dtrace(1), the argu-
     ments 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 argument types in
     the probe definition, and thus the	native type is dynamically 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: exist-
     ing 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 pro-
     vide 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 obtained
     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 Unreachable:

	   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 ker-
     nel to represent the ICMP header of an ICMP packet, defined in RFC	792.
     Linux has a corresponding type, struct icmphdr, for the same purpose, but
     its field names differ from FreeBSD's struct icmp.	 Similarly, 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 rep-
     resent 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
     Solaris 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 spec-
     ified as part of a	probe definition.  The DTrace framework	uses the mod-
     ule 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	performance
     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	Ports 11.2		April 18, 2015		    FreeBSD Ports 11.2

NAME | SYNOPSIS | DESCRIPTION | PROVIDERS | EXAMPLES | SEE ALSO | AUTHORS | BUGS

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

home | help