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
pmlogger(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.example.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 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 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 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 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 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.
- 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),
pmReconnectContext(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.