, zs_usage_read

, zs_usage_diff

, zs_usage_free

- read system configuration and utilization

Synopsis

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

zs_usage_t zs_usage_read(zs_ctl_t zsctl);

zs_usage_t zs_usage_diff(zs_usage_t u1, zs_usage_t u2);

void zs_usage_free(zs_usage_t zsctl);

Description

The zs_usage_read() function reads the system configuration and utilization with respect to zones, memory, and CPU.

Each zs_usage_read() will return a zs_usage_t object, which includes the following information:

• The current system resources and their utilization.

• The currently running zones. All properties reflect the current running state of each zone.

• The usage of each resource by each zone.

• The usage by each zone of its configured limits.

• The currently existing processor sets. All properties and usages reflect the current running state of each processor set.

• The usage of each processor set by each zone utilizing it.

Increasing utilization values are described libzonestat(3LIB). Increasing values continually increase, starting at zero from the point at which zs_open(3ZONESTAT) was first called.

For all other utilization values, utilization information will be the usage at the point in time at which zs_usage_read() is called.

For zones and processors sets that were booted or created after zs_open() was called, the increasing usage values will be usage since the most recent boot or creation before the call to zs_usage_read().

The zs_usage_diff() function computes and returns the utilization differences between two zs_usage_t objects returned by zs_usage_read(). Both u1 and u2 must be read from the same zsctl object. u2 must be read after u1.

The purpose of zs_usage_diff() is to simplify the comparison of zs_usage_read() calls made at a interval.

The returned zs_usage_t object will contain:

• The current system resources, as they exist in u2.

• The zones and processor sets that exist in u2.

• For increasing utilization values, the value of (u2 - u1). If a specific value does not exist in u1 (such as the CPU utilization for a zone in u2 which does not exist in u1), the value will be the value from u2.

• For non-increasing utilization values, the value of u2.

The zs_usage_free() function frees the memory associated with a zs_usage_t object returned by zs_usage_read() or zs_usage_diff().

Return Values

On success, zs_usage_free() and zs_usage_diff() return a pointer to a zonestat usage object. On failure, zs_open() returns NULL.

Errors

The zs_usage_diff() function will fail if:

EAGAIN

Insufficient resources are available.

ENOMEM

Insufficient memory is available.

The zs_usage_read() function will fail if:

EAGAIN

Insufficient resources are available.

EINTR

A signal was caught.

ENOMEM

Insufficient memory is available.

ESRCH

Unable to connect to the zones monitoring service. See Notes.

Examples

Example 1 Read zone CPU utilization.

The following example uses zs_usage_read() to read each zones CPU utilization at a regular interval.

#include <zonestat.h>
...
extern int time_to_quit; /* hypothetical quit notification */
...

zs_ctl_t ctl;
zs_usage_t last;
zs_usage_t next;
zs_usage_t diff;
zs_zone_t zone;
timestruct_t time;
uint64_t cpus;

ctl = zs_usage_open();  /* Open zone statistics */
last = zs_usage_read(); /* Read initial usage */
for (;;) {

        sleep(10);
        next = zs_usage_read();
        diff = zs_usage_diff(last, next);

        /* Walk zones in usage data */
        for (zone = zs_zone_first(diff); zone != NULL ;
            zone = zs_zone_next(diff, zone)) {

                /*
                 * fetch cpu time used by zone over interval in terms of
                 * seconds and nanoseconds
                 */
                zs_resource_used_zone_time(zone, ZS_RESOURCE_CPU,
                    &time);

                /*
                 * fetch cpu time used by zone over interval in terms of
                 * cpu used.  100 equals one cpu.  For example, a
                 * value of 250 means the zone used 2.5 cpus worth of
                 * time between last and next.
                 */
                zs_resource_used_zone_uint64(zone, ZS_RESOURCE_CPU,
                    &cpus;

        }
        zs_usage_free(diff);
        zs_usage_free(last);
        last = next;

        if (time_to_quit)
                break;
}
zs_usage_free(last)

Attributes

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

The zs_usage_*() 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), pooladm(1M), psrset(1M), rcapadm(1M), swap(1M), zoneadm(1M), zonestatd(1M), libpool(3LIB), libzonestat(3LIB), zs_open(3ZONESTAT), zs_pset(3ZONESTAT), zs_property(3ZONESTAT), zs_pset_zone(3ZONESTAT), zs_resource(3ZONESTAT), zs_zone(3ZONESTAT), attributes(5), resource_controls(5)

Notes

The service svc:/system/zones-monitoring:default must be enabled in the global zone in order for zs_usage_read() to succeed. This requirement exists for use of libzonestat(3LIB) in both the global zone and non-global zones.

If the zones-monitoring service goes off line, ESRCH will be returned. At this point the zsctl object is no longer usable. Use zs_close(zsctl) and use zs_open(3ZONESTAT) to reconnect.