usr.bin/kcollect/kcollect.8

   1 .\" Copyright (c) 2017 The DragonFly Project.  All rights reserved.
   2 .\"
   3 .\" This code is derived from software contributed to The DragonFly Project
   4 .\" by Matthew Dillon <dillon@backplane.com>
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\"
  10 .\" 1. Redistributions of source code must retain the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer.
  12 .\" 2. Redistributions in binary form must reproduce the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer in
  14 .\"    the documentation and/or other materials provided with the
  15 .\"    distribution.
  16 .\"
  17 .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  18 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  19 .\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
  20 .\" FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE
  21 .\" COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
  22 .\" INCIDENTAL, SPECIAL, EXEMPLARY OR CONSEQUENTIAL DAMAGES (INCLUDING,
  23 .\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  24 .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
  25 .\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
  26 .\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
  27 .\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  28 .\" SUCH DAMAGE.
  29 .\"
  30 .Dd July 29, 2017
  31 .Dt KCOLLECT 8
  32 .Os
  33 .Sh NAME
  34 .Nm kcollect
  35 .Nd extract kernel-collected statistics
  36 .Sh SYNOPSIS
  37 .Nm
  38 .Op Fl o Ar fields
  39 .Op Fl b Ar file
  40 .Op Fl f
  41 .Op Fl l
  42 .Op Fl g
  43 .Op Fl s
  44 .Op Fl t Ar time
  45 .Op Fl G
  46 .Op Fl W Ar width
  47 .Op Fl H Ar height
  48 .Op Fl w Ar plotfile
  49 .Op Fl x Ar gnuplot_options
  50 .Sh DESCRIPTION
  51 The
  52 .Nm
  53 utility extracts regularly collected statistics accumulated by the kernel.
  54 The kernel typically keeps around 23 hours worth of statistics.
  55 If no specific output option is specified, a human-readable text dump
  56 of the accumulated statistics will be output starting with the most recent
  57 collection and then going back in time.
  58 .Pp
  59 The following options are available:
  60 .Bl -tag -width indent
  61 .It Fl o Ar fields
  62 Indicate which fields to extract.  If not specified, all available
  63 fields are extracted.  Unknown fields are ignored.  Note that not
  64 all commands will filter based on the field list.
  65 .Pp
  66 You may specify space or comma-separated fieldnames.  Whitespace is
  67 ignored.  Use the
  68 .Fl l
  69 option to get a list of available fields.
  70 .It Fl b Ar file
  71 Dump the data to a dbm database, creating the database if necessary.
  72 Data is indexed by gmt time, which will be calculated from the ticks.
  73 Duplicate tuples are ignored.  The database will retain data from prior
  74 runs.
  75 .Pp
  76 THIS IS A TODO OPTION, NOT YET IMPLEMENTED.
  77 .Nm
  78 is smart and will not overwrite the record if it exactly matches what
  79 would be written.
  80 .It Fl g
  81 Generate gnuplot output for the data.
  82 .It Fl s
  83 Smooth plot output (only applicable to gnuplot).
  84 This may make it more readable.  Data is smoothed using an exponential
  85 average over 10 samples (~100 seconds).
  86 .It Fl t Ar time
  87 Specify the number of seconds worth of recent data to extract.
  88 The 'm', 'h', and 'd' suffixes can be used to specify the value in minutes,
  89 hours, or days.
  90 .It Fl x
  91 Generate gnuplot output for the data and pipe it to gnuplot for display
  92 to X11.
  93 .It Fl l
  94 List all available fields and the field format
  95 .It Fl f
  96 Dump available output then enter a 60-second sleep/collection loop
  97 to incrementally collect and output more data.
  98 If outputting to gnuplot, the plot will be updated regularly.  However,
  99 please note that this is fairly expensive since the plot data has to
 100 be completely re-sent to gnuplot on each update.
 101 .It Fl w Ar plotfile
 102 Generate gnuplot output to a .png or .jpg file, depending on the extension
 103 of the filename you supply.
 104 .It Fl G
 105 Timestamps for text output will be in GMT instead of localtime.
 106 .It Fl W Ar width
 107 .It Fl H Ar height
 108 Set the width and height of the output plot for the plotfile or for X.
 109 The default is 512x512.
 110 .El
 111 .Sh SEE ALSO
 112 .Xr systat 1
 113 .Sh HISTORY
 114 A
 115 .Nm
 116 utility appeared in
 117 .Dx 4.9 .