usr.bin/kcollect/kcollect.8

.\" Copyright (c) 2017 The DragonFly Project.  All rights reserved.
.\"
.\" This code is derived from software contributed to The DragonFly Project
.\" by Matthew Dillon <dillon@backplane.com>
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\"
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in
.\"    the documentation and/or other materials provided with the
.\"    distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
.\" FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE
.\" COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
.\" INCIDENTAL, SPECIAL, EXEMPLARY OR CONSEQUENTIAL DAMAGES (INCLUDING,
.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
.\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.Dd July 23, 2019
.Dt KCOLLECT 8
.Os
.Sh NAME
.Nm kcollect
.Nd extract kernel-collected statistics
.Sh SYNOPSIS
.Nm
.Op Fl o Ar fields
.Op Fl O Ar format
.Op Fl b Ar file
.Op Fl d Ar file
.Op Fl r Ar file
.Op Fl f
.Op Fl F
.Op Fl l
.Op Fl g
.Op Fl s
.Op Fl t Ar time
.Op Fl G
.Op Fl W Ar width
.Op Fl H Ar height
.Op Fl w Ar plotfile
.Op Fl x Ar gnuplot_options
.Sh DESCRIPTION
The
.Nm
utility extracts regularly collected statistics accumulated by the kernel.
The kernel typically keeps around 23 hours worth of statistics.
If no specific output option is specified, a human-readable text dump
of the accumulated statistics will be output starting with the most recent
collection and then going back in time.
.Pp
The following options are available:
.Bl -tag -width indent
.It Fl o Ar fields
Indicate which fields to extract.
If not specified, all available fields are extracted.
Unknown fields are ignored.
Note that not all commands will filter based on the field list.
.Pp
You may specify space or comma-separated fieldnames.
Whitespace is ignored.
Use the
.Fl l
option to get a list of available fields.
.It Fl O Ar format
Specify the desired output format.
The following output formats are available:
.Bl -tag -width indent
.It text
This is the default.
It produces a human readable text output.
.It influxdb
EXPERIMENTAL.
It tries to dump the entries in a InfluxDB line protocol compatible format.
.El
.It Fl b Ar file
Dump the data to a dbm database, creating the database if necessary.
Data is indexed by gmt time, which will be calculated from the ticks.
Duplicate tuples are ignored.
The database will retain data from prior runs.
.It Fl d Ar file
Load the data from a dbm database instead of loading the active data
from the current machine.
.It Fl r Ar file
This will overwrite headers stored in the specified dbm database with the
in-memory headers.
This can be used to renormalize saved historical dbm files when machine specs
change, or if the dbm is somehow missing the header fields.
.It Fl g
Generate gnuplot output for the data.
.It Fl s
Smooth plot output (only applicable to gnuplot).
This may make it more readable.
Data is smoothed using an exponential average over 10 samples (~100 seconds).
.It Fl t Ar time
Specify the number of seconds worth of recent data to extract.
The 'm', 'h', and 'd' suffixes can be used to specify the value in minutes,
hours, or days.
.It Fl x
Generate gnuplot output for the data and pipe it to gnuplot for display
to X11.
.It Fl l
List all available fields and the field format
.It Fl f
Dump available output then enter a 60-second sleep/collection loop
to incrementally collect and output more data.
If outputting to gnuplot, the plot will be updated regularly.
However, please note that this is fairly expensive since the plot data has to
be completely re-sent to gnuplot on each update.
.It Fl F
Same as
.Fl f
but do not display the whole buffer at the beginning.
.It Fl w Ar plotfile
Generate gnuplot output to a .png or .jpg file, depending on the extension
of the filename you supply.
.It Fl G
Timestamps for text output will be in GMT instead of localtime.
.It Fl W Ar width
.It Fl H Ar height
Set the width and height of the output plot for the plotfile or for X.
The default is 512x512.
.El
.Pp
The standard
.Nm
display shows the following statistics:
.Pp
.Bl -tag -width syscalls -compact
.It load
system load average
.It user
% of total cpu time in user mode
.It syst
% of total cpu time in system mode
.It idle
% of total cpu time in idle mode
.It swapuse
% of total swap space used
.It swapano
total amount of anonymous swap used in MB
.It swapcac
total amount of swapcache in MB
.It fault
total amount of vm faults including both zero-fill and cow faults
.It cow
total amount of copy-on-write faults
.It zfill
total amount of zero-fill faults
.It free
amount of free memory in bytes
.It cache
amount of almost free memory in bytes
.It inact
amount of inactive memory in bytes
.It act
amount of active memory in bytes
.It wired
amount of wired/kernel memory in bytes
.It syscalls
total amount of system calls
.It nlookup
total amount of path lookups
.It intr
total amount of nominal external interrupts
.It ipi
total amount of inter-cpu interrupts
.It timer
total amount of timer interrupts
.El
.Pp
The output fields in bytes are typically converted with
.Xr humanize_number 3
before displaying, at least for the default output format.
.Sh SEE ALSO
.Xr systat 1
.Sh HISTORY
A
.Nm
utility appeared in
.Dx 4.9 .