PMNEWCONTEXT(3)

💖 PMNEWCONTEXT(3) — the manual page bestie 💖

okay so this is pmNewContext from the Performance Co-Pilot library functions manual, and we're gonna get you fluent in it, no cap. ✨

---

🌸 NAME 🌸

pmNewContext — establish a new PMAPI context (it's giving "new era, new me" but for performance metrics) 🦋

---

✨ C SYNOPSIS ✨

#include <pcp/pmapi.h>

int pmNewContext(int type, const char *name);

cc ... -lpcp

---

💅 DESCRIPTION 💅

So basically, an app using the Performance Metrics Application Programming Interface (PMAPI) can juggle several concurrent contexts at once, and each one is tied to a source of performance metrics — like pmcd(1) on some host, or a set of archives of performance metrics as created by pmlogger(1), or a stand-alone connection on the local host that does not involve pmcd(1). multiple contexts? she contains multitudes. 💜

pmNewContext is the one you call to establish a new context. The source of the metrics is identified by name, and it can be either a host name (when type is PM_CONTEXT_HOST), or a comma-separated list of names referring to a set of archives (when type is PM_CONTEXT_ARCHIVE). Each element of that list can either be the base name common to all of the physical files of an archive, or the name of a directory containing archives. 🗂️

🎀 when type is PM_CONTEXT_HOST 🎀

For a type of PM_CONTEXT_HOST, besides identifying a host, the name can also encode extra optional info: 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. iconic networking moment fr fr. 🌐

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 establish a context for pmcd(1) on the local host. the default! remember it! 🫶

🌈 when type is PM_CONTEXT_ARCHIVE 🌈

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 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. so many file extensions bestie, it's a whole alphabet. 🔥

⚠️ the archive-set restrictions ⚠️

If more than one archive is specified for a type of PM_CONTEXT_ARCHIVE, there are some restrictions on the archives within the set — and these are not optional, they're the vibe check the archives must pass:

• 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.

like, they all gotta match, it's giving synchronized swimming. 🏊‍♀️

💀 when type is PM_CONTEXT_LOCAL 💀

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 operations involve function calls rather than IPC message passing — for PM_CONTEXT_LOCAL contexts this may mean lower latency for operations like pmFetch(3), but at the cost of longer initialization time and possible access control differences compared to pmcd(1). tradeoffs, we love to see them. 😭

When this type of context is used, the range of accessible performance 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). 💫

🔐 the PM_CONTEXT_HOST extra flags 🔐

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 container (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. 👑 (the way they got phased out… periodt.)

📦 the PM_CONTEXT_ARCHIVE extra flags 📦

When type is PM_CONTEXT_ARCHIVE, additional flags can be added to the type for restricted handling of the archive suited to applications 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 volume). 🗃️

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. precedence! she said it first, she wins!

🦋 what you get when it's set up 🦋

The initial instance profile is set up to select all instances in all instance domains. In the case of a set of archives, 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 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 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). main character energy: the context stays until something else steals the spotlight. ✨

⏳ the timeout tea ⏳

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. 🐢

---

🚨 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. same object code format or it's a whole situation. 💀

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. no multitasking bestie, pick a lane. 🙈

Applications that use gethostbyname(3) 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(3) internally. ⚠️

---

🔍 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.
• 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

these are the error codes and they are NOT playing around. 💅

---

🌿 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.

---

👀 SEE ALSO 👀

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).

---

and that's the whole page bestie!! this was Performance Co-Pilot, PCP, PMNEWCONTEXT(3), and you ate that. go establish some contexts, stay single-threaded, and remember: local: is the default. mwah! 💖🎀🦋✨