241 lines
8.0 KiB
Groff
241 lines
8.0 KiB
Groff
.\" Copyright (c) 2013 Mark Johnston <markj@freebsd.org>
|
|
.\" All rights reserved.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions
|
|
.\" are met:
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
|
|
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
|
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
|
|
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
|
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
|
|
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
|
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
|
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
|
|
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
|
.\" SUCH DAMAGE.
|
|
.\"
|
|
.\" $FreeBSD$
|
|
.\"
|
|
.Dd July 3, 2013
|
|
.Dt SDT 9
|
|
.Os
|
|
.Sh NAME
|
|
.Nm SDT
|
|
.Nd a DTrace framework for adding statically-defined tracing probes
|
|
.Sh SYNOPSIS
|
|
.In sys/sdt.h
|
|
.Fn SDT_PROVIDER_DECLARE prov
|
|
.Fn SDT_PROVIDER_DEFINE prov
|
|
.Fn SDT_PROBE_DECLARE prov mod func name
|
|
.Fn SDT_PROBE_DEFINE prov mod func name sname
|
|
.Fn SDT_PROBE_DEFINE0 prov mod func name sname
|
|
.Fn SDT_PROBE_DEFINE1 prov mod func name sname arg0
|
|
.Fn SDT_PROBE_DEFINE2 prov mod func name sname arg0 arg1
|
|
.Fn SDT_PROBE_DEFINE3 prov mod func name sname arg0 arg1 arg2
|
|
.Fn SDT_PROBE_DEFINE4 prov mod func name sname arg0 arg1 arg2 arg3
|
|
.Fn SDT_PROBE_DEFINE5 prov mod func name sname arg0 arg1 arg2 arg3 arg4
|
|
.Fn SDT_PROBE_DEFINE6 prov mod func name sname arg0 arg1 arg2 arg3 arg4 arg5
|
|
.Fn SDT_PROBE_DEFINE7 prov mod func name sname arg0 arg1 arg2 arg3 arg4 arg5 \
|
|
arg6
|
|
.Fn SDT_PROBE0 prov mod func name
|
|
.Fn SDT_PROBE1 prov mod func name arg0
|
|
.Fn SDT_PROBE2 prov mod func name arg0 arg1
|
|
.Fn SDT_PROBE3 prov mod func name arg0 arg1 arg2
|
|
.Fn SDT_PROBE4 prov mod func name arg0 arg1 arg2 arg3
|
|
.Fn SDT_PROBE5 prov mod func name arg0 arg1 arg2 arg3 arg4
|
|
.Fn SDT_PROBE6 prov mod func name arg0 arg1 arg2 arg3 arg4 arg5
|
|
.Fn SDT_PROBE7 prov mod func name arg0 arg1 arg2 arg3 arg4 arg5 arg6
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Nm
|
|
macros allow programmers to define static trace points in kernel code.
|
|
These trace points are used by the
|
|
.Nm
|
|
framework to create DTrace probes, allowing the code to be instrumented
|
|
using
|
|
.Xr dtrace 1 .
|
|
By default,
|
|
.Nm
|
|
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.
|
|
.Pp
|
|
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
|
|
.Nm
|
|
trace points: one for IPv4 packets and one for IPv6 packets.
|
|
.Pp
|
|
In addition to defining DTrace probes, the
|
|
.Nm
|
|
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
|
|
.Nm
|
|
probes for FreeBSD's
|
|
.Xr sctp 4
|
|
implementation.
|
|
.Pp
|
|
The
|
|
.Fn SDT_PROVIDER_DECLARE
|
|
and
|
|
.Fn SDT_PROVIDER_DEFINE
|
|
macros are used respectively to declare and define a DTrace provider named
|
|
.Ar prov
|
|
with the
|
|
.Nm
|
|
framework.
|
|
A provider need only be defined once; however, the provider must be declared
|
|
before defining any
|
|
.Nm
|
|
probes belonging to that provider.
|
|
.Pp
|
|
Similarly, the
|
|
.Fn SDT_PROBE_DECLARE
|
|
and
|
|
.Fn SDT_PROBE_DEFINE*
|
|
macros are used to declare and define DTrace probes using the
|
|
.Nm
|
|
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
|
|
.Nm
|
|
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
|
|
.Sx BUGS
|
|
section.
|
|
Note in particular that probes must not be defined across multiple kernel
|
|
modules.
|
|
The
|
|
.Fn SDT_PROBE_DEFINE*
|
|
macros also take an extra
|
|
.Ar sname
|
|
parameter.
|
|
This is used to allow the creation of probes with names containing the
|
|
.Ql -
|
|
character.
|
|
Specifically, the
|
|
.Ar name
|
|
argument should contain the probe name with all dashes converted to underscores,
|
|
and the
|
|
.Ar sname
|
|
argument should be the probe name as it will be referenced by D scripts.
|
|
.Pp
|
|
The
|
|
.Fn 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
|
|
.Fn 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.
|
|
.Pp
|
|
The
|
|
.Fn SDT_PROBE*
|
|
macros are used to create
|
|
.Nm
|
|
trace points.
|
|
They are meant to be added to executable code and can be used to instrument the
|
|
code in which they are called.
|
|
.Sh EXAMPLES
|
|
The following probe definition will create a DTrace probe called
|
|
.Ql icmp::unreach:pkt-receive ,
|
|
which would hypothetically be triggered when the kernel receives an ICMP packet
|
|
of type Destination Unreachable:
|
|
.Bd -literal -offset indent
|
|
SDT_PROVIDER_DECLARE(icmp);
|
|
|
|
SDT_PROBE_DEFINE2(icmp, , unreach, pkt_receive, pkt-receive,
|
|
"struct mbuf *", "struct icmp *");
|
|
|
|
.Ed
|
|
This particular probe would take two arguments: a pointer to the
|
|
.Xr mbuf 9
|
|
containing the incoming packet, and a pointer to the ICMP header for the packet.
|
|
Note that the module name of this probe is not specified.
|
|
.Pp
|
|
Consider a DTrace probe which fires when the network stack receives an IP
|
|
packet.
|
|
Such a probe would be defined by multiple tracepoints:
|
|
.Bd -literal -offset indent
|
|
SDT_PROBE_DEFINE2(ip, , , receive, receive, "struct mbuf *",
|
|
"struct ifnet *", "struct ip *", "struct ip6_hdr *");
|
|
|
|
int
|
|
ip_input(struct mbuf *m)
|
|
{
|
|
struct ip *ip;
|
|
...
|
|
ip = mtod(m, struct ip *);
|
|
SDT_PROBE4(ip, , , receive, m, m->m_pkthdr.rcvif, ip, NULL);
|
|
...
|
|
}
|
|
|
|
int
|
|
ip6_input(struct mbuf *m)
|
|
{
|
|
struct ip6_hdr *ip6;
|
|
...
|
|
ip6 = mtod(m, struct ip6_hdr *);
|
|
SDT_PROBE4(ip, , , receive, m, m->m_pkthdr.rcvif, NULL, ip6);
|
|
...
|
|
}
|
|
|
|
.Ed
|
|
In particular, the probe should fire when the kernel receives either an IPv4
|
|
packet or an IPv6 packet.
|
|
.Sh SEE ALSO
|
|
.Xr dtrace 1
|
|
.Sh AUTHORS
|
|
.An -nosplit
|
|
DTrace and the
|
|
.Nm
|
|
framework were originally ported to FreeBSD from Solaris by
|
|
.An John Birrell Aq jb@FreeBSD.org .
|
|
This manual page was written by
|
|
.An Mark Johnston Aq markj@FreeBSD.org .
|
|
.Sh BUGS
|
|
The
|
|
.Nm
|
|
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.
|
|
.Nm
|
|
will set the module name properly if it is left unspecified in the probe
|
|
definition; see the
|
|
.Sx EXAMPLES
|
|
section.
|
|
.Pp
|
|
One of the goals of the original
|
|
.Nm
|
|
implementation (and by extension, of FreeBSD's port) is that inactive
|
|
.Nm
|
|
probes should have no performance impact.
|
|
This is unfortunately not the case;
|
|
.Nm
|
|
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.
|