share/man/man9/SDT.9

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