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.

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