| SDT.9 (282444) | SDT.9 (260817) |
|---|---|
| 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. --- 8 unchanged lines hidden (view full) --- 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.\" | 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. --- 8 unchanged lines hidden (view full) --- 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.\" | 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 | 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 --- 145 unchanged lines hidden (view full) --- 189.Pp 190The 191.Fn SDT_PROBE* 192macros are used to create 193.Nm 194trace points. 195They are meant to be added to executable code and can be used to instrument the 196code in which they are called. | 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 --- 145 unchanged lines hidden (view full) --- 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. | |
| 211.Sh EXAMPLES | 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 | |
| 228The following probe definition will create a DTrace probe called | 196The following probe definition will create a DTrace probe called |
| 229.Ql icmp:::receive-unreachable , | 197.Ql icmp::unreach:pkt-receive , |
| 230which would hypothetically be triggered when the kernel receives an ICMP packet 231of type Destination Unreachable: 232.Bd -literal -offset indent 233SDT_PROVIDER_DECLARE(icmp); 234 | 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, |
| 236 "struct icmp *"); 237 238.Ed 239This particular probe would take a single argument: a pointer to the struct 240containing the ICMP header for the packet. 241Note that the module name of this probe is not specified. 242.Pp 243Consider a DTrace probe which fires when the network stack receives an IP 244packet. 245Such a probe would be defined by multiple tracepoints: 246.Bd -literal -offset indent | 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 *", |
| 248 "struct ip *", "struct ip6_hdr *"); 249 250int 251ip_input(struct mbuf *m) 252{ 253 struct ip *ip; 254 ... 255 ip = mtod(m, struct ip *); --- 39 unchanged lines hidden (view full) --- 295.Ar struct icmp_hdr_dt , 296and define translators from each of the three OS-specific types to 297.Ar struct icmp_hdr_dt , 298all in the 299.Xr dtrace 1 300library path. 301Then the FreeBSD probe above can be defined with: 302.Bd -literal -offset indent | 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 *); --- 39 unchanged lines hidden (view full) --- 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 *", |
| 304 "struct icmp_hdr_dt *"); 305.Ed 306.Sh SEE ALSO 307.Xr dtrace 1 308.Sh AUTHORS 309.An -nosplit 310DTrace and the 311.Nm 312framework were originally ported to FreeBSD from Solaris by 313.An John Birrell Aq jb@FreeBSD.org . 314This manual page was written by 315.An Mark Johnston Aq markj@FreeBSD.org . 316.Sh BUGS 317The 318.Nm | 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 |
| 323name of a probe should match the name of the module in which its defined. 324.Nm 325will set the module name properly if it is left unspecified in the probe 326definition; see the 327.Sx EXAMPLES 328section. 329.Pp 330One of the goals of the original 331.Nm 332implementation (and by extension, of FreeBSD's port) is that inactive 333.Nm 334probes should have no performance impact. 335This is unfortunately not the case; 336.Nm 337trace points will add a small but non-zero amount of latency to the code 338in which they are defined. 339A more sophisticated implementation of the probes will help alleviate this 340problem. | 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. |