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