man/man1/zonestat.1

.\"
.\" This file and its contents are supplied under the terms of the
.\" Common Development and Distribution License ("CDDL"), version 1.0.
.\" You may only use this file in accordance with the terms of version
.\" 1.0 of the CDDL.
.\"
.\" A full copy of the text of the CDDL should have accompanied this
.\" source.  A copy of the CDDL is also available via the Internet at
.\" http://www.illumos.org/license/CDDL.
.\"
.\" Copyright (c) 2010, Oracle and/or its affiliates. All rights reserved.
.\" Copyright 2019 OmniOS Community Edition (OmniOSce) Association.
.\" Copyright 2023 Peter Tribble.
.\"
.Dd February 18, 2023
.Dt ZONESTAT 1
.Os
.Sh NAME
.Nm zonestat
.Nd report active zone statistics
.Sh SYNOPSIS
.Nm
.Op Fl z Ar zonelist
.Op Fl r Ar reslist
.Op Fl n Ar namelist
.Op Fl T Ar u Ns | Ns Ar d Ns | Ns Ar i
.Op Fl R Ar reports
.Op Fl q
.Op Fl p Oo Fl P Ar lines Oc
.Op Fl S Ar cols
.Ar interval
.Oo Ar duration
.Oo Ar report
.Oc Oc
.Sh DESCRIPTION
The
.Nm
utility reports on the cpu, memory, and resource control utilization of the
currently running zones.
Each zone's utilization is reported both as a percentage of system resources
and the zone's configured limits.
.Pp
The
.Nm
utility prints a series of interval reports at the specified interval.
It optionally also prints one or more summary reports at a specified interval.
.Pp
The default output is a summary of cpu, physical, and virtual memory
utilization.
The -r option can be used to select the specific resources to be shown in
the output.
.Pp
The following options are supported:
.Bl -tag -width Ds
.It Fl z Ar zonename Ns Oo Ar ,zonename Ns ... Oc
Specify a list of zones on which to report.
By default all zones are reported.
In addition to a comma-separated list, multiple
.Fl z
options can be specified to report on a set of zones.
The output will include any resources which have usage by the specified zone(s).
.It Fl r Ar resource Ns Oo Ar ,resource Ns ... Oc
Specify resource types on which to report.
The available resources are:
.Bd -ragged -offset indent
.Em physical-memory ,
.Em virtual-memory ,
.Em locked-memory ,
.Em processor-set ,
.Em processes ,
.Em lwps ,
.Em shm-memory ,
.Em shm-ids ,
.Em sem-ids ,
.Em msg-ids ,
.Em lofi
.Ed
.Pp
The following nicknames can also be specified as resource names:
.Bl -tag -width indent
.It Em summary
A summary of cpu, physical-memory, and virtual-memory usage.
.It Em memory
physical-memory, virtual-memory, and locked-memory.
.It Em psets
processor-set
.It Em default-pset
The default pset only.
.It Em limits
processes, lwps, and lofi
.It Em sysv
shm-memory, shm-ids, sem-ids, and msg-ids
.It Em all
all resource types.
.El
.Pp
By default the summary resource is printed.
.Pp
In addition to a comma-separated list, multiple
.Fl r
options can be specified to report on a set of resources types.
.Pp
The system's cpus can be partitioned into processor sets
(psets)  By default, all cpus are in a single pset named
.Em pset_default .
.Pp
Memory is not partition-able into sets.
The zonestat utility output for these resources will show them as named
.Em mem_default
and
.Em vm_default .
.Pp
The
.Em all
resource specifies that all resource types should be reported.
.It Fl n Ar name Ns Oo Ar ,name Oc
Specify a list of resource names on which to report.
For pset resources, this is the name of the processor set.
For physical-memory, locked-memory, and virtual-memory resources,
the only names are
.Em mem_default
and
.Em vm_default .
.Pp
Dedicated-cpu processor sets can be specified by their pset
name, or by just their zonename.
.Pp
Processor sets created by psrset can be specified by their pool
pset name, or just by their psetid.
.Pp
In addition to a comma-separated list, multiple
.Fl n
options can be specified to report on a set of resources.
.It Fl T Ar u Ns | Ns Ar d Ns | Ns Ar i
Include the timestamp of each report.
The following formats are supported:
.Bl -tag -width indent
.It u
A printed representation of the internal representation of time;
see
.Xr time 2 .
This is also known as unix time.
.It d
Standard date format; see
.Xr date 1 .
This option is not valid with
.Fl p .
.It i
Time formatted as the ISO 8601 compliant format:
.D1     YYYYMMDDThhmmssZ
.El
.It Fl R Ar report Ns Oo Ar ,report Oc
Print a summary report.
The supported report types are described below.
In addition to a comma-separated list, multiple
.Fl R
options may be specified for a set of summary reports.
.Bl -tag -width indent
.It total
Prints a summary report detailing the following for each resource:
.Bl -tag -width indent
.It psets
Total cpu used since start of command invocation.
The percent used for each zone includes time that a zone was not running.
For instance, if a zone used 100% of the cpu while it was running, but the zone
was halted for half of the intervals, then the summary report will show the
zone used 50% of the cpu time.
.It memory, limits, sysv
Average resource used of all intervals reported since command invocation.
This average factors in intervals in which a zone was not running.
For example if a zone used on average of 100M of physical memory while it was
running, and was only running for half the intervals, then the summary report
will show that the zone used 50M of physical memory on average.
.El
.It average
Similar to
.Em total ,
but only intervals in which a zone is running are factored in.
For example, if a zone was only running for a single interval, and during that
interval, the zone used 200M of virtual memory, then its average
virtual-memory will be 200M, regardless of the number of intervals reported
before the summary report.
.It high
Print a summary report detailing the highest usage of each resource and zone
during any interval of the zonestat utility invocation.
.El
.It Fl S Ar col Ns Oo Ar ,col Oc
Sort zones utilizing each resource.
The following sorting columns can be specified.
.Bl -tag -width indent
.It name
Sort alphanumerically by zone name.
.It used
Sort by quantity of resource used.
.It cap
Sort by configured cap.
.It pcap
Sort by percent of cap used.
.It shr
Sort by allocated share.
.It pshru
Sort by percent of share used.
.El
.Pp
By default, output is sorted by quantity of resource used.
.Pp
The values cpu, physical-memory, and virtual-memory can also be specified as
sort values and determine which of cpu, physical-memory, and virtual-memory
is used as the sort key in the summary output.
.It Fl q
Only print summary reports (requires
.Fl R ) .
All interval reports are omitted.
.It Fl p
Print output in stable, machine-parsable format.
Individual fields will be delimited with :.
The line format is:
.Pp
.D1    <report type>:<resource type>:<field>[:<field>]*
.Pp
If
.Fl T
is specified each line is prefixed with a timestamp:
.Pp
.D1    <timestamp>:<report type>:<resource type>:<field>[:<field>]*
.Pp
The report types are:
.Bd -ragged -offset indent
.Em report-total ,
.Em report-average ,
.Em report-high ,
.Em interval
.Ed
.Pp
The resource types are:
.Bd -ragged -offset indent
.Em header ,
.Em footer ,
.Em summary ,
.Em physical-memory ,
.Em virtual-memory ,
.Em locked-memory ,
.Em processor-set ,
.Em processes ,
.Em lwps ,
.Em shm-memory ,
.Em shm-ids ,
.Em sem-ids ,
.Em msg-ids ,
.Em lofi
.Ed
.Pp
The
.Em header
resource is a special resource used to mark the beginning of an interval or
summary report.
All output lines between header resources belong to the same report.
Each header has a matching footer.
.Pp
The remaining fields are resource type specific.
See the zonestat utility output for details.
.Pp
All existing output fields are stable.
Future versions may introduce new report and resource types.
Future versions may also add additional new fields to the end of existing
output lines.
.It Fl P Ar line Ns Oo Ar ,line Oc
For parsable output, specify lines to output in parsable output.
One or more of the following line types can be chosen:
.Bl -tag -width indent
.It resource
The lines describing each resource.
.It total
The total utilization of each resource.
.It system
The utilization of each resource by the system.
This includes the kernel, and any resource consumption not attributable to a
specific zone.
When zonestat is run from within a non-global-zone, this value will be the
aggregate resource consumed by the system and all other zones.
.It zones
Lines detailing the per-zone utilization of each resource.
.It header, footer
Each interval and summary report has a header, which prints details such
as the interval and count information.
After each report, any footer is also printed
.El
.El
.Ss OPERANDS
.Bl -tag -width indent
.It interval
Specifies the length in seconds to pause between each interval report.
An interval specified as the textual value
.Em default
will use the configured interval of the zones
monitoring service - see
.Xr zonestatd 8 .
.Pp
Interval is required.
An interval of zero is not permitted.
The interval can be specified as [nh][nm][ns], such as 10s or 1m.
.It duration
Specifies the number of intervals to report.
Defaults to infinity if not specified.
The command duration is (interval * duration).
A duration of zero is invalid.
A duration specified as the textual value
.Em inf
can also be specified to explicitly choose infinity.
.Pp
Duration can also be specified as [nh][nm][ns].
In this case, duration will be interpreted as the duration of execution time.
The actual duration will be rounded up to the nearest multiple of the interval.
.It report
Specify the summary report period.
For instance, a report of 4 would produce reports every 4 intervals.
If the command duration is not a multiple of report, then the last report will
be of any remaining intervals.
.Pp
Report can also be specified as [nh][nm][ns].
In this case, reports will be output at the specified time period, rounded up
to the nearest interval.
If the command duration is not a multiple of report, then the last report will
be of any remaining intervals.
.Pp
Requires
.Fl R .
If
.Fl R
is specified and report is not, the report period will be the entire command
duration, producing the specified reports at the end of execution.
.El
.Ss OUTPUT
The column headings in the output have the following meanings:
.Bl -tag -width indent
.It SYSTEM-MEMORY
The total amount of memory available on the physical host.
.It SYSTEM-LIMIT
The maximum amount of resource available on the physical host.
.It CPUS
The number of cpus allocated to a processor set.
.It ONLINE
Of the cpus allocated to a processor set, the number of cpus
which can execute processes.
.It MIN/MAX
The minimum and maximum number of cpus which may be allocated
to the processor set by the system.
.It ZONE
The zone using the resource.
In addition to zone names, this column may also contain:
.Bl -tag -width indent
.It [total]
The total quantity of resource used system-wide.
.It [system]
The quantity of resource used by the kernel or in a manner not associated with
any particular zone.
.Pp
When zonestat is used within a non-global zone, [system] designates the
aggregate resource used by the system and by all other zones.
.El
.It USED
The amount of resource used.
.It PCT
The amount of resource used as a percent of the total resource.
.It %PART
The amount of cpu used as a percentage of the total cpu in a processor-set to
which the zone is bound.
A zone can only have processes bound to multiple processor sets if it is the
global zone, or if psrset(8) psets are used.
If multiple binding are found for a zone, its %PART will be the fraction used
of all bound psets.
For [total] and [system], %PART is the percent used of all cpus on the system.
.It CAP
If a zone is configured to have a cap on the given resource, the cap will be
displayed in this column.
.It %CAP
The amount of resource used as a percent of zone's configured cap.
.It SHRS
The number of shares allocated to the zone.
For the [total] row, this will be the total number of shares allocated to all
zones sharing the resource.
.Pp
If a zone is not configured to use shares, and is sharing a
resource with other zones that are configured to use shares,
this column will contain
.Em no-fss
for the zone.
.It %SHR
The fraction of the total shares allocated to the zone.
For instance, if 2 zones share a processor set, each with 10 shares, then each
zone will have a %SHR of 50%.
.It %SHRU
Of the share allocated to the zone, the fraction of resource
used.
Zones using all of their share will have a %SHRU of 100%.
Because shares are only enforced when there is resource contention, it is
possible for a zone to have a %SHRU in excess of 100%.
.El
.Sh IMPLEMENTATION NOTES
The zonestat utility depends on the zones-monitoring service:
.Pp
.D1 svc:/system/zones-monitoring:default
.Pp
If the zones-monitoring service is stopped while the zonestat utility is
running, the zonestat command invocation will quit without printing additional
reports.
.Pp
The reports will be printed if zonestat is interrupted (by ctrl-c,
.Dv SIGINT )
before reaching the next report period.
.Sh EXIT STATUS
.Ex -std
.Bl -tag -width indent
.It 0
Successful completion.
.It 1
An error occurred.
.It 2
Invalid usage.
.It 3
The svc:/system/zones-monitoring:default service is not running or not
responding.
.El
.Sh EXAMPLES
Example 1:  Summary of cpu and memory utilization every 5 seconds.
.Bd -literal
       # zonestat 5 1
       Collecting data for first interval...
       Interval: 1, Duration: 0:00:05
       SUMMARY         Cpus/Online: 8/8   Physical: 8100M    Virtual: 23.9G
		----------CPU---------- ----PHYSICAL----- -----VIRTUAL-----
	   ZONE  USED %PART  %CAP %SHRU  USED   PCT  %CAP  USED   PCT  %CAP
        [total]  1.22 15.3%     -     - 4206M 51.9%     - 6298M 25.7%     -
       [system]  0.01 0.15%     -     - 2783M 34.3%     - 3905M 15.9%     -
          zoneA  0.99 12.4%     -     - 35.8M 0.44%     - 31.7M 0.12%     -
          zoneB  0.12 1.59%     -     - 18.6M 0.23%     - 12.9M 0.05%     -
         global  0.08 1.08%     -     - 1273M 15.7%     - 2251M 9.19%     -
.Ed
.Pp
Example 2:  Using parsable output, fetching only zone usages.
.Pp
The following command will produce parsable output, printing one
line per zone using each pset resource for a 5 second interval.
.Bd -literal

       # zonestat -p -P zones -r psets 5 1

.Ed
.Pp
Example 3:  Report on the default pset.
.Pp
The following command will report on the default pset once a second
for one minute.
.Bd -literal

       # zonestat -r default-pset 1 1m

.Ed
.Pp
Example 4:  Report total and high utilization.
.Pp
The following command monitors silently at a 10 second interval
for 24 hours, producing a total and high report every 1 hour.
.Bd -literal

       # zonestat -q -R total,high 10s 24h 1h

.Ed
.Sh INTERFACE STABILITY
Command invocation and parsable output is Committed.
Human readable output (default output) is uncommitted.
.Sh SECURITY
When run from within a non-global zone (NGZ), only processor sets
visible to the NGZ are reported.
The NGZ output will include all of other system resources, such as memory and
limits.
.Pp
For all reported resources, the NGZ's usage will be output.
Usage of each resource by the system, global zone, and all other
zones, will be reported as used by
.Em system .
.Sh SEE ALSO
.Xr date 1 ,
.Xr prctl 1 ,
.Xr timezone 5 ,
.Xr privileges 7 ,
.Xr resource_controls 7 ,
.Xr zones 7 ,
.Xr pooladm 8 ,
.Xr poolcfg 8 ,
.Xr rcapadm 8 ,
.Xr zoneadm 8 ,
.Xr zonecfg 8 ,
.Xr zonestatd 8