lspai(8)

NAME
lspai - list Processor Activity Instrumentation (PAI) counters and values

SYNOPSIS
lspai [--format FORMAT] [-n] [-t TYPE]
lspai [--format FORMAT] [-n] [-t TYPE] [-a][-d][-i SECONDS] [-l COUNT] [-s][-x][-x] [-c LIST] [CPULIST]
lspai -h|--help
lspai -v|--version

DESCRIPTION
On the first line lspai displays the Processor Activity Instrumentation (PAI) counters for Linux on IBM Z. The output lists the available PAI counter names and numbers in various formats. If CPULIST is specified or any of the options -a, -d, -s, -x, -X, -l or -i, are present on the command line, lspai command extracts counter values from the specified PAI counter sets. Counter sets can be specified and extracted for individual CPUs. By default the output is a comma-separated list of values. Each line starts with a timestamp followed by the extracted counter values. A header line shows each counter name and the counter number in parenthesis. For other formats, use the --format option.

OPTIONS

-h, --help
    Displays help information, then exits.

-v, --version
    Displays version information, then exits.

-a, --allcpu
    Displays counter values from each CPU. The default is a total summary line of all counters from all CPUs.

-d, --delta
    Displays counter values in form of deltas. Each counter value shows the increment to the previous output line. Without this flag the total value of each counter is displayed.

-c, --counters LIST
    Specify a comma separated list of counter names to be printed. If a counter name does not match any valid counter name, it is omitted.

-s, --short
    Displays counter names as short names in the heading. A short name consists of a letter for the counter set followed by a number. For example, this flag displays counter number 0 in the PAI crypto counter set as C0 instead of CRYPTO_ALL. Valid counter set letters are:

    C   PAI crypto counter set

    N   PAI NNPA counter set

-t, --type TYPE
    Specifies the PAI counter set to list. Valid counter set values are crypto and nnpa. By default, the command lists all available PAI counter sets. NNPA refers to the Neural Network Processing Assist facility counter set. Crypto refers to the Cryptografic Processing Assist facility counter set.

-n, --numeric
    Shows the PAI counter sets sorted by counter number. Default sort order is PAI counter name.

--format FORMAT
    Retrieve output in one of the following formats: JSON, csv, json-seq, jsonl or pairs. If no format is specified, the output defaults to a human-readable format.

-i, --interval SECONDS
    Specifies a time interval, in seconds, that the command waits between read operations. The default is 60 seconds.

-l, --loop COUNT
    Performs the specified number of read operations. The default is one.

-x, --hex
    Displays counter values as hexadecimal values.

-X, --hex0x
    Displays counter values as hexadecimal values with a leading 0x prefix.

EXAMPLE
The lspai invocation lists all PAI Neural Network Processing Assist Facility (NNPA) counters in numeric order:
# lspai -t nnpa -n
RAW     NAME			DESCRIPTION
13:6144 NNPA_ALL		Counter 0 / PAI NNPA counter set
13:6145 NNPA_ADD		Counter 1 / PAI NNPA counter set
13:6146 NNPA_SUB		Counter 2 / PAI NNPA counter set
13:6147 NNPA_MUL		Counter 3 / PAI NNPA counter set
...
The first column shows the raw event number suitable for perf(8) raw event specification. The second column shows the PAI NNPA counter name, suitable for perf(8) event specification by name. The third gives a short explanation, if available.

The lspai invocation displays all PAI Neural Network Processing Assist Facility (NNPA) counters values. Ten iterations with a two second delay in between is printed on the screen.
# lspai -i 2 -l 10 -t nnpa -n
Date,Time,CPU,NNPA_ALL(0),NNPA_ADD(1),NNPA_SUB(2),NNPA_MUL(3),NNPA_DIV(4),
NNPA_MIN(5),NNPA_MAX(6),NNPA_LOG(7),NNPA_EXP(8),NNPA_IBM_RESERVED_9(9),
NNPA_RELU(10),NNPA_TANH(11),NNPA_SIGMOID(12),NNPA_SOFTMAX(13),NNPA_BATCHNORM(14),
NNPA_MAXPOOL2D(15),NNPA_AVGPOOL2D(16),NNPA_LSTMACT(17),NNPA_GRUACT(18),
NNPA_CONVOLUTION(19),NNPA_MATMUL_OP(20),NNPA_MATMUL_OP_BCAST23(21),
NNPA_SMALLBATCH(22),NNPA_LARGEDIM(23),NNPA_SMALLTENSOR(24),NNPA_1MFRAME(25),
NNPA_2GFRAME(26),NNPA_ACCESSEXCEPT(27)
2025-05-13,08:18:27,Total,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0
2025-05-13,08:18:29,Total,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0
2025-05-13,08:18:31,Total,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0
2025-05-13,08:18:33,Total,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0
2025-05-13,08:18:35,Total,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0
2025-05-13,08:18:37,Total,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0
2025-05-13,08:18:39,Total,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0
2025-05-13,08:18:41,Total,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0
2025-05-13,08:18:43,Total,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0
2025-05-13,08:18:45,Total,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0
#

This lspai example displays the value of PAI crypto counter number 7. It is field number 116 in the output. This counter is incremented after lspai is started and the table shows the delta values for PAI crypto counter 7.
# lspai -d -s -i 5 -l3 -t crypto | awk -F , '{ print $1 ","  $2 "," $3 ","  $4 "," $116; }'
Date,Time,CPU,C0,C7
2025-06-24,13:02:24,Total,0,0
2025-06-24,13:02:29,Delta,77122286,77122284
2025-06-24,13:02:34,Delta,92574403,92574403
#

The following table shows the total value for PAI crypto counter 7 after lspai is started.
# lspai -s -i 5 -l3 -t crypto | awk -F , '{ print $1 ","  $2 "," $3 ","  $4 "," $116; }'
Date,Time,CPU,C0,C7
2025-06-24,13:03:01,Total,0,0
2025-06-24,13:03:06,Total,72550754,72566121
2025-06-24,13:03:11,Total,164633982,164650377
#

SEE ALSO
pai(8) lscpumf(8)