pmdaeventclient(3) [centos man page]
PMDAEVENTCLIENT(3) Library Functions Manual PMDAEVENTCLIENT(3) NAME
pmdaEventNewClient, pmdaEventEndClient, pmdaEventClients - client context tracking interfaces for event queues C SYNOPSIS
#include <pcp/pmapi.h> #include <pcp/impl.h> #include <pcp/pmda.h> int pmdaEventNewClient(int context); int pmdaEventEndClient(int context); int pmdaEventClients(pmAtomValue *avp); cc ... -lpcp_pmda -lpcp DESCRIPTION
A Performance Metrics Domain Agent (PMDA) that exports event records needs to track which clients are connected to it, in order that it can track which events have been sent to which clients so far. Only once an event has been sent to all monitoring tools that registered an in- terest can the event be discarded and any memory reclaimed. The PMDA(3) library provides callback routines for PMDA developers to provide custom handling of client connections and disconnections. If the PMDA is making use of the event queueing mechanism provided by pmdaEventNewQueue(3) and friends, client connections and disconnections must be tracked via calls to pmdaEventNewClient and pmdaEventEndClient respectively. This allows the library to keep track of when events can be discarded from a queue, for example, for the context specified. This parameter is passed into the e_endCallBack function directly, and for other callback functions is available via the e_context field of the pmdaExt structure. Additionally, it can be queried at any time using pmdaGetContext(3). Sometimes it is useful for the PMDA to export a metric indicating the current count of attached clients - this is available using the pm- daEventClients routine, which will fill in the avp pmAtomValue structure on behalf of a PMDA fetch callback routine. SEE ALSO
pmdaEventNewArray(3), pmdaEventNewQueue(3), PMAPI(3), PMDA(3) and pmEventFlagsStr(3). Performance Co-Pilot PCP PMDAEVENTCLIENT(3)
Check Out this Related Man Page
PMDAEVENTQUEUE(3) Library Functions Manual PMDAEVENTQUEUE(3) NAME
pmdaEventNewQueue, pmdaEventNewActiveQueue, pmdaEventQueueHandle, pmdaEventQueueAppend, pmdaEventQueueRecords, pmdaEventQueueClients, pmdaEventQueueCounter, pmdaEventQueueBytes, pmdaEventQueueMemory - utilities for PMDAs managing event queues C SYNOPSIS
#include <pcp/pmapi.h> #include <pcp/impl.h> #include <pcp/pmda.h> int pmdaEventNewQueue(const char *name, size_t maxmem); int pmdaEventNewActiveQueue(const char *name, size_t maxmem, int nclients); int pmdaEventQueueHandle(const char *name); int pmdaEventQueueAppend(int handle, void *buffer, size_t bytes, struct timeval *tv); typedef int (*pmdaEventDecodeCallBack)(int, void *, int, struct timeval *, void *); int pmdaEventQueueRecords(int handle, pmAtomValue *avp, int context, pmdaEventDecodeCallBack decoder, void *data); int pmdaEventQueueClients(int handle, pmAtomValue *avp); int pmdaEventQueueCounter(int handle, pmAtomValue *avp); int pmdaEventQueueBytes(int handle, pmAtomValue *avp); int pmdaEventQueueMemory(int handle, pmAtomValue *avp); cc ... -lpcp_pmda -lpcp DESCRIPTION
A Performance Metrics Domain Agent (PMDA) that exports event records must effectively act an event multiplexer. Events consumed by the PM- DA may have to be forwarded on to any number of monitoring tools (or "client contexts"). These tools may be requesting events at different sampling intervals, and are very unlikely to request an event at the exact moment it arrives at the PMDA, making some form of event buffer- ing and queueing scheme a necessity. Events must be held by the PMDA until either all registered clients have been sent them, or until a memory limit has been reached by the PMDA at which point it must discard older events as new ones arrive. The routines described here are designed to assist the PMDA developer in managing both client contexts and queues of events at a high lev- el. These fit logically above lower level primitives, such as those described in pmdaEventNewArray(3), and shield the average PMDA from the details of directly building event record arrays for individual client contexts. The PMDA registers a new queue of events using either pmdaEventNewQueue or pmdaEventNewActiveQueue. These are passed an identifying name (for diagnostic purposes, and for subsequent lookup by pmdaEventQueueLookup) and maxmem, an upper bound on the memory (in bytes) that can be consumed by events in this queue, before beginning to discard them (resulting in "missed" events for any client that has not kept up). If a queue is dynamically allocated (such that the PMDA may already have clients connected) the pmdaEventNewActiveQueue interface should be used, with the additional numclients parameter indicating the count of active client connections. The return is a negative error code on failure, suitable for decoding by the pmErrStr(3) routine. Any non-negative value indicates success, and provides a handle suitable for passing into the other API routines. For each new event received by the PMDA, the pmdaEventQueueAppend routine should be called, placing that event into the queue identified by handle. The event itself must be contained in the passed in buffer, having bytes length. The timestamp associated with the event (time at which the event occurred) is passed in via the final tv parameter. In the PMDAs specific implementation of its fetch callback, when values for an event metric have been requested, the pmdaEventQueueRecords routine should be used. It is passed the queue handle and the avp pmAtomValue structure to fill with event records, for the client making that fetch request (identified by the context parameter). Finally, the PMDA must also pass in an event decoding routine, which is respon- sible for decoding the fields of a single event into the individual event parameters of that event. The data parameter is an opaque cookie that can be used to pass situation-specific information into each decoder invocation. Under some situations it is useful for the PMDA to export state about the queues under its control. The accessor routines - pmdaEven- tQueueClients, pmdaEventQueueCounter, pmdaEventQueueBytes and pmdaEventQueueMemory provide a mechanism for querying a queue by its handle and filling in a pmAtomValue structure that the pmdaFetchCallBack method should return. SEE ALSO
PMAPI(3), PMDA(3), pmdaEventNewClient(3) and pmdaEventNewArray(3). Performance Co-Pilot PCP PMDAEVENTQUEUE(3)