1 .\" Copyright (c) 2013-2015 Mark Johnston <markj@freebsd.org>
2 .\" All rights reserved.
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
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.
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
32 .Nd a DTrace framework for adding statically-defined tracing probes
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 \
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 \
55 .Fn SDT_PROBE_DEFINE4_XLATE prov mod func name arg0 xarg0 arg1 xarg1 \
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
74 macros allow programmers to define static trace points in kernel code.
75 These trace points are used by the
77 framework to create DTrace probes, allowing the code to be instrumented
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.
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
94 trace points: one for IPv4 packets and one for IPv6 packets.
96 In addition to defining DTrace probes, the
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
107 .Fn SDT_PROVIDER_DECLARE
109 .Fn SDT_PROVIDER_DEFINE
110 macros are used respectively to declare and define a DTrace provider named
115 A provider need only be defined once; however, the provider must be declared
118 probes belonging to that provider.
121 .Fn SDT_PROBE_DECLARE
123 .Fn SDT_PROBE_DEFINE*
124 macros are used to declare and define DTrace probes using the
127 Once a probe has been defined, trace points for that probe may be added to
129 DTrace probe identifiers consist of a provider, module, function and name, all
130 of which may be specified in the
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
139 Note in particular that probes must not be defined across multiple kernel
144 character (dash) is wanted in a probe name,
145 then it should be represented as
147 (double underscore) in the probe
149 parameter passed to various
152 because of technical reasons
153 (a dash is not valid in C identifiers).
156 .Fn SDT_PROBE_DEFINE*
157 macros also allow programmers to declare the types of the arguments that are
159 This is optional; if the argument types are omitted (through use of the
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
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
172 This is mainly useful when porting probe definitions from other operating
176 the arguments of a probe defined using these macros will have types which match
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
192 macros are used to create
195 They are meant to be added to executable code and can be used to instrument the
196 code in which they are called.
198 A number of kernel DTrace providers are available.
199 In general, these providers define stable interfaces and should be treated as
200 such: existing D scripts may be broken if a probe is renamed or its arguments
202 However, it is often useful to define ad-hoc
204 probes for debugging a subsystem or driver.
205 Similarly, a developer may wish to provide a group of
207 probes without committing to their future stability.
208 Such probes should be added to the
210 provider instead of defining a new provider.
212 The DTrace providers available on the current system can be listed with
213 .Bd -literal -offset indent
214 dtrace -l | sed 1d | awk '{print $2}' | sort -u
217 A detailed list of the probes offered by a given provider can be obtained by
218 specifying the provider using the
221 For example, to view the probes and argument types for the
224 .Bd -literal -offset indent
228 The following probe definition will create a DTrace probe called
229 .Ql icmp:::receive-unreachable ,
230 which would hypothetically be triggered when the kernel receives an ICMP packet
231 of type Destination Unreachable:
232 .Bd -literal -offset indent
233 SDT_PROVIDER_DECLARE(icmp);
235 SDT_PROBE_DEFINE1(icmp, , , receive__unreachable,
239 This particular probe would take a single argument: a pointer to the struct
240 containing the ICMP header for the packet.
241 Note that the module name of this probe is not specified.
243 Consider a DTrace probe which fires when the network stack receives an IP
245 Such a probe would be defined by multiple tracepoints:
246 .Bd -literal -offset indent
247 SDT_PROBE_DEFINE3(ip, , , receive, "struct ifnet *",
248 "struct ip *", "struct ip6_hdr *");
251 ip_input(struct mbuf *m)
255 ip = mtod(m, struct ip *);
256 SDT_PROBE3(ip, , , receive, m->m_pkthdr.rcvif, ip, NULL);
261 ip6_input(struct mbuf *m)
265 ip6 = mtod(m, struct ip6_hdr *);
266 SDT_PROBE3(ip, , , receive, m->m_pkthdr.rcvif, NULL, ip6);
271 In particular, the probe should fire when the kernel receives either an IPv4
272 packet or an IPv6 packet.
274 Consider the ICMP probe discussed above.
275 We note that its second argument is of type
277 which is a type defined in the FreeBSD kernel to represent the ICMP header of
278 an ICMP packet, defined in RFC 792.
279 Linux has a corresponding type,
281 for the same purpose, but its field names differ from FreeBSD's
283 Similarly, illumos defines the
285 type, again with different field names.
287 .Ql icmp:::pkt-receive
288 probes defined in all three operating systems,
289 one would still have to write OS-specific scripts to extract a given field out
290 of the ICMP header argument.
291 Dynamically-translated types solve this problem: one can define an
294 struct to represent an ICMP header, say
295 .Ar struct icmp_hdr_dt ,
296 and define translators from each of the three OS-specific types to
297 .Ar struct icmp_hdr_dt ,
301 Then the FreeBSD probe above can be defined with:
302 .Bd -literal -offset indent
303 SDT_PROBE_DEFINE1_XLATE(ip, , , receive, "struct icmp *",
304 "struct icmp_hdr_dt *");
318 framework were originally ported to FreeBSD from Solaris by
319 .An John Birrell Aq Mt jb@FreeBSD.org .
320 This manual page was written by
321 .An Mark Johnston Aq Mt markj@FreeBSD.org .
325 macros allow the module and function names of a probe to be specified as part of
327 The DTrace framework uses the module name of probes to determine which probes
328 should be destroyed when a kernel module is unloaded, so the module
329 name of a probe should match the name of the module in which its defined.
331 will set the module name properly if it is left unspecified in the probe
336 One of the goals of the original
338 implementation (and by extension, of FreeBSD's port) is that inactive
340 probes should have no performance impact.
341 This is unfortunately not the case;
343 trace points will add a small but non-zero amount of latency to the code
344 in which they are defined.
345 A more sophisticated implementation of the probes will help alleviate this