kstat-1 - API for kernel statistics
#include <rad/client/1/kstat.h> cc [ flag... ] file... -lkstat1_client [ library... ] interface Kstat kstat_Kstatinfo_t * info ; (ro) boolean_t stale ; (ro) kstat_Snapshot_t * snapshot ; (ro) rc_err_t kstat_Kstat_fresh_snapshot(rc_instance_t *inst, kstat_Snapshot_t **result); interface Control rc_err_t kstat_Control_update(rc_instance_t *inst); Enumerated Types enum Ksdtype typedef enum kstat_Ksdtype { KK_CHAR = 0, KK_INT32 = 1, KK_UINT32 = 2, KK_INT64 = 3, KK_UINT64 = 4, KK_FLOAT = 5, KK_DOUBLE = 6, KK_STRING = 7, } kstat_Ksdtype_t; enum Kstype typedef enum kstat_Kstype { KK_RAW = 0, KK_NAMED = 1, KK_INTR = 2, KK_IO = 3, KK_TIMER = 4, KK_UNKNOWN = 5, } kstat_Kstype_t; Structured Types struct Ksvalue typedef struct kstat_Ksvalue kstat_Ksvalue_t; struct kstat_Ksvalue { kstat_Ksdtype_t kk_discriminant; char *kk_CHAR; int kk_INT32; unsigned int kk_UINT32; long long kk_INT64; unsigned long long kk_UINT64; float kk_FLOAT; double kk_DOUBLE; char *kk_STRING; }; void kstat_Ksvalue_free(kstat_Ksvalue_t *in); struct Kstat_named typedef struct kstat_Kstat_named kstat_Kstat_named_t; struct kstat_Kstat_named { char *kkn_name; kstat_Ksvalue_t *kkn_value; }; void kstat_Kstat_named_free(kstat_Kstat_named_t *in); struct Kstat_intr typedef struct kstat_Kstat_intr kstat_Kstat_intr_t; struct kstat_Kstat_intr { unsigned int kki_hard; unsigned int kki_soft; unsigned int kki_watchdog; unsigned int kki_spurious; unsigned int kki_multsvc; }; void kstat_Kstat_intr_free(kstat_Kstat_intr_t *in); struct Kstat_timer typedef struct kstat_Kstat_timer kstat_Kstat_timer_t; struct kstat_Kstat_timer { char *kkt_name; unsigned long long kkt_num_events; unsigned long long kkt_elapsed_time; unsigned long long kkt_min_time; unsigned long long kkt_max_time; unsigned long long kkt_start_time; unsigned long long kkt_stop_time; }; void kstat_Kstat_timer_free(kstat_Kstat_timer_t *in); struct Kstat_io typedef struct kstat_Kstat_io kstat_Kstat_io_t; struct kstat_Kstat_io { unsigned long long kki_nread; unsigned long long kki_nwritten; unsigned int kki_reads; unsigned int kki_writes; unsigned long long kki_wtime; unsigned long long kki_wlentime; unsigned long long kki_wlastupdate; unsigned long long kki_rtime; unsigned long long kki_rlentime; unsigned long long kki_rlastupdate; unsigned int kki_wcnt; unsigned int kki_rcnt; }; void kstat_Kstat_io_free(kstat_Kstat_io_t *in); struct Ksdata typedef struct kstat_Ksdata kstat_Ksdata_t; struct kstat_Ksdata { kstat_Kstype_t kk_discriminant; rc_opaque_t *kk_RAW; kstat_Kstat_named_t **kk_NAMED; int kk_NAMED_count; kstat_Kstat_intr_t *kk_INTR; kstat_Kstat_io_t *kk_IO; kstat_Kstat_timer_t **kk_TIMER; int kk_TIMER_count; char *kk_UNKNOWN; }; void kstat_Ksdata_free(kstat_Ksdata_t *in); struct Snapshot typedef struct kstat_Snapshot kstat_Snapshot_t; struct kstat_Snapshot { unsigned long long ks_snaptime; kstat_Ksdata_t *ks_data; }; void kstat_Snapshot_free(kstat_Snapshot_t *in); struct Kstatinfo typedef struct kstat_Kstatinfo kstat_Kstatinfo_t; struct kstat_Kstatinfo { char *kk_module; char *kk_name; char *kk_klass; int kk_instance; kstat_Kstype_t kk_type; unsigned long long kk_crtime; }; void kstat_Kstatinfo_free(kstat_Kstatinfo_t *in);
KSTAT-1(3rad) RAD Module Definitions KSTAT-1(3rad) NAME kstat - API for kernel statistics SYNOPSIS #include <rad/client/1/kstat.h> cc [ flag... ] file... -lkstat1_client [ library... ] interface Kstat kstat_Kstatinfo_t * info ; (ro) boolean_t stale ; (ro) kstat_Snapshot_t * snapshot ; (ro) rc_err_t kstat_Kstat_fresh_snapshot(rc_instance_t *inst, kstat_Snapshot_t **result); interface Control rc_err_t kstat_Control_update(rc_instance_t *inst); Enumerated Types enum Ksdtype typedef enum kstat_Ksdtype { KK_CHAR = 0, KK_INT32 = 1, KK_UINT32 = 2, KK_INT64 = 3, KK_UINT64 = 4, KK_FLOAT = 5, KK_DOUBLE = 6, KK_STRING = 7, } kstat_Ksdtype_t; enum Kstype typedef enum kstat_Kstype { KK_RAW = 0, KK_NAMED = 1, KK_INTR = 2, KK_IO = 3, KK_TIMER = 4, KK_UNKNOWN = 5, } kstat_Kstype_t; Structured Types struct Ksvalue typedef struct kstat_Ksvalue kstat_Ksvalue_t; struct kstat_Ksvalue { kstat_Ksdtype_t kk_discriminant; char *kk_CHAR; int kk_INT32; unsigned int kk_UINT32; long long kk_INT64; unsigned long long kk_UINT64; float kk_FLOAT; double kk_DOUBLE; char *kk_STRING; }; void kstat_Ksvalue_free(kstat_Ksvalue_t *in); struct Kstat_named typedef struct kstat_Kstat_named kstat_Kstat_named_t; struct kstat_Kstat_named { char *kkn_name; kstat_Ksvalue_t *kkn_value; }; void kstat_Kstat_named_free(kstat_Kstat_named_t *in); struct Kstat_intr typedef struct kstat_Kstat_intr kstat_Kstat_intr_t; struct kstat_Kstat_intr { unsigned int kki_hard; unsigned int kki_soft; unsigned int kki_watchdog; unsigned int kki_spurious; unsigned int kki_multsvc; }; void kstat_Kstat_intr_free(kstat_Kstat_intr_t *in); struct Kstat_timer typedef struct kstat_Kstat_timer kstat_Kstat_timer_t; struct kstat_Kstat_timer { char *kkt_name; unsigned long long kkt_num_events; unsigned long long kkt_elapsed_time; unsigned long long kkt_min_time; unsigned long long kkt_max_time; unsigned long long kkt_start_time; unsigned long long kkt_stop_time; }; void kstat_Kstat_timer_free(kstat_Kstat_timer_t *in); struct Kstat_io typedef struct kstat_Kstat_io kstat_Kstat_io_t; struct kstat_Kstat_io { unsigned long long kki_nread; unsigned long long kki_nwritten; unsigned int kki_reads; unsigned int kki_writes; unsigned long long kki_wtime; unsigned long long kki_wlentime; unsigned long long kki_wlastupdate; unsigned long long kki_rtime; unsigned long long kki_rlentime; unsigned long long kki_rlastupdate; unsigned int kki_wcnt; unsigned int kki_rcnt; }; void kstat_Kstat_io_free(kstat_Kstat_io_t *in); struct Ksdata typedef struct kstat_Ksdata kstat_Ksdata_t; struct kstat_Ksdata { kstat_Kstype_t kk_discriminant; rc_opaque_t *kk_RAW; kstat_Kstat_named_t **kk_NAMED; int kk_NAMED_count; kstat_Kstat_intr_t *kk_INTR; kstat_Kstat_io_t *kk_IO; kstat_Kstat_timer_t **kk_TIMER; int kk_TIMER_count; char *kk_UNKNOWN; }; void kstat_Ksdata_free(kstat_Ksdata_t *in); struct Snapshot typedef struct kstat_Snapshot kstat_Snapshot_t; struct kstat_Snapshot { unsigned long long ks_snaptime; kstat_Ksdata_t *ks_data; }; void kstat_Snapshot_free(kstat_Snapshot_t *in); struct Kstatinfo typedef struct kstat_Kstatinfo kstat_Kstatinfo_t; struct kstat_Kstatinfo { char *kk_module; char *kk_name; char *kk_klass; int kk_instance; kstat_Kstype_t kk_type; unsigned long long kk_crtime; }; void kstat_Kstatinfo_free(kstat_Kstatinfo_t *in); DESCRIPTION API com.oracle.solaris.rad.kstat [1] This API exposes kernel statistics, or kstats, to rad(8) clients. Two core interfaces are provided: 1. Kstat - an object that represents a kstat 2. Control - an administration object Python kstat wrapper. INTERFACES interface Kstat The Kstat interface represents a kernel statistic. Handles to this type of object can be retrieved from the RAD server using a kstat proxy object. To retrieve a specific instance, be aware of these additional keys: 1. a key named "class" paired with a kstat class 2. a key named "module" paired with a kstat module 3. a key named "instance" paired with a kstat module (integer) instance 4. a key named "name" paired with a kstat name For example, to print statistics about a particular CPU on a system: Kstat Properties kstat_Kstatinfo_t * info (read-only) -- static kstat information rc_err_t kstat_Kstat_get_info(rc_instance_t *inst, kstat_Kstatinfo_t **result); Get property value. Arguments: inst -- RAD instance result -- Property value returned boolean_t stale (read-only) -- true if the kstat doesn't exist kstats are often associated with parts of the system that can come and go over time, and likewise will come and go. To simplify consumers, a kstat object once referenced will remain but be marked stale when the underlying kstat object goes away. rc_err_t kstat_Kstat_get_stale(rc_instance_t *inst, boolean_t *result); Get property value. Arguments: inst -- RAD instance result -- Property value returned kstat_Snapshot_t * snapshot (read-only) -- a snapshot of the kstat as of the last update rc_err_t kstat_Kstat_get_snapshot(rc_instance_t *inst, kstat_Snapshot_t **result); Get property value. Arguments: inst -- RAD instance result -- Property value returned Read Error: void ** -- the kstat doesn't currently exist Kstat Methods rc_err_t kstat_Kstat_fresh_snapshot(rc_instance_t *inst, kstat_Snapshot_t **result); obtains a fresh snapshot of the kstat Arguments: inst -- RAD instance result Kstat Retrieve rc_err_t kstat_Kstat__rad_get_name(adr_name_t **result, int n, ...); Obtain RAD name of a Kstat object. Arguments: result -- RAD name n -- Number of key-value pairs provided as variadic arguments ... -- Optional key-value pairs that compose the primary key rc_err_t kstat_Kstat__rad_lookup(rc_conn_t *c, boolean_t strict, rc_instance_t **result, int n, ...); Lookup a Kstat instance. Construct a RAD name for the interface based on the provided key-value pairs and perform a lookup. If successful, instance reference is returned in the result. Arguments: c -- RAD connection handle strict -- Strict (B_TRUE) or relaxed (B_FALSE) versioning result -- RAD instance n -- Number of key-value pairs provided as variadic arguments ... -- Optional key-value pairs that compose the primary key rc_err_t kstat_Kstat__rad_list(rc_conn_t *c, boolean_t strict, adr_pattern_scheme_t scheme, adr_name_t ***result, int *result_count, int n, ...); List RAD names of a available Kstat instances. Returns an array and array size of matching object names. Arguments: c -- RAD connection handle strict -- Strict (B_TRUE) or relaxed (B_FALSE) versioning scheme -- Apply glob (NS_GLOB) or regex (NS_REGEX) matching result -- Array of RAD names result_count -- Number of names in result array n -- Number of key-value pairs provided as variadic arguments ... -- Optional key-value pairs that compose the primary key interface Control The Control interface is an administrative API into the kstats subsystem. Handles to this type of object can be retrieved from the RAD server using a simple object proxy. Control Methods rc_err_t kstat_Control_update(rc_instance_t *inst); update the kstat chain Updates the kstat chain. All referenced kstats' snapshots are updated. After update, the set of available kstats may change. Arguments: inst -- RAD instance Control Retrieve rc_err_t kstat_Control__rad_get_name(adr_name_t **result, int n, ...); Obtain RAD name of a Control object. Arguments: result -- RAD name n -- Number of key-value pairs provided as variadic arguments ... -- Optional key-value pairs that compose the primary key rc_err_t kstat_Control__rad_lookup(rc_conn_t *c, boolean_t strict, rc_instance_t **result, int n, ...); Lookup a Control instance. Construct a RAD name for the interface based on the provided key-value pairs and perform a lookup. If successful, instance reference is returned in the result. Arguments: c -- RAD connection handle strict -- Strict (B_TRUE) or relaxed (B_FALSE) versioning result -- RAD instance n -- Number of key-value pairs provided as variadic arguments ... -- Optional key-value pairs that compose the primary key rc_err_t kstat_Control__rad_list(rc_conn_t *c, boolean_t strict, adr_pattern_scheme_t scheme, adr_name_t ***result, int *result_count, int n, ...); List RAD names of a available Control instances. Returns an array and array size of matching object names. Arguments: c -- RAD connection handle strict -- Strict (B_TRUE) or relaxed (B_FALSE) versioning scheme -- Apply glob (NS_GLOB) or regex (NS_REGEX) matching result -- Array of RAD names result_count -- Number of names in result array n -- Number of key-value pairs provided as variadic arguments ... -- Optional key-value pairs that compose the primary key ENUMERATED TYPES enum Ksdtype -- a named kstat data value type typedef enum kstat_Ksdtype { KK_CHAR = 0, KK_INT32 = 1, KK_UINT32 = 2, KK_INT64 = 3, KK_UINT64 = 4, KK_FLOAT = 5, KK_DOUBLE = 6, KK_STRING = 7, } kstat_Ksdtype_t; KK_CHAR (0) -- a string (of up to a fixed size) KK_INT32 (1) -- a signed 32-bit integer KK_UINT32 (2) -- an unsigned 32-bit integer KK_INT64 (3) -- a signed 64-bit integer KK_UINT64 (4) -- an unsigned 64-bit integer KK_FLOAT (5) -- a 32-bit floating point number KK_DOUBLE (6) -- a 64-bit floating point number KK_STRING (7) -- an arbitrary lengthed string enum Kstype -- kstat type typedef enum kstat_Kstype { KK_RAW = 0, KK_NAMED = 1, KK_INTR = 2, KK_IO = 3, KK_TIMER = 4, KK_UNKNOWN = 5, } kstat_Kstype_t; KK_RAW (0) -- raw data, can be anything KK_NAMED (1) -- name/value pairs KK_INTR (2) -- interrupt statistics KK_IO (3) -- I/O statistics KK_TIMER (4) -- event timers KK_UNKNOWN (5) STRUCTURED TYPES struct Ksvalue -- a named kstat data value typedef struct kstat_Ksvalue kstat_Ksvalue_t; struct kstat_Ksvalue { kstat_Ksdtype_t kk_discriminant; char *kk_CHAR; int kk_INT32; unsigned int kk_UINT32; long long kk_INT64; unsigned long long kk_UINT64; float kk_FLOAT; double kk_DOUBLE; char *kk_STRING; }; void kstat_Ksvalue_free(kstat_Ksvalue_t *in); This is a struct representing a named kstat data value. Use the discriminant enum to determine what type of data the value holds. Fields: kk_discriminant kk_CHAR kk_INT32 kk_UINT32 kk_INT64 kk_UINT64 kk_FLOAT kk_DOUBLE kk_STRING struct Kstat_named -- a named kstat name/value pair typedef struct kstat_Kstat_named kstat_Kstat_named_t; struct kstat_Kstat_named { char *kkn_name; kstat_Ksvalue_t *kkn_value; }; void kstat_Kstat_named_free(kstat_Kstat_named_t *in); Fields: kkn_name -- counter name kkn_value -- counter value struct Kstat_intr -- interrupt statistics typedef struct kstat_Kstat_intr kstat_Kstat_intr_t; struct kstat_Kstat_intr { unsigned int kki_hard; unsigned int kki_soft; unsigned int kki_watchdog; unsigned int kki_spurious; unsigned int kki_multsvc; }; void kstat_Kstat_intr_free(kstat_Kstat_intr_t *in); Counters for various types of interrupts. Fields: kki_hard -- hardware interrupts kki_soft -- soft interrupts kki_watchdog -- watchdog interrupts kki_spurious -- spurious interrupts kki_multsvc -- multiple-service interrupts struct Kstat_timer -- a timer kstat statistic typedef struct kstat_Kstat_timer kstat_Kstat_timer_t; struct kstat_Kstat_timer { char *kkt_name; unsigned long long kkt_num_events; unsigned long long kkt_elapsed_time; unsigned long long kkt_min_time; unsigned long long kkt_max_time; unsigned long long kkt_start_time; unsigned long long kkt_stop_time; }; void kstat_Kstat_timer_free(kstat_Kstat_timer_t *in); Provides basic counting and timing information. Fields: kkt_name -- event name kkt_num_events -- number of events kkt_elapsed_time -- cumulative elapsed time kkt_min_time -- shortest event duration kkt_max_time -- longest event duration kkt_start_time -- previous event start time kkt_stop_time -- previous event stop time struct Kstat_io -- I/O statistics typedef struct kstat_Kstat_io kstat_Kstat_io_t; struct kstat_Kstat_io { unsigned long long kki_nread; unsigned long long kki_nwritten; unsigned int kki_reads; unsigned int kki_writes; unsigned long long kki_wtime; unsigned long long kki_wlentime; unsigned long long kki_wlastupdate; unsigned long long kki_rtime; unsigned long long kki_rlentime; unsigned long long kki_rlastupdate; unsigned int kki_wcnt; unsigned int kki_rcnt; }; void kstat_Kstat_io_free(kstat_Kstat_io_t *in); Fields: kki_nread -- number of bytes read kki_nwritten -- number of bytes written kki_reads -- number of read operations kki_writes -- number of write operations kki_wtime -- cumulative wait time kki_wlentime -- cumulative wait length*time product kki_wlastupdate -- last time wait queue changed kki_rtime -- cumulative run time kki_rlentime -- cumulative run length*time product kki_rlastupdate -- last time run queue changed kki_wcnt -- count of elements in wait state kki_rcnt -- count of elements in run state struct Ksdata -- typed kernel statistics data typedef struct kstat_Ksdata kstat_Ksdata_t; struct kstat_Ksdata { kstat_Kstype_t kk_discriminant; rc_opaque_t *kk_RAW; kstat_Kstat_named_t **kk_NAMED; int kk_NAMED_count; kstat_Kstat_intr_t *kk_INTR; kstat_Kstat_io_t *kk_IO; kstat_Kstat_timer_t **kk_TIMER; int kk_TIMER_count; char *kk_UNKNOWN; }; void kstat_Ksdata_free(kstat_Ksdata_t *in); Use the discriminant enum to determine what type of data the structure holds. Fields: kk_discriminant kk_RAW kk_NAMED kk_NAMED_count kk_INTR kk_IO kk_TIMER kk_TIMER_count kk_UNKNOWN struct Snapshot -- a snapshot in time of a kernel statistic typedef struct kstat_Snapshot kstat_Snapshot_t; struct kstat_Snapshot { unsigned long long ks_snaptime; kstat_Ksdata_t *ks_data; }; void kstat_Snapshot_free(kstat_Snapshot_t *in); Fields: ks_snaptime -- when this snapshot was taken ks_data -- statistic snapshot data struct Kstatinfo -- static kstat information typedef struct kstat_Kstatinfo kstat_Kstatinfo_t; struct kstat_Kstatinfo { char *kk_module; char *kk_name; char *kk_klass; int kk_instance; kstat_Kstype_t kk_type; unsigned long long kk_crtime; }; void kstat_Kstatinfo_free(kstat_Kstatinfo_t *in); Fields: kk_module -- module name kk_name -- kstat name kk_klass -- kstat class kk_instance -- module's instance kk_type -- kstat data type kk_crtime -- kstat creation time VERSION 1.0 ATTRIBUTES See attributes(7) for descriptions of the following attributes: +--------------------+----------------------------------------+ | ATTRIBUTE TYPE | ATTRIBUTE VALUE | +--------------------+----------------------------------------+ |Availability | system/management/rad/module/rad-kstat | +--------------------+----------------------------------------+ |Interface Stability | Private | +--------------------+----------------------------------------+ SEE ALSO rad(8) NOTES 1. Accessing Python documentation for this module: $ pydoc rad.bindings.com.oracle.solaris.rad.kstat_1 Solaris 11.4 2017-02-01 KSTAT-1(3rad)