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
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
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
58          defined 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
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

ENVIRONMENT

115       PMCD_CONNECT_TIMEOUT
116              Timeout period (in seconds) for pmcd(1) connection attempts.
117
118       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
125       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

CAVEATS

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
138       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
144       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

SEE ALSO

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

DIAGNOSTICS

156       PM_ERR_PERMISSION
157
158              No permission to perform requested operation
159
160       PM_ERR_CONNLIMIT
161
162              PMCD connection limit for this host exceeded
163
164       PM_ERR_NOCONTEXT
165
166              Requested context type was not PM_CONTEXT_LOCAL, PM_CONTEXT_HOST
167              or PM_CONTEXT_ARCHIVE.
168
169       PM_ERR_LOGOVERLAP
170
171              Archives overlap in time
172
173       PM_ERR_LOGHOST
174
175              Archives differ by host
176
177       PM_ERR_LOGTIMEZONE
178
179              Archives differ by time zone.
180
181       PM_ERR_LOGCHANGETYPE
182
183              The type of a metric differs among archives
184
185       PM_ERR_LOGCHANGESEM
186
187              The semantics of a metric differs among archives
188
189       PM_ERR_LOGCHANGEINDOM
190
191              The instance domain of a metric differs among archives
192
193       PM_ERR_LOGCHANGEUNITS
194
195              The units of a metric differs among archives
196
197
198
199Performance Co-Pilot                  PCP                      PMNEWCONTEXT(3)
Impressum