Provided by: freebsd-manpages_11.1-3_all bug

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 surrounding 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, 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 logically-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 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 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
     manually cast them to the correct types in their D scripts.  It is strongly recommended 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 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 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: existing 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 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 argument 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
     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 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 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 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 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.