NAME¶
SDT
—
a DTrace framework for adding statically-defined
tracing probes
SYNOPSIS¶
#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.
EXAMPLES¶
The following probe definition will create a DTrace probe called
‘
icmp::unreach:pkt-receive
’, which would
hypothetically be triggered when the kernel receives an ICMP packet of type
Destination Unreachable:
SDT_PROVIDER_DECLARE(icmp);
SDT_PROBE_DEFINE1(icmp, , unreach, pkt__receive,
"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)
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 name of a
probe to be specified as part of a probe definition. However, 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.