FreeBSD Manual Pages

SDT(9) BSD Kernel Developer's Manual SDT(9)
NAMESDT -- 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 de-
fault, SDT trace points are disabled and have no effect on the surround-
ing 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 re-
spectively 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 structicmp, 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, structicmphdr, for the same purpose, but
its field names differ from FreeBSD's structicmp. 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 structicmp_hdr_dt, and define translators
from each of the three OS-specific types to structicmp_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 ALSOdtrace(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 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 de-
fined. A more sophisticated implementation of the probes will help alle-
viate this problem.
BSD April 18, 2015 BSD