mirror of
https://git.FreeBSD.org/src.git
synced 2024-12-21 11:13:30 +00:00
Add a man page for the SDT_* macros, which can be used to define new static
DTrace probes and providers in kernel code. MFC after: 1 week
This commit is contained in:
Mark Johnston
parent
d63fca7a07
commit
98491bfaa4
Notes:
svn2git
2020-12-20 02:59:44 +00:00
svn path=/head/; revision=252895
@ -236,6 +236,7 @@ MAN= accept_filter.9 \
|
||||
rwlock.9 \
|
||||
sbuf.9 \
|
||||
scheduler.9 \
|
||||
SDT.9 \
|
||||
securelevel_gt.9 \
|
||||
selrecord.9 \
|
||||
sema.9 \
|
||||
@ -1147,6 +1148,11 @@ MLINKS+=scheduler.9 curpriority_cmp.9 \
|
||||
scheduler.9 sched_setup.9 \
|
||||
scheduler.9 setrunnable.9 \
|
||||
scheduler.9 updatepri.9
|
||||
MLINKS+=SDT.9 SDT_PROVIDER_DECLARE.9 \
|
||||
SDT.9 SDT_PROVIDER_DEFINE.9 \
|
||||
SDT.9 SDT_PROBE_DECLARE.9 \
|
||||
SDT.9 SDT_PROBE_DEFINE.9 \
|
||||
SDT.9 SDT_PROBE.9
|
||||
MLINKS+=securelevel_gt.9 securelevel_ge.9
|
||||
MLINKS+=selrecord.9 seldrain.9 \
|
||||
selrecord.9 selwakeup.9
|
||||
|
||||
243
share/man/man9/SDT.9
Normal file
243
share/man/man9/SDT.9
Normal file
@ -0,0 +1,243 @@
|
||||
.\" 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
|
||||
.Pp
|
||||
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
|
||||
.Pp
|
||||
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
|
||||
.Pp
|
||||
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.
|
||||
Loading…
Reference in New Issue
Block a user