filters/stats/nbdkit-stats-filter.pod

   1 =head1 NAME
   2
   3 nbdkit-stats-filter - display statistics about operations
   4
   5 =head1 SYNOPSIS
   6
   7  nbdkit --filter=stats PLUGIN statsfile=FILE
   8                        [statsappend=true] [statsthreshold=PERCENTILE]
   9
  10 =head1 DESCRIPTION
  11
  12 C<nbdkit-stats-filter> is a filter that displays statistics about NBD
  13 operations, such as the number of bytes read and written.  Statistics
  14 are written to a file once when nbdkit exits.
  15
  16 =head1 EXAMPLE OUTPUT
  17
  18  # nbdkit --filter=exitlast --filter=stats memory 25G statsfile=example.txt
  19  # nbd-client localhost /dev/nbd1 && mkfs.ext4 /dev/nbd1 && sync &&
  20    nbd-client -d /dev/nbd1
  21  [....]
  22  # cat example.txt
  23  total: 191 ops, 21.917545 s, 25.13 GiB, 1.15 GiB/s
  24  read: 136 ops, 0.000230 s, 3.16 MiB, 13.43 GiB/s op, 147.83 KiB/s total
  25    Request size and alignment breakdown:
  26      12 bits: 68.4% (93 reqs, 372.00 KiB total)
  27           12 bit aligned: 100.0% (93)
  28           13 bit aligned:  72.0% (67)
  29           14 bit aligned:  55.9% (52)
  30           15 bit aligned:  48.4% (45)
  31           16 bit aligned:  43.0% (40)
  32      14 bits: 10.3% (14 reqs, 296.00 KiB total)
  33           12 bit aligned: 100.0% (14)
  34           13 bit aligned:  35.7% (5)
  35           19 bit aligned:  21.4% (3)
  36  [....]
  37      other sizes:  3.7% (5 reqs, 3.16 MiB total)
  38
  39  write: 36 ops, 0.125460 s, 132.38 MiB, 1.03 GiB/s op, 6.04 MiB/s total
  40    Request size and alignment breakdown:
  41      12 bits: 50.0% (18 reqs, 72.00 KiB total)
  42           12 bit aligned: 100.0% (18)
  43           13 bit aligned:  77.8% (14)
  44           27 bit aligned:  72.2% (13)
  45           31 bit aligned:  66.7% (12)
  46           32 bit aligned:  33.3% (6)
  47           33 bit aligned:  22.2% (4)
  48           34 bit aligned:  11.1% (2)
  49      14 bits: 30.6% (11 reqs, 224.00 KiB total)
  50           12 bit aligned: 100.0% (11)
  51           27 bit aligned:  90.9% (10)
  52      25 bits: 11.1% (4 reqs, 128.00 MiB total)
  53           25 bit aligned: 100.0% (4)
  54           26 bit aligned:  50.0% (2)
  55           27 bit aligned:  25.0% (1)
  56      16 bits:  2.8% (1 reqs, 64.00 KiB total)
  57           16 bit aligned: 100.0% (1)
  58
  59  trim: 14 ops, 0.002687 s, 25.00 GiB, 9304.06 GiB/s op, 1.14 GiB/s total
  60    Request size and alignment breakdown:
  61      31 bits: 85.7% (12 reqs, 24.00 GiB total)
  62           24 bit aligned: 100.0% (12)
  63      24 bits:  7.1% (1 reqs, 16.00 MiB total)
  64
  65  flush: 5 ops, 0.000002 s, 0 bytes, 0 bytes/s op, 0 bytes/s total
  66
  67
  68 =head1 PARAMETERS
  69
  70 =over 4
  71
  72 =item B<statsfile=>FILE
  73
  74 The file where we write the stats.
  75
  76 This parameter is required.
  77
  78 =item B<statsappend=true>
  79
  80 If set then we append to the file instead of replacing it.
  81
  82 =item B<statsthreshold=>PERCENTILE
  83
  84 If non-zero, track request size and alignment distribution and print
  85 histogram.
  86
  87 Requests are grouped by the number of bits that are needed to represent
  88 the request size (e.g. a request of size 3892 needs will be grouped
  89 with all requests of size 2^11=2048 to 2^12-1=4095), and the number of
  90 trailing zero bits in the offset.
  91
  92 Histogram output is truncated to PERCENTILE of requests. Default: 95.
  93
  94 =back
  95
  96 =head1 FILES
  97
  98 =over 4
  99
 100 =item F<$filterdir/nbdkit-stats-filter.so>
 101
 102 The filter.
 103
 104 Use C<nbdkit --dump-config> to find the location of C<$filterdir>.
 105
 106 =back
 107
 108 =head1 VERSION
 109
 110 C<nbdkit-stats-filter> first appeared in nbdkit 1.14.
 111
 112 =head1 SEE ALSO
 113
 114 L<nbdkit(1)>,
 115 L<nbdkit-filter(3)>,
 116 L<nbdkit-log-filter(1)>.
 117
 118 =head1 AUTHORS
 119
 120 Richard W.M. Jones
 121
 122 Nikolaus Rath
 123
 124 =head1 COPYRIGHT
 125
 126 Copyright Red Hat