HYPTOP(8)

💅 hyptop(8)

Okay bestie, welcome to the hyptop(8) page from the System Manager's Manual — and yes, it's giving “Show hypervisor performance data on System z” main-character energy. ✨

🌸 NAME

hyptop — Show hypervisor performance data on System z. 💖

🦋 SYNOPSIS

hyptop [OPTIONS]

✨ DESCRIPTION

Okay so hyptop provides a dynamic real-time view of a hypervisor environment on System z. 🫶 It works with either the z/VM hypervisor or the LPAR hypervisor. Depending on the available data it shows, for example, CPU and memory information about running LPARs or z/VM guests.

hyptop provides two windows:

sys_list: Shows a list of systems that the hypervisor is currently running.
sys: Shows one system in more detail.

System names in hyptop are either LPAR names as shown on the SE or HMC, or z/VM guest IDs that identify z/VM guest virtual machines. 🎀

You can run hyptop in interactive mode (default) or in batch mode with the "-b" option. For how to use the interactive mode, see the online help (enter "?" after hyptop is started). 👑

💜 OPTIONS

Here's the option menu, bestie — every flag, no skipping. 💅

-h, --help — Print usage information, then exit. 🙈
-v, --version — Print version information, then exit. 🦋
-w <WINDOW NAME>, --window=<WINDOW NAME> — Select current window. Use the options "--sys", "--fields", and "--sort" to modify the current window. The last window specified with the "--window" option will be used as start window. The default window is "sys_list". 💅
-s <SYSTEM>,..., --sys=<SYSTEM>,... — Select systems for current window. If this option is specified, only the selected systems are shown for the window. For window "sys" only one system can be specified. 🎀
-f <F_LETTER>[:<UNIT>],..., --fields=<F_LETTER>[:<UNIT>],... — Select fields and units in the current window. "F_LETTER" is the field letter that identifies uniquely a field (for example "c" for CPU time). "UNIT" is the used entity for displaying data for the field (for example "us" for microseconds). See FIELDS and UNITS below for definitions. If the "--fields" option is specified, only the selected fields are shown. 🌸
-S <F_LETTER>, --sort=<F_LETTER> — Select sort field for current window. To reverse the sort order, specify the option twice. See FIELDS below for definitions. ⭐
-t <TYPE>,..., --cpu-types=<TYPE>,... — Select CPU types that are used for CPU time calculations. See CPU TYPES below for definitions. 🔥
-b, --batch-mode — Use batch mode (no curses). This can be useful for sending output from hyptop to another program, a file, or a line mode terminal. In this mode no user input is accepted. 💻
--format=<FORMAT> — Use this option to show output in a machine-readable 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 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 a 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 separate JSON data structure separated by ASCII Line Feed character (0x0a, LF). See section "OUTPUT FORMAT" for more details.
- pairs — Textual key=value pairs.
- csv — Comma-separated-value (CSV) list. All values are enclosed in double quotation marks and separated by commas. The first line of output contains a list of headings. Subsequent lines each represent data for one system in one iteration.

This option implies the "--batch-mode" option. 🫶

--all — Use this option with the "--format" option to include fields without valid values in the output. Fields without valid values are omitted from the output by default. When you use the "--all" option, the invalid values are included and shown as "null". 💀
-d <SECONDS>, --delay=<SECONDS> — Specifies the delay between screen updates. ⏳
-m <FACTOR>, --smt-factor=<FACTOR> — Specifies a workload dependent SMT speedup factor. For IBM z15 servers, the default value is 1.3. If the workload benefits from SMT, you can specify a higher value. If the workload does not benefit from SMT, specifying lower values results in more accurate reports of real CPU SMT utilization field for LPARs. There is no hard boundary except that it must be a positive value. Example ranges to select a sensible value from:

For IBM z13: [0.8, 1.3]
For IBM z15: [1.1, 1.5]

-n <ITERATIONS>, --iterations=<ITERATIONS> — Specifies the maximum number of iterations before ending. 🌈

🧚 PREREQUISITES

The following things are required to run hyptop:

The Linux kernel must have the required support to provide the performance data.
debugfs has to be mounted.
The hyptop user must have read permission for the required debugfs files.
You can always monitor the guest operating system where hyptop is running.

To monitor any other operating system instances running on the same hypervisor as hyptop, you will need additional permissions.

For z/VM, the guest virtual machine must have privilege class B.
For LPAR, on the HMC or SE security menu of the LPAR activation profile, select the Global performance data control checkbox.

To mount debugfs, you can use this command:

# mount none -t debugfs /sys/kernel/debug

To make this persistent, add the following to "/etc/fstab":

none     /sys/kernel/debug       debugfs defaults        0 0

🦋 FIELDS

The supported fields depend on the available data on the hypervisor. This is different between LPAR and z/VM. It might also depend on machine type, z/VM version and kernel version. Each field has a unique field letter that can be used to select the field in interactive mode or through the "--fields" command line option. 💖

💅 The fields under LPAR

✨ In `"sys_list"` and `"sys"` window

'c' — Core dispatch time per second
'e' — Thread time per second
'S' — Real CPU SMT utilization
'm' — Management time per second
'C' — Total core dispatch time
'E' — Total thread time
'M' — Total management time
'o' — Online time

🎀 In `"sys_list"` window

'#' — Number of cores (sum of initial and reserved)
'T' — Number of threads (sum of initial and reserved)

🌸 In `"sys"` window

'p' — CPU type
'v' — Visualization of core dispatch time per second

💜 The fields under z/VM

🦋 In `"sys_list"` and `"sys"` window

'c' — CPU time per second
'm' — Management time per second (*)
'C' — Total CPU time
'M' — Total management time (*)
'o' — Online time

🎀 In `"sys_list"` window

'#' — Number of CPUs
'O' — Number of operating CPUs
'u' — Used memory
'a' — Maximum memory
'r' — Current weight
'x' — Maximum weight

✨ In `"sys"` window

'v' — Visualization of CPU time per second

(*) Only available for the local guest virtual machine Only available if the system has the required support

🌈 UNITS

Depending on the field type the values can be displayed in different units. The following units are supported:

⏳ Time

'us' — Microseconds (10^-6 seconds)
'ms' — Millisconds (10^-3 seconds)
'%' — Hundreds of a second (10^-2 seconds) or percent
's' — Seconds
'm' — Minutes
'hm' — Hours & Minutes
'dhm' — Days & Hours & Minutes

🧠 Memory

'kib' — Kibibytes (1.024 bytes)
'mib' — Mebibytes (1.048.576 bytes)
'gib' — Gibibytes (1.073.741.824 bytes)

🎀 Miscellaneous

'str' — String
'#' — Count/Number
'vis' — Visualization

👑 CPU TYPES

Depending on the hypervisor different CPU types are supported. These CPU types can be selected either interactively or with the --cpu-types command line option. The calculation of the CPU data only uses CPUs of the specified types. 💅

On LPAR the following CPU types are supported:

'IFL' — Integrated Facility for Linux
'CP' — CP processor type
'UN' — Unspecified processor type (other than CP or IFL)

NOTE: It is possible that on older machines also IFLs are shown as CPs. On z/VM currently only the processor type 'UN' is available.

🔥 CPU DATA

For Linux on z/VM, no performance data is available for individual CPUs on remote guests. Therefore, the hyptop "sys" window shows identical values for each of the operating CPUs. For the CPU time fields, these values represent the total across all operating CPUs divided by the number of operating CPUs. For the online time field, the value is the time during which at least one CPU has been operational. Operating CPUs are shown with CPU identifier "0" and stopped CPUs with "1". 💀

✨ OUTPUT FORMATS ✨

Ok so this bit is extra tea ☕ for a couple of the output formats — like, the details you'd want if you're parsing this stuff instead of just vibing at it. Let's go 💅

🌸 json 🌸

The JSON output is one top-level object, and it's giving very structured, very demure. Here's what's in it (key-value pairs, bestie):

meta: tool meta-data, including the API level, the version, the host name, and the time of invocation 🕐
hyptop: the hypervisor performance data itself

All the performance data sits in an array of iteration objects under the "hyptop" property of that top-level object. Each iteration object has these properties:

iteration: the sequential count of the current iteration 🔢
time and time_epoch: when the iteration was recorded — one human-readable, one as Unix epoch
cputypes: how many CPUs hyptop detected, per CPU type. Possible properties are cp, ifl and un
systems: when the "sys_list" window is selected, this holds an array of system objects with the performance data per system. Each system object has a "system" property plus properties for its performance data (peep below 👇)
cpus: when the "sys" window is selected, this holds an array of CPU objects with the performance data per CPU of the selected system. Each CPU object has a "coreid" property plus properties for its performance data (again, below)
summary: aggregated performance data over all systems in the "systems" or "cpus" array 🫶

All the performance data available for the platform (LPAR, z/VM) that hyptop is running on gets shown. Picking specific fields with --fields? Not supported, sorry babe 🙈 — but you can change the units of fields. Performance data properties are labeled after their respective columns.

Example JSON output for a single iteration — iconic, honestly:

{
  "meta": {
    "api_level": 1,
    "version": "2.35.0",
    "host": "mylpar.local",
    "time_epoch": 1730787834,
    "time": "2024-11-05 07:23:54+0100"
  },
  "hyptop": [
    {
      "iteration": 0,
      "time_epoch": 1730787834,
      "time": "2024-11-05 07:23:54+0100",
      "cputypes": {
        "ifl": 124,
        "cp": 1,
        "un": 0
      },
      "systems": [
        {
          "system": "MYLPAR",
          "#core": 30,
          "#the": 60,
          "core": 379.57,
          "the": 382.43,
          "smt": 294.73,
          "mgm": 2.09,
          "core+": "1503:13",
          "the+": "2060:45",
          "mgm+": "22:19",
          "online": "18:18:09"
        }
      ],
      "summary": {
        "#core": 30,
        "#the": 60,
        "core": 379.57,
        "the": 382.43,
        "smt": 294.73,
        "mgm": 2.09,
        "core+": "1503:13",
        "the+": "2060:45",
        "mgm+": "22:19",
        "online": "18:18:09"
      }
    }
  ]
}

🦋 json-seq 🦋

json-seq is the JSON output format's sibling — same DNA, but with these differences, bestie:

the output is a sequence of top-level JSON objects, each one on 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), all in accordance with RFC7464 📜
the first object carries the tool meta-data properties defined in the previous section
every subsequent object represents performance data for one iteration

🎀 jsonl 🎀

jsonl is the data streaming variation of the JSON output format described above — same properties as the json-seq output, except the JSON data is separated only by an ASCII Line Feed character (0x0a, LF). That's it. That's the whole difference. Slay for simplicity 💅

🔥 EXAMPLES 🔥

Wanna start hyptop with the "sys_list" window in interactive mode? Say less:

# hyptop

Wanna start hyptop with the "sys_list" window in batch mode? Periodt:

# hyptop -b

Wanna start hyptop with the "sys_list" window in interactive mode, with the fields CPU time (in milliseconds) and online time (unit default), sorted by online time? Here you go:

# hyptop -f c:ms,o -S o

Wanna start hyptop with the "sys" window for system "MYLPAR", with the fields CPU time (unit milliseconds) and online time (unit default), and sort the output reverse according to online time? Yes, the double -S o is on purpose, don't come for me:

# hyptop -w sys -s MYLPAR -f c:ms,o -S o -S o

Wanna start hyptop with the "sys_list" window in batch mode with update delay 5 seconds and 10 iterations? Chef's kiss:

# hyptop -b -d 5 -n 10

Wanna start hyptop with the "sys_list" window using only the CPU types IFL and CP for CPU time calculation? Ate:

# hyptop -t ifl,cp

Wanna show a single iteration of performance data as a formatted JSON object for system "MYLPAR", with fields CPU time, thread time, management time and online time in microseconds? Obsessed with this one:

# hyptop -f C:us,E:us,M:us,o:us --format json -n 1 -s MYLPAR

🌈 ENVIRONMENT 🌈

TERM — this environment variable specifies your terminal type. To run hyptop in interactive mode, TERM has to be set. Interactive mode is not available for terminals that have TERM=dumb (e.g. line mode terminals) 😭 so set it properly, okay?

And that's a wrap on this manpage, bestie 🫶 This little beauty comes from s390-tools, dated Nov 2009 and filed as HYPTOP(8) — go forth and monitor those hypervisors, you main character 👑💖

📦 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

HYPTOP(8)

💅 hyptop(8)

🌸 NAME

🦋 SYNOPSIS

✨ DESCRIPTION

💜 OPTIONS

🧚 PREREQUISITES

🦋 FIELDS

💅 The fields under LPAR

✨ In "sys_list" and "sys" window

🎀 In "sys_list" window

🌸 In "sys" window

💜 The fields under z/VM

🦋 In "sys_list" and "sys" window

🎀 In "sys_list" window

✨ In "sys" window

🌈 UNITS

⏳ Time

🧠 Memory

🎀 Miscellaneous

👑 CPU TYPES

🔥 CPU DATA

✨ OUTPUT FORMATS ✨

🌸 json 🌸

🦋 json-seq 🦋

🎀 jsonl 🎀

🔥 EXAMPLES 🔥

🌈 ENVIRONMENT 🌈

✨ In `"sys_list"` and `"sys"` window

🎀 In `"sys_list"` window

🌸 In `"sys"` window

🦋 In `"sys_list"` and `"sys"` window

🎀 In `"sys_list"` window

✨ In `"sys"` window