chpstat(8)

💖 `chpstat(8)` — channel-path statistics, bestie 💖

🌸 NAME 🌸

chpstat — Display channel-path statistics. No cap, that's the whole vibe.

✨ SYNOPSIS ✨

chpstat [OPTIONS] [ACTIONS] [CHPIDS]

🦋 DESCRIPTION 🦋

Okay so use chpstat to view channel-path statistics like utilization and throughput, and also to query and control the status of the channel-path statistics function. It's giving main character observability.

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-path's 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 🏛️

Log on to the Hardware Management Console (HMC)
Select the target LPAR
Start Customize Activation Profiles HMC Task
Enable Security/Global performance data control setting

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

🌀 DPM Partition 🌀

Log on to the Hardware Management Console (HMC)
Select the target partition
Start Partition Details HMC Task
Enable Controls/Access global performance data setting
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 ⚡

Pick your action, bestie. These are the controls. 💅

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

Here come the options. All of them. No skipping. 😤

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

okay so some of the output formats have ✨extra tea✨ for you, and this section is where we spill it.

json

the JSON output is one big top-level object, and it's holding these properties (key-value pairs, iykyk):

meta — tool meta-data, like the API level, version, host name, and time of invocation 🕐
chpstat — the channel-path statistics data 💅

note bestie: for a given API level, the output format is guaranteed to stay compatible, which means: - required child-objects are not removed - format and contents of existing objects and properties are retained - new child-objects and properties may be added

so your scripts are safe, fr fr. 🫶

channel-path statistics data lives as an array of iteration objects under the "chpstat" property in the top-level object.

each iteration object has a property called "channel_paths", and its value is 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. very organized, very main character. 👑

these object properties are required and will always be part of the JSON output:

for iteration objects: "iteration", "time", "time_epoch", and "channel_paths"
for channel-path objects: "chpid", "type", "cmg", "shared"

all the other properties are optional and get omitted from JSON output if the associated value is unavailable. but if you pass --all, those unavailable properties are listed too — as either empty strings or negative values, depending on the value type. 🎀

example JSON output for a 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
          }
        }
      ]
    }
  ]
}

like, look at all those properties. she's stunning. 😭💖

json-seq

json-seq is a variation on the JSON output format we just talked about, with these differences:

output is a sequence of top-level JSON objects, each one contained in a 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 the tool meta-data properties defined in the previous section
subsequent objects each represent channel-path statistics data for one iteration

so it's the JSON you love, just chopped into a stream. slay. ✨

jsonl

jsonl is the data streaming variation of the JSON output format described above, with the same properties as the json-seq output — the only difference being that JSON data is separated only by an ASCII Line Feed character (0x0a, LF). no fancy record separator here, just vibes and newlines. 🌈

💀 EXIT CODES 💀

0 — program finished successfully. we love a happy ending 🎀
1 — usage error. you called her wrong, bestie 🙈
2 — a run-time error occurred. something went sideways mid-run 😭

🌸 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

go off, honestly. 🔥

👑 SEE ALSO 👑

lschp(8), chchp(8) — your other faves, go give them a read 💜

and that's the whole page, bestie! this iconic little number ships with s390-tools and lives at chpstat(8) — go forth, stat those channel paths, and remember: the facts stay exactly where they were, only the vibe got upgraded. 💅✨🦋

📦 where this page comes from

opensuse-leap 16.0: s390-tools 2.44.1-160000.1.1 · MIT
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on 2026-11-04: a language model's rewrite of the original, under its terms

chpstat(8)

💖 chpstat(8) — channel-path statistics, bestie 💖

🌸 NAME 🌸

✨ SYNOPSIS ✨

🦋 DESCRIPTION 🦋

💅 Output options 💅

🔐 Authorization 🔐

🏛️ Classic mode LPAR 🏛️

🌀 DPM Partition 🌀

🎀 Channel-Measurement Groups 🎀

⚡ ACTIONS ⚡

🌈 OPTIONS 🌈

📊 OUTPUT FORMAT 📊

json

json-seq

jsonl

💀 EXIT CODES 💀

🌸 EXAMPLES 🌸

👑 SEE ALSO 👑

💖 `chpstat(8)` — channel-path statistics, bestie 💖