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 archive logs of performance metrics as created by pm‐
20 logger(1), or a standalone connection on the local host that does not
21 involve 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 archive logs (type is PM_CONTEXT_ARCHIVE). Each element of the list
27 may either be the base name common to all of the physical files of an
28 archive log or the name of a directory containing archive logs.
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 The initial instance profile is set up to select all instances in all
84 instance domains. In the case of a set of archives, the initial col‐
85 lection time is also set to zero, so that an initial pmFetch(3) will
86 result in the earliest set of metrics being returned from the set of
87 archives.
88 Once established, the association between a context and a source of
90 metrics is fixed for the life of the context, however routines are pro‐
91 vided to independently manipulate both the instance profile (see pmAd‐
92 dProfile(3) and pmDelProfile(3)) and the collection time for archives
93 (see pmSetMode(3)).
94 pmNewContext returns a handle that may be used with subsequent calls to
96 pmUseContext(3).
97 The new context remains the current PMAPI context for all subsequent
99 calls across the PMAPI, until another call to pmNewContext(3) is made,
100 or the context is explicitly changed with a call to pmDupContext(3) or
101 pmUseContext(3), or destroyed using pmDestroyContext(3).
102 When attempting to connect to a remote pmcd(1) on a machine that is
104 booting, pmNewContext could potentially block for a long time until the
105 remote machine finishes its initialization. pmNewContext will abort
106 and return an error if the connection has not been established after
107 some specified interval has elapsed. The default interval is 5 sec‐
108 onds. This may be modified by setting PMCD_CONNECT_TIMEOUT in the en‐
109 vironment to a real number of seconds for the desired timeout. This is
110 most useful in cases where the remote host is at the end of a slow net‐
111 work, requiring longer latencies to establish the connection correctly.
112
114 When using a type of PM_CONTEXT_LOCAL, the operating system PMDA may
115 export data structures directly from the kernel, which means that the
116 pmNewContext caller should be an executable program compiled for the
117 same object code format as the booted kernel.
118 In addition, applications using a PM_CONTEXT_LOCAL context must be sin‐
120 gle-threaded because the various DSO PMDAs may not be thread-safe.
121 This restriction is enforced at the PMAPI(3), where routines may return
122 the error code PM_ERR_THREAD if the library detects calls from more
123 than one thread.
124 Applications that use gethostbyname(3) should exercise caution because
126 the static fields in struct hostent may not be preserved across some
127 PMAPI(3) calls. In particular, pmNewContext(3) and pmReconnectCon‐
128 text(3) both may call gethostbyname(3) internally.
129
131 PM_ERR_PERMISSION
132 No permission to perform requested operation
134 PM_ERR_CONNLIMIT
136 PMCD connection limit for this host exceeded
138 PM_ERR_NOCONTEXT
140 Requested context type was not PM_CONTEXT_LOCAL, PM_CONTEXT_HOST
142 or PM_CONTEXT_ARCHIVE.
143 PM_ERR_LOGOVERLAP
145 Archives overlap in time
147 PM_ERR_LOGHOST
149 Archives differ by host
151 PM_ERR_LOGTIMEZONE
153 Archives differ by time zone.
155 PM_ERR_LOGCHANGETYPE
157 The type of a metric differs among archives
159 PM_ERR_LOGCHANGESEM
161 The semantics of a metric differs among archives
163 PM_ERR_LOGCHANGEINDOM
165 The instance domain of a metric differs among archives
167 PM_ERR_LOGCHANGEUNITS
169 The units of a metric differs among archives
171
173 PMCD_CONNECT_TIMEOUT
174 Timeout period (in seconds) for pmcd(1) connection attempts.
175 PMCD_PORT
177 TCP/IP port(s) for connecting to pmcd(1), historically was 4321
178 and more recently the officially registered port 44321; in the
179 current release, pmcd listens on both these ports as a transi‐
180 tional arrangement. If used, should be set to a comma-separated
181 list of numerical port numbers.
182 PMDA_PATH
184 When searching for PMDAs to be loaded when type is PM_CON‐
185 TEXT_LOCAL, the PMDA_PATH environment variable may be used to
186 define a search path of directories to be used to locate the
187 PMDA executables. The default search path is
188 $PCP_SHARE_DIR/lib:/usr/pcp/lib.
189
191 pmcd(1), pmproxy(1), pmAddProfile(3), PMAPI(3), pmDelProfile(3), pmDe‐
192 stroyContext(3), pmDupContext(3), pmGetConfig(3), pmReconnectCon‐
193 text(3), pmSetMode(3), pmUseContext(3), pmWhichContext(3), pcp.conf(5)
194 and pcp.env(5).
195Performance Co-Pilot PCP PMNEWCONTEXT(3)