1PMNEWCONTEXT(3)            Library Functions Manual            PMNEWCONTEXT(3)
2
3
4

NAME

6       pmNewContext - establish a new PMAPI context
7

C SYNOPSIS

9       #include <pcp/pmapi.h>
10
11       int pmNewContext(int type, const char *name);
12
13       cc ... -lpcp
14

DESCRIPTION

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
23       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
30       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
38       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
47       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
50       •  The archives must all have been generated on the same host.
51
52       •  The archives must not overlap in time.
53
54       •  The archives must all have been created using the same time zone.
55
56       •  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
60       •  The type of each metric must be the same in all of the archives.
61
62       •  The  semantics  of  each  metric  must be the same in all of the ar‐
63          chives.
64
65       •  The units of each metric must be the same in all of the archives.
66
67       •  The instance domain of each metric must be the same in  all  of  the
68          archives.
69
70       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
76       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
83       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
89       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
95       pmNewContext returns a handle that may be used with subsequent calls to
96       pmUseContext(3).
97
98       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
103       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

CAVEATS

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
119       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
125       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

DIAGNOSTICS

131       PM_ERR_PERMISSION
132
133              No permission to perform requested operation
134
135       PM_ERR_CONNLIMIT
136
137              PMCD connection limit for this host exceeded
138
139       PM_ERR_NOCONTEXT
140
141              Requested context type was not PM_CONTEXT_LOCAL, PM_CONTEXT_HOST
142              or PM_CONTEXT_ARCHIVE.
143
144       PM_ERR_LOGOVERLAP
145
146              Archives overlap in time
147
148       PM_ERR_LOGHOST
149
150              Archives differ by host
151
152       PM_ERR_LOGTIMEZONE
153
154              Archives differ by time zone.
155
156       PM_ERR_LOGCHANGETYPE
157
158              The type of a metric differs among archives
159
160       PM_ERR_LOGCHANGESEM
161
162              The semantics of a metric differs among archives
163
164       PM_ERR_LOGCHANGEINDOM
165
166              The instance domain of a metric differs among archives
167
168       PM_ERR_LOGCHANGEUNITS
169
170              The units of a metric differs among archives
171

ENVIRONMENT

173       PMCD_CONNECT_TIMEOUT
174              Timeout period (in seconds) for pmcd(1) connection attempts.
175
176       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
183       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

SEE ALSO

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).
195
196
197
198Performance Co-Pilot                  PCP                      PMNEWCONTEXT(3)
Impressum