libzonestat - zones statistics library
cc [flag ...] file -lzonestat [library... ] #include <zonestat.h>
Functions in this library provide a general purpose mechanism for providing zone related resource usage statistics.
The zonestat library reports system wide and per-zone utilization of physical memory, virtual memory, and CPU resources.
Physical memory usage is reported for both RSS and locked memory. Resident set size (RSS) is the quantity of physical memory that is in use by each zone. Locked memory is physical memory pinned by applications in zones, usually for performance purposes. Physical memory which is locked cannot be paged out to disk when there is memory pressure.
The virtual memory reported is the total memory allocated by each zone. This includes both anonymous memory allocated by processes (heap, stack, anon), system V shared memory, and memory consumed by tmpfs file systems (/tmp). The system's total virtual memory is the sum of its physical memory (RAM) and disk swap devices.
CPU utilization is reported both in terms of total CPU as well as relative to any processor sets. Processor sets can be created by psrset(8), resource pools (poolcfg(8)), and by dedicated CPU resources created via zonecfg(8). It is possible for a zone to consume CPU time in more than one processor set. This can be due a zone's processes being bound to multiple processor sets, or due to an entire zone being rebound from one processor set to another.
For each physical resource, overall usage is reported, as well as system usage, aggregate usage by all zones, and per-zone usage. system usage reflects usage by the system which cannot be attributed to a particular zone, such as resource usage by service threads in the kernel.
In addition to usage of physical resources, libzonestat also reports resource usage relative to each zone's configured resource limits.
This library depends on the zones monitoring service:
svc:/system/zones-monitoring:default
The library will fail to open and read resource usage information if this service is not online. From within a NGZ, the global zone must have an online zones monitoring service for the library to function.
The zs_open(3ZONESTAT) function is used to create a handle to the zones monitoring service. The zs_usage_read(3ZONESTAT) function is used to read the current usage information. This usage information can then be inspected using the remaining library functions. There are also library functions for comparing two usage readings. These are the zs_usage_*() functions.
Each usage reading contains usage information on a variety of resource types. The zs_resource_*() functions can be used to access the usage of each resource stored in a usage reading. The following resource types are supported:
The system's online CPUs. This includes all CPUs that on-line or no-intr state.
This resource is an increasing resource, with values reflecting utilization since zs_open() was first called.
The CPU resource in term of ncpus * 100 is retrieved via zs_resource_*_int64(). These values will reflect the quantity of CPUs used since zs_open() was first called.
The zs_resource_total_time(), zs_resource_used_time(), and zs_resource_zone_used_time() functions return increasing utilization values. These values continually increase, starting from zero at the point when zs_open() was first called.
Reports the stolen time for system's online CPUs. The stolen time is supported only by some zone brands. If the stolen time is not supported by the brand, either ZS_LIMIT_NONE (for cpu values) or ZS_PCT_NONE (for percentages) is returned.
The value of stolen time reflects the time when the zone could not run, as the host might be using CPU resources for other purposes. For more information about stolen time, see solaris-kz(7).
The system's physical memory usage in terms of resident pages (RSS).
The system's physical memory usage in terms of locked (unpageable) pages.
Reserved virtual memory. Virtual memory is comprised of the system's RAM and disk swap devices. Virtual memory is reserved when applications allocate memory, such as via brk(2), malloc(3C), mmap(MAP_ANON), or shmget(2).
The amount of space allocated on disk swap devices. This is the amount of memory that is currently paged out to swap devices. Only ZS_USER_ALL and ZS_FREE is available for the disk swap resource (see user options below). libzonestat does not report a disk swap usage breakdown by the system and zones.
The number of lightweight processes allocated. There is no ZS_USER_SYSTEM user for this resource.
The number of processes allocated. This includes zombie processes. There is no ZS_USER_SYSTEM user for this resource.
The total size of all System V shared memory segments created. There is no ZS_USER_SYSTEM user for this resource.
The total number all System V shared memory segments created. There is no ZS_USER_SYSTEM user for this resource.
The total number of System V semaphores created. There is no ZS_USER_SYSTEM user for this resource.
The total number of System V message queues created. There is no ZS_USER_SYSTEM user for this resource.
The total number of syscalls. There is no ZS_USER_FREE user for this resource.
The total number of forks. There is no ZS_USER_FREE user for this resource.
The total number of vforks. There is no ZS_USER_FREE user for this resource.
The total number of fork fails. There is no ZS_USER_FREE user for this resource.
The total number of execs. There is no ZS_USER_FREE user for this resource.
The total number of semops. There is no ZS_USER_FREE user for this resource.
The number of read calls. There is no ZS_USER_FREE user for this resource.
The number of write calls. There is no ZS_USER_FREE user for this resource.
The number bytes read by rdwr(). There is no ZS_USER_FREE user for this resource.
The number bytes written by rdwr(). There is no ZS_USER_FREE user for this resource.
The number of pathname lookups. There is no ZS_USER_FREE user for this resource.
The following resource properties are defined:
The total number of CPUs.
The system's 1 minute load average.
The system's 5 minute load average.
The system's 15 minute load average.
Each resource has a type defining the unit of measurement that of the data returned. The supported types are:
The resource is defined as time. A timestruc_t is used to store the value in seconds and nanoseconds.
The resource is defined as an integer number representing a quantity. A uint64_t is used to store the value.
The resource is defined as an integer number of bytes. A uint64_t is used to store the value.
Resource usage can be queried for the following users:
Total resource used.
Resource used by the system. This is any resource usage which cannot be associated with a particular zone, such as resource usage by the kernel.
Aggregate resource used by all zones.
Resource not used.
See individual resource descriptions above for user restrictions on individual resources.
Each usage read via zs_usage_read() contains a list of the zone which are running at the time the usage was read. The zs_zone_*() functions provide access to this list of zones, and to the following properties and resource limits for each zone:
The name of the zone. The string will be up to length ZS_ZONENAME_MAX, including the null terminating character.
The zoneid of the zone.
The IP networking type of the zone. This property will have a value of ZS_IPTYPE_SHARED or ZS_IPTYPE_EXCLUSIVE.
The CPU type of the zone. If the zone has a dedicated CPU resource configured, the CPU type will be ZS_CPUTYPE_DEDICATED. Otherwise the CPU type will be ZS_CPUTYPE_SHARED.
The default scheduling class of the zone.
A list of scheduling classes that are found running inside the zone. The value is a set of flags defined as ZS_SCHED_*. If the ZS_SCHED_CONFLICT flag is included, this means the zone has processes in both FSS, as well as TS, IA, or FX, with priority less than 60. The behavior of the FSS class is undefined in this scenario.
The quantity of CPU shares allocated to zone. If the zone has no processes running in the FSS scheduling class, the value will be ZS_LIMIT_NONE. If the zone has processes running in FSS, the value will be between 0 and ZS_SHARES_UNLIMITED, inclusive.
The name of the resource pool to which the zone is bound. If resource pools are not enabled, the value will be pool_default.
The name of the pool pset to which the zone is bound. If resource pools are disabled, the value will be pset_default.
Each usage reading contains usage information on a variety of resource types. The zs_resource_*() functions can be used to access the usage of each resource stored in a usage reading. The following resource types are supported:
Each zone can be limited to a decimal number of CPUs worth of CPU time. The value of the CPU cap is 100 times the number of CPUs to cap. For instance, a CPU cap of 50 is a limit to 0.50 CPUs worth of CPU time.
The usage values for this limit are increasing, starting at zero when zs_open() is first called.
The limit in term of ncpus * 100 is retrieved via zs_zone_limit_int64() and zs_zone_limit_used_uint64(). These values will reflect the quantity of CPUs used since zs_open() was first called.
The amount of CPU time available and used under the limit is retrieved via zs_zone_limit_time() and zs_zone_limit_used_time(). These functions return increasing utilization values. These values continually increase, starting from zero at the point when zs_open() was first called, or from the point when the zone or pset was first booted or created.
Each zone's limit of resident pages of physical memory in bytes.
Each zone's limit of locked pages of physical memory in bytes.
The zone's limit of virtual memory (swap) reservation in bytes. Each zone's swap reservations are backed by both physical memory and disk swap devices.
The number of lightweight processes (lwps) executing in each zone.
The number of processes executing in each zone, including zombie processes, which are exited processes that have not been waited upon by their parent process.
Each zone's total size of all System V shared memory segments created. There is no ZS_USER_SYSTEM() user for this resource.
Each zone's number all System V shared memory segments created. There is no ZS_USER_SYSTEM() user for this resource.
Each zone's number of System V semaphores created. There is no ZS_USER_SYSTEM() user for this resource.
Each zone's total number of System V message queues created. There is no ZS_USER_SYSTEM user for this resource.
Each zone's total number of lofi devices created. See lofiadm(8).
Each usage read via zs_usage_read() contains a list of the processor sets which existed at the time the usage was read. The zs_pset_t*() functions provide access to this list of pset, and to the following properties defined for each pset:
The name of the processor set. The string will be up to length ZS_PSETNAME_MAX, including the null terminating character.
The psetid of the processor set.
If the processor set was created by a zonecfg add dedicated-CPU resource, the type will be ZS_CPUTYPE_DEDICATED. Otherwise, the type is ZS_CPUTYPE_SHARED.
The number CPUs assigned to the processor set.
The number of CPUs assigned to the processor set which are in the on-line or no-intr state.
The minimum number of CPUs that the system may assign to the processor set.
The maximum number of CPUs that the system may assign to the processor set.
The total number of CPU shares of all zones running in the processor set.
A list of scheduling classes that are found running inside the processor set. The value is a set of flags defined as ZS_SCHED_*. If the ZS_SCHED_CONFLICT flag is included, this means the zone has processor set has processes both in FSS, as well as TS, IA, or FX, with priority less than 60. The behavior of the FSS class is undefined in this scenario.
The system's 1 minute load average.
The system's 5 minute load average.
The system's 15 minute load average.
In addition to properties, the zs_pset_used_*() functions provide total time, CPU used, percent used, and CPU time used of each processor set.
Each processor set can be in use by one or more zones. The zs_pset_zone_*() functions provide per-zone usage information for each pset. It is also possible for an individual zone to be using more than one pset. In this case, the given zone will appear in the per-zone usage information for every pset that it is using.
The following properties exist on each per-zone pset usage:
A list of scheduling classes that are found running within the zone inside the given pset. The value is a set of flags defined as ZS_SCHED_*. If the ZS_SCHED_CONFLICT flag is included, this means the zone has processes in TS, IA, or FX, with priority less than 60, while other zones using the processor set are using FSS.
The number of CPU shares of the zone running in the pset. The value will be ZS_LIMIT_NONE if the zone is not running in the FSS scheduling class. If the zone has processes running in FSS in the processor set, the value will be between 0 and ZS_SHARES_UNLIMITED , inclusive.
The CPU cap of the zone. See ZS_LIMIT_CPU for description.
In addition to properties, the zs_pset_zone_used_*() functions provide to per-zone CPUs used, percent used, and CPU time of each processor set. Percent of CPU share, and percent of CPU share used is also provided:
The percentage of the pset used by a zone. The value is pct * 100, with 10000 meaning 100%.
The percentage of a zone's CPU cap that is used by the zone in this pset. The value is pct * 100, with 10000 meaning 100%.
Of the total CPU shares of all zones running in the pset, the percent that belong to this zone. The value is pct * 100, with 10000 meaning 100%.
For example, if there are four zones in the pset, each with 10 CPU shares, each would have a value of 2500 (25% * 100).
Of a zones CPU shares, the percent of them that are being used by the zone's CPU utilization in this pset. The value is pct * 100, with 10000 meaning 100%. This value can exceed 100% (10000) as a zone can use more that its CPU share if there is no contention by other zones.
The shared object libzonestat.so.1 provides the public interfaces defined below. See intro(3) for additional information on shared object interfaces.
|
shared object
64-bit shared object
See attributes(7) for descriptions of the following attributes:
|
The zs_open() function is MT-Safe. The remaining zs_*() functions are MT-Safe with the exception that only one thread may actively use a zs_ctl_t object at any time. Synchronization is left to the application.
zonestat(1), libpool(3LIB), zs_open(3ZONESTAT), zs_property(3ZONESTAT), zs_pset(3ZONESTAT), zs_pset_zone(3ZONESTAT), zs_resource(3ZONESTAT), zs_usage(3ZONESTAT), zs_zone(3ZONESTAT), attributes(7), resource-controls(7), pooladm(8), psrset(8), rcapadm(8), swap(8), zoneadm(8), zonecfg(8), zonestatd(8)
The service svc:/system/zones-monitoring:default must be enabled in the global zone in order for zs_open() and zs_read_usage() to succeed. This requirement exists for use of libzonestat in both the global zone and non-global zones.