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
18 associated 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
20 pmlogger(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
58 defined 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
109 environment to a real number of seconds for the desired timeout. This
110 is most useful in cases where the remote host is at the end of a slow
111 network, requiring longer latencies to establish the connection cor‐
112 rectly.
113
115 PMCD_CONNECT_TIMEOUT
116 Timeout period (in seconds) for pmcd(1) connection attempts.
117 PMCD_PORT
119 TCP/IP port(s) for connecting to pmcd(1), historically was 4321
120 and more recently the officially registered port 44321; in the
121 current release, pmcd listens on both these ports as a transi‐
122 tional arrangement. If used, should be set to a comma-separated
123 list of numerical port numbers.
124 PMDA_PATH
126 When searching for PMDAs to be loaded when type is PM_CON‐
127 TEXT_LOCAL, the PMDA_PATH environment variable may be used to
128 define a search path of directories to be used to locate the
129 PMDA executables. The default search path is
130 $PCP_SHARE_DIR/lib:/usr/pcp/lib.
131
133 When using a type of PM_CONTEXT_LOCAL, the operating system PMDA may
134 export data structures directly from the kernel, which means that the
135 pmNewContext caller should be an executable program compiled for the
136 same object code format as the booted kernel.
137 In addition, applications using a PM_CONTEXT_LOCAL context must be sin‐
139 gle-threaded because the various DSO PMDAs may not be thread-safe.
140 This restriction is enforced at the PMAPI(3), where routines may return
141 the error code PM_ERR_THREAD if the library detects calls from more
142 than one thread.
143 Applications that use gethostbyname(3) should exercise caution because
145 the static fields in struct hostent may not be preserved across some
146 PMAPI(3) calls. In particular, pmNewContext(3) and pmReconnectCon‐
147 text(3) both may call gethostbyname(3) internally.
148
150 pmcd(1), pmproxy(1), pmAddProfile(3), PMAPI(3), pmDelProfile(3), pmDe‐
151 stroyContext(3), pmDupContext(3), pmGetConfig(3), pmReconnectCon‐
152 text(3), pmSetMode(3), pmUseContext(3), pmWhichContext(3), pcp.conf(5)
153 and pcp.env(5).
154
156 PM_ERR_PERMISSION
157 No permission to perform requested operation
159 PM_ERR_CONNLIMIT
161 PMCD connection limit for this host exceeded
163 PM_ERR_NOCONTEXT
165 Requested context type was not PM_CONTEXT_LOCAL, PM_CONTEXT_HOST
167 or PM_CONTEXT_ARCHIVE.
168 PM_ERR_LOGOVERLAP
170 Archives overlap in time
172 PM_ERR_LOGHOST
174 Archives differ by host
176 PM_ERR_LOGTIMEZONE
178 Archives differ by time zone.
180 PM_ERR_LOGCHANGETYPE
182 The type of a metric differs among archives
184 PM_ERR_LOGCHANGESEM
186 The semantics of a metric differs among archives
188 PM_ERR_LOGCHANGEINDOM
190 The instance domain of a metric differs among archives
192 PM_ERR_LOGCHANGEUNITS
194 The units of a metric differs among archives
196Performance Co-Pilot PCP PMNEWCONTEXT(3)