Tribblix: manual page: zonestat.1

ZONESTAT(1) User Commands ZONESTAT(1)

NAME

zonestat - report active zone statistics

SYNOPSIS

zonestat [-z zonelist] [-r reslist] [-n namelist] [-T u|d|i]
[-R reports] [-q] [-p [-P lines]] [-S cols] interval [duration
[report]]

DESCRIPTION

The zonestat 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.

The zonestat utility prints a series of interval reports at the
specified interval. It optionally also prints one or more summary
reports at a specified interval.

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.

The following options are supported:

-z zonename[,zonename...]
Specify a list of zones on which to report. By default all
zones are reported. In addition to a comma-separated list,
multiple -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).

-r resource[,resource...]
Specify resource types on which to report. The available
resources are:

physical-memory, virtual-memory, locked-memory,
processor-set, processes, lwps, shm-memory, shm-ids,
sem-ids, msg-ids, lofi

The following nicknames can also be specified as resource
names:

summary
A summary of cpu, physical-memory, and virtual-memory
usage.

memory physical-memory, virtual-memory, and locked-memory.

psets processor-set

default-pset
The default pset only.

limits processes, lwps, and lofi

sysv shm-memory, shm-ids, sem-ids, and msg-ids

all all resource types.

By default the summary resource is printed.

In addition to a comma-separated list, multiple -r options can
be specified to report on a set of resources types.

The system's cpus can be partitioned into processor sets
(psets) By default, all cpus are in a single pset named
pset_default.

Memory is not partition-able into sets. The zonestat utility
output for these resources will show them as named mem_default
and vm_default.

The all resource specifies that all resource types should be
reported.

-n name[,name]
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 mem_default and vm_default.

Dedicated-cpu processor sets can be specified by their pset
name, or by just their zonename.

Processor sets created by psrset can be specified by their pool
pset name, or just by their psetid.

In addition to a comma-separated list, multiple -n options can
be specified to report on a set of resources.

-T u|d|i
Include the timestamp of each report. The following formats
are supported:

u A printed representation of the internal representation
of time; see time(2). This is also known as unix time.

d Standard date format; see date(1). This option is not
valid with -p.

i Time formatted as the ISO 8601 compliant format:
YYYYMMDDThhmmssZ

-R report[,report]
Print a summary report. The supported report types are
described below. In addition to a comma-separated list,
multiple -R options may be specified for a set of summary
reports.

total Prints a summary report detailing the following for
each resource:

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.

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.

average
Similar to 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.

high Print a summary report detailing the highest usage of
each resource and zone during any interval of the
zonestat utility invocation.

-S col[,col]
Sort zones utilizing each resource. The following sorting
columns can be specified.

name Sort alphanumerically by zone name.

used Sort by quantity of resource used.

cap Sort by configured cap.

pcap Sort by percent of cap used.

shr Sort by allocated share.

pshru Sort by percent of share used.

By default, output is sorted by quantity of resource used.

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.

-q Only print summary reports (requires -R). All interval reports
are omitted.

-p Print output in stable, machine-parsable format. Individual
fields will be delimited with :. The line format is:

<report type>:<resource type>:<field>[:<field>]*

If -T is specified each line is prefixed with a timestamp:

<timestamp>:<report type>:<resource
type>:<field>[:<field>]*

The report types are:

report-total, report-average, report-high, interval

The resource types are:

header, footer, summary, physical-memory, virtual-memory,
locked-memory, processor-set, processes, lwps,
shm-memory, shm-ids, sem-ids, msg-ids, lofi

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

The remaining fields are resource type specific. See the
zonestat utility output for details.

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.

-P line[,line]
For parsable output, specify lines to output in parsable
output. One or more of the following line types can be chosen:

resource
The lines describing each resource.

total The total utilization of each resource.

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.

zones Lines detailing the per-zone utilization of each
resource.

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

OPERANDS

interval
Specifies the length in seconds to pause between each interval
report. An interval specified as the textual value default
will use the configured interval of the zones monitoring
service - see zonestatd(8).

Interval is required. An interval of zero is not permitted.
The interval can be specified as [nh][nm][ns], such as 10s or
1m.

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 inf can also be specified to
explicitly choose infinity.

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.

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.

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.

Requires -R. If -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.

OUTPUT

The column headings in the output have the following meanings:

SYSTEM-MEMORY
The total amount of memory available on the physical host.

SYSTEM-LIMIT
The maximum amount of resource available on the physical host.

CPUS The number of cpus allocated to a processor set.

ONLINE Of the cpus allocated to a processor set, the number of cpus
which can execute processes.

MIN/MAX
The minimum and maximum number of cpus which may be allocated
to the processor set by the system.

ZONE The zone using the resource. In addition to zone names, this
column may also contain:

[total]
The total quantity of resource used system-wide.

[system]
The quantity of resource used by the kernel or in a
manner not associated with any particular zone.

When zonestat is used within a non-global zone,
[system] designates the aggregate resource used by the
system and by all other zones.

USED The amount of resource used.

PCT The amount of resource used as a percent of the total resource.

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

CAP If a zone is configured to have a cap on the given resource,
the cap will be displayed in this column.

%CAP The amount of resource used as a percent of zone's configured
cap.

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.

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 no-fss for the zone.

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

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

IMPLEMENTATION NOTES

The zonestat utility depends on the zones-monitoring service:

svc:/system/zones-monitoring:default

If the zones-monitoring service is stopped while the zonestat utility
is running, the zonestat command invocation will quit without printing
additional reports.

The reports will be printed if zonestat is interrupted (by ctrl-c,
SIGINT) before reaching the next report period.

EXIT STATUS

The zonestat utility exits 0 on success, and >0 if an error occurs.

0 Successful completion.

1 An error occurred.

2 Invalid usage.

3 The svc:/system/zones-monitoring:default service is not running
or not responding.

EXAMPLES

Example 1: Summary of cpu and memory utilization every 5 seconds.

# 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% -

Example 2: Using parsable output, fetching only zone usages.

The following command will produce parsable output, printing one line
per zone using each pset resource for a 5 second interval.

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

Example 3: Report on the default pset.

The following command will report on the default pset once a second for
one minute.

# zonestat -r default-pset 1 1m

Example 4: Report total and high utilization.

The following command monitors silently at a 10 second interval for 24
hours, producing a total and high report every 1 hour.

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

INTERFACE STABILITY

Command invocation and parsable output is Committed. Human readable
output (default output) is uncommitted.

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.

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