Getting storage system information using the stats command

About the stats command

The stats command provides access, through the command line or scripts, to a set of predefined data collection tools in Data ONTAP called counters. These counters provide you with information about your storage system, either instantaneously or over a period of time.

About objects, instances, and counters

Stats counters are grouped by what object they provide data for. Stats objects can be physical entities such as system, processor or disk; logical entities such as volume or aggregate; protocols such as iscsi or fcp, or other modules on your storage system. To see a complete list of the stat objects, you can use the stats list objects command.

Each object can have zero or more instances on your storage system, depending on your system configuration. Each instance of an object has its own name. For example, for a system with two processors, the instance names are processor0 and processor1.

Counters have an associated privilege mode; if you are not currently running with sufficient privilege for a particular counter, it is not recognized as a valid counter.

How you use the stats command

When you use the stats command to get information about your storage system, you need to make the following decisions:

What counters do you want to collect information from, on what object instances?
For more information, see About objects, instances, and counters.
Do you want to specify the counters on the command line or do you want to use a predetermined set of counters called a preset file?
Some preset files are provided with Data ONTAP. You can also create your own.

For more information, see About the stats preset files.
How do you want the information to be returned and formatted?
You can control where the information is returned (to the console or to a file) and how it is formatted.

For more information, see Changing the output of a stats command.
How do you want to invoke the stats command?
You can invoke the stats command using the following methods:
- A single invocation
  This method retrieves information from the specified counters once and stops.
  
  For more information, see Using the stats command interactively in singleton mode.
- A periodic invocation
  For this method, information is retrieved from the specified counters repeatedly, at a time interval of your choice. You can specify a number of iterations to be performed, or the stats command can run until you stop it explicitly.
  
  For more information, see Using the stats command interactively in repeat mode.
- As a background process
  This method enables you to initiate a stats command process that runs in the background until you terminate it explicitly, when the average values for the specified counters are returned.
  
  For more information, see Using the stats command in background mode.

Viewing the list of available counters

To display the list of counters for a particular object on the command line, complete the following step.

Step	Action
1	Enter the following command: stats list counters object_name object_name is the name of the object you want to list the available counters for.

Example

cli> stats list counters system

Counters for object name: system

        nfs_ops

        cifs_ops

        http_ops

        dafs_ops

        fcp_ops

        iscsi_ops

        net_data_recv

        net_data_sent

        disk_data_read

        disk_data_written

        cpu_busy

        avg_processor_busy

        total_processor_busy

        num_processors

Getting more details about a counter

If you are planning to process the information you get from a stats command, you might want to understand how a counter presents its information. Or, you might want to get more details about the information that counter collects. To get more details about a specific counter, complete the following step.

Step	Action
1	Enter the following command: *stats explain counters object_name* [counter_name]** object_name is the name of the object the counter is associated with. counter_name is the name of the counter you want more details about. If counter_name is omitted, information about all counters on the specified object is returned. Result The following fields are returned for every specified counter: Name Description Properties The Properties field describes the type of information that is returned by this counter. Properties include the following types: `percent` for values that are a percentage value, such as `cpu_busy` `rate` for values that describe a value per time, such as `disk_data_read` `average` for values that return an average, such as `write_latency` `raw` for simple values that have no type, such as `num_processors` Unit The Unit field describes how value returned by this counter can be interpreted. The Unit field can be in one of the following groups of values: `percent` for counters with a Properties of `percent` The unit per time period for counters with a Properties of `rate`, such as `kb_per_sec` or `per_sec`. The time unit for counters that return timing values, such as `write_latency`

Step

Action

Enter the following command:

stats explain counters object_name [counter_name]

object_name is the name of the object the counter is associated with.

counter_name is the name of the counter you want more details about. If counter_name is omitted, information about all counters on the specified object is returned.

Result

The following fields are returned for every specified counter:

Name
Description
Properties
The Properties field describes the type of information that is returned by this counter. Properties include the following types:
- percent for values that are a percentage value, such as cpu_busy
- rate for values that describe a value per time, such as disk_data_read
- average for values that return an average, such as write_latency
- raw for simple values that have no type, such as num_processors
Unit
The Unit field describes how value returned by this counter can be interpreted. The Unit field can be in one of the following groups of values:
- percent for counters with a Properties of percent
- The unit per time period for counters with a Properties of rate, such as kb_per_sec or per_sec.
- The time unit for counters that return timing values, such as write_latency

Example

cli> stats explain counters system cpu_busy

Counters for object name: system

Name: cpu_busy

Description: Percentage of time one or more processors is busy in 
the system

Properties: percent

Unit: percent

Using the stats command interactively in singleton mode

When you want to see a set of information about the system's current state at the command line, you can use the stats command in singleton mode. To do so, complete the following step.

Step	Action
1	Enter the following command: *stats show object_def* [object_def...]** object_def is one of the following values: An object name (`object_name`) Example `stats show system` This returns statistics from all counters provided for all instances of the specified object. The name of a specific instance (`object_name:instance_name`) Example stats show processor:processor0 This returns statistics from all counters provided for the specified instance of the specified object. The name of a specific counter (`object_name:instance_name:counter_name`) Example stats show system::net_data_recv Note* To see the statistic for all instances of the object, use an asterisk (``) for the instance name. To specify an instance name that includes spaces, enclose the name in double quotes (`"name with spaces"`). To specify an instance name that contains a colon (:), repeat the colon (`disk:20::00::00::20::37::de::4a::8e`). An asterisk (``) This returns statistics for all instances of all objects.

Step

Action

Enter the following command:

stats show object_def [object_def...]

object_def is one of the following values:

An object name (object_name)

Example

stats show system

This returns statistics from all counters provided for all instances of the specified object.

The name of a specific instance (object_name:instance_name)

Example

stats show processor:processor0

This returns statistics from all counters provided for the specified instance of the specified object.

The name of a specific counter (object_name:instance_name:counter_name)

Example

stats show system:*:net_data_recv

Note
To see the statistic for all instances of the object, use an asterisk (*) for the instance name.

To specify an instance name that includes spaces, enclose the name in double quotes ("name with spaces").

To specify an instance name that contains a colon (:), repeat the colon (disk:20::00::00::20::37::de::4a::8e).

An asterisk (*)
This returns statistics for all instances of all objects.

Example

The following command shows all current statistics for a volume named myvol.

cli> stats show volume:myvol

volume:myvol:total_ops:132/s

volume:myvol:avg_latency:13ms

volume:myvol:read_ops:5/s

volume:myvol:read_data:1923b/s

volume:myvol:read_latency:23ms

volume:myvol:write_ops:186/s

volume:myvol:write_data:1876b/s

volume:myvol:write_latency:6ms

volume:myvol:other_ops:0/s

volume:myvol:other_latency:0ms

Using the stats command interactively in repeat mode

If you want to see a statistic every few seconds, you can invoke the stats command in repeat mode. To do so, complete the following step:

Step	Action
1	Enter the following command: *stats show [-n num] [-i interval] object_def* [object_def...]** num specifies the number of times you want the command to be run. If this parameter is omitted, the command is repeated until you issue a break. interval specified the interval between the iterations of the `stats` command. The default value is one second. object_def is specified as described in Using the stats command interactively in singleton mode.

Step

Action

Enter the following command:

stats show [-n num] [-i interval] object_def 
[object_def...]

num specifies the number of times you want the command to be run. If this parameter is omitted, the command is repeated until you issue a break.

interval specified the interval between the iterations of the stats command. The default value is one second.

object_def is specified as described in Using the stats command interactively in singleton mode.

Example

You could use the following command to display how your processor usage is changing over time:

stats show -i 1 processor:*:processor_busy

Instance processor_busy

processor0            32

processor1             1

processor0            68

processor1            10

processor0            54

processor1            29

processor0            51

...

Using the stats command in background mode

You can collect information from a specified set of counters over time in the background using the stats start and stats stop commands. The information collected is averaged over the period and displayed when the stats stop command is issued. You can initiate multiple stats commands in background mode, giving each of them a name so you can control them individually.

Note
Each instance of a stats command consumes a small amount of system resources. If you start a large number of stats commands in background mode, you could affect overall storage system performance. To avoid this issue, make sure that you stop all background stats commands that you start.

To collect system information over time, complete the following steps:

Step	Action
1	To start collecting the information, enter the following command: *stats start [-I identifier] object_def* [object_def...]** identifier names this instance of the `stats` command so you can refer to it later to show results. If you are running only one background `stats` command, you can omit this parameter. object_def is specified as described in Using the stats command interactively in singleton mode.
2	If you want to display interim results without stopping the background `stats` command, enter the following command: *stats show [-I identifier]* identifier names the instance of the `stats` command you want to display interim results for. If you are running only one background `stats` command, you can omit this parameter.
3	To stop data collection and output the final results, enter the following command: *stats stop [-I identifier]* identifier names the instance of the `stats` command you want to stop and display results for. If you are running only one background `stats` command, you can omit this parameter.

Step

Action

To start collecting the information, enter the following command:

stats start [-I identifier] object_def [object_def...]

identifier names this instance of the stats command so you can refer to it later to show results. If you are running only one background stats command, you can omit this parameter.

object_def is specified as described in Using the stats command interactively in singleton mode.

If you want to display interim results without stopping the background stats command, enter the following command:

stats show [-I identifier]

identifier names the instance of the stats command you want to display interim results for. If you are running only one background stats command, you can omit this parameter.

To stop data collection and output the final results, enter the following command:

stats stop [-I identifier]

identifier names the instance of the stats command you want to stop and display results for. If you are running only one background stats command, you can omit this parameter.

Changing the output of a stats command

Data ONTAP enables you to control the format and destination of the output of the stats command. This could be useful if you are processing the information with another tool or script, or if you want to store the output in a file so you can process it at a later time.

There are three ways you can affect the format and destination of the output of a stats command:

You can send the output to a file rather than the console.
You can determine whether the output appears in columns or rows.
You can specify a delimiter.

Sending stats output to a file

To send stats output to a file, you add -o filename to your stats show or stats stop command line, where filename is the pathname to the file you want to receive the stats output. The file does not need to exist, although any directory in the path must already exist.

Using rows and columns

To determine whether the output is formatted in rows or columns, you add the -r or -c option to your stats show or stats stop command line.

The -r option formats the output in rows, and is the default if the -i option is not specified.

Example output in rows:

cli> stats show qtree:*:nfs_ops

qtree:vol1/proj1:nfs_ops:186/s

qtree:vol3/proj2:nfs_ops:208/s

The -c option formats the output in columns, and is the default only if the -i option is specified.

Example output in columns

cli> stats show -c qtree:*:nfs_ops

Instance nfs_ops

/s

vol1/proj1      143

vol3/proj2      408

Note
The "/s" line shows the unit for the applicable column. In this example, there is one column, and it is number of operations per second.

If you are displaying multiple objects that have different counters, the column format may be difficult to read. In this case, use the row format.

Specifying a delimiter

You might need to specify a delimiter so that your output can be imported into a database or spreadsheet. To add a delimiter, you use the -d delimiter option to your stats show or stats stop command line. The -d option only has effect if your output is in column format.

Example output with specified delimiter

In the following example, the same counter is listed as for the column output example, except that it is comma-delimited.

cli> stats show -d , -c qtree:*:nfs_ops

Instance nfs_ops

/s

vol1/proj1,265

vol3/proj2,12

About the stats preset files

Data ONTAP provides some XML files that output a predetermined set of statistics that you can use without having to construct a script or type in a complicated command on the command line. The preset files are located in the /etc/stats/preset directory.

Using the preset files

To use a preset file, you add -p filename to your stats show or stats stop command line. You can also add counters on the command line. If any options you specify on the command line conflict with the preset file, your command line options take precedence.

You can also create your own preset files.

For more information about preset files, see the na_stats_preset(5) man page.