man1/na_stats(1) manual page

stats - command for collecting and viewing statistical information

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 ]

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

-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.

print_header indicates whether or not to print column headers. Default: on.

print_units indicates whether or not to print counter units. Default: on.

catenate_instances indicates whether or not each instance should be printed on a separate line or not when performing column output. Default: off

-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.

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 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.

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 defintions are merged into a single set of statistics to display.

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.

      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
      ...

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 asso-
  ciated  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-dimen-
  sional 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: _NF_NF_

      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

NAME

SYNOPSIS

DESCRIPTION

USAGE

Objects, Instances and Counters

Preset Configurations

EXAMPLES