s390-tools/hyptop/hyptop.8

.\" Copyright 2017 IBM Corp.
.\" s390-tools is free software; you can redistribute it and/or modify
.\" it under the terms of the MIT license. See LICENSE for details.
.\"
.TH HYPTOP 8 "Nov 2009" "s390-tools"
.SH NAME
hyptop \- Show hypervisor performance data on System z

.SH SYNOPSIS
.B hyptop
[OPTIONS]

.SH DESCRIPTION
.B hyptop
provides a dynamic real-time view of a hypervisor environment on System z.
It works with either the z/VM 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:
.IP "     -"
sys_list: Shows a list of systems that the hypervisor is currently running
.IP "     -"
sys: Shows one system in more detail.
.PP
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.
.PP
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).

.SH OPTIONS
.TP
.BR "\-h" " or " "\-\-help"
Print usage information, then exit.

.TP
.BR "\-v" " or " "\-\-version"
Print version information, then exit.

.TP
.BR "\-w <WINDOW NAME>" " or " "\-\-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".
.TP
.BR "\-s <SYSTEM>,..." " or " "\-\-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.
.TP
.BR "\-f <F_LETTER>[:<UNIT>],..." " or " "\-\-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.
.TP
.BR "\-S <F_LETTER>" " or " "\-\-sort=<F_LETTER>"
Select sort field for current window. To reverse the sort order, specify the
option twice. See FIELDS below for definitions.
.TP
.BR "\-t <TYPE>,..." " or " "\-\-cpu-types=<TYPE>,..."
Select CPU types that are used for CPU time calculations. See CPU TYPES
below for definitions.
.TP
.BR "\-b" " or " "\-\-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.
.TP
.BR "\-\-format=<FORMAT>"
.RS
Use this option to show output in a machine-readable format. FORMAT can be
one of:

.IP \(bu 3
.B 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.
.BR

See section "OUTPUT FORMAT" for more details.
.BR
.PP
.IP \(bu 3
.B 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.
.BR

See section "OUTPUT FORMAT" for more details.
.BR
.PP
.IP \(bu 3
.B 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).
.BR

See section "OUTPUT FORMAT" for more details.
.BR
.PP
.IP \(bu 3
.B pairs:
Textual key=value pairs

.PP
.IP \(bu 3
.B csv:
Comma-separated-value (CSV) list
.BR

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.
.PP
This option implies the "\-\-batch-mode" option.
.RE
.BR "\-\-all"
.RS
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".
.RE
.TP
.BR "\-d <SECONDS>" " or " "\-\-delay=<SECONDS>"
Specifies the delay between screen updates.
.TP
.BR "\-m <FACTOR>" " or " "\-\-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]
.TP
.BR "\-n <ITERATIONS>" " or " "\-\-iterations=<ITERATIONS>"
Specifies the maximum number of iterations before ending.

.SH PREREQUISITES
The following things are required to run hyptop:

.IP "     -"
The Linux kernel must have the required support to  provide  the
performance data.
.IP "     -"
debugfs has to be mounted.
.IP "     -"
The hyptop user must have read permission for the required debugfs files.
.IP "     -"
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.

.PP
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


.SH 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 following fields are available 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 following fields are available 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

.SH 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

.SH 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.

.SH 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".

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

.SS json

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

.IP \(bu 3
.BR meta :
Tool meta-data including API level, version, host name, and time of invocation
.PP
.IP \(bu 3
.BR hyptop :
Hypervisor performance data
.PP

Performance data is stored as an array of iteration objects under the "hyptop"
property in the top-level object. Iteration objects contain the following properties:

.IP \(bu 3
.BR iteration :
sequential count of the current iteration
.PP
.IP \(bu 3
.BR "time" " and " "time_epoch" :
time when the iteration was recorded, in human-readable format and as Unix
epoch.
.PP
.IP \(bu 3
.BR cputypes :
contains the number of CPUs hyptop detected, per CPU type. Possible properties
are
.BR "cp" ", " "ifl" " and " "un".
.PP
.IP \(bu 3
.BR systems :
when the "sys_list" window is selected, contains an array of system objects
that contain the performance data per system. Each system object contains a
"system" property and properties for its performance data (see below).
.PP
.IP \(bu 3
.BR cpus :
when the "sys" window is selected, contains an array of CPU objects
that contain the performance data per CPU of the selected system. Each CPU
object contains a "coreid" property and properties for its performance data
(see below).
.PP
.IP \(bu 3
.BR summary :
contains aggregated performance data over all systems in the "systems" or
"cpus" array.
.PP

All performance data available for the platform (LPAR, z/VM) hyptop is executed
on is shown. Selecting specific fields with \-\-fields is not supported but it
is possible to change the units of fields. Properties for performance data are
labeled after their respective columns.

Example JSON output for a single iteration:
.br

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

.SS json\-seq

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

.IP \(bu 3
Output consists of a sequence of top-level JSON objects, each contained in
single line with no indentation
.br

.IP \(bu 3
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
.br
.PP

.IP \(bu 3
The first object contains tool meta-data properties defined in the previous
section
.br
.PP

.IP \(bu 3
Subsequent objects each represent performance data for one iteration
.br
.PP

.SS 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).


.SH EXAMPLES
To start hyptop with the "sys_list" window in interactive mode, enter:
.br

  # hyptop

.br
To start hyptop with the "sys_list" window in batch mode, enter:
.br

  # hyptop -b

.br
To start hyptop with the "sys_list" window in interactive mode with the fields
CPU time (in milliseconds) and online time (unit default) and sort the
output according to online time, enter:
.br

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

.br
To start hyptop with the "sys" window with system "MYLPAR" with the fields CPU
time (unit milliseconds) and online time  (unit  default)  and  sort  the
output reverse according the online time, enter:
.br

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

.br
To start hyptop with the "sys_list" window in batch mode with update delay 5
seconds and 10 iterations, enter:
.br

  # hyptop -b -d 5 -n 10

.br
To start  hyptop with the "sys_list" window and use only CPU types IFL and CP
for CPU time calculation, enter:
.br

  # hyptop -t ifl,cp

.br
To show a single iteration of performance data as a formatted JSON object for
system "MYLPAR" and with fields CPU time, thread time, management time and
online time in microseconds, enter:
.br

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

.SH ENVIRONMENT
.TP
.B TERM
The TERM environment variable specifies your terminal type. To run
\fBhyptop\fP in interactive mode the TERM environment variable has
to be set. The interactive mode is not available for terminals that
have TERM=dumb (e.g. line mode terminals).