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 September 18, 2014
  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/param.h
  35 .In sys/queue.h
  36 .In sys/sdt.h
  37 .Fn SDT_PROVIDER_DECLARE prov
  38 .Fn SDT_PROVIDER_DEFINE prov
  39 .Fn SDT_PROBE_DECLARE prov mod func name
  40 .Fn SDT_PROBE_DEFINE prov mod func name
  41 .Fn SDT_PROBE_DEFINE0 prov mod func name
  42 .Fn SDT_PROBE_DEFINE1 prov mod func name arg0
  43 .Fn SDT_PROBE_DEFINE2 prov mod func name arg0 arg1
  44 .Fn SDT_PROBE_DEFINE3 prov mod func name arg0 arg1 arg2
  45 .Fn SDT_PROBE_DEFINE4 prov mod func name arg0 arg1 arg2 arg3
  46 .Fn SDT_PROBE_DEFINE5 prov mod func name arg0 arg1 arg2 arg3 arg4
  47 .Fn SDT_PROBE_DEFINE6 prov mod func name arg0 arg1 arg2 arg3 arg4 arg5
  48 .Fn SDT_PROBE_DEFINE7 prov mod func name arg0 arg1 arg2 arg3 arg4 arg5   \
  49     arg6
  50 .Fn SDT_PROBE_DEFINE0_XLATE prov mod func name
  51 .Fn SDT_PROBE_DEFINE1_XLATE prov mod func name arg0 xarg0
  52 .Fn SDT_PROBE_DEFINE2_XLATE prov mod func name arg0 xarg0 arg1 xarg1
  53 .Fn SDT_PROBE_DEFINE3_XLATE prov mod func name arg0 xarg0 arg1 xarg1 \
  54     arg2 xarg2
  55 .Fn SDT_PROBE_DEFINE4_XLATE prov mod func name arg0 xarg0 arg1 xarg1 \
  56     arg2 xarg2 arg3 xarg3
  57 .Fn SDT_PROBE_DEFINE5_XLATE prov mod func name arg0 xarg0 arg1 xarg1 \
  58     arg2 xarg2 arg3 xarg3 arg4 xarg4
  59 .Fn SDT_PROBE_DEFINE6_XLATE prov mod func name arg0 xarg0 arg1 xarg1 \
  60     arg2 xarg2 arg3 xarg3 arg4 xarg4 arg5 xarg5
  61 .Fn SDT_PROBE_DEFINE7_XLATE prov mod func name arg0 xarg0 arg1 xarg1 \
  62     arg2 xarg2 arg3 xarg3 arg4 xarg4 arg5 xarg5 arg6 xarg6
  63 .Fn SDT_PROBE0 prov mod func name
  64 .Fn SDT_PROBE1 prov mod func name arg0
  65 .Fn SDT_PROBE2 prov mod func name arg0 arg1
  66 .Fn SDT_PROBE3 prov mod func name arg0 arg1 arg2
  67 .Fn SDT_PROBE4 prov mod func name arg0 arg1 arg2 arg3
  68 .Fn SDT_PROBE5 prov mod func name arg0 arg1 arg2 arg3 arg4
  69 .Fn SDT_PROBE6 prov mod func name arg0 arg1 arg2 arg3 arg4 arg5
  70 .Fn SDT_PROBE7 prov mod func name arg0 arg1 arg2 arg3 arg4 arg5 arg6
  71 .Sh DESCRIPTION
  72 The
  73 .Nm
  74 macros allow programmers to define static trace points in kernel code.
  75 These trace points are used by the
  76 .Nm
  77 framework to create DTrace probes, allowing the code to be instrumented
  78 using
  79 .Xr dtrace 1 .
  80 By default,
  81 .Nm
  82 trace points are disabled and have no effect on the surrounding code.
  83 When a DTrace probe corresponding to a given trace point is enabled, threads
  84 that execute the trace point will call a handler and cause the probe to fire.
  85 Moreover, trace points can take arguments, making it possible to pass data
  86 to the DTrace framework when an enabled probe fires.
  87 .Pp
  88 Multiple trace points may correspond to a single DTrace probe, allowing
  89 programmers to create DTrace probes that correspond to logical system events
  90 rather than tying probes to specific code execution paths.
  91 For instance, a DTrace probe corresponding to the arrival of an IP packet into
  92 the network stack may be defined using two
  93 .Nm
  94 trace points: one for IPv4 packets and one for IPv6 packets.
  95 .Pp
  96 In addition to defining DTrace probes, the
  97 .Nm
  98 macros allow programmers to define new DTrace providers, making it possible to
  99 namespace logically-related probes.
 100 An example is FreeBSD's sctp provider, which contains
 101 .Nm
 102 probes for FreeBSD's
 103 .Xr sctp 4
 104 implementation.
 105 .Pp
 106 The
 107 .Fn SDT_PROVIDER_DECLARE
 108 and
 109 .Fn SDT_PROVIDER_DEFINE
 110 macros are used respectively to declare and define a DTrace provider named
 111 .Ar prov
 112 with the
 113 .Nm
 114 framework.
 115 A provider need only be defined once; however, the provider must be declared
 116 before defining any
 117 .Nm
 118 probes belonging to that provider.
 119 .Pp
 120 Similarly, the
 121 .Fn SDT_PROBE_DECLARE
 122 and
 123 .Fn SDT_PROBE_DEFINE*
 124 macros are used to declare and define DTrace probes using the
 125 .Nm
 126 framework.
 127 Once a probe has been defined, trace points for that probe may be added to
 128 kernel code.
 129 DTrace probe identifiers consist of a provider, module, function and name, all
 130 of which may be specified in the
 131 .Nm
 132 probe definition.
 133 Note that probes should not specify a module name: the module name of a probe is
 134 used to determine whether or not it should be destroyed when a kernel module is
 135 unloaded.
 136 See the
 137 .Sx BUGS
 138 section.
 139 Note in particular that probes must not be defined across multiple kernel
 140 modules.
 141 .Pp
 142 If
 143 .Ql -
 144 character (dash) is wanted in a probe name,
 145 then it should be represented as
 146 .Ql __
 147 (double underscore) in the probe
 148 .Ar name
 149 parameter passed to various
 150 .Fn SDT_*
 151 macros,
 152 because of technical reasons
 153 (a dash is not valid in C identifiers).
 154 .Pp
 155 The
 156 .Fn SDT_PROBE_DEFINE*
 157 macros also allow programmers to declare the types of the arguments that are
 158 passed to probes.
 159 This is optional; if the argument types are omitted (through use of the
 160 .Fn SDT_PROBE_DEFINE
 161 macro), users wishing to make use of the arguments will have to manually cast
 162 them to the correct types in their D scripts.
 163 It is strongly recommended that probe definitions include a declaration of their
 164 argument types.
 165 .Pp
 166 The
 167 .Fn SDT_PROBE_DEFINE*_XLATE
 168 macros are used for probes whose argument types are to be dynamically translated
 169 to the types specified by the corresponding
 170 .Ar xarg
 171 arguments.
 172 This is mainly useful when porting probe definitions from other operating
 173 systems.
 174 As seen by
 175 .Xr dtrace 1 ,
 176 the arguments of a probe defined using these macros will have types which match
 177 the
 178 .Ar xarg
 179 types in the probe definition.
 180 However, the arguments passed in at the trace point will have types matching the
 181 native argument types in the probe definition, and thus the native type is
 182 dynamically translated to the translated type.
 183 So long as an appropriate translator is defined in
 184 .Pa /usr/lib/dtrace ,
 185 scripts making use of the probe need not concern themselves with the underlying
 186 type of a given
 187 .Nm
 188 probe argument.
 189 .Pp
 190 The
 191 .Fn SDT_PROBE*
 192 macros are used to create
 193 .Nm
 194 trace points.
 195 They are meant to be added to executable code and can be used to instrument the
 196 code in which they are called.
 197 .Sh EXAMPLES
 198 The following probe definition will create a DTrace probe called
 199 .Ql icmp::unreach:pkt-receive ,
 200 which would hypothetically be triggered when the kernel receives an ICMP packet
 201 of type Destination Unreachable:
 202 .Bd -literal -offset indent
 203 SDT_PROVIDER_DECLARE(icmp);
 204
 205 SDT_PROBE_DEFINE1(icmp, , unreach, pkt__receive,
 206     "struct icmp *");
 207
 208 .Ed
 209 This particular probe would take a single argument: a pointer to the struct
 210 containing the ICMP header for the packet.
 211 Note that the module name of this probe is not specified.
 212 .Pp
 213 Consider a DTrace probe which fires when the network stack receives an IP
 214 packet.
 215 Such a probe would be defined by multiple tracepoints:
 216 .Bd -literal -offset indent
 217 SDT_PROBE_DEFINE3(ip, , , receive, "struct ifnet *",
 218     "struct ip *", "struct ip6_hdr *");
 219
 220 int
 221 ip_input(struct mbuf *m)
 222 {
 223         struct ip *ip;
 224         ...
 225         ip = mtod(m, struct ip *);
 226         SDT_PROBE3(ip, , , receive, m->m_pkthdr.rcvif, ip, NULL);
 227         ...
 228 }
 229
 230 int
 231 ip6_input(struct mbuf *m)
 232 {
 233         struct ip6_hdr *ip6;
 234         ...
 235         ip6 = mtod(m, struct ip6_hdr *);
 236         SDT_PROBE3(ip, , , receive, m->m_pkthdr.rcvif, NULL, ip6);
 237         ...
 238 }
 239
 240 .Ed
 241 In particular, the probe should fire when the kernel receives either an IPv4
 242 packet or an IPv6 packet.
 243 .Pp
 244 Consider the ICMP probe discussed above.
 245 We note that its second argument is of type
 246 .Ar struct icmp ,
 247 which is a type defined in the FreeBSD kernel to represent the ICMP header of
 248 an ICMP packet, defined in RFC 792.
 249 Linux has a corresponding type,
 250 .Ar struct icmphdr ,
 251 for the same purpose, but its field names differ from FreeBSD's
 252 .Ar struct icmp .
 253 Similarly, illumos defines the
 254 .Ar icmph_t
 255 type, again with different field names.
 256 Even with the
 257 .Ql icmp:::pkt-receive
 258 probes defined in all three operating systems,
 259 one would still have to write OS-specific scripts to extract a given field out
 260 of the ICMP header argument.
 261 Dynamically-translated types solve this problem: one can define an
 262 OS-independent
 263 .Xr c 7
 264 struct to represent an ICMP header, say
 265 .Ar struct icmp_hdr_dt ,
 266 and define translators from each of the three OS-specific types to
 267 .Ar struct icmp_hdr_dt ,
 268 all in the
 269 .Xr dtrace 1
 270 library path.
 271 Then the FreeBSD probe above can be defined with:
 272 .Bd -literal -offset indent
 273 SDT_PROBE_DEFINE1_XLATE(ip, , , receive, "struct icmp *",
 274     "struct icmp_hdr_dt *");
 275 .Ed
 276 .Sh SEE ALSO
 277 .Xr dtrace 1
 278 .Sh AUTHORS
 279 .An -nosplit
 280 DTrace and the
 281 .Nm
 282 framework were originally ported to FreeBSD from Solaris by
 283 .An John Birrell Aq jb@FreeBSD.org .
 284 This manual page was written by
 285 .An Mark Johnston Aq markj@FreeBSD.org .
 286 .Sh BUGS
 287 The
 288 .Nm
 289 macros allow the module name of a probe to be specified as part of a probe
 290 definition.
 291 However, the DTrace framework uses the module name of probes to determine
 292 which probes should be destroyed when a kernel module is unloaded, so the module
 293 name of a probe should match the name of the module in which its defined.
 294 .Nm
 295 will set the module name properly if it is left unspecified in the probe
 296 definition; see the
 297 .Sx EXAMPLES
 298 section.
 299 .Pp
 300 One of the goals of the original
 301 .Nm
 302 implementation (and by extension, of FreeBSD's port) is that inactive
 303 .Nm
 304 probes should have no performance impact.
 305 This is unfortunately not the case;
 306 .Nm
 307 trace points will add a small but non-zero amount of latency to the code
 308 in which they are defined.
 309 A more sophisticated implementation of the probes will help alleviate this
 310 problem.