__pmlocalpmda(3) [centos man page]
PMLOCALPMDA(3) Library Functions Manual PMLOCALPMDA(3) NAME
__pmLocalPMDA - change the table of DSO PMDAs for PM_CONTEXT_LOCAL contexts C SYNOPSIS
#include <pcp/pmapi.h> #include <pcp/impl.h> int __pmLocalPMDA(int op, int domain, const char *name, const char *init); cc ... -lpcp DESCRIPTION
PCP contexts of type PM_CONTEXT_LOCAL are used by clients that wish to fetch metrics directly from one or more PMDAs on the local host without involving pmcd(1). A PMDA that is to be used in this way must have been built as a Dynamic Shared Object (DSO). Historically the table of PMDAs available for use with PM_CONTEXT_LOCAL was hardcoded to the following: * The PMDA (or PMDAs) that export the operating system performance data and data about process activity. * The mmv PMDA. * The sample PMDA provided $PCP_LITE_SAMPLE or $PMDA_LOCAL_SAMPLE is set in the environment - used mostly for QA and testing. The initial table of PMDAs available for use with PM_CONTEXT_LOCAL is now generated dynamically from all those PMDAs that have been in- stalled as DSOs on the local host. The one exception is the ``pmcd'' PMDA which only operates correctly in the address space of a running pmcd(1) process and so is not available to an application using a PM_CONTEXT_LOCAL context. __pmLocalPMDA provides a number of services to amend the table of PMDAs available for use with PM_CONTEXT_LOCAL. The op argument specifies the what should be done and takes one of the following values and actions: PM_LOCAL_ADD Append an entry to the table for the PMDA with a Performance Metrics Domain (PMD) of domain, the path to the DSO PMDA is given by path and the PMDA's initialization routine is init. PM_LOCAL_DEL Removes all entries in the table where the domain matches, or the path matches. Setting the arguments domain to -1 or path to NULL to force matching on the other argument. The init argument is ignored. PM_LOCAL_CLEAR Remove all entries from the table. All the other arguments are ignored in this case. The domain, name and init arguments have similar syntax and semantics to the associated fields in the pmcd(1) configuration file. The one difference is the path argument which is used by __pmLocalPMDA to find a likely looking DSO by searching in this order: $PCP_PM- DAS_DIR/path, path, $PCP_PMDAS_DIR/path.dso-suffix and finally path.dso-suffix (dso-suffix is the local platform specific default file name suffix for a DSO, e.g. so for Linux, dylib for Mac OS X, dll for Windows, etc.). RETURN VALUE
In most cases, __pmLocalPMDA returns 0 to indicate success. If op is invalid, then the return value is PM_ERR_CONV else if there is no matching table entry found for a PM_LOCAL_DEL operation, PM_ERR_INDOM is returned. SEE ALSO
pmcd(1), PMAPI(3), pmNewContext(3) and __pmSpecLocalPMDA(3). Performance Co-Pilot PMLOCALPMDA(3)
Check Out this Related Man Page
PMNEWCONTEXT(3) Library Functions Manual PMNEWCONTEXT(3) NAME
pmNewContext - establish a new PMAPI context C SYNOPSIS
#include <pcp/pmapi.h> int pmNewContext(int type, const char *name); cc ... -lpcp DESCRIPTION
An application using the Performance Metrics Application Programming Interface (PMAPI) may manipulate several concurrent contexts, each associated with a source of performance metrics, e.g. pmcd(1) on some host, or an archive log of performance metrics as created by pmlog- ger(1), or a standalone connection on the local host that does not involve pmcd(1). pmNewContext may be used to establish a new context. The source of the metrics is identified by name, and may be either a host name (type is PM_CONTEXT_HOST), or the base name common to all of the physical files of an archive log (type is PM_CONTEXT_ARCHIVE). For a type of PM_CONTEXT_HOST, in addition to identifying a host the name may also be used to encode additional optional information in the form of a pmcd(1) port number, a pmproxy(1) hostname and a proxy port number. For example the name "app23:14321,4321@firewall.exam- ple.com:11111" specifies a connection on port 14321 (or port 4321 if 14321 is unavailable) to pmcd(1) on the host app23 via port 11111 to pmproxy(1) on the host firewall.example.com. For a type of PM_CONTEXT_ARCHIVE, name may also be the name of any of the physical files of an archive, e.g. myarchive.meta (the metadata file) or myarchive.index (the temporal index) or myarchive.0 (the first data volume of the archive) or myarchive.0.bz2 or myarchive.0.bz (the first data volume compressed with bzip2(1)) or myarchive.0.gz or myarchive.0.Z or myarchive.0.z (the first data volume compressed with gzip(1)), myarchive.1 or myarchive.3.bz2 or myarchive.42.gz etc. In the case where type is PM_CONTEXT_LOCAL, name is ignored, and the context uses a standalone connection to the PMDA methods used by pmcd(1). When this type of context is used, the range of accessible performance metrics is constrained to those from the operating system, and optionally the ``proc'', ``sample'' and ``ib'' PMDAs. In the case where type is PM_CONTEXT_HOST, additional flags can be added to the type to indicate if the connection to pmcd(1) should be encrypted (PM_CTXFLAG_SECURE), deferred (PM_CTXFLAG_SHALLOW) and if the file descriptor used to communicate with pmcd(1), should not be shared across contexts (PM_CTXFLAG_EXCLUSIVE). These final two context flags are now deprecated and ignored. The initial instance profile is set up to select all instances in all instance domains. In the case of an archive, the initial collection time is also set to zero, so that an initial pmFetch(3) will result in the earliest set of metrics being returned from the archive. Once established, the association between a context and a source of metrics is fixed for the life of the context, however routines are pro- vided to independently manipulate both the instance profile (see pmAddProfile(3) and pmDelProfile(3)) and the collection time for archives (see pmSetMode(3)). pmNewContext returns a handle that may be used with subsequent calls to pmUseContext(3). The new context remains the current PMAPI context for all subsequent calls across the PMAPI, until another call to pmNewContext(3) is made, or the context is explicitly changed with a call to pmDupContext(3) or pmUseContext(3), or destroyed using pmDestroyContext(3). When attempting to connect to a remote pmcd(1) on a machine that is booting, pmNewContext could potentially block for a long time until the remote machine finishes its initialization. pmNewContext will abort and return an error if the connection has not been established after some specified interval has elapsed. The default interval is 5 seconds. This may be modified by setting PMCD_CONNECT_TIMEOUT in the envi- ronment to a real number of seconds for the desired timeout. This is most useful in cases where the remote host is at the end of a slow network, requiring longer latencies to establish the connection correctly. ENVIRONMENT
PMCD_CONNECT_TIMEOUT Timeout period (in seconds) for pmcd(1) connection attempts. PMCD_PORT TCP/IP port(s) for connecting to pmcd(1), historically was 4321 and more recently the officially registered port 44321; in the cur- rent release, pmcd listens on both these ports as a transitional arrangement. If used, should be set to a comma-separated list of numerical port numbers. PMDA_PATH When searching for PMDAs to be loaded when type is PM_CONTEXT_LOCAL, the PMDA_PATH environment variable may be used to define a search path of directories to be used to locate the PMDA executables. The default search path is $PCP_SHARE_DIR/lib:/usr/pcp/lib. CAVEATS
When using a type of PM_CONTEXT_LOCAL, the operating system PMDA may export data structures directly from the kernel, which means that the pmNewContext caller should be an executable program compiled for the same object code format as the booted kernel. In addition, applications using a PM_CONTEXT_LOCAL context must be single-threaded because the various DSO PMDAs may not be thread-safe. This restriction is enforced at the PMAPI(3), where routines may return the error code PM_ERR_THREAD if the library detects calls from more than one thread. Applications that use gethostbyname(3N) should exercise caution because the static fields in struct hostent may not be preserved across some PMAPI(3) calls. In particular, pmNewContext(3) and pmReconnectContext(3) both may call gethostbyname(3N) internally. SEE ALSO
pmcd(1), pmproxy(1), pmAddProfile(3), PMAPI(3), pmDelProfile(3), pmDestroyContext(3), pmDupContext(3), pmGetConfig(3), pmReconnectCon- text(3), pmSetMode(3), pmUseContext(3), pmWhichContext(3), pcp.conf(5) and pcp.env(5). DIAGNOSTICS
PM_ERR_PERMISSION No permission to perform requested operation PM_ERR_CONNLIMIT PMCD connection limit for this host exceeded PM_ERR_NOCONTEXT Requested context type was not PM_CONTEXT_LOCAL, PM_CONTEXT_HOST or PM_CONTEXT_ARCHIVE. Performance Co-Pilot PCP PMNEWCONTEXT(3)