.\" 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 ZIOMON_MGR 8 "Jul 2008" "s390-tools"

.SH NAME
ziorep_utilization \- Utilization report for FCP adapters.

.SH SYNOPSIS
.B ziorep_utilization
[-V] [-v] [-h] [-b <begin>] [-e <end>] [-i <time>] [-s] [-c <chpid>] [-x] [-t <num>] <filename>

.SH DESCRIPTION
.B ziorep_utilization
Prints a report from the specified data.

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

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

.TP
.BR "\-V" " or " "\-\-verbose"
Be verbose.

.TP
.BR "\-b" " or " "\-\-begin"
Limit the timeframe to consider to data beginning with the specified date.
.br
Dates must be specified in the following format: YYYY-MM-DD HH:MM[:SS].
.br
E.g. 2008-03-21 09:08 is 9:08 on March 21, 2008.

.TP
.BR "\-e" " or " "\-\-end"
Limit the timeframe to consider to data ending with the specified date.
.br
Dates must be specified in the following format: YYYY-MM-DD HH:MM[:SS].
.br
E.g. 2008-03-21 09:08 is 9:08 on March 21, 2008.

.TP
.BR "\-i" " or " "\-\-interval"
Specify an aggregation interval. The interval is given in seconds, and must be a multiple
of the interval as found in the source data.

.TP
.BR "\-s" " or " "\-\-summary"
Print a summary of the data, then exit.

.TP
.BR "\-c" " or " "\-\-chpid"
Only consider the specified physical adapter. Adapters must be specified in hex.
If multiple adapters should be specified, specify each one separately.

.TP
.BR "\-x" " or " "\-\-export-csv"
Write data to file(s) in CSV format. Output filenames will be based on the data filename.

.TP
.BR "\-t" " or " "\-\-topline"
Repeat topline after specified number of frames.
0 for no repeat (default).

.SH OUTPUT
Here is a list of the columns and their descriptions.
Timestamps of the frames printed depict the ending of the respective timeframe.

.TP
.BR "adapter in %"
FCP adapter utilization in percent.
.br
.IR "min" ", " "max" " and " avg "
gives the minimum, maximum and average utilization respectively.

.TP
.BR "bus in %"
Bus utilization of the FCP adapter in percent.
.br
.IR "min" ", " "max" " and " avg "
gives the minimum, maximum and average utilization respectively.

.TP
.BR "cpu in %"
Utilization of the cpu on the FCP adapter in percent.
.br
.IR "min" ", " "max" " and " avg "
gives the minimum, maximum and average utilization respectively.

.TP
.BR "qdio util.%"
gives the qdio utilization in percent.
.br
.IR "max" " and " avg "
gives the maximum and average utilization respectively. Note that the minimum value is not reported since it provides no additional information: You will see the number of queue full encounters rise drastically before the minimum becomes non-zero.

.TP
.BR "queue full"
The number of instances where a request to the adapter could not be submitted
due to no empty slots left in the outbound queue.

.TP
.BR "fail"
The number of failures as reported by the FCP adapter.
.br
.IR "erc"
is the number of error recovery conditions.

.TP
.BR "thp in MS/s"
gives the average throughput over time (transmitted data volume / elapsed time), not over number of requests (sum over all request throughputs / number of requests)! This means that a long-running request with a significantly different throughput profile from the rest will have a bigger impact as a brief one with the same throughput profile would. This gives a better impression of the overall profile and especially makes requests with very low throughputs have a bigger impact, making it easier to detect anomalies.
.br
.IR "rd" " and " "wrt"
give the values for read and write requests respectively.

.TP
.BR "I/O reqs"
give the number of I/O requests processed in the respective interval.
.br
.IR "rd" " and " "wrt"
give the values for read and write requests respectively.


.SH EXAMPLES
Print a utilization report using
.IR sample.log
, considering adapters 4e and 4f only.
Only data between 8:57 April 5, 2008, and 17:09 June 21, 2008, should be considered.
Data should be aggregated to 60 second intervals.

ziorep_utilization -c 4e -c 4f -i 60 -b "2008-04-05 08:57" -e "2008-06-21 17:09"


.SH "SEE ALSO"
.BR ziorep_config (8),
.BR ziorep_traffic (8)