|
HTML rendering created 2025-09-06 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 | CAVEATS | DIAGNOSTICS | ENVIRONMENT | SEE ALSO | COLOPHON |
|
|
|
PMNEWCONTEXT(3) Library Functions Manual PMNEWCONTEXT(3)
pmNewContext - establish a new PMAPI context
#include <pcp/pmapi.h>
int pmNewContext(int type, const char *name);
cc ... -lpcp
An application using the Performance Metrics Application Program‐
ming Interface (PMAPI) may manipulate several concurrent contexts,
each associated with a source of performance metrics, e.g. pmcd(1)
on some host, or a set of archives of performance metrics as cre‐
ated by pmlogger(1), or a stand-alone 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 a comma-separated list of names
referring to a set of archives (type is PM_CONTEXT_ARCHIVE). Each
element of the list may either be the base name common to all of
the physical files of an archive or the name of a directory con‐
taining archives.
For a type of PM_CONTEXT_HOST, in addition to identifying a host
the name may also be used to encode additional optional informa‐
tion 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.example.com:11111" specifies a connec‐
tion 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.
Alternatively, for a type of PM_CONTEXT_HOST, name may be unix:
for an authenticated Unix domain socket connection to pmcd(1) on
the localhost or local: for an authenticated connection to pmcd(1)
on the localhost via a Unix domain socket if available, else via
an internet socket connection to localhost. local: is the default
choice for most applications when calling pmNewContext to estab‐
lish a context for pmcd(1) on the local host.
For a type of PM_CONTEXT_ARCHIVE, each element of the list of
names in 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 da‐
ta 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 com‐
pressed with gzip(1)), myarchive.1 or myarchive.3.bz2 or
myarchive.42.gz etc.
If more than one archive is specified for a type of PM_CON‐
TEXT_ARCHIVE, there are some restrictions on the archives within
the set:
• The archives must all have been generated on the same host.
• The archives must not overlap in time.
• The archives must all have been created using the same time
zone.
• The PMID of each metric should be the same in all of the
archives. Multiple PMIDs are currently tolerated by using the
first PMID defined for each metric and ignoring subsequent
PMIDs.
• The type of each metric must be the same in all of the
archives.
• The semantics of each metric must be the same in all of the
archives.
• The units of each metric must be the same in all of the
archives.
• The instance domain of each metric must be the same in all of
the archives.
In the case where type is PM_CONTEXT_LOCAL, name is ignored, and
the context uses a stand-alone connection to the PMDA methods used
by pmcd(1). The mechanism in the library uses the same ``plugin''
architecture that operates between pmcd(1) and DSO PMDAs, so oper‐
ations involve function calls rather than IPC message passing -
for PM_CONTEXT_LOCAL contexts this may mean lower latency for op‐
erations like pmFetch(3), but at the cost of longer initialization
time and possible access control differences compared to pmcd(1).
When this type of context is used, the range of accessible perfor‐
mance metrics is constrained to those from the DSO PMDAs defined
in the pmcd(1) configuration file /etc/pcp/pmcd/pmcd.conf, so
those reported by the command
$ awk '$3 == "dso" {print}' /etc/pcp/pmcd/pmcd.conf
or alternatively reported by the command
$ pminfo -f pmcd.agent.type | grep 'value 0'
This usually means the PMDA exporting metrics from the operating
system and the ``pmcd'', ``pmproxy'' and may includes some others
like ``mmv''. Alternate DSO PMDAs can be used, refer to
pmSpecLocalPMDA(3).
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), should be encrypted if possible
(PM_CTXFLAG_RELAXED), is deferred (PM_CTXFLAG_SHALLOW), should use
authentication (PM_CTXFLAG_AUTH), should be a connection to a con‐
tainer (PM_CTXFLAG_CONTAINER), or if the file descriptor used to
communicate with pmcd(1), should not be shared across contexts
(PM_CTXFLAG_EXCLUSIVE). Both the PM_CTXFLAG_SHALLOW and
PM_CTXFLAG_EXCLUSIVE flags are now deprecated and ignored.
When type is PM_CONTEXT_ARCHIVE, additional flags can be added to
the type for restricted handling of the archive suited to applica‐
tions that are aware of the structure of PCP archives, namely
PM_CTXFLAG_NO_FEATURE_CHECK (do not check feature compatibility
for archive label records), PM_CTXFLAG_METADATA_ONLY (open only
the metadata, not the data volume(s) nor the index) and
PM_CTXFLAG_LAST_VOLUME (open the archive at the start of the last
data volume, instead of the default start of the first data vol‐
ume).
Multiple flags can be specified by bit-wise ``or-ing'' of the
PM_CTXFLAG macros, but not all combinations make sense, e.g. if
PM_CTXFLAG_METADATA_ONLY and PM_CTXFLAG_LAST_VOLUME are specified,
PM_CTXFLAG_METADATA_ONLY takes precedence.
The initial instance profile is set up to select all instances in
all instance domains. In the case of a set of archives, the ini‐
tial collection time is also set to zero, so that an initial
pmFetch(3) will result in the earliest set of metrics being re‐
turned from the set of archives.
Once established, the association between a context and a source
of metrics is fixed for the life of the context, however routines
are provided 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 subse‐
quent 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. pmNewCon‐
text will abort and return an error if the connection has not been
established after some specified interval has elapsed. The de‐
fault interval is 5 seconds. This may be modified by setting PM‐
CD_CONNECT_TIMEOUT in the environment 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 la‐
tencies to establish the connection correctly.
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 com‐
piled 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 rou‐
tines may return the error code PM_ERR_THREAD if the library de‐
tects calls from more than one thread.
Applications that use gethostbyname(3) should exercise caution be‐
cause 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(3) internally.
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_CON‐
TEXT_HOST or PM_CONTEXT_ARCHIVE.
PM_ERR_LOGOVERLAP
Archives overlap in time
PM_ERR_LOGHOST
Archives differ by host
PM_ERR_LOGCHANGETYPE
The type of a metric differs among archives
PM_ERR_LOGCHANGESEM
The semantics of a metric differs among archives
PM_ERR_LOGCHANGEINDOM
The instance domain of a metric differs among archives
PM_ERR_LOGCHANGEUNITS
The units of a metric differs among archives
PMCD_CONNECT_TIMEOUT
Timeout period (in seconds) for pmcd(1) connection at‐
tempts.
PMCD_PORT
TCP/IP port(s) for connecting to pmcd(1), historically was
4321 and more recently the officially registered port
44321; in the current 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.
pmcd(1), pminfo(1), pmproxy(1), PMAPI(3), pmAddProfile(3),
pmDelProfile(3), pmDestroyContext(3), pmDupContext(3), pmFetch(3),
pmGetConfig(3), pmReconnectContext(3), pmSetMode(3),
pmSpecLocalPMDA(3), pmUseContext(3), pmWhichContext(3),
pcp.conf(5) and pcp.env(5).
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
pcp@groups.io. This page was obtained from the project's upstream
Git repository ⟨https://github.com/performancecopilot/pcp.git⟩ on
2025-08-11. (At that time, the date of the most recent commit
that was found in the repository was 2025-08-11.) 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 man-pages@man7.org
Performance Co-Pilot PCP PMNEWCONTEXT(3)
Pages that refer to this page: pcpintro(1), pmgenmap(1), pmlogdump(1), pmstat(1), pcpintro(3), pmaddderived(3), pmaddprofile(3), pmapi(3), pmaundeltaindom(3), pmdelprofile(3), pmdestroycontext(3), pmdupcontext(3), pmfetch(3), pmfetcharchive(3), pmfetchgroup(3), pmgetarchivelabel(3), pmgetcontexthostname(3), pmgetoptions(3), __pmlocalpmda(3), pmlookuplabels(3), pmlookupname(3), pmnameall(3), pmnameid(3), pmnewcontext(3), pmnewcontextzone(3), pmparsehostattrsspec(3), pmparsehostspec(3), pmreconnectcontext(3), pmregisterderived(3), pmsetmode(3), pmspeclocalpmda(3), pmtrimnamespace(3), pmusecontext(3), pmwebapi(3), pmwhichcontext(3), QmcSource(3)
|
HTML rendering created 2025-09-06 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. |
|