The fetchgroup functions implement a registration-based mechanism
to fetch groups of performance metrics, including automation for
general unit, rate and type conversions as well as convenient
instance and value encodings. They constitute a powerful and
compact alternative to the classic Performance Metrics
Application Programming Interface (PMAPI(3)) sequence of separate
lookup, check, fetch, iterate, extract and convert functions.
The general idea consists of two stages. In the setup stage, the
application identifies metrics of interest by name and with
desired conversions, and register a unique pmAtomValue output
location where the fetchgroup system is to later deposit the
result. It is also possible to identify a metric with an
instance domain, and register a unique vector of pmAtomValue
objects for them. In the operation stage, one simple
pmFetchGroup function fetches, decodes, converts, and stores all
metrics to their destinations, where the application can read
them directly. This function may be called repeatedly, and each
time new pmAtomValue values will be stored in the same
destinations. Rate conversions between consecutive samples may
be requested.
Each fetchgroup is associated with a private PMAPI context, so it
can manipulate instance profiles and other such state without
disrupting other contexts. The instance profile is manipulated
to optimize fetches of individual items, even if some are derived
metrics. This private PMAPI context belongs to the fetchgroup,
is used for all of its internal operations, and will be
destroyed.
Multiple fetchgroups may be used concurrently, independently. An
opaque type pmFG is used to identify a fetchgroup, which is
passed to all related function calls.
Creating a fetchgroup
int pmCreateFetchGroup(pmFG *ptr, int type, const char *name);
This function creates a new fetchgroup, associated with a new
PMAPI context. The type and name parameters are relayed to
pmNewContext(3) for creation of the context. The fetchgroup
identifier is returned upon success through the ptr pointer.
This object is later used as a parameter to all other fetchgroup
functions. The private PMAPI context may be accessed with
pmGetFetchGroupContext, if required.
The normal function return code is zero, and ptr is set. This
function may fail in case of pmNewContext or memory allocation
errors. Those are indicated with a negative return code and a
cleared ptr value.
Getting the private PMAPI context
int pmGetFetchGroupContext(pmFG pmfg);
This function returns the private PMAPI context used by the given
fetchgroup. It may be safely used to adjust some configuration
parameters of the context, such as via pmSetMode(3), before
fetchgroup extension and fetching begins.
However, mutation of this context by PMAPI functions after this
time may disrupt fetchgroup functionality. For example, a
pmSetMode call could invalidate one rate-conversion time-step.
The normal function return code is the context number.
Extending a fetchgroup with a metric instance of interest
int pmExtendFetchGroup_item(pmFG pmfg, const char *metric, const
char *instance, const char *scale, pmAtomValue
*out_value, int out_type, int *out_sts);
This function registers interest in a single metric and optional
instance. The metric name is given in the mandatory metric
parameter, which is checked immediately via pmLookupName(3) and
other calls. If and only if the metric has an instance domain,
the specific instance of interest may be named by the instance
parameter, which is checked immediately via pmNameInDom(3);
otherwise pass NULL. If the fetchgroup context is a set of
archives, it is possible that the metric / instance pair is not
yet defined at the current time origin. Therefore, this function
may attempt to seek to the end of the current set of archives
temporarily to retry the metric / instance lookup.
The optional scale parameter specifies desired unit/scale/rate
conversions for the metric value. It can take the following
values:
NULL
No unit/scale conversion. If metric has PM_SEM_COUNTER
semantics, perform rate conversion.
rate
Perform rate conversion regardless of semantics, and no
unit/scale conversion.
instant
Perform no rate conversion regardless of semantics, and no
unit/scale conversion.
EXPRESSION
Perform unit/scale/rate conversion as specified by the
EXPRESSION, which is parsed by pmParseUnitsStr(3). This may
be useful to assert a canonical scaling for the resulting
metric value, independent of PCP version or configuration.
Dimensionality must match the metric, except if rate
conversion is requested, in which case the time dimension
must be one smaller than the metric's time dimension. Note
that the type of rate conversion performed here matches the
rate(x) function in derived metric expressions, in that it is
calculated as the naive difference between previous and
current values of a metric, divided by elapsed time. For
example, if a counter wraps around, or a non-counter value
decreases, a negative output rate may be computed.
The optional but usual out_value parameter specifies the
pmAtomValue where the converted result should later be stored.
If the value is NULL, fetching and conversions will be attempted,
and possible errors reported, but the result tossed away. The
mandatory out_type parameter specifes the PM_TYPE_* requested for
the output value. It need not match the metric's native type, as
the fetchgroup facility is capable of casting between all
supported types (including to and from strings).
Any errors subsequently encountered during fetching,
unit/scale/rate conversion, or casting, will result in the
assignment of a sentinel value to the output pmAtomValue (see the
``UNUSUAL SITUATIONS'' section below). In addition, if the
optional out_sts parameter is specified, an appropriate PMAPI
error code will be stored there.
As a review, only the pmfg, metric, and out_type parameters are
mandatory. Others may be NULL to indicate applicaton
disinterest.
The normal function return code is zero. This function may fail
in case of various lookup, type- and conversion- checking errors.
Those are indicated with a negative return code.
Extending a fetchgroup with a metric instance domain of interest
int pmExtendFetchGroup_indom(pmFG pmfg, const char* metric, const
char *scale, int out_inst_codes[], char
*out_inst_names[], pmAtomValue out_values[], int
out_type, int out_stss[], unsigned int out_maxnum,
unsigned int *out_num, int *out_sts);
This function generalizes the pmExtendFetchGroup_item function by
registering interest in a whole instance domain. Therefore, the
function registers preallocated vectors for output variables
(instead of a singleton). Instances will be stored in sorted
order in elements of those vectors. The concepts are otherwise
the same.
The metric name is specified by the mandatory metric parameter.
Note that it may refer to a metric without an instance domain, in
which case the single output value will appear as one unnamed
instance.
The optional scale parameter specifies desired unit/scale/rate
conversions for the metric value, same as above.
The optional out_inst_codes parameter specifies a vector of
integers, where the raw instance number of the fetched metrics
should later be stored.
The optional out_inst_names parameter specifies a vector of
strings, where the instance names of the fetched metrics should
later be stored. If an instance does not have a corresponding
name, a NULL pointer is stored instead. The application must not
modify or free(3) strings in that vector.
The optional out_values parameter specifies a vector of
pmAtomValue objects where the converted result should later be
stored. The mandatory out_type parameter specifies the PM_TYPE_*
requested for the all output values, same as above.
The optional out_stss parameter specifies a vector of integers
where per-instance error codes should be stored.
The mandatory out_maxnum parameter specifies the number of
elements of the vectors above. In other words, it tells the
fetchgroup the maximum number of instances which are expected.
The optional out_num parameter specifies an integer where the
actual number of instances should later be stored. It will range
between 0 and out_maxnum. It is initialized to 0 by this
function.
Finally, the optional out_sts parameter specifies a single
location where an integer status code for the overall fetch for
this metric should be stored. Normally, this will be zero.
Other than a severe fetch error, one may see a PM_ERR_TOOBIG here
if the number of instances actually encountered was larger than
out_maxnum.
Any errors subsequently encountered during fetching,
unit/scale/rate conversion, or casting, will result in the
assignment of a sentinel value to the appropriate output
pmAtomValue (see the ``UNUSUAL SITUATIONS'' section below). In
addition, if the optional out_stss parameter was specified, a
PMAPI error code will be stored in the appropriate position.
As a review, only the pmfg, metric, out_type, and out_maxnum
parameters are mandatory. Others may be NULL to indicate
applicaton disinterest.
The normal function return code is zero. This function may fail
in case of various lookup, type- and conversion- checking errors.
Those are indicated with a negative return code.
Extending a fetchgroup with an event field
int pmExtendFetchGroup_event(pmFG pmfg, const char *metric, const
char *instance, const char *field, const char *scale,
struct timespec out_times[], pmAtomValue out_values[],
int out_type, int out_stss[], unsigned int out_maxnum,
unsigned int *out_num, int *out_sts);
This function registers interest in all instances of one field of
all records of an event metric. Since event metrics may return
multiple records per fetch, and each record may have multiple
fields of a given field metric type, this function registers
preallocated vectors for output variables, similarly to
pmExtendFetchGroup_indom. They are filled in temporal/sequential
order.
The metric name is specified by the mandatory metric parameter.
It must be of PM_TYPE_EVENT. If the metric has an instance
domain, the instance parameter is mandatory to identify the
instance of interest.
The field to extract from event records is specified by the
mandatory field parameter, which is a metric name of normal
scalar type. As is typical for event field metrics, it should
not have an instance domain. The optional scale parameter
specifies desired unit/scale conversions on this metric value.
Rate conversions are not available, because of ambiguity about
which previous value to compute rates from.
The optional out_times parameter specifies a vector of timespec
structs, which will receive a copy of the timestamp of the event
record where each particular field was found.
The optional out_values parameter specifies a vector of
pmAtomValue objects where the converted result should later be
stored. The mandatory out_type parameter specifies the PM_TYPE_*
requested for the output values.
The optional out_stss parameter specifies a vector of integers
where per-field error codes should be stored.
The mandatory out_maxnum parameter specifies the number of
elements of the vectors above. In other words, it tells the
fetchgroup the maximum number of instances which are expected.
The optional out_num parameter specifies an integer where the the
actual number of instances should later be stored. It will range
between zero and out_maxnum. It is initialized to zero by this
function.
Finally, the optional out_sts parameter specifies a single
location where an integer status code for the overall fetch for
this metric should be stored. Normally, this will be zero, even
if no event field values were found (out_num would then be zero).
Other than a severe fetch error, one may see a PM_ERR_TOOBIG here
if the number of fields actually encountered was larger than
out_maxnum.
Any errors subsequently encountered during fetching, unit/scale
conversion, or casting, will result in the assignment of a
sentinel value to the appropriate output pmAtomValue (see the
``UNUSUAL SITUATIONS'' section below). In addition, if the
optional out_stss parameter was specified, a PMAPI error code
will be stored in the appropriate position.
As a review, only the pmfg, metric, field, out_type, and
out_maxnum parameters are mandatory. Others may be NULL to
indicate applicaton disinterest.
The normal function return code is zero. This function may fail
in case of various lookup, type- and conversion- checking errors.
Those are indicated with a negative return code.
Extending a fetchgroup with the fetch timestamp
int pmExtendFetchGroup_timestamp(pmFG pmfg, struct timeval
*out_value);
This function registers interest in the pmResult timestamp. If
the out_value pointer is non-NULL, at every future pmFetchGroup
call, the corresponding result timestamp will be copied there.
Fetching all metrics in a fetchgroup
int pmFetchGroup(pmFG pmfg);
This function performs one pmFetch on its private PMAPI context,
including all the metrics that were registered via prior
pmExtendFetchGroup_* calls. It runs all the data extraction and
conversion operations necessary to populate all the requested
output variables.
The normal function return code is zero or positive, as per the
underlying pmFetch function. This function may fail in case of
severe fetch errors, which are indicated with a negative return
code.
In the case of per-metric availability or conversion errors, or
severe fetch errors, output variables are reset to sentinel
values and individual error codes are set. PM_ERR_AGAIN signals
rate-conversion failure due to lack of a previous value.
However, temporarily absent metrics with discrete semantics are
exempt from some sentinel/error processing: if a pmFetchGroup
fails to collect a result for a discrete metric (pmResult
pmValueSet.numval==0), then the last seen valid value (if any) is
retained. This is intended to ease the processing of sets of
archives with a mixture of once- and repeatedly-sampled metrics.
Clearing a fetchgroup
int pmClearFetchGroup(pmFG pmfg);
When the current fetch state of a fetchgroup is no longer needed,
it may be explicitly reset with this function. It releases any
dynamically stored state but keeps the private PMAPI context
intact for subsequent use (i.e. no change to the context is made
at all and the context remains at the current fetch offset). It
frees any pointers such as indom instance names or strings that
may have been stored in output variables.
Destroying a fetchgroup
int pmDestroyFetchGroup(pmFG pmfg);
When the fetchgroup is no longer needed, it may be explicitly
freed with this function. It releases any dynamically stored
state, as well as the private PMAPI context. It clears frees any
pointers such as indom instance names or strings that may have
been stored in output variables.
