PMUNPACKEVENTRECORDS(3) Library Functions Manual PMUNPACKEVENTRECORDS(3)NAME
pmUnpackEventRecords - unpack event records
C SYNOPSIS
#include <pcp/pmapi.h>
int pmUnpackEventRecords(pmValueSet *vsp, int idx, pmResult ***rap);
cc ... -lpcp
DESCRIPTION
Event records are encoded as a packed array of records within a pmResult using a container metric with a value of type PM_TYPE_EVENT.
pmUnpackEventRecords may be used to unpack event records from a metric value identified by vsp and idx. If the metric has a singular
value, idx should be 0, else the ordinal instance value identified by idx will be unpacked, i.e. vsp->vlist[idx]. The unpacked records are
turned into pmResult structures, one per event record and one metric per event parameter, and rap is returned as a pointer to an array
(NULL pointer terminated) of pointers to the pmResult structures.
Some control information from the packed event records is unpacked into additional ``anonymous'' metrics as follows:
1. If the event record has a non-zero flags value, then the corresponding pmResult will have the flags value encoded with the additional
metric event.flags that is inserted ahead of all other event parameters.
2. If the event record flag is set to PM_EVENT_FLAG_MISSED, then the corresponding pmResult will have one metric event.missed with a value
that equals the number of event records ``missed'' because either the PMDA could not keep up, or the PMAPI client did not collect the
event records fast enough.
pmUnpackEventRecords returns the number of pmResult structures as the return value, which is >= 0 for success.
rset and the associated pmResult structures may be freed using the convenience function pmFreeEventResult(3).
RETURN VALUE
The following errors are possible:
PM_ERR_CONV
The values associated with vsp are not encoded using the format PM_VAL_DPTR or PM_VAL_SPTR, or the flags at the head of the event
record has an unexpected value.
PM_ERR_INST
The value associated with vsp is not singular as expected.
PM_ERR_TYPE
vsp is not a value of type PM_TYPE_EVENT.
PM_ERR_TOOSMALL
The value identified by vbp is not legal because the value length is less than the minimum size, or the number of event records
encoded in the (value header) pmEventArray structure is negative, or the number of missed event records in the pmEventArray array
is negative.
PM_ERR_TOOBIG
Either vsp indicates more than one value is present (all the event records are expected to be packed in a single metric value),
or when unpacking the event records, the processing continues past the end of the enclosing value. Indicates corruption of the
packed event record.
PM_ERR_TYPE
Event parameters must have one of the arithmetic types, else PM_TYPE_AGGREGATE, PM_TYPE_STRING or PM_TYPE_AGGREGATE_STATIC.
other values < 0
refer to pmErrStr(3).
SEE ALSO PMAPI(3) and pmFreeEventResult(3).
Performance Co-Pilot PCP PMUNPACKEVENTRECORDS(3)
Check Out this Related Man Page
PMDAEVENTARRAY(3) Library Functions Manual PMDAEVENTARRAY(3)NAME
pmdaEventNewArray, pmdaEventResetArray, pmdaEventReleaseArray, pmdaEventAddRecord, pmdaEventAddMissedRecord, pmdaEventAddParam, pmdaEvent-
GetAddr - utilities for PMDAs to build packed arrays of event records
C SYNOPSIS
#include <pcp/pmapi.h>
#include <pcp/impl.h>
#include <pcp/pmda.h>
int pmdaEventNewArray(void);
int pmdaEventResetArray(int idx);
int pmdaEventReleaseArray(int idx);
int pmdaEventAddRecord(int idx, struct timeval *tp, int flags);
int pmdaEventAddMissedRecord(int idx, struct timeval *tp, int nmissed);
int pmdaEventAddParam(int idx, pmID pmid, int type, pmAtomValue *avp);
pmEventArray *pmdaEventGetAddr(int idx);
cc ... -lpcp
DESCRIPTION
A Performance Metrics Domain Agent (PMDA) that wishes to export event records (or trace records) is encouraged to use a metric of type
PM_TYPE_EVENT to encode a group of event records into a single packed array.
The packed array of event records format is defined in <pcp/pmapi.h> and consists of a pmEventArray structure, containing a variable number
of pmEventRecord structures, each of which contains a variable number of pmEventParameter structures, which in turn may contain a variable
length value for each parameter of each event record.
The routines described here are designed to assist the PMDA developer in building a packed array of event records, and managing all of the
memory allocations required to hold each instance of an array of event records in a contiguous buffer. Normal use would be as part of PM-
DA's pmdaFetchCallBack method.
pmdaEventNewArray is used to create a new event array. The return value is a small integer that is used as the idx parameter to the other
routines to identify a specific event array. If needed, a PMDA can create and use multiple event arrays.
To start a new cycle and refill an event array from the beginning, call pmdaEventResetArray.
If the PMDA has finished with an event array, pmdaEventReleaseArray may be used to release the underlying storage and ``close'' the event
array so that subsequent attempts to use idx will return PM_ERR_NOCONTEXT.
To start a new event record, use pmdaEventAddRecord. The timestamp for the event record is given via tp and the flags parameter may be
used to set the control field that determines the type of the event record - flags may be the bit-wise ``or'' of one or more of the
PM_EVENT_FLAG_* values defined in <pcp/pmapi.h> (but note that PM_EVENT_FLAG_MISSED should not be used in this context).
If event records have been missed, either because the PMDA cannot keep up or because the PMAPI client cannot keep up, then pmdaEventAd-
dMissedRecord may be used. idx and tp have the same meaning as for pmdaEventAddRecord and nmissed is the number of event records that have
been missed at this point in the time-series of event records. pmdaEventAddMissedRecord may be called multiple times for a single batch of
event records if there are more than one ``missed event record'' episode.
Once an event record has been started by calling pmdaEventAddRecord, one or more event parameters may be added using pmdaEventAddParam.
The pmid and type parameters decribe the PMID of the parameter and the data type (one of the PM_TYPE_* values from <pcp/pmapi.h>) of the
value that is passed via avp. type should one where the size of the value is implied by the type or by the length of a string value (for
PM_TYPE_STRING) or encoded within avp->vbp (for PM_TYPE_AGGREGATE).
Once the packed array has been constructed, pmdaEventGetAddr should be used to initialize the ea_type and ea_len fields at the start of the
pmEventArray and return the base address of the event array that is assigned to the vp field of the pmAtomValue structure that the
pmdaFetchCallBack method should return.
EXAMPLE
The following skeletal code shows how these routines might be used.
int sts;
int myarray;
int first = 1;
pmEventArray eap;
if (first) {
first = 0;
if ((myarray = pmdaEventNewArray()) < 0) {
// report error and fail
}
}
pmdaEventResetArray(myarray);
// loop over all event records to be exported
... {
struct timeval stamp;
int flags;
// establish timestamp and set flags to 0 or some combination
// of PM_EVENT_FLAG_POINT, PM_EVENT_FLAG_START, PM_EVENT_FLAG_ID,
// etc
if ((sts = pmdaEventAddRecord(myarray, &stamp, flags)) < 0) {
// report error and fail
}
// loop over all parameters for this event record
... {
pmID pmid;
int type;
pmAtomValue atom;
// construct pmid, type and atom for the parameter and
// its value
if ((sts = pmdaEventAddParam(myarray, pmid, type, &atom)) < 0) {
// report error and fail
}
}
// if some event records were missed (could be at the start
// of the exported set, or at the end, or in the middle, or
// a combination of multiple missed record episodes)
... {
int nmiss;
struct timeval stamp;
if ((sts = pmdaEventAddMissedRecord(myarray, &stamp, nmiss)) < 0) {
// report error and fail
}
}
}
// finish up
eap = pmdaEventGetAddr(myarray);
SEE ALSO pmdaEventNewQueue(3), pmdaEventNewClient(3), PMDA(3) and pmEventFlagsStr(3).
Performance Co-Pilot PCP PMDAEVENTARRAY(3)