1PMNEWCONTEXT(3) Library Functions Manual PMNEWCONTEXT(3)
2
6 pmNewContext - establish a new PMAPI context
7
9 #include <pcp/pmapi.h>
10 int pmNewContext(int type, const char *name);
12 cc ... -lpcp
14
16 An application using the Performance Metrics Application Programming
17 Interface (PMAPI) may manipulate several concurrent contexts, each as‐
18 sociated with a source of performance metrics, e.g. pmcd(1) on some
19 host, or a set of archives of performance metrics as created by pmlog‐
20 ger(1), or a standalone connection on the local host that does not in‐
21 volve pmcd(1).
22 pmNewContext may be used to establish a new context. The source of the
24 metrics is identified by name, and may be either a host name (type is
25 PM_CONTEXT_HOST), or a comma-separated list of names referring to a set
26 of archives (type is PM_CONTEXT_ARCHIVE). Each element of the list may
27 either be the base name common to all of the physical files of an ar‐
28 chive or the name of a directory containing archives.
29 For a type of PM_CONTEXT_HOST, in addition to identifying a host the
31 name may also be used to encode additional optional information in the
32 form of a pmcd(1) port number, a pmproxy(1) hostname and a proxy port
33 number. For example the name "app23:14321,4321@firewall.exam‐
34 ple.com:11111" specifies a connection on port 14321 (or port 4321 if
35 14321 is unavailable) to pmcd(1) on the host app23 via port 11111 to
36 pmproxy(1) on the host firewall.example.com.
37 For a type of PM_CONTEXT_ARCHIVE, each element of the list of names in
39 name may also be the name of any of the physical files of an archive,
40 e.g. myarchive.meta (the metadata file) or myarchive.index (the tempo‐
41 ral index) or myarchive.0 (the first data volume of the archive) or
42 myarchive.0.bz2 or myarchive.0.bz (the first data volume compressed
43 with bzip2(1)) or myarchive.0.gz or myarchive.0.Z or myarchive.0.z (the
44 first data volume compressed with gzip(1)), myarchive.1 or
45 myarchive.3.bz2 or myarchive.42.gz etc.
46 If more than one archive is specified for a type of PM_CONTEXT_ARCHIVE,
48 there are some restrictions on the archives within the set:
49 • The archives must all have been generated on the same host.
51 • The archives must not overlap in time.
53 • The archives must all have been created using the same time zone.
55 • The PMID of each metric should be the same in all of the archives.
57 Multiple PMIDs are currently tolerated by using the first PMID de‐
58 fined for each metric and ignoring subsequent PMIDs.
59 • The type of each metric must be the same in all of the archives.
61 • The semantics of each metric must be the same in all of the ar‐
63 chives.
64 • The units of each metric must be the same in all of the archives.
66 • The instance domain of each metric must be the same in all of the
68 archives.
69 In the case where type is PM_CONTEXT_LOCAL, name is ignored, and the
71 context uses a standalone connection to the PMDA methods used by
72 pmcd(1). When this type of context is used, the range of accessible
73 performance metrics is constrained to those from the operating system,
74 and optionally the ``proc'', ``sample'' and ``ib'' PMDAs.
75 In the case where type is PM_CONTEXT_HOST, additional flags can be
77 added to the type to indicate if the connection to pmcd(1) should be
78 encrypted (PM_CTXFLAG_SECURE), deferred (PM_CTXFLAG_SHALLOW) and if the
79 file descriptor used to communicate with pmcd(1), should not be shared
80 across contexts (PM_CTXFLAG_EXCLUSIVE). Both the PM_CTXFLAG_SHALLOW
81 and PM_CTXFLAG_EXCLUSIVE flags are now deprecated and ignored.
82 When type is PM_CONTEXT_ARCHIVE, additional flags can be added to the
84 type for restricted handling of the archive suited to applications that
85 are aware of the structure of PCP archives, namely PM_CTXFLAG_NO_FEA‐
86 TURE_CHECK (do not check feature compatibility for archive label
87 records) and PM_CTXFLAG_METADATA_ONLY (open only the metadata, not the
88 data volume(s) nor the index). Currently these additional flags are
89 only used by pmlogrewrite(1) and pmlogdump(1).
90 The initial instance profile is set up to select all instances in all
92 instance domains. In the case of a set of archives, the initial col‐
93 lection time is also set to zero, so that an initial pmFetch(3) will
94 result in the earliest set of metrics being returned from the set of
95 archives.
96 Once established, the association between a context and a source of
98 metrics is fixed for the life of the context, however routines are pro‐
99 vided to independently manipulate both the instance profile (see pmAd‐
100 dProfile(3) and pmDelProfile(3)) and the collection time for archives
101 (see pmSetMode(3)).
102 pmNewContext returns a handle that may be used with subsequent calls to
104 pmUseContext(3).
105 The new context remains the current PMAPI context for all subsequent
107 calls across the PMAPI, until another call to pmNewContext(3) is made,
108 or the context is explicitly changed with a call to pmDupContext(3) or
109 pmUseContext(3), or destroyed using pmDestroyContext(3).
110 When attempting to connect to a remote pmcd(1) on a machine that is
112 booting, pmNewContext could potentially block for a long time until the
113 remote machine finishes its initialization. pmNewContext will abort
114 and return an error if the connection has not been established after
115 some specified interval has elapsed. The default interval is 5 sec‐
116 onds. This may be modified by setting PMCD_CONNECT_TIMEOUT in the en‐
117 vironment to a real number of seconds for the desired timeout. This is
118 most useful in cases where the remote host is at the end of a slow net‐
119 work, requiring longer latencies to establish the connection correctly.
120
122 When using a type of PM_CONTEXT_LOCAL, the operating system PMDA may
123 export data structures directly from the kernel, which means that the
124 pmNewContext caller should be an executable program compiled for the
125 same object code format as the booted kernel.
126 In addition, applications using a PM_CONTEXT_LOCAL context must be sin‐
128 gle-threaded because the various DSO PMDAs may not be thread-safe.
129 This restriction is enforced at the PMAPI(3), where routines may return
130 the error code PM_ERR_THREAD if the library detects calls from more
131 than one thread.
132 Applications that use gethostbyname(3) should exercise caution because
134 the static fields in struct hostent may not be preserved across some
135 PMAPI(3) calls. In particular, pmNewContext(3) and pmReconnectCon‐
136 text(3) both may call gethostbyname(3) internally.
137
139 PM_ERR_PERMISSION
140 No permission to perform requested operation
142 PM_ERR_CONNLIMIT
144 PMCD connection limit for this host exceeded
146 PM_ERR_NOCONTEXT
148 Requested context type was not PM_CONTEXT_LOCAL, PM_CONTEXT_HOST
150 or PM_CONTEXT_ARCHIVE.
151 PM_ERR_LOGOVERLAP
153 Archives overlap in time
155 PM_ERR_LOGHOST
157 Archives differ by host
159 PM_ERR_LOGTIMEZONE
161 Archives differ by time zone.
163 PM_ERR_LOGCHANGETYPE
165 The type of a metric differs among archives
167 PM_ERR_LOGCHANGESEM
169 The semantics of a metric differs among archives
171 PM_ERR_LOGCHANGEINDOM
173 The instance domain of a metric differs among archives
175 PM_ERR_LOGCHANGEUNITS
177 The units of a metric differs among archives
179
181 PMCD_CONNECT_TIMEOUT
182 Timeout period (in seconds) for pmcd(1) connection attempts.
183 PMCD_PORT
185 TCP/IP port(s) for connecting to pmcd(1), historically was 4321
186 and more recently the officially registered port 44321; in the
187 current release, pmcd listens on both these ports as a transi‐
188 tional arrangement. If used, should be set to a comma-separated
189 list of numerical port numbers.
190 PMDA_PATH
192 When searching for PMDAs to be loaded when type is PM_CON‐
193 TEXT_LOCAL, the PMDA_PATH environment variable may be used to
194 define a search path of directories to be used to locate the
195 PMDA executables. The default search path is
196 $PCP_SHARE_DIR/lib:/usr/pcp/lib.
197
199 pmcd(1), pmproxy(1), pmAddProfile(3), PMAPI(3), pmDelProfile(3), pmDe‐
200 stroyContext(3), pmDupContext(3), pmGetConfig(3), pmReconnectCon‐
201 text(3), pmSetMode(3), pmUseContext(3), pmWhichContext(3), pcp.conf(5)
202 and pcp.env(5).
203Performance Co-Pilot PCP PMNEWCONTEXT(3)