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