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 an archive log of performance metrics as created by pmlog‐
20 ger(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 the base name common to all of the physical files
26 of an archive log (type is PM_CONTEXT_ARCHIVE).
27 For a type of PM_CONTEXT_HOST, in addition to identifying a host the
29 name may also be used to encode additional optional information in the
30 form of a pmcd(1) port number, a pmproxy(1) hostname and a proxy port
31 number. For example the name "app23:14321,4321@firewall.exam‐
32 ple.com:11111" specifies a connection on port 14321 (or port 4321 if
33 14321 is unavailable) to pmcd(1) on the host app23 via port 11111 to
34 pmproxy(1) on the host firewall.example.com.
35 For a type of PM_CONTEXT_ARCHIVE, name may also be the name of any of
37 the physical files of an archive, e.g. myarchive.meta (the metadata
38 file) or myarchive.index (the temporal index) or myarchive.0 (the first
39 data volume of the archive) or myarchive.0.bz2 or myarchive.0.bz (the
40 first data volume compressed with bzip2(1)) or myarchive.0.gz or
41 myarchive.0.Z or myarchive.0.z (the first data volume compressed with
42 gzip(1)), myarchive.1 or myarchive.3.bz2 or myarchive.42.gz etc.
43 In the case where type is PM_CONTEXT_LOCAL, name is ignored, and the
45 context uses a standalone connection to the PMDA methods used by
46 pmcd(1). When this type of context is used, the range of accessible
47 performance metrics is constrained to those from the operating system,
48 and optionally the ``proc'', ``sample'' and ``ib'' PMDAs.
49 In the case where type is PM_CONTEXT_HOST, additional flags can be
51 added to the type to indicate if the connection to pmcd(1) should be
52 encrypted (PM_CTXFLAG_SECURE), deferred (PM_CTXFLAG_SHALLOW) and if the
53 file descriptor used to communicate with pmcd(1), should not be shared
54 across contexts (PM_CTXFLAG_EXCLUSIVE). The PM_CTXFLAG_SHALLOW flag is
55 now deprecated and ignored.
56 The initial instance profile is set up to select all instances in all
58 instance domains. In the case of an archive, the initial collection
59 time is also set to zero, so that an initial pmFetch(3) will result in
60 the earliest set of metrics being returned from the archive.
61 Once established, the association between a context and a source of
63 metrics is fixed for the life of the context, however routines are pro‐
64 vided to independently manipulate both the instance profile (see pmAd‐
65 dProfile(3) and pmDelProfile(3)) and the collection time for archives
66 (see pmSetMode(3)).
67 pmNewContext returns a handle that may be used with subsequent calls to
69 pmUseContext(3).
70 The new context remains the current PMAPI context for all subsequent
72 calls across the PMAPI, until another call to pmNewContext(3) is made,
73 or the context is explicitly changed with a call to pmDupContext(3) or
74 pmUseContext(3), or destroyed using pmDestroyContext(3).
75 When attempting to connect to a remote pmcd(1) on a machine that is
77 booting, pmNewContext could potentially block for a long time until the
78 remote machine finishes its initialization. pmNewContext will abort
79 and return an error if the connection has not been established after
80 some specified interval has elapsed. The default interval is 5 sec‐
81 onds. This may be modified by setting PMCD_CONNECT_TIMEOUT in the
82 environment to a real number of seconds for the desired timeout. This
83 is most useful in cases where the remote host is at the end of a slow
84 network, requiring longer latencies to establish the connection cor‐
85 rectly.
86
88 PMCD_CONNECT_TIMEOUT
89 Timeout period (in seconds) for pmcd(1) connection attempts.
90 PMCD_PORT
92 TCP/IP port(s) for connecting to pmcd(1), historically was 4321
93 and more recently the officially registered port 44321; in the
94 current release, pmcd listens on both these ports as a transi‐
95 tional arrangement. If used, should be set to a comma-separated
96 list of numerical port numbers.
97 PMDA_PATH
99 When searching for PMDAs to be loaded when type is PM_CON‐
100 TEXT_LOCAL, the PMDA_PATH environment variable may be used to
101 define a search path of directories to be used to locate the
102 PMDA executables. The default search path is
103 $PCP_SHARE_DIR/lib:/usr/pcp/lib.
104
106 When using a type of PM_CONTEXT_LOCAL, the operating system PMDA may
107 export data structures directly from the kernel, which means that the
108 pmNewContext caller should be an executable program compiled for the
109 same object code format as the booted kernel.
110 In addition, applications using a PM_CONTEXT_LOCAL context must be sin‐
112 gle-threaded because the various DSO PMDAs may not be thread-safe.
113 This restriction is enforced at the PMAPI(3), where routines may return
114 the error code PM_ERR_THREAD if the library detects calls from more
115 than one thread.
116 Applications that use gethostbyname(3) should exercise caution because
118 the static fields in struct hostent may not be preserved across some
119 PMAPI(3) calls. In particular, pmNewContext(3) and pmReconnectCon‐
120 text(3) both may call gethostbyname(3) internally.
121
123 pmcd(1), pmproxy(1), pmAddProfile(3), PMAPI(3), pmDelProfile(3), pmDe‐
124 stroyContext(3), pmDupContext(3), pmGetConfig(3), pmReconnectCon‐
125 text(3), pmSetMode(3), pmUseContext(3), pmWhichContext(3), pcp.conf(5)
126 and pcp.env(5).
127
129 PM_ERR_PERMISSION
130 No permission to perform requested operation
132 PM_ERR_CONNLIMIT
134 PMCD connection limit for this host exceeded
136 PM_ERR_NOCONTEXT
138 Requested context type was not PM_CONTEXT_LOCAL, PM_CONTEXT_HOST
140 or PM_CONTEXT_ARCHIVE.
141Performance Co-Pilot PCP PMNEWCONTEXT(3)