chpstat(8)

NAME
chpstat - Display channel-path statistics

SYNOPSIS
chpstat [OPTIONS] [ACTIONS] [CHPIDS]

DESCRIPTION
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.
When run without further options, data for all channel-paths is displayed repeatedly with a 5 second delay in table format. You can limit output to specific channel-paths by listing the associated CHPIDs on the command line.
Note: Channel-path statistics are only available on systems running in an LPAR or DPM partition.

  Output options
Without options, chpstat displays performance statistics data in table format. Use options --columns, --all and --cmg to change the list of columns to display.
You can use option --format to select a machine-readable list output format (JSON, key-value pairs, or comma-separated values), and option --keys to restrict output to only a specific set of data keys.
Additional options can be used to display the raw source data used for calculating channel-path statistics:

•   Characteristics: Static data describing base characteristics of a channel-path.
    Use option --chars to view characteristics data.

•   Utilization: Raw data about a channel-paths current utilization. This data is updated regularly at model-dependent intervals that typically last a few seconds (see key "interval"). Use option --util to view raw utilization data.

•   Metrics: Performance statistics derived from utilization and characteristics data.
    Note: Metrics data is calculated as averages over all utilization update intervals that fall within the selected chpstat update interval.
    Use option --metrics to view metrics data.

  Authorization
A special authorization setting needs to be enabled for a system to be able to access channel-path statistics data. Classic mode LPAR

1.  Logon on to the Hardware Management Console (HMC)

2.  Select the target LPAR

3.  Start "Customize Activation Profiles" HMC Task

4.  Enable "Security/Global performance data control" setting

Note: The LPAR needs to be deactivated/re-activated for the change to become effective. DPM Partition

1.  Logon on to the Hardware Management Console (HMC)

2.  Select the target partition

3.  Start "Partition Details" HMC Task

4.  Enable "Controls/Access global performance data" setting

5.  Press "Apply" - the change will be active immediately

  Channel-Measurement Groups
A Channel-Measurement Group (CMG) is a number associated with each channel-path that determines the type of available statistics data for that channel-path.

ACTIONS
-s, --status
    Show channel-path statistics status Possible status values are:

    •   enabled: Statistics facility is active

    •   disabled: Statistics facility is inactive

    •   unsupported: Statistics facility is not supported.
        Note that channel-path statistics are only available when running in LPAR or DPM partition.

-e, --enable
    Enable channel-path statistics
    After booting Linux, the channel-path statistics facility starts in disabled state. Use option --enable to enable it.
-d, --disable
    Disable channel-path statistics
-l, --list-columns
    List available table columns
    Use this option to get a list of available table column names and associated short description. A comma-separated list of column names can be used with option --columns to select the columns to display in table output format.
-L, --list-keys
    List available data keys
    Use this option to get a list of available keys that can be used with option --keys to select data pairs to display in machine-readable output format.
-h, --help
    Print usage information, then exit
-v, --version
    Print version information, then exit

OPTIONS
-n, --iterations NUM
    Display NUM reports before ending
    By default, chpstat shows output repeatedly until interrupted. Use option --iterations to specify how many times output should be updated before exiting. A value of 0 indicates an unlimited number of iterations.
-i, --interval NUM
    Pause NUM seconds between display
    Use this option to specify the number of seconds to wait between output updates. Valid values are between 1 and 2140. Note: It is recommended to use interval values of at least the model-dependent statistics update interval (see key "interval").
-c, --columns COL,..
    Select table columns to show in table output format
    To get a list of available columns, use option --list-columns. If a channel-path does not provide data for a selected column, the corresponding table field is set to '-'.
-k, --keys KEY,..
    Select 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 option --list-keys. If a channel-path does not provide data for a selected key, the corresponding value is set to "".
-a, --all
    Show all table columns and key data
    Use this option to select all supported columns and keys for output.
--scale UNIT
    Scale BPS values by UNIT Use this option to specify a value by which bytes-per-seconds (BPS) values - such as read and write throughput - are scaled in human-readable output. Note that scaling is not applied to values in machine-readable output format as produced with option --format. Accepted values are:

    •   auto: Scale automatically to fit value into each column. To indicate the current scaling factor, an SI-suffix is added to each scaled number (e.g. K for 1000). This is the default.

    •   auto-iec: Same as auto but using power-of-two based IEC-suffixes (e.g. Ki for 1024).

    •   number: Scale by number

    •   K: Scale by 1000 (KB)

    •   M: Scale by 1,000,000 (MB)

    •   G: Scale by 1,000,000,000 (GB)

    •   T: Scale by 1,000,000,000,000 (TB)

    •   Ki: Scale by 1024 (KiB)

    •   Mi: Scale by 1,048,576 (MiB)

    •   Gi: Scale by 1,073,741,824 (GiB)

    •   Ti: Scale by 1,099,511,627,776 (TiB)

--cmg CMG,..
    Show data for specified CMGs only
    Use this option to limit output to CHPIDs with the specified Channel-Measurement-Groups (CMG). This option also selects table columns suitable for the specified CMGs.
--format FORMAT
    Show data in specified FORMAT Use this option to show output in a machine-readable format. FORMAT can be either of:

    •   json: Single JavaScript Object Notation (JSON) data structure Data for all iterations is formatted as one JSON data structure formatted in multiple lines to make them more readable by humans.
        See section "OUTPUT FORMAT" for more details.

    •   json-seq: Sequence of JSON data structures Data for each iteration is formatted as separate JSON data structure prefixed with an ASCII Record Separator character (0x1e) and suffixed with an ASCII Line Feed character (0x0a) in accordance with RFC7464.
        See section "OUTPUT FORMAT" for more details.

    •   jsonl: Line-delimited JSON data structures Data for each iteration is formatted as a single JSON data structure separated by an ASCII Line Feed character (0x0a, LF). See section "OUTPUT FORMAT" for more details.

    •   pairs: Textual key=value pairs By default, keys have a prefix that makes them unique across one tool invocation. This prefix can be removed by specifying option --no-prefix.

    •   csv: Comma-Separated-Value (CSV) list
        All values are quoted with double-quotes 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
    List channel-path measurement characteristics Use this option to display static data describing base characteristics of a channel-path. This option implies a machine-readable format.
--util
    List unprocessed utilization data Use this option to display raw channel-path utilization data that is updated regularly by firmware at model-dependent intervals that typically last a few seconds (see key "interval"). This option implies machine-readable output format.
--metrics
    List performance metrics
    Use this option to display performance statistics data derived from utilization and characteristics data. This option implies 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
    Do 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
    Hide key prefix in 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 option --no-prefix to remove this prefix.

OUTPUT FORMAT
This section contains additional information for some of the supported output formats.

  json
JSON output consists of a top-level object with the following properties (key-value pairs):

•   meta: Tool meta-data including API level, version, host name, and time of invocation

•   chpstat: Channel-path statistics data

Note: For a given API level, the output format is guaranteed to remain compatible, that is:

•   required child-objects are not removed

•   format and contents of existing objects and properties are retained

•   new child-objects and properties may be added

Channel-path statistics data is stored as an array of iteration objects under the "chpstat" property in the top-level object. Each iteration object contains a property named "channel_paths" the value of which consists of an array of objects representing data for one channel-path during one iteration. Objects for a single channel-path contain further child-objects that group related properties together.
The following object properties are required and will always be part of JSON output:

•   For iteration objects: "iteration", "time", "time_epoch", and "channel_paths"

•   For channel-path objects: "chpid", "type", "cmg", "shared"

All other properties are optional and will be omitted from JSON output if the associated value is unavailable. If option --all is specified, unavailable properties are also listed as either empty strings or negative values, depending on the value type. Example JSON output for single iteration and channel-path with all properties:
{
  "meta": {
    "api_level": 1,
    "version": "2.32.0",
    "host": "localhost",
    "time_epoch": 1714663282,
    "time": "2024-05-02 17:21:22+0200"
  },
  "chpstat": [
    {
      "iteration": 0,
      "time_epoch": 1714663282,
      "time": "2024-05-02 17:21:22+0200",
      "channel_paths": [
        {
          "chpid": "0.00",
          "type": 0,
          "cmg": 0,
          "shared": 0,
          "speed": "",
          "characteristics": {
            "dpu_id": 0,
            "max_bus_cycles": 0,
            "max_channel_work_units": 0,
            "max_write_data_units": 0,
            "max_read_data_units": 0,
            "data_unit_size": 0,
            "data_unit_size_cpc": 0,
            "msg_unit_size": 0,
            "msg_unit_size_cpc": 0,
            "dpu_num_cores": 0
          },
          "utilization": {
            "timestamp": 0,
            "bus_cycles_cpc": 0,
            "channel_work_units_cpc": 0,
            "channel_work_units": 0,
            "data_units_written_cpc": 0,
            "data_units_written": 0,
            "data_units_read_cpc": 0,
            "data_units_read": 0,
            "total_ficon_ops_cpc": 0,
            "total_deferred_ficon_ops_cpc": 0,
            "sum_ficon_ops_cpc": 0,
            "total_hpf_ops_cpc": 0,
            "total_deferred_hpf_ops_cpc": 0,
            "sum_hpf_ops_cpc": 0,
            "channel_path_busy_time_cpc": 0,
            "channel_path_busy_time": 0,
            "msg_units_sent": 0,
            "msg_units_sent_cpc": 0,
            "unsuccessful_attempts_to_send": 0,
            "unavailable_receive_buffers": 0,
            "unavailable_receive_buffers_cpc": 0,
            "data_units_sent": 0,
            "data_units_sent_cpc": 0,
            "dpu_channel_exec_time_cpc": 0,
            "dpu_exec_time_cpc": 0
          },
          "metrics": {
            "interval": 0.0,
            "util_total": 0.0,
            "util_part": 0.0,
            "util_bus": 0.0,
            "read_total": 0.0,
            "read_part": 0.0,
            "write_total": 0.0,
            "write_part": 0.0,
            "ficon_rate": 0.0,
            "ficon_active": 0.0,
            "ficon_defer": 0.0,
            "hpf_rate": 0.0,
            "hpf_active": 0.0,
            "hpf_defer": 0.0,
            "msg_rate_part": 0.0,
            "msg_rate_total": 0.0,
            "msg_size_part": 0.0,
            "msg_size_total": 0.0,
            "send_fail_part": 0.0,
            "rcv_fail_part": 0.0,
            "rcv_fail_total": 0.0,
            "dpu_util": 0.0,
            "dpu_util_total": 0.0,
            "dpu_util_part": 0.0
          }
        }
      ]
    }
  ]
}

  json-seq
The json-seq output format is a variation of the JSON output format described above with the following differences:

•   Output consists of a sequence of top-level JSON objects, each contained in single line with no indentation

•   Each top-level object is prefixed by an ASCII Record Separator character (0x1e) and suffixed with an ASCII Line Feed character (0x0a) in accordance with RFC7464

•   The first object contains tool meta-data properties defined in the previous section

•   Subsequent objects each represent channel-path statistics data for one iteration

  jsonl
The jsonl output format is a data streaming variation of the JSON output format described above with the same properties as the json-seq output with the difference that JSON data is separated only by an ASCII Line Feed character (0x0a, LF).

EXIT CODES

0   Program finished successfully

1   Usage error

2   A run-time error occurred

EXAMPLES
Display current channel-path statistics status in JSON format:
    $ chpstat --status --format json

Determine the model-dependent update interval for CHPID 0.f0:
    $ chpstat --keys interval -n 1 --no-prefix 0.f0 --format pairs

Collect partition write throughput statistics for 1 hour in CSV format:
    $ chpstat -n 60 -i 60 --format csv --key time,chpid,write_part

SEE ALSO
lschp(8), chchp(8)