1 .\"
2 .\" This file and its contents are supplied under the terms of the
3 .\" Common Development and Distribution License ("CDDL"), version 1.0.
4 .\" You may only use this file in accordance with the terms of version
5 .\" 1.0 of the CDDL.
6 .\"
7 .\" A full copy of the text of the CDDL should have accompanied this
8 .\" source. A copy of the CDDL is also available via the Internet at
9 .\" http://www.illumos.org/license/CDDL.
10 .\"
11 .\" Copyright (c) 2010, Oracle and/or its affiliates. All rights reserved.
12 .\" Copyright 2019 OmniOS Community Edition (OmniOSce) Association.
13 .\"
14 .Dd April 04, 2019
15 .Dt zonestat 1
16 .Os
17 .Sh NAME
18 .Nm zonestat
19 .Nd report active zone statistics.
20 .Sh SYNOPSIS
21 .Nm
22 .Op Fl z Ar zonelist
23 .Op Fl r Ar reslist
24 .Op Fl n Ar namelist
25 .Op Fl T Ar u Ns | Ns Ar d Ns | Ns Ar i
26 .Op Fl R Ar reports
27 .Op Fl q
28 .Op Fl p Oo Fl P Ar lines Oc
29 .Op Fl S Ar cols
30 .Ar interval
31 .Oo Ar duration
32 .Oo Ar report
33 .Oc Oc
34 .Sh DESCRIPTION
35 The
36 .Nm
37 utility reports on the cpu, memory, and resource control utilization of the
38 currently running zones.
39 Each zone's utilization is reported both as a percentage of system resources
40 and the zone's configured limits.
41 .Pp
42 The
43 .Nm
44 utility prints a series of interval reports at the specified interval.
45 It optionally also prints one or more summary reports at a specified interval.
46 .Pp
47 The default output is a summary of cpu, physical, and virtual memory
48 utilization.
49 The -r option can be used to choose detailed output for specific resources.
50 .Pp
51 The following options are supported:
52 .Bl -tag -width Ds
53 .It Fl z Ar zonename Ns Oo Ar ,zonename Oc
54 Specify a list of zones on which to report.
55 By default all zones are reported.
56 In addition to a comma-separated list, multiple
57 .Fl z
58 options can be specified to report on a set of zones.
59 The output will include any resources which have usage by the specified zone(s).
60 .It Fl r Ar resource Ns Oo Ar ,resource Oc
61 Specify resource types on which to report.
62 The available resources are:
63 .Bd -ragged -offset indent
64 .Em physical-memory ,
65 .Em virtual-memory ,
66 .Em locked-memory ,
67 .Em processor-sets ,
68 .Em processes ,
69 .Em lwps ,
70 .Em shm-memory ,
71 .Em shm-ids ,
72 .Em sem-ids ,
73 .Em msg-ids ,
74 .Em lofi
75 .Ed
76 .Pp
77 The following nicknames can also be specified as resource names:
78 .Bl -tag -width indent
79 .It Em summary
80 A summary of cpu, physical-memory, and virtual memory usage.
81 .It Em memory
82 physical-memory, virtual-memory, and locked memory.
83 .It Em psets
84 processor-sets
85 .It Em default-pset
86 The default pset only.
87 .It Em limits
88 processes, lwps, lofi
89 .It Em sysv
90 shm-memory, shm-ids, sem-ids msg-ids
91 .It Em all
92 all resource types.
93 .El
94 .Pp
95 By default the summary resource is printed.
96 .Pp
97 In addition to a comma-separated list, multiple
98 .Fl r
99 options can be specified to report on a set of resources types.
100 .Pp
101 The system's cpus can be partitioned into processor sets
102 (psets) By default, all cpus are in a single pset named
103 .Em pset_default .
104 .Pp
105 Memory is not partition-able into sets.
106 The zonestat utility output for these resources will show them as named
107 .Em mem_default
108 and
109 .Em vm_default .
110 .Pp
111 The
112 .Em all
113 resource specifies that all resource types should be reported.
114 .It Fl n Ar name Ns Oo Ar ,name Oc
115 Specify a list resource names on which to report.
116 For pset resources, this is the name of the processor set.
117 For physical-memory, locked-memory, and virtual-memory resources,
118 the only names are
119 .Em mem_default
120 and
121 .Em vm_default .
122 .Pp
123 Dedicated-cpu processor sets can be specified by their pset
124 name, or by just their zonename.
125 .Pp
126 Processor sets created by psrset can be specified by their pool
127 pset name, or just by their psetid.
128 .Pp
129 In addition to a comma-separated list, multiple
130 .Fl n
131 options can be specified to report on a set of resources.
132 .It Fl T Ar u Ns | Ns Ar d Ns | Ns Ar i
133 Include timestamp of each report.
134 The following formats are supported:
135 .Bl -tag -width indent
136 .It u
137 A printed representation of the internal representation of time;
138 see
139 .Xr time 2 .
140 This is also known as unix time.
141 .It d
142 Standard date format; see
143 .Xr date 1 .
144 This option is not valid with
145 .Fl p .
146 .It i
147 Time formatted as the ISO 8601 compliant format:
148 .D1 YYYYMMDDThhmmssZ
149 .El
150 .It Fl R Ar report Ns Oo Ar ,report Oc
151 Print a summary report.
152 The supported report types are described below.
153 In addition to a comma-separated list, multiple
154 .Fl R
155 options may be specified for a set of summary reports.
156 .Bl -tag -width indent
157 .It total
158 Prints a summary report detailing the following for each resource:
159 .Bl -tag -width indent
160 .It psets
161 Total cpu used since start of command invocation.
162 The percent used for each zone includes time that a zone was not running.
163 For instance, if a zone used 100% of the cpu while it was running, but the zone
164 was halted for half of the intervals, then the summary report will show the
165 zone used 50% of the cpu time.
166 .It memory, limits, sysv
167 Average resource used of all intervals reported since command invocation.
168 This average factors in intervals in which a zone was not running.
169 For example if a zone used on average of 100M of physical memory while it was
170 running, and was only running for half the intervals, then the summary report
171 will show that the zone used 50M of physical memory on average.
172 .El
173 .It average
174 Similar to
175 .Em total ,
176 but only intervals in which a zone is running are factored in.
177 For example, if a zone was only running for a single interval, and during that
178 interval, the zone used 200M of virtual memory, then its average
179 virtual-memory will be 200M, regardless of the number of intervals reported
180 before the summary report.
181 .It high
182 Print a summary report detailing the highest usage of each resource and zone
183 during any interval of the zonestat utility invocation.
184 .El
185 .It Fl S Ar col Ns Oo Ar ,col Oc
186 Sort zones utilizing each resource.
187 The following sorting columns can be specified.
188 .Bl -tag -width indent
189 .It name
190 Sort alphanumerically by zone name.
191 .It used
192 Sort by quantity of resource used.
193 .It cap
194 Sort by configured cap.
195 .It pcap
196 Sort by percent of cap used.
197 .It shr
198 Sort by allocated share.
199 .It pshru
200 Sort by percent of share used.
201 .El
202 .Pp
203 By default, output is sorted by quantity of resource used.
204 .It Fl q
205 Only print summary reports (requires
206 .Fl R ) .
207 All interval reports are omitted.
208 .It Fl p
209 Print output in stable, machine-parsable format.
210 Individual fields will be delimited with :.
211 The line format is:
212 .Pp
213 .D1 <report type>:<resource>:<field>[:<field>]*
214 .Pp
215 If
216 .Fl T
217 is specified each line is prefixed with a timestamp:
218 .Pp
219 .D1 <timestamp>:<report type>:<resource>:<field>[:<field>]*
220 .Pp
221 The report types are:
222 .Bd -ragged -offset indent
223 .Em report-total ,
224 .Em report-average ,
225 .Em report-high ,
226 .Em interval
227 .Ed
228 .Pp
229 The resource types are:
230 .Bd -ragged -offset indent
231 .Em header ,
232 .Em footer ,
233 .Em summary ,
234 .Em physical-memory ,
235 .Em virtual-memory ,
236 .Em locked-memory ,
237 .Em processor-set ,
238 .Em processes ,
239 .Em lwps ,
240 .Em sysv-shared-memory ,
241 .Em sysv-shmids ,
242 .Em sysv-semids ,
243 .Em sysv-msgids ,
244 .Em lofi
245 .Ed
246 .Pp
247 The
248 .Em header
249 resource is a special resource used to state the beginning of an interval or
250 summary report.
251 All output lines between header resources belong to the same report.
252 Each header has a matching footer.
253 .Pp
254 The remaining fields are resource type specific.
255 See the zonestat utility output for details.
256 .Pp
257 All existing output fields are stable.
258 Future versions may introduce new report and resource types.
259 Future versions may also add additional new fields to the end of existing
260 output lines.
261 .It Fl P Ar line Ns Oo Ar ,line Oc
262 For parsable output, specify lines to output in parsable output.
263 One or more of the following line types can be chosen:
264 .Bl -tag -width indent
265 .It resource
266 The lines describing each resource.
267 .It total
268 The total utilization of each resource.
269 .It system
270 The utilization of each resource by the system.
271 This includes the kernel, and any resource consumption not contributable to a
272 specific zone.
273 When zonestat is run from within a non-global-zone, this value will be the
274 aggregate resource consumed by the system and all other zones.
275 .It zones
276 Lines detailing the per-zone utilization of each resource.
277 .It header, footer
278 Each interval and summary report has a header, which prints details such
279 as the interval and count information.
280 After each report, any footer is also printed
281 .El
282 .El
283 .Ss OPERANDS
284 .Bl -tag -width indent
285 .It interval
286 Specifies the length in seconds to pause between each interval report.
287 An interval of
288 .Em default
289 will use the configured interval of the zones
290 monitoring service (see
291 .Xr zonestatd 1m .)
292 .Pp
293 Interval is required.
294 An interval of zero is not permitted.
295 The interval can be specified as [nh][nm][ns], such as 10s or 1m.
296 .It duration
297 Specifies the number of intervals to report.
298 Defaults to infinity if not specified.
299 The command duration is (interval * duration).
300 A duration of zero is invalid.
301 A value of
302 .Em inf
303 can also be specified to explicitly choose infinity.
304 .Pp
305 Duration can also be specified as [nh][nm][ns].
306 In this case, duration will be interpreted as the duration of execution time.
307 The actual duration will be rounded up to the nearest multiple of the interval.
308 .It report
309 Specify the summary report period.
310 For instance, a report of 4 would produce reports every 4 intervals.
311 If the command duration is not a multiple of report, then the last report will
312 be of any remaining intervals.
313 .Pp
314 Report can also be specified as [nh][nm][ns].
315 In this case, reports will be output at the specified time period, rounded up
316 to the nearest interval.
317 If the command duration is not a multiple of report, then the last report will
318 be of any remaining intervals.
319 .Pp
320 Requires
321 .Fl R .
322 If
323 .Fl R
324 is specified and report is not, the report period will be the entire command
325 duration, producing the specified reports at the end of execution.
326 .El
327 .Ss OUTPUT
328 The following list defines the column heading of the command output:
329 .Bl -tag -width indent
330 .It SYSTEM-MEMORY
331 The total amount of memory available on the physical host.
332 .It SYSTEM-LIMIT
333 The maximum amount of resource available on the physical host.
334 .It CPUS
335 The number of cpus allocated to a processor set.
336 .It ONLINE
337 Of the cpus allocated to a processor set, the number of cpus
338 which can execute processes.
339 .It MIN/MAX
340 The minimum and maximum number of cpus which may be allocated
341 to the processor set by the system.
342 .It ZONE
343 The zone using the resource.
344 In addition to zone names, this column may also contain:
345 .Bl -tag -width indent
346 .It [total]
347 The total quantity of resource used system-wide.
348 .It [system]
349 The quantity of resource used by the kernel or in a manner not associated with
350 any particular zone.
351 .Pp
352 When zonestat is used within a non-global zone, [system] designates the
353 aggregate resource used by the system and by all other zones.
354 .El
355 .It USED
356 The amount of resource used.
357 .It PCT
358 The amount of resource used as a percent of the total resource.
359 .It %PART
360 The amount of cpu uses as a percentage of the total cpu in a processor-set to
361 which the zone is bound.
362 A zone can only have processes bound to multiple processor sets if it is the
363 global zone, or if psrset(1m) psets are used.
364 If multiple binding are found for a zone, its %PART will be the fraction used
365 of all bound psets.
366 For [total] and [system], %PART is the percent used of all cpus on the system.
367 .It CAP
368 If a zone is configured to have a cap on the given resource, the cap will be
369 displayed in this column.
370 .It %CAP
371 The amount of resource used as a percent of zone's configured cap.
372 .It SHRS
373 The number of shares allocated to the zone.
374 For the [total] row, this will be the total number of shares allocated to all
375 zones sharing the resource.
376 .Pp
377 If a zone is not configured to use shares, and is sharing a
378 resource with other zones that are configured to use shares,
379 this column will contain
380 .Em no-fss
381 for the zone.
382 .It %SHR
383 The fraction of the total shares allocated to the zone.
384 For instance, if 2 zones share a processor set, each with 10 shares, then each
385 zone will have a %SHR of 50%.
386 .It %SHRU
387 Of the share allocated to the zone, the fraction of resource
388 used.
389 Zones using all of their share will have a %SHRU of 100%.
390 Because shares are only enforced when there is resource contention, it is
391 possible for a zone to have a %SHRU in excess of 100%.
392 .El
393 .Sh IMPLEMENTATION NOTES
394 The zonestat utility depends on the zones monitoring service:
395 .Pp
396 .D1 svc/system/zonestat:default
397 .Pp
398 If the zonestat service is stopped while the zonestat utility is running, the
399 zonestat command invocation will quit without printing additional reports.
400 .Pp
401 The reports will be printed if zonestat is interrupted (by ctrl-c, SIGINT)
402 before reaching the next report period.
403 .Sh EXIT STATUS
404 .Ex -std
405 .Bl -tag -width indent
406 .It 0
407 Successful completion.
408 .It 1
409 An error occurred.
410 .It 2
411 Invalid usage.
412 .It 3
413 svc:system/zones_monitoring:default not running or not responding.
414 .El
415 .Sh EXAMPLES
416 Example 1: Summary of cpu and memory utilization every 5 seconds.
417 .Bd -literal
418 # zonestat 5 1
419 SUMMARY
420 -----CPU------------- ----PHYSICAL--- ----VIRTUAL----
421 ZONE USED %PART %CAP %SHRU USED PCT %CAP USED PCT %CAP
422 [total] 9.74 30% - - 7140M 21% - 10.6G 22% -
423 [system] 0.28 0.8% - - 6535M 19% - 10.4G 21% -
424 global 9.10 28% - - 272M 0.8% - 366M 0.7% -
425 zoneA 0.32 1.0% - - 256M 0.7% - 265M 0.5% -
426 zoneB 0.00 0.0% - - 77.6M 0.2% - 71.1M 0.1% -
427 .Ed
428 .Pp
429 Example 2: Using parsable output, fetching only zone usages.
430 .Pp
431 The following command will produce parsable output, printing one
432 line per zone using each pset resource for a 5 second interval.
433 .Bd -literal
434
435 # zonestat -p -P zones -r psets 5 1
436
437 .Ed
438 .Pp
439 Example 3: Report on the default pset.
440 .Pp
441 The following command will report on the default pset once a second
442 for one minute.
443 .Bd -literal
444
445 # zonestat -r default-pset 1 1m
446
447 .Ed
448 .Pp
449 Example 4: Report total and high utilization.
450 .Pp
451 The following command monitors silently at a 10 second interval
452 for 24 hours, producing a total and high report every 1 hour.
453 .Bd -literal
454
455 # zonestat -q -R total,high 10s 24h 1h
456
457 .Ed
458 .Sh INTERFACE STABILITY
459 Command invocation and parsable output is Committed.
460 Human readable output (default output) is uncommitted.
461 .Sh SECURITY
462 When run from within a non-global zone (NGZ), only processor sets
463 visible to the NGZ are reported.
464 The NGZ output will include all of other system resources, such as memory and
465 limits.
466 .Pp
467 For all reported resources, the NGZ's usage will be output.
468 Usage of each resource by the system, global zone, and all other
469 zones, will be reported as used by
470 .Em system .
471 .Sh SEE ALSO
472 .Xr date 1 ,
473 .Xr pooladm 1m ,
474 .Xr poolcfg 1m ,
475 .Xr prctl 1m ,
476 .Xr rcapadm 1m ,
477 .Xr zoneadm 1m ,
478 .Xr zonecfg 1m ,
479 .Xr zonestatd 1m ,
480 .Xr libzonestat 3lib ,
481 .Xr timezone 4 ,
482 .Xr privileges 5 ,
483 .Xr resource_controls 5 ,
484 .Xr zones 5