share/man/man4/dtrace_io.4

   1 .\" Copyright (c) 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 .\" $FreeBSD$
  26 .\"
  27 .Dd April 18, 2015
  28 .Dt DTRACE_IO 4
  29 .Os
  30 .Sh NAME
  31 .Nm dtrace_io
  32 .Nd a DTrace provider for tracing events related to disk I/O
  33 .Sh SYNOPSIS
  34 .Fn io:::start "struct bio *" "struct devstat *"
  35 .Fn io:::done "struct bio *" "struct devstat *"
  36 .Sh DESCRIPTION
  37 The
  38 .Nm io
  39 provider allows the tracing of disk I/O events.
  40 The
  41 .Fn io:::start
  42 probe fires when a I/O request is about to be sent to the backing driver of a
  43 .Xr disk 9
  44 object.
  45 This occurs after all
  46 .Xr GEOM 4
  47 transformations have been performed on the request.
  48 The
  49 .Fn io:::done
  50 probe fires when a I/O request is completed.
  51 Both probes take a
  52 .Vt "struct bio *"
  53 representing the I/O request as their first argument.
  54 The second argument is a
  55 .Vt "struct devstat *"
  56 for the underlying
  57 .Xr disk 9
  58 object.
  59 .Sh ARGUMENTS
  60 The fields of
  61 .Vt "struct bio"
  62 are described in the
  63 .Xr g_bio 9
  64 manual page, and the fields of
  65 .Vt "struct devstat"
  66 are described in the
  67 .Xr devstat 9
  68 manual page.
  69 Translators for the
  70 .Vt bufinfo_t
  71 and
  72 .Vt devinfo_t
  73 D types are defined in
  74 .Pa /usr/lib/dtrace/io.d .
  75 .Sh FILES
  76 .Bl -tag -width "/usr/lib/dtrace/io.d" -compact
  77 .It Pa /usr/lib/dtrace/io.d
  78 DTrace type and translator definitions for the
  79 .Nm io
  80 provider.
  81 .El
  82 .Sh EXAMPLES
  83 The following script shows a per-process breakdown of total I/O by disk device:
  84 .Bd -literal -offset indent
  85 #pragma D option quiet
  86
  87 io:::start
  88 {
  89         @[args[1]->device_name, execname, pid] = sum(args[0]->bio_bcount);
  90 }
  91
  92 END
  93 {
  94         printf("%10s %20s %10s %15s\\n", "DEVICE", "APP", "PID", "BYTES");
  95         printa("%10s %20s %10d %15@d\\n", @);
  96 }
  97 .Ed
  98 .Sh COMPATIBILITY
  99 This provider is not compatible with the
 100 .Nm io
 101 provider found in Solaris, as its probes use native
 102 .Fx
 103 argument types.
 104 .Sh SEE ALSO
 105 .Xr dtrace 1 ,
 106 .Xr devstat 9 ,
 107 .Xr SDT 9
 108 .Sh HISTORY
 109 The
 110 .Nm io
 111 provider first appeared in
 112 .Fx
 113 9.2 and 10.0.
 114 .Sh AUTHORS
 115 This manual page was written by
 116 .An Mark Johnston Aq Mt markj@FreeBSD.org .
 117 .Sh BUGS
 118 The
 119 .Fn io:::wait-start
 120 and
 121 .Fn io:::wait-done
 122 probes are not currently implemented on
 123 .Fx .