From 05f0aeb61e511dc4048105593b2e980acc4dbf6a Mon Sep 17 00:00:00 2001 From: Sumanth Korikkar Date: Wed, 8 Jan 2025 08:57:03 +0100 Subject: [PATCH] zpwr: Add man page for zpwr tool MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add man page for zpwr tool and its usage. Reviewed-by: Jan Höppner Signed-off-by: Sumanth Korikkar Signed-off-by: Jan Höppner --- zpwr/Makefile | 2 + zpwr/man/zpwr.1 | 232 ++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 234 insertions(+) create mode 100644 zpwr/man/zpwr.1 diff --git a/zpwr/Makefile b/zpwr/Makefile index 02581a68..c56dee26 100644 --- a/zpwr/Makefile +++ b/zpwr/Makefile @@ -15,7 +15,9 @@ zpwr: $(OBJECTS) $(rootdir)/libutil/libutil.a -lm install: all $(INSTALL) -d -m 755 $(DESTDIR)$(USRBINDIR) + $(INSTALL) -d -m 755 $(DESTDIR)$(MANDIR)/man1 $(INSTALL) -g $(GROUP) -o $(OWNER) -m 755 zpwr $(DESTDIR)$(USRBINDIR) + $(INSTALL) -g $(GROUP) -o $(OWNER) -m 644 man/zpwr.1 $(DESTDIR)$(MANDIR)/man1 clean: rm -f *.o *~ zpwr core diff --git a/zpwr/man/zpwr.1 b/zpwr/man/zpwr.1 new file mode 100644 index 00000000..deaceafe --- /dev/null +++ b/zpwr/man/zpwr.1 @@ -0,0 +1,232 @@ +.\" Copyright 2025 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. +.\" +.ds c \fBzpwr\fP +.TH zpwr 1 "Feb 2025" "s390-tools" zpwr +.SH NAME +zpwr \- Display power readings of a partition and central processor complex +(CPC) on an IBM Z or LinuxONE server. +.SH SYNOPSIS +.sp +.nf +\fIzpwr\fR + [\-d | \-\-delay=] [\-c | \-\-count=] + [\-\-format=] + [\-s | \-\-stream] + [\-v | \-\-version] + [\-h | \-\-help] +.fi +.SH DESCRIPTION +.sp +zpwr displays power readings of a partition and central processor complex +(CPC) on an IBM Z or LinuxONE server. +.sp +Partition readings include CPU, storage and I/O power readings. It specifies +the number of units allocated to the configuration at the time the reading was +taken. +.sp +CPC readings include total, unassigned resources and infrastructure power +readings. +.sp +Power reading units are automatically presented in a human readable format, +whereas complex formats like json, csv, json-seq, pairs display the power +readings in microwatts. +.sp +CPC power readings can be retrieved only when the required authorization was +set for the LPAR. Enable the required authorization by setting "Global +Performance Data" in LPAR's activation profile. +.sp +If the power readings cannot be retrieved, the power readings return an empty +string or null in complex formats, and the power readings are not displayed in +human readable format. +.SH OPTIONS +.PP +\-\-format= +.RS 4 +Retrieve power readings in the following formats: json, csv, +json-seq or pairs. If no format is specified in the command, the output will +default to the human readable format. +.sp +When the format is json, csv, json-seq or pairs, the power readings are +displayed in microwatts. +.RE +.PP +\-d, \-\-delay +.RS 4 +Retrieve power readings after specified delay in seconds has elapsed. +.RE +.PP +\-c , \-\-count= +.RS 4 +Required number of power readings. +.sp +The \-\-count option can only be used in conjunction with \-\-stream or +\-\-delay option. +.RE +.PP +\-s, \-\-stream +.RS 4 +Retrieve power readings in stream mode. A new power reading will be displayed +only after an interval has elapsed since the last power reading request. +The interval is automatically calculated in stream mode. +.sp +The \-\-stream and \-\-delay options are mutually exclusive. +.RE +.PP +\-v, \-\-version +.RS 4 +Print version information. +.RE +.PP +\-h, \-\-help +.RS 4 +Print usage information. +.RE +.SH OUTPUT +.B Iteration +.RS 4 +Iteration number of the current power readings. If the power reading is +requested before the time interval has elapsed, cached power readings might be +returned. The iteration number helps to determine if the cached power readings +are provided. +.RE +.PP +.B Time +.RS 4 +The time at which power readings were taken, expressed in human readable format. +.RE +.PP +.B Time epoch +.RS 4 +The time at which power readings were taken, expressed in epoch time. +.PP +.B sec +.RS 4 +The number of seconds elapsed since the Unix epoch. +.RE +.PP +.B nsec +.RS 4 +The number of nanoseconds elapsed since the last full seconds. +.RE +.RE +.PP +.B Update interval +.RS 4 +Indicates the time interval in nanoseconds after which new power readings are +available. If the power readings is requested before the time interval has +elapsed, cached power readings might be returned. +.RE +.PP +.B CPU +.RS 4 +CPU power reading of a partition. +.RE +.PP +.B Storage +.RS 4 +Storage power reading of a partition. +.RE +.PP +.B I/O +.RS 4 +I/O power reading of a partition. +.RE +.PP +.B Total +.RS 4 +Specifies number of units for all electrical and mechanical components of the +system. +.RE +.PP +.B Unassigned Resources +.RS 4 +Specifies number of units for all types of resources in the standby state or +reserved state at the time the reading was taken. +.RE +.PP +.B Infrastructure +.RS 4 +Specifies number of units for all subsystems in the CPC which do not provide +CPU, storage or I/O resources to partitions. +.RE +.SH "EXAMPLES" +1. Display power readings in human readable format. +.nf +.ft CW +# zpwr +LPAR CPU: 140.00 W +LPAR Storage: 1.72 W +LPAR I/O: 40.00 W + +CPC Total: 15.40 kW +CPC Unassigned Resources: 7.48 kW +CPC Infrastructure: 5.31 kW + +Update interval: 10.00 s +.ft +.fi +.sp 1 +2. Perform two power measurements with a delay of 10 seconds and output the +data in json format. +.nf +.ft CW +# zpwr --format json --delay 10 --count 2 +{ + "meta": { + "api_level": "1", + "version": "2.36.0-build-20250107", + "host": "lpar001", + "time_epoch": "1736316898", + "time": "2025-01-08 07:14:58+0100" + }, + "zpwr": [ + { + "iteration": "0", + "time": "2025-01-08 07:14:58+0100", + "time_epoch_sec": "1736316898", + "time_epoch_nsec": "10935887", + "update_interval": "10000000000", + "lpar": [ + "cpu": "140000000", + "storage": "1719200", + "io": "40000000" + ], + "cpc": [ + "total": "15406000000", + "unassigned_resources": "7578848100", + "infrastructure": "5283946300" + ] + }, + { + "iteration": "1", + "time": "2025-01-08 07:15:08+0100", + "time_epoch_sec": "1736316908", + "time_epoch_nsec": "11113153", + "update_interval": "10000000000", + "lpar": [ + "cpu": "140000000", + "storage": "1719200", + "io": "40000000" + ], + "cpc": [ + "total": "15401000000", + "unassigned_resources": "7569928400", + "infrastructure": "5284866000" + ] + } + ] +} +.ft +.fi +.sp 1 +3. Display power readings in csv format and in stream mode. +.nf +.ft CW +# zpwr --format csv --stream +"iteration","time","time_epoch_sec","time_epoch_nsec","update_interval","cpu","storage","io","total","unassigned_resources","infrastructure" +"0","2025-01-08 07:17:05+0100","1736317025","592784684","10000000000","143000000","1708200","40000000","15550000000","7659162700","5337186700" +"1","2025-01-08 07:17:15+0100","1736317035","592937261","10000000000","143000000","1708200","40000000","15533000000","7650389100","5328960300" +.ft +.fi