|
HTML rendering created 2024-06-26 by Michael Kerrisk, author of The Linux Programming Interface. For details of in-depth Linux/UNIX system programming training courses that I teach, look here. Hosting by jambit GmbH. |
|
|
NAME | C SYNOPSIS | DESCRIPTION | EXAMPLE | METRIC LOOKUP | METRIC CHANGES | COMMUNICATION ATTRIBUTES | PRIVATE DATA | CAVEAT | DIAGNOSTICS | SEE ALSO | COLOPHON |
|
|
|
PMDAINIT(3) Library Functions Manual PMDAINIT(3)
pmdaInit, pmdaRehash, pmdaSetData, pmdaExtGetData,
pmdaExtSetData, pmdaSetFlags, pmdaSetCommFlags, pmdaExtSetFlags -
initialize a PMDA
#include <pcp/pmapi.h>
#include <pcp/pmda.h>
void pmdaInit(pmdaInterface *dispatch, pmdaIndom *indoms,
int nindoms, pmdaMetric *metrics, int nmetrics);
void pmdaRehash(pmdaExt *pmda, pmdaMetric *metrics,
int nmetrics);
void pmdaSetFlags(pmdaInterface *dispatch, int flags);
void pmdaSetCommFlags(pmdaInterface *dispatch, int flags);
void pmdaExtSetFlags(pmdaExt *pmda, int flags);
void pmdaSetData(pmdaInterface *dispatch, void *data);
void pmdaExtSetData(pmdaExt *pmda, void *data);
void *pmdaExtGetData(pmdaExt *pmda);
cc ... -lpcp_pmda -lpcp
pmdaInit initializes a PMDA so that it is ready to receive PDUs
from pmcd(1). The function expects as arguments the instance do‐
main table (indoms) and the metric description table (metrics)
that are initialized by the PMDA. The arguments nindoms and
nmetrics should be set to the number of instances and metrics in
the tables, respectively.
Much of the pmdaInterface structure can be automatically initial‐
ized with pmdaDaemon(3), pmdaGetOpt(3) and pmdaDSO(3). pmdaInit
completes the PMDA initialization phase with three operations.
The first operation adds the domain and instance numbers to the
instance and metric tables. Singular metrics (metrics without an
instance domain) should have the instance domain PM_INDOM_NULL
set in the indom field of the pmDesc structure (see
pmLookupDesc(3)). Metrics with an instance domain should set
this field to be the serial number of the instance domain in the
indoms table.
The instance domain table may be made empty by setting indoms to
NULL and nindoms to 0. This allows the caller to provide custom
Fetch and Instance callback functions. The metric table may be
made empty by setting metrics to NULL and nmetrics to 0. This
allows the caller to provide custom Fetch and Descriptor callback
functions.
For example, a PMDA has three metrics: A, B and C, and two in‐
stance domains X and Y, with two instances in each instance do‐
main. The instance domain and metrics description tables could
be defined as:
static pmdaInstid _X[] = {
{ 0, "X1" }, { 1, "X2" }
};
static pmdaInstid _Y[] = {
{ 0, "Y1" }, { 1, "Y2" }
};
static pmdaIndom indomtab[] = {
#define X_INDOM 0
{ X_INDOM, 2, _X },
#define Y_INDOM 3
{ Y_INDOM, 2, _Y }
};
static pmdaMetric metrictab[] = {
/* A */
{ (void *)0,
{ PMDA_PMID(0,0), PM_TYPE_U32, PM_INDOM_NULL, PM_SEM_INSTANT,
{ 0,0,0,0,0,0} }, },
/* B */
{ (void *)0,
{ PMDA_PMID(0,1), PM_TYPE_U32, X_INDOM, PM_SEM_INSTANT,
{ 0,0,0,0,0,0} }, },
/* C */
{ (void *)0,
{ PMDA_PMID(0,2), PM_TYPE_DOUBLE, Y_INDOM, PM_SEM_INSTANT,
{ 0,1,0,0,PM_TIME_SEC,0} }, }
};
The metric description table defines metric A with no instance
domain, metric B with instance domain X and metric C with in‐
stance domain Y. Metric C has units of seconds, while the other
metrics have no units (simple counters). pmdaInit will take
these structures and assign the PMDA(3) domain number to the
it_indom field of each instance domain. This identifier also re‐
places the indom field of all metrics which have that instance
domain, so that they are correctly associated.
The second stage opens the help text file, if one was specified
with the -h command line option (see pmdaGetOpt(3)) or as a help‐
text argument to pmdaDSO(3) or pmdaDaemon(3).
The final stage involves preparing the metric table lookup strat‐
egy.
When fetch and descriptor requests are made of the PMDA, each re‐
quested PMID must be mapped to a metric table entry. There are
currently three strategies for performing this mapping - direct,
linear and hashed. Each has its own set of tradeoffs and an ap‐
propriate strategy should be selected for each PMDA.
If all of the metric PMID item numbers correspond to the position
in the metrics table, then direct mapping is used. This is the
most efficient of the lookup functions as it involves a direct
array index (no additional memory is required nor any additional
processing overhead). If the PMID numbering requirement is met
by the PMDA, it is ideal. This strategy can be explicitly re‐
quested by calling pmdaSetFlags(pmda, PMDA_EXT_FLAG_DIRECT) be‐
fore calling pmdaInit. In this case, if the direct mapping is
not possible (e.g. due to an oversight on the part of the PMDA
developer), a warning is logged and the linear strategy is used
instead.
The second strategy (linear search) is the default, when a direct
mapping cannot be established. This provides greater flexibility
in the PMID numbering scheme, as the PMDA item numbers do not
have to be unique (hence, the PMID cluster numbers can be used
more freely, which is often extremely convenient for the PMDA de‐
veloper). However, lookup involves a linear walk from the start
of the metric table until a matching PMID is found, for each re‐
quested PMID in a request.
The third strategy (hash lookup) can be requested by calling pm‐
daSetFlags(pmda, PMDA_EXT_FLAG_HASHED) before calling pmdaInit.
This strategy is most useful for PMDAs with large numbers of met‐
rics (many hundreds, or thousands). Such PMDAs will almost al‐
ways use the cluster numbering scheme, so the direct lookup
scheme becomes inappropriate. They may also be prepared to sac‐
rifice a small amount of additional memory for a hash table, map‐
ping PMID to metric table offsets, to speed up lookups in their
vast metric tables.
This final strategy can also be used by PMDAs serving up dynami‐
cally numbered metrics. For this case, the pmdaRehash function
should be used to replace the metric table when new metrics be‐
come available, or existing metrics are removed. The PMID hash
mapping will be recomputed at the same time that the new metric
table is installed.
It should be well understood by PMDA authors that metric metadata
for individual metrics is fixed, and ideally would not ever
change. In the situation where metadata is incorrect and is up‐
dated, such a change requires correction to logged metrics using
pmlogrewrite(1), and as a result should be avoided whenever pos‐
sible.
However, a PMDA may become aware of new domain metrics at run‐
time, and in this case it is ideal to export them immediately
(without any collector system restart). In this situation, the
PMDA can inform all running PMAPI clients that may have already
explored the metric namespace (for example, using
pmTraversePMNS(3)) of the change to the metric namespace.
This is achieved using pmdaSetFlags(pmda, PMDA_EXT_NAMES_CHANGE)
which will result in the PMCD_NAMES_CHANGE state change notifica‐
tion being sent to each PMAPI client on next fetch. If the newly
discovered metrics have label metadata associated, then the PM‐
DA_EXT_LABEL_CHANGE flag may also be set, which will result in
the PMCD_LABEL_CHANGE notification being sent as well.
pmdaExtSetFlags is equivalent to pmdaSetFlags, and is provided as
a convenience interface in situations where the pmdaExt is more
readily available than the pmdaInterface structure.
Agents that make use of authentication or container attributes
should indicate this using the pmdaSetCommFlags interface. This
indicates the need for these attributes to be communicated on the
channel between the PMDA and pmcd or local context client. Valid
flags are PMDA_FLAG_AUTHORIZE (for authentication related attrib‐
utes) and PMDA_FLAG_CONTAINER (for container name related attrib‐
utes).
A facility for associating private PMDA data with the pmdaExt
structure is available. This allows a PMDA to associate an arbi‐
trary (and typically not global) pointer with the pmdaExt such
that it can be later obtained during callbacks. The interfaces
for setting this pointer are pmdaSetData and pmdaExtSetData, and
pmdaExtGetData for subsequently retrieving it.
The PMDA must be using PMDA_INTERFACE_2 or later, as specified in
the call to pmdaDSO(3) or pmdaDaemon(3) to use pmdaInit.
The PMDA must use PMDA_INTERFACE_7 or later to issue state change
notifications using pmdaSetFlags or pmdaExtSetFlags.
pmdaInit will set dispatch->status to a value less than zero if
there is an error that would prevent the PMDA(3) from successful‐
ly running. pmcd(1) will terminate the connection to the PMDA(3)
if this occurs.
pmdaInit may issue any of these messages:
PMDA interface version interface not supported
The interface version is not supported by pmdaInit.
Using pmdaFetch() but fetch call back not set
The fetch callback, pmdaFetch(3), requires an additional
callback to be provided using pmdaSetFetchCallBack(3).
Illegal instance domain inst for metric pmid
The instance domain inst that was specified for metric
pmid is not within the range of the instance domain table.
No help text path specified
The help text callback, pmdaText(3), requires a help text
file for the metrics to have been opened, however no path
to the help text was specified as a command line option,
or as an argument to pmdaDSO(3) or pmdaDaemon(3). This
message is only a warning.
Direct mapping for metrics disabled @ num
The unit numbers of the metrics did not correspond to the
index in the metric description table. The direct mapping
failed for metric number num in the metrics table. This
is less efficient but is not fatal and the message is only
a warning.
Hashed mapping for metrics disabled @ num
A memory allocation failure occurred while building the
hash table to index the metric description table. This is
a non-fatal warning message - a fallback to linear search‐
ing will be automatically performed should this situation
arise.
newhelp(1), pmcd(1), pmlogrewrite(1), PMAPI(3), PMDA(3),
pmdaDaemon(3), pmdaDSO(3), pmdaFetch(3), pmdaGetOpt(3),
pmdaText(3), pmLookupDesc(3) and pmTraversePMNS(3).
This page is part of the PCP (Performance Co-Pilot) project. In‐
formation about the project can be found at ⟨http://www.pcp.io/⟩.
If you have a bug report for this manual page, send it to
[email protected]. This page was obtained from the project's
upstream Git repository
⟨https://github.com/performancecopilot/pcp.git⟩ on 2024-06-14.
(At that time, the date of the most recent commit that was found
in the repository was 2024-06-14.) If you discover any rendering
problems in this HTML version of the page, or you believe there
is a better or more up-to-date source for the page, or you have
corrections or improvements to the information in this COLOPHON
(which is not part of the original manual page), send a mail to
[email protected]
Performance Co-Pilot PCP PMDAINIT(3)
Pages that refer to this page: pmlogger(1), pmda(3), pmdacache(3), pmdaconnect(3), pmdadso(3), pmdafetch(3), pmdahelp(3), pmdalabel(3), pmdatext(3)
|
HTML rendering created 2024-06-26 by Michael Kerrisk, author of The Linux Programming Interface. For details of in-depth Linux/UNIX system programming training courses that I teach, look here. Hosting by jambit GmbH. |
|