Manual Pages
Table of Contents
stats - command for collecting and viewing statistical
information
stats commands arguments ...
The stats family of commands reports various statistics
collected by the system.
The stats command may be run in one of three ways:
a. Singleton, in which current counter values are displayed
as a snapshot. (stats show)
b. Repeating, in which counter values are displayed
multiple times at a fixed interval. (stats show
-i)
c. Period, in which counters are gathered over a single
period of time and then displayed (stats
start/stats stop). Intermediate results may also be
shown, by using stats show.
stats list objects [-p preset]
Displays the names of objects active in the system
for which data is available . If -p is specified
the objects used by the preset preset will be
listed.
stats list instances [-p preset] | [ object_name ]
Display the list of active instance names for a
given object, or if -p is specified the instances
used by the preset preset. If neither -p nor
object_name is specified then all instances for all
objects are listed.
stats list counters [-p preset] | [ object_name ]
Display the list of all counters associated with an
object, or if -p is specified the counters used by
the preset preset. If neither -p nor object_name
is specified then all counters for all objects are
listed.
stats list presets
Display the list of defined presets in the system.
stats explain counters [ object_name [ counter_name ] ]
Displays an explanation for specific counter(s) in
the specified object, or all counters in all
objects if no object_name or counter_name are
given.
stats show [ -n num ] [ -i interval ] [ -o path ] [ -d
delimiter ] [ -p preset ] -O option=value{,option=value} ]
[ -r | -c ] [ -e ] [ -I identifier | object_def [
object_def ...] ]
Shows all or selected statistics in various formats.
If neither -i nor -I options are used a single
1-second snapshot of statistics will be used.
If -i (interval) is used then statistics will be
output repeatedly at the specified interval. If -I
(identifier) is used, where the identifier is a
valid name used with stats start, then the statistics
since the stats start will be displayed.
-
-p preset Use the preset configuration
-
preset for
default format and object selection. See the section
on Preset Configurations below for more information.
-
-r|-c
- If the -r option is used then the output will be in
rows (with one data element per row). If -c is used
then the output will in columns, with one data element
per column. -r and -c are mutually exclusive.
If -i is used then the default is -c, otherwise the
default is -r.
-
-i interval
-
Specifies that output should be produced periodically,
with an interval of interval seconds between
each set of output. interval is a positive, nonzero
value.
-
-n num
-
Terminate the output after num number of iterations
when -i is used. The num is a positive, non-zero
integer. If no num value is specified the output
will run forever till a user issues a break.
-
-o pathname
-
Send output to pathname on the appliance instead of
the default output for the command.
-
-d delimiter
-
Change the column delimiter from the default TAB
character to the specified ielimiter.
-
-e
- Allow extended regular expressions (regex) for
instance and counter names. When -e is used the
instance and counter names are independently interpreted
as regular expression The character `*' is
still a wild-card representing all instances and/or
counter names. The regular expression is not
anchored, if necessary use ^ to indicate the start
of an instance or counter name, and $ to indicate
the end of an instance or counter name.
-
-O option=value[,...]
-
Set stats options. The value for each option may be
"on" or "off". See na_stats_preset for a list of
options that may be set, including print_header,
whether or not to print column headers, and
print_units, whether or not to print counter units.
-
-I identifier
-
If multiple stats requests are being run, using
stats start, then each may be identified by a
unique name. This may also be used with stats show
to display incremental results (from the initial
stats start statistics snapshot until the stats
show.) The identifier is a printable text string
from one to 32 characters in length.
stats start [-p preset] [-I identifier] [object_def [
object_def ...]]
Indicates that statistics collection should begin at the
current point in time. This subcommand must be used
before the stats stop subcommand. The choice of
objects/instance/counters to be monitored is specified
with the start subcommand, not with the stop subcommand.
If identifier is already in use then that identifier will
be reused (the old statistics associated with the identifier
is discarded). See the description for stats show
for information on the -p and -I options.
stats stop [-p preset] [-I identifier] [-r] [-c] [-o path_name]
[-d delimiter] [-O option=value[,...]] [-a]
Causes statistics collection to end at this point in time,
and output is displayed on the appliance console or redirected
to the file specified.
If multiple stats start commands are concurrently running,
with different identifiers, then -I identifier should be
used to indicate which command should be stopped. If no
identifier is given then the most recent stats start command
will be used.
If the -a (all) option is used then all background
requests will be stopped and the output discarded.
See the description for stats show for a description of
other options.
The statistics data can be displayed in various levels of
granularity: all statistics data available (using the *
key as a wildcard to represent all objects), statistics
data for a single object in the system, statistics data
for a single instance of an object, statistics data for a
single counter in an instance of an object and finally
data for a single counter across all the instances of an
object (using * as a wildcard to represent various
instances). Statistics are grouped into several object
classes, which may be regarded as a logical grouping of
counters. Each object has one or more instances, each
with a distinct name.
An object definition (object_def) is one of the following:
A single "*" means all counters in all instances of
all objects.
object_name A given object_name includes all counters
in all instances of a specific object.
object_name:instance_name A given instance_name of
a given object_name includes all counters in the
specific instance of the object.
object_name:instance_name:counter_name: A given
counter_name of a given object_name specific
instance. Use the instance_name "*" to mean counters
in all instances of the given object.
Note that instance names may contain spaces, in which case
the object definition string should be quoted. If an
instance name contains the separator character ":" then it
must be dereferenced by using it twice, for example an
instance name "my:name" should be given as "my::name"
If an instance and/or counter is specified more than once,
for example on the command line and in a preset, then only
the first occurance will be displayed in output.
The stats command supports preset configurations that contain
commonly used combinations of statistics and formats.
The preset to be used is specified with the -p command
line argument, for example:
stats show -p my_preset_file
Each preset is stored in a file in the /etc/stats/preset
appliance directory.
If command line arguments are given in addition to a preset,
then the command line argument takes precedence over
the preset value. Object definitions may be given both on
the command line and in a preset file. In this case the
two sets of definitions are merged into a single set of
statistics to display.
The presets currently known to the system can be displayed
using stats list presets.
See na_stats_preset(5) for a description of the preset
file format.
To produce a sysstat like output of cpu_busy once every
second, for 10 iterations. This uses the default column
output when -i is specified. filer*> stats show -i 1 -n 10 system:system:cpu_busy
Instance cpu_busy
%
system 23%
system 22%
system 22%
...
Gather all system statistics over a 60 second interval.
The command does not return a filer prompt until the output
is written to the stats.out file.
filer*> stats show -i 60 -n 1 -o /measure/stats.out system
List all available counters for the processor object.
filer*> stats list counters processor
Counters for object name: processor
processor_busy
Explain the user_writes counter in the disk object.
filer*> stats explain counters disk user_writes
Counters for object name: disk
Name: user_writes
Description: Number of disk write operations initiated each second for storing data associated with user requests
Properties: rate
Unit: per_sec
Start system statistics gathering in the background, using
identifier "MyStats", display the values while gathering
continues, then stop gathering and display final values:
filer*> stats start -I MyStats system
filer*>
filer*> stats show -I MyStats
system:system:nfs_ops:2788
system:system:cifs_ops:1390
system:system:http_ops:0
...
filer*>
filer*> stats stop -I MyStats
system:system:nfs_ops:3001
system:system:cifs_ops:5617
system:system:http_ops:0
...
Use a regular expression to extract all counters containing
_ops or disk from the system object:
stats show -e system:*:(_ops|disk)
Use a regular expression to show counters for all volumes
with a through m as the second part of the instance name:
stats show -e volume:^.[a-m]:
Print system counters, suppressing those with a calculated
value of zero:
stats show -O print_zero_values=false system
/etc/stats/preset
Location of preset description files.
na_stats_preset (5)
Individual counters may be zero, one or two dimensional.
That is, a single value, a vector or an array may be associated
with a counter. (The dimensions of a specific
counter may be viewed using the stats explain counters
subcommand.) Display of counters that are 1- or 2-dimensional
is peformed as a list or grid, which is better
viewed using row format.
When using column format (-c) or the default interval (-i)
format, each line of output is a single instance, with the
column data being formed from the data in multiple
instances and/or iterations. It is assumed that all
instances have the same counters selected for display. If
this is not true, for example multiple objects are
selected, or specific instances of the same object are
chosen with different counters, then the output will be
formatted using multiple lines, potentially with different
counter types in the same column position.
In this case it may be appropriate to either specify row
format (-r), or catentate all instances/objects together
into a single line, for example:
filer*> stats show -i 1 -r
ifnet:e0:recv_packects ifnet:e4:send_packets
ifnet:e1:recv_packets:1000/s
ifnet:e4:send_packets:7799/s
ifnet:e1:recv_packets:2040/s
ifnet:e4:send_packets:1799/s
ifnet:e1:recv_packets:2340/s
ifnet:e4:send_packets:799/s
or:
filer*> stats show -i 1 -O catenate_instances=on
ifnet:e0:recv_packects ifnet:e4:send_packets
Instance recv_packets Instance send_packets
/s /s
e0 1000 e4 7799
e0 2040 e4 1799
e0 2340 e4 799
Table of Contents