Manual Pages


Table of Contents

NAME

stats - Command for collecting and viewing statistical information

SYNOPSIS

stats commands arguments ...

DESCRIPTION

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.

USAGE

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 ]

Displays 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 ]

Displays 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

Displays 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, non-zero 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 delimiter.

-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 expressions. 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 pathname] [-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.

Objects, Instances and Counters

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 in a given instance_name of a given object_name. 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 occurrence will be displayed in output.

Preset Configurations

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.

EXAMPLES

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.
      FAS*> 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 node prompt until the output is written to the stats.out file.

      FAS*> stats show -i 60 -n 1 -o /measure/stats.out system

List all available counters for the processor object.

      FAS*> stats list counters processor
      Counters for object name: processor
           processor_busy

Explain the user_writes counter in the disk object.

      FAS*> 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:

      FAS*> stats start -I MyStats system
      FAS*>
      FAS*> stats show -I MyStats
      system:system:nfs_ops:2788
      system:system:cifs_ops:1390
      system:system:http_ops:0
      ...
      FAS*>
      FAS*> 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

FILES

/etc/stats/preset

Location of preset description files.

SEE ALSO

na_stats_preset (5)

LIMITATIONS

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 performed 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 catenate all instances/objects together into a single line, for example:

      FAS*> 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:
      FAS*> 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