chpstat - Display channel-path statistics

Edit online

Use chpstat to view channel-path statistics such as utilization and throughput, and to query and control the status of the channel-path statistics function.

Channel-path statistics are only available on Linux® instances that run in an LPAR or DPM partition.

The channel-path measurement firmware facility updates statistics data at model-dependent intervals that typically range between 2 and 4 seconds. Use values larger than this update interval for the --interval option.

Authorization

To access channel-path statistics, a special authorization setting must be enabled for the partition where the Linux instance runs.

Classic mode LPAR
  1. Logon on to the Hardware Management Console (HMC).
  2. Select the target LPAR.
  3. Start the Customize Activation Profiles HMC task.
  4. Enable the Security/Global performance data control setting.
  5. Deactivate and then activate the LPAR for the change to become effective.
DPM partition
  1. Logon on to the HMC.
  2. Select the target partition.
  3. Start the Partition Details HMC task.
  4. Enable Controls/Access global performance data setting.
  5. Click Apply. The change takes effect immediately.

Enabling and disabling channel-path statistics

Channel-path statistics are disabled after booting Linux, and must be enabled. Use the chpstat to enable and disable channel-path statistics

  1. Optional. Check the status of channel-path statistics by using the chpstat --status command:
    # chpstat --status
Channel-path statistics are disabled
    Alternatively, you can read the cm_enable sysfs attribute to check the status:
    # cat /sys/devices/css0/cm_enable
0
  2. To enable channel-path statistics, issue:
    # chpstat --enable
Enabling channel-path statistics
    Alternatively, you can write to the cm_enable sysfs attribute to enable channel-path statistics:
    # echo 1 > /sys/devices/css0/cm_enable
Correspondingly, you can disable channel-path statistics using the chpstat command:
# chpstat --disable
Disabling channel-path statistics
or by writing 0 to the cm_enable sysfs attribute.

Syntax

Figure 1. chpstat syntax

1  chpstat + <CHPID>
1 -s
1 -e
1 -d
1 -l
1 -L
2? -n<NUM>

2? -i<NUM>

2? --scale<UNIT>

2? --cmg+ ,<CMG>

2? -a
2? -c+ ,<COL>

2? -k+ , <KEY>
2? --format<FORMAT>
2? --chars
2? --metrics
2? --util
2? --no-ansi
2? --no-prefix
where the actions are:
-s or --status
shows channel-path statistics status. Possible status values are:
  • enabled: The statistics facility is active.
  • disabled: The statistics facility is inactive.
  • unsupported: The statistics facility is not supported.
Channel-path statistics are only available when running in an LPAR or DPM partition.
-e or --enable
enables channel-path statistics. After booting Linux, the channel-path statistics facility starts disabled. Use the --enable option to enable it.
-d or --disable
disables channel-path statistics.
-l or --list-columns
lists available table columns. Use this option to obtain a list of available table column names and associated short descriptions. A comma-separated list of column names can be used with the --columns option to select the columns to display in table output format.
-L or --list-keys
lists available data keys. Use this option to obtain a list of available keys that can be used with the --keys option to select data pairs to display in machine-readable output format.
-h or --help
prints usage information then exits.
-v or --version
prints version information then exits.
and options are:
(no options)
displays data in table format for all channel-paths repeatedly with a 5-second delay.
-n or --iterations <NUM>
displays <NUM> reports before ending. By default, chpstat shows output repeatedly until interrupted. Use the --iterations option to specify how many times the output is updated before exiting. A value of 0 indicates an unlimited number of iterations.
-i or --interval <NUM>
pauses <NUM> seconds between displays.
Use this option to specify the number of seconds to wait between output updates. Valid values are in the range 1 to 2140.
Note: Use interval values of at least the model-dependent statistics update interval.
-c or --columns <COL>
selects table columns to show in table output format. To list available columns, use the --list-columns option. If a channel-path does not provide data for a selected column, the corresponding table field is set to "-". Specify multiple columns as a comma-separated list.
-k or --keys <KEY>,...
selects keys to show in machine-readable output format. Use this option to select the data to show in machine-readable output format. To get a list of available keys, use the --list-keys option. If a channel-path does not provide data for a selected key, the corresponding value is set to "".
-a or --all
shows all table columns and key data. Use this option to select all supported columns and keys for output.
--scale <UNIT>
scales bytes-per-seconds (B/s) values by <UNIT>. Use this option to specify a value by which B/s values - such as read and write throughput - are scaled in table output format. Accepted values are:
  • auto: Scale automatically to fit the value into each column. This value is the default.
  • number: Scale by number
  • K: Scale by 1024 (KiB)
  • M: Scale by 1,048,576 (MiB)
  • G: Scale by 1,073,741,824 (GiB)
  • T: Scale by 1,099,511,627,776 (TiB)
--cmg <CMG>
shows data for specified channel measurement groups (CMGs) only. Use this option to limit output to CHPIDs with the specified CMGs. This option also selects table columns suitable for the specified CMGs. Specify multiple CMGs as a comma-separated list.
--format <FORMAT>
shows data in the specified format.

Use this option to show output in a machine-readable format. The format (<FORMAT>) can be one of:

  • json: Single JavaScript™ Object Notation (JSON) data structure. Data for all iterations is formatted as one JSON data structure consisting of multiple lines to make it more readable by humans. See the man page for details.
  • json-seq: Sequence of JSON data structures. Data for each iteration is formatted as a separate JSON data structure. The structure is prefixed with an ASCII record-separator character (0x1e) and suffixed with an ASCII line-feed character (0x0a) in accordance with RFC7464. See the man page for details.
  • pairs: Textual key=value pairs. By default, keys have a prefix that makes them unique across one tool invocation. To remove this prefix, specify the --no-prefix option.
  • csv: Comma-separated value (CSV) list. All values are quoted with double quotation marks and separated by commas. The first line of output contains a list of headings. Subsequent lines each represent data for one CHPID in one iteration.
--chars
lists channel-path measurement characteristics. Use this option to display static data that describes the base characteristics of a channel path. This option implies a machine-readable format.
--util
lists unprocessed utilization data. Use this option to display raw channel-path utilization data that the firmware updates regularly at model-dependent intervals that typically last a few seconds. This option implies a machine-readable output format.
--metrics
lists performance metrics. Use this option to display performance statistics data that is derived from utilization and characteristics data. This option implies a machine-readable output format.
Note: Metrics data is calculated as averages over all utilization update intervals that fall within the selected chpstat update interval.
--no-ansi
does not use ANSI terminal codes in output. When specified, this option suppresses the use of ANSI terminal control characters in table output format. Such characters are used to clear the screen, and to invert the colors for table heading display. Use this option when an output terminal does not support these control characters.
--no-prefix
hides key prefix in the pairs output format. By default, keys that are shown in the pairs machine-readable output format have a prefix that makes them unique across a tool invocation. Use the --noprefix option to remove this prefix.
Example pairs output for the chpid key with prefix: 
chpstat[0].channel_paths[0].chpid="0.1d"
Without prefix: 
chpid="0.1d"

Examples

  • To display channel-path statistics repeatedly with a 5-second delay:
    # chpstat
Collecting initial utilization data
Iteration: 0 Date: <YYYY-MM-DD> Time: <HH:MM:SS> Host: localhost
    CHANNEL-PATH       UTILIZATION(%) DPU   READ(B/s)  WRITE(B/s)
ID TYP CMG SHR SPEED  PART TOTAL  BUS  ID  PART TOTAL  PART TOTAL
1d  25   2   1     -  0.00  0.01 0.00   -  0.00  0.00  0.00 6.08M
21  1b   2   1   32G  0.00  0.00 0.00   -  0.00  0.00  0.00  0.00
22  1b   5   1   32G  0.00  3.27 1.72   0  0.00 53.3M  0.00 46.8M
50  25   4   1     -  0.00  2.50 1.20   0  0.00 3.47M  0.00 8.22M
34  1b   2   1   32G  0.00  0.00 0.00   -  0.00  0.00  0.00  0.00
61  25   2   1     -  0.00  0.01 0.00   -  0.00  0.00  0.00 6.64M
62  25   2   1     -  0.00  0.01 0.00   -  0.00  0.00  0.00  644K
63  25   2   1     -  0.00  0.01 0.00   -  0.00  0.00  0.00  359K
  • To display detailed statistics of FICON/HPF channel-paths that make use of the Data Processing Unit (DPU) feature that was introduced with IBM® z17 ™:
    # chpstat --cmg 5
Collecting initial utilization data
Iteration: 0 Date: <YYYY-MM-DD> Time: <HH:MM:SS> Host: localhost

    CHANNEL-PATH       UTILIZATION(%)  DPU UTILIZATION(%)   READ(B/s)  WRITE(B/s)     FICON-OPS         HPF-OPS    
ID TYP CMG SHR SPEED  PART TOTAL DATA  ID PART TOTAL FULL  PART TOTAL  PART TOTAL  RATE ACTV DEFER  RATE ACTV DEFER
22  1b   5   1   32G  0.00  3.60 1.26   0 0.00  1.09 8.33  0.00 38.3M  0.00 31.0M 115.1 1.00  0.00 9.82K 1.03  0.00
23  1b   5   1   32G  0.00  4.17 1.24   0 0.00  1.11 8.29  0.00 37.7M  0.00 25.0M 223.0 1.00  0.00 9.65K 1.00  0.00
    For more information about the DPU feature, see https://www.redbooks.ibm.com/abstracts/sg245444.html.
  • To display detailed statistics of FCP channel-paths that make use of the IBM z17 DPU feature:
    # chpstat --cmg 4
Collecting initial utilization data
Iteration: 0 Date: <YYYY-MM-DD> Time: <HH:MM:SS> Host: localhost

    CHANNEL-PATH       UTILIZATION(%)  DPU UTILIZATION(%)   READ(B/s)  WRITE(B/s)
ID TYP CMG SHR SPEED  PART TOTAL DATA  ID PART TOTAL FULL  PART TOTAL  PART TOTAL
50  25   4   1     -  0.00  2.51 1.13   0 0.00  0.80 0.00  0.00 26.1M  0.00 36.0M
51  25   4   1     -  0.00  1.81 1.17   0 0.00  0.86 0.00  0.00 24.8M  0.00 37.6M
  • To limit display to CHPID 0.1d:
    # chpstat 0.1d
Collecting initial utilization data
Iteration: 0 Date:  <YYYY-MM-DD> Time: <HH:MM:SS> Host: localhost

    CHANNEL-PATH     UTILIZATION(%)   READ(B/s)  WRITE(B/s)
ID TYP CMG SHR SPEED PART TOTAL  BUS PART TOTAL  PART TOTAL
1d  25   2   1     - 0.00  0.01 0.00 0.00 34.0K 16.0K 4.55M
  • To customize the list of data columns to display, use the --columns option:
    # chpstat --columns chpid,read_total,write_total
Collecting initial utilization data
Iteration: 0 Date: <YYYY-MM-DD> Time: <HH:MM:SS> Host: localhost

    READ   WRITE
ID  TOTAL  TOTAL
1d 511.98 41.50K
21   0.00   0.00
34   0.00   0.00
61  1.50K 31.50K
62 1024.0  1.32M
63   0.00 789.0K
bd 162.26  11.00
    Use the --list-columns option to get a list of supported output columns and their descriptions.
  • To display current channel-path statistics status in JSON format:
    # chpstat --status --format json
  • To determine the model-dependent update interval for CHPID 0.f0: 
    # chpstat --keys interval -n 1 --no-prefix 0.f0 --format pairs
  • To collect partition-write-throughput statistics for one hour in CSV format:
    # chpstat -n 60 -i 60 --format csv --key time,chpid,write_part