share/man/man9/SDT.9

   1 .\" Copyright (c) 2013 Mark Johnston <markj@freebsd.org>
   2 .\" All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\"
  13 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  16 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  17 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  18 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  19 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  20 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  21 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  22 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  23 .\" SUCH DAMAGE.
  24 .\"
  25 .\" $FreeBSD$
  26 .\"
  27 .Dd July 3, 2013
  28 .Dt SDT 9
  29 .Os
  30 .Sh NAME
  31 .Nm SDT
  32 .Nd a DTrace framework for adding statically-defined tracing probes
  33 .Sh SYNOPSIS
  34 .In sys/sdt.h
  35 .Fn SDT_PROVIDER_DECLARE prov
  36 .Fn SDT_PROVIDER_DEFINE prov
  37 .Fn SDT_PROBE_DECLARE prov mod func name
  38 .Fn SDT_PROBE_DEFINE prov mod func name sname
  39 .Fn SDT_PROBE_DEFINE0 prov mod func name sname
  40 .Fn SDT_PROBE_DEFINE1 prov mod func name sname arg0
  41 .Fn SDT_PROBE_DEFINE2 prov mod func name sname arg0 arg1
  42 .Fn SDT_PROBE_DEFINE3 prov mod func name sname arg0 arg1 arg2
  43 .Fn SDT_PROBE_DEFINE4 prov mod func name sname arg0 arg1 arg2 arg3
  44 .Fn SDT_PROBE_DEFINE5 prov mod func name sname arg0 arg1 arg2 arg3 arg4
  45 .Fn SDT_PROBE_DEFINE6 prov mod func name sname arg0 arg1 arg2 arg3 arg4 arg5
  46 .Fn SDT_PROBE_DEFINE7 prov mod func name sname arg0 arg1 arg2 arg3 arg4 arg5   \
  47     arg6
  48 .Fn SDT_PROBE0 prov mod func name
  49 .Fn SDT_PROBE1 prov mod func name arg0
  50 .Fn SDT_PROBE2 prov mod func name arg0 arg1
  51 .Fn SDT_PROBE3 prov mod func name arg0 arg1 arg2
  52 .Fn SDT_PROBE4 prov mod func name arg0 arg1 arg2 arg3
  53 .Fn SDT_PROBE5 prov mod func name arg0 arg1 arg2 arg3 arg4
  54 .Fn SDT_PROBE6 prov mod func name arg0 arg1 arg2 arg3 arg4 arg5
  55 .Fn SDT_PROBE7 prov mod func name arg0 arg1 arg2 arg3 arg4 arg5 arg6
  56 .Sh DESCRIPTION
  57 .Pp
  58 The
  59 .Nm
  60 macros allow programmers to define static trace points in kernel code.
  61 These trace points are used by the
  62 .Nm
  63 framework to create DTrace probes, allowing the code to be instrumented
  64 using
  65 .Xr dtrace 1 .
  66 By default,
  67 .Nm
  68 trace points are disabled and have no effect on the surrounding code.
  69 When a DTrace probe corresponding to a given trace point is enabled, threads
  70 that execute the trace point will call a handler and cause the probe to fire.
  71 Moreover, trace points can take arguments, making it possible to pass data
  72 to the DTrace framework when an enabled probe fires.
  73 .Pp
  74 Multiple trace points may correspond to a single DTrace probe, allowing
  75 programmers to create DTrace probes that correspond to logical system events
  76 rather than tying probes to specific code execution paths.
  77 For instance, a DTrace probe corresponding to the arrival of an IP packet into
  78 the network stack may be defined using two
  79 .Nm
  80 trace points: one for IPv4 packets and one for IPv6 packets.
  81 .Pp
  82 In addition to defining DTrace probes, the
  83 .Nm
  84 macros allow programmers to define new DTrace providers, making it possible to
  85 namespace logically-related probes.
  86 An example is FreeBSD's sctp provider, which contains
  87 .Nm
  88 probes for FreeBSD's
  89 .Xr sctp 4
  90 implementation.
  91 .Pp
  92 The
  93 .Fn SDT_PROVIDER_DECLARE
  94 and
  95 .Fn SDT_PROVIDER_DEFINE
  96 macros are used respectively to declare and define a DTrace provider named
  97 .Ar prov
  98 with the
  99 .Nm
 100 framework.
 101 A provider need only be defined once; however, the provider must be declared
 102 before defining any
 103 .Nm
 104 probes belonging to that provider.
 105 .Pp
 106 Similarly, the
 107 .Fn SDT_PROBE_DECLARE
 108 and
 109 .Fn SDT_PROBE_DEFINE*
 110 macros are used to declare and define DTrace probes using the
 111 .Nm
 112 framework.
 113 Once a probe has been defined, trace points for that probe may be added to
 114 kernel code.
 115 DTrace probe identifiers consist of a provider, module, function and name, all
 116 of which may be specified in the
 117 .Nm
 118 probe definition.
 119 Note that probes should not specify a module name: the module name of a probe is
 120 used to determine whether or not it should be destroyed when a kernel module is
 121 unloaded.
 122 See the
 123 .Sx BUGS
 124 section.
 125 Note in particular that probes must not be defined across multiple kernel
 126 modules.
 127 The
 128 .Fn SDT_PROBE_DEFINE*
 129 macros also take an extra
 130 .Ar sname
 131 parameter.
 132 This is used to allow the creation of probes with names containing the
 133 .Ql -
 134 character.
 135 Specifically, the
 136 .Ar name
 137 argument should contain the probe name with all dashes converted to underscores,
 138 and the
 139 .Ar sname
 140 argument should be the probe name as it will be referenced by D scripts.
 141 .Pp
 142 The
 143 .Fn SDT_PROBE_DEFINE*
 144 macros also allow programmers to declare the types of the arguments that are
 145 passed to probes.
 146 This is optional; if the argument types are omitted (through use of the
 147 .Fn SDT_PROBE_DEFINE
 148 macro), users wishing to make use of the arguments will have to manually cast
 149 them to the correct types in their D scripts.
 150 It is strongly recommended that probe definitions include a declaration of their
 151 argument types.
 152 .Pp
 153 The
 154 .Fn SDT_PROBE*
 155 macros are used to create
 156 .Nm
 157 trace points.
 158 They are meant to be added to executable code and can be used to instrument the
 159 code in which they are called.
 160 .Sh EXAMPLES
 161 .Pp
 162 The following probe definition will create a DTrace probe called
 163 .Ql icmp::unreach:pkt-receive ,
 164 which would hypothetically be triggered when the kernel receives an ICMP packet
 165 of type Destination Unreachable:
 166 .Bd -literal -offset indent
 167 SDT_PROVIDER_DECLARE(icmp);
 168
 169 SDT_PROBE_DEFINE2(icmp, , unreach, pkt_receive, pkt-receive,
 170     "struct mbuf *", "struct icmp *");
 171
 172 .Ed
 173 This particular probe would take two arguments: a pointer to the
 174 .Xr mbuf 9
 175 containing the incoming packet, and a pointer to the ICMP header for the packet.
 176 Note that the module name of this probe is not specified.
 177 .Pp
 178 Consider a DTrace probe which fires when the network stack receives an IP
 179 packet.
 180 Such a probe would be defined by multiple tracepoints:
 181 .Bd -literal -offset indent
 182 SDT_PROBE_DEFINE2(ip, , , receive, receive, "struct mbuf *",
 183     "struct ifnet *", "struct ip *", "struct ip6_hdr *");
 184
 185 int
 186 ip_input(struct mbuf *m)
 187 {
 188         struct ip *ip;
 189         ...
 190         ip = mtod(m, struct ip *);
 191         SDT_PROBE4(ip, , , receive, m, m->m_pkthdr.rcvif, ip, NULL);
 192         ...
 193 }
 194
 195 int
 196 ip6_input(struct mbuf *m)
 197 {
 198         struct ip6_hdr *ip6;
 199         ...
 200         ip6 = mtod(m, struct ip6_hdr *);
 201         SDT_PROBE4(ip, , , receive, m, m->m_pkthdr.rcvif, NULL, ip6);
 202         ...
 203 }
 204
 205 .Ed
 206 In particular, the probe should fire when the kernel receives either an IPv4
 207 packet or an IPv6 packet.
 208 .Sh SEE ALSO
 209 .Xr dtrace 1
 210 .Sh AUTHORS
 211 .An -nosplit
 212 DTrace and the
 213 .Nm
 214 framework were originally ported to FreeBSD from Solaris by
 215 .An John Birrell Aq jb@FreeBSD.org .
 216 This manual page was written by
 217 .An Mark Johnston Aq markj@FreeBSD.org .
 218 .Sh BUGS
 219 .Pp
 220 The
 221 .Nm
 222 macros allow the module name of a probe to be specified as part of a probe
 223 definition.
 224 However, the DTrace framework uses the module name of probes to determine
 225 which probes should be destroyed when a kernel module is unloaded, so the module
 226 name of a probe should match the name of the module in which its defined.
 227 .Nm
 228 will set the module name properly if it is left unspecified in the probe
 229 definition; see the
 230 .Sx EXAMPLES
 231 section.
 232 .Pp
 233 One of the goals of the original
 234 .Nm
 235 implementation (and by extension, of FreeBSD's port) is that inactive
 236 .Nm
 237 probes should have no performance impact.
 238 This is unfortunately not the case;
 239 .Nm
 240 trace points will add a small but non-zero amount of latency to the code
 241 in which they are defined.
 242 A more sophisticated implementation of the probes will help alleviate this
 243 problem.