Go to main content

man pages section 3: Library Interfaces and Headers

Exit Print View

Updated: Thursday, June 13, 2019
 
 

libzonestat(3LIB)

Name

libzonestat - zones statistics library

Synopsis

cc [flag ...] file -lzonestat [library... ]
#include <zonestat.h>

Description

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.

Reading Utilization

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.

Resources

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:

ZS_RESOURCE_CPU

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.

ZS_RESOURCE_CPU_STOLEN

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

ZS_RESOURCE_RAM_RSS

The system's physical memory usage in terms of resident pages (RSS).

ZS_RESOURCE_RAM_LOCKED

The system's physical memory usage in terms of locked (unpageable) pages.

ZS_RESOURCE_VM

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

ZS_RESOURCE_DISK_SWAP

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.

ZS_RESOURCE_LWPS

The number of lightweight processes allocated. There is no ZS_USER_SYSTEM user for this resource.

ZS_RESOURCE_PROCESSES

The number of processes allocated. This includes zombie processes. There is no ZS_USER_SYSTEM user for this resource.

ZS_RESOURCE_SHM_MEMORY

The total size of all System V shared memory segments created. There is no ZS_USER_SYSTEM user for this resource.

ZS_RESOURCE_SHM_IDS

The total number all System V shared memory segments created. There is no ZS_USER_SYSTEM user for this resource.

ZS_RESOURCE_SEM_IDS

The total number of System V semaphores created. There is no ZS_USER_SYSTEM user for this resource.

ZS_RESOURCE_MSG_IDS

The total number of System V message queues created. There is no ZS_USER_SYSTEM user for this resource.

ZS_RESOURCE_SYSCALL

The total number of syscalls. There is no ZS_USER_FREE user for this resource.

ZS_RESOURCE_FORK

The total number of forks. There is no ZS_USER_FREE user for this resource.

ZS_RESOURCE_VFORK

The total number of vforks. There is no ZS_USER_FREE user for this resource.

ZS_RESOURCE_FORK_FAIL

The total number of fork fails. There is no ZS_USER_FREE user for this resource.

ZS_RESOURCE_EXEC

The total number of execs. There is no ZS_USER_FREE user for this resource.

ZS_RESOURCE_SEMA

The total number of semops. There is no ZS_USER_FREE user for this resource.

ZS_RESOURCE_READ

The number of read calls. There is no ZS_USER_FREE user for this resource.

ZS_RESOURCE_WRITE

The number of write calls. There is no ZS_USER_FREE user for this resource.

ZS_RESOURCE_READBYTE

The number bytes read by rdwr(). There is no ZS_USER_FREE user for this resource.

ZS_RESOURCE_WRITEBYTE

The number bytes written by rdwr(). There is no ZS_USER_FREE user for this resource.

ZS_RESOURCE_NAME_LOOKUP

The number of pathname lookups. There is no ZS_USER_FREE user for this resource.

The following resource properties are defined:

ZS_RESOURCE_PROP_CPU_TOTAL

The total number of CPUs.

ZS_RESOURCE_PROP_CPU_LOAD_1MIN

The system's 1 minute load average.

ZS_RESOURCE_PROP_CPU_LOAD_5MIN

The system's 5 minute load average.

ZS_RESOURCE_PROP_CPU_LOAD_15MIN

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:

ZS_RESOURCE_TYPE_TIME

The resource is defined as time. A timestruc_t is used to store the value in seconds and nanoseconds.

ZS_RESOURCE_TYPE_COUNT

The resource is defined as an integer number representing a quantity. A uint64_t is used to store the value.

ZS_RESOURCE_TYPE_BYTES

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:

ZS_USER_ALL

Total resource used.

ZS_USER_SYSTEM

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.

ZS_USER_ZONES

Aggregate resource used by all zones.

ZS_USER_FREE

Resource not used.

See individual resource descriptions above for user restrictions on individual resources.

Zones

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:

ZS_ZONE_PROP_NAME

The name of the zone. The string will be up to length ZS_ZONENAME_MAX, including the null terminating character.

ZS_ZONE_PROP_ID

The zoneid of the zone.

ZS_ZONE_PROP_IPTYPE

The IP networking type of the zone. This property will have a value of ZS_IPTYPE_SHARED or ZS_IPTYPE_EXCLUSIVE.

ZS_ZONE_PROP_CPUTYPE

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.

ZS_ZONE_PROP_DEFAULT_SCHED

The default scheduling class of the zone.

ZS_ZONE_PROP_SCHEDULERS

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.

ZS_ZONE_PROP_CPU_SHARES

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.

ZS_ZONE_PROP_POOLNAME

The name of the resource pool to which the zone is bound. If resource pools are not enabled, the value will be pool_default.

ZS_ZONE_PROP_PSETNAME

The name of the pool pset to which the zone is bound. If resource pools are disabled, the value will be pset_default.

Zone limits

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:

ZS_LIMIT_CPU

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.

ZS_LIMIT_RAM_RSS

Each zone's limit of resident pages of physical memory in bytes.

ZS_LIMIT_RAM_LOCKED

Each zone's limit of locked pages of physical memory in bytes.

ZS_LIMIT_VM

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.

ZS_LIMIT_MAX_LWPS

The number of lightweight processes (lwps) executing in each zone.

ZS_LIMIT_MAX_PROCESSES

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.

ZS_LIMIT_MAX_SHM_MEMORY

Each zone's total size of all System V shared memory segments created. There is no ZS_USER_SYSTEM() user for this resource.

ZS_LIMIT_MAX_SHM_IDS

Each zone's number all System V shared memory segments created. There is no ZS_USER_SYSTEM() user for this resource.

ZS_LIMIT_MAX_SEM_IDS

Each zone's number of System V semaphores created. There is no ZS_USER_SYSTEM() user for this resource.

ZS_LIMIT_MAX_MSG_IDS

Each zone's total number of System V message queues created. There is no ZS_USER_SYSTEM user for this resource.

ZS_LIMIT_MAX_LOFI

Each zone's total number of lofi devices created. See lofiadm(8).

Psets

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:

ZS_PSET_PROP_NAME

The name of the processor set. The string will be up to length ZS_PSETNAME_MAX, including the null terminating character.

ZS_PSET_PROP_ID

The psetid of the processor set.

ZS_PSET_PROP_CPUTYPE

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.

ZS_PSET_PROP_SIZE

The number CPUs assigned to the processor set.

ZS_PSET_PROP_ONLINE

The number of CPUs assigned to the processor set which are in the on-line or no-intr state.

ZS_PSET_PROP_MIN

The minimum number of CPUs that the system may assign to the processor set.

ZS_PSET_PROP_MAX

The maximum number of CPUs that the system may assign to the processor set.

ZS_PSET_PROP_CPU_SHARES

The total number of CPU shares of all zones running in the processor set.

ZS_PSET_PROP_SCHEDULERS

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.

ZS_PSET_PROP_LOAD_1MIN

The system's 1 minute load average.

ZS_PSET_PROP_LOAD_5MIN

The system's 5 minute load average.

ZS_PSET_PROP_LOAD_15MIN

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.

Pset Per-Zone Utilization

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:

ZS_PZ_PROP_SCHEDULERS

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.

ZS_PZ_PROP_CPU_SHARES

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.

ZS_PZ_PROP_CPU_CAP

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:

ZS_PZ_PCT_PSET

The percentage of the pset used by a zone. The value is pct * 100, with 10000 meaning 100%.

ZS_PZ_PCT_CPU_CAP

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

ZS_PZ_PCT_PSET_SHARESZS_PZ_PCT_PSET_SHARES

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

ZS_PZ_PCT_CPU_SHARE

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.

INTERFACES

The shared object libzonestat.so.1 provides the public interfaces defined below. See intro(3) for additional information on shared object interfaces.

zs_close
zs_open
zs_property_double
zs_property_int
zs_property_int64
zs_property_string
zs_property_type
zs_property_uint
zs_property_uint64
zs_pset_list
zs_pset_property
zs_pset_total_cpus
zs_pset_total_time
zs_pset_used_cpus
zs_pset_used_pct
zs_pset_used_time
zs_pset_walk
zs_pset_zone_get_pset
zs_pset_stolen_all_time
zs_pset_stolen_all_cpus
zs_pset_stolen_all_pct
zs_pset_stolen_time
zs_pset_stolen_cpus
zs_pset_stolen_pct
zs_pset_stolen_zones_time
zs_pset_stolen_zones_cpus
zs_pset_stolen_zones_pct
zs_pset_zone_get_zone
zs_pset_zone_list
zs_pset_zone_property
zs_pset_zone_used_cpus
zs_pset_zone_used_pct
zs_pset_zone_used_time
zs_pset_zone_walk
zs_resource_property
zs_resource_total_time
zs_resource_total_uint64
zs_resource_type
zs_resource_used_pct
zs_resource_used_time
zs_resource_used_uint64
zs_resource_used_zone_pct
zs_resource_used_zone_time
zs_resource_used_zone_uint64
zs_usage_diff
zs_usage_free
zs_usage_read
zs_zone_limit_time
zs_zone_limit_typ
zs_zone_limit_uint64
zs_zone_limit_used_pct
zs_zone_limit_used_time
zs_zone_limit_used_uint64
zs_zone_list
zs_zone_property
zs_zone_walk

Files

/usr/lib/libzonestat.so.1

shared object

/usr/lib/64/libzonestat.so.1

64-bit shared object

Attributes

See attributes(7) for descriptions of the following attributes:

ATTRIBUTE TYPE
ATTRIBUTE VALUE
Availability
system/zones
Interface Stability
Committed
MT-Level
See below.

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.

See Also

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)

Notes

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.