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 d Ar file
  41 .Op Fl r Ar file
  42 .Op Fl f
  43 .Op Fl l
  44 .Op Fl g
  45 .Op Fl s
  46 .Op Fl t Ar time
  47 .Op Fl G
  48 .Op Fl W Ar width
  49 .Op Fl H Ar height
  50 .Op Fl w Ar plotfile
  51 .Op Fl x Ar gnuplot_options
  52 .Sh DESCRIPTION
  53 The
  54 .Nm
  55 utility extracts regularly collected statistics accumulated by the kernel.
  56 The kernel typically keeps around 23 hours worth of statistics.
  57 If no specific output option is specified, a human-readable text dump
  58 of the accumulated statistics will be output starting with the most recent
  59 collection and then going back in time.
  60 .Pp
  61 The following options are available:
  62 .Bl -tag -width indent
  63 .It Fl o Ar fields
  64 Indicate which fields to extract.  If not specified, all available
  65 fields are extracted.  Unknown fields are ignored.  Note that not
  66 all commands will filter based on the field list.
  67 .Pp
  68 You may specify space or comma-separated fieldnames.  Whitespace is
  69 ignored.  Use the
  70 .Fl l
  71 option to get a list of available fields.
  72 .It Fl b Ar file
  73 Dump the data to a dbm database, creating the database if necessary.
  74 Data is indexed by gmt time, which will be calculated from the ticks.
  75 Duplicate tuples are ignored.  The database will retain data from prior
  76 runs.
  77 .It Fl d Ar file
  78 Load the data from a dbm database instead of loading the active data
  79 from the current machine.
  80 .It Fl r Ar file
  81 This will overwrite headers stored in the specified dbm database with the
  82 in-memory headers.  This can be used to renormalize saved historical dbm
  83 files when machine specs change, or if the dbm is somehow missing the
  84 header fields.
  85 .It Fl g
  86 Generate gnuplot output for the data.
  87 .It Fl s
  88 Smooth plot output (only applicable to gnuplot).
  89 This may make it more readable.  Data is smoothed using an exponential
  90 average over 10 samples (~100 seconds).
  91 .It Fl t Ar time
  92 Specify the number of seconds worth of recent data to extract.
  93 The 'm', 'h', and 'd' suffixes can be used to specify the value in minutes,
  94 hours, or days.
  95 .It Fl x
  96 Generate gnuplot output for the data and pipe it to gnuplot for display
  97 to X11.
  98 .It Fl l
  99 List all available fields and the field format
 100 .It Fl f
 101 Dump available output then enter a 60-second sleep/collection loop
 102 to incrementally collect and output more data.
 103 If outputting to gnuplot, the plot will be updated regularly.  However,
 104 please note that this is fairly expensive since the plot data has to
 105 be completely re-sent to gnuplot on each update.
 106 .It Fl w Ar plotfile
 107 Generate gnuplot output to a .png or .jpg file, depending on the extension
 108 of the filename you supply.
 109 .It Fl G
 110 Timestamps for text output will be in GMT instead of localtime.
 111 .It Fl W Ar width
 112 .It Fl H Ar height
 113 Set the width and height of the output plot for the plotfile or for X.
 114 The default is 512x512.
 115 .El
 116 .Sh SEE ALSO
 117 .Xr systat 1
 118 .Sh HISTORY
 119 A
 120 .Nm
 121 utility appeared in
 122 .Dx 4.9 .