Product SiteDocumentation Site

3.8.8. PMAPI Record-Mode Services

The functions described in this section provide Performance Metrics Application Programming Interface (PMAPI) record-mode services. These services allow a monitor tool to establish connections to pmlogger co-processes, which they create and control for the purposes of recording live performance data from (possibly) multiple hosts. Since pmlogger records for one host only, these services can administer a group of loggers, and set up archive folios to track the logs. Tools like pmafm can subsequently use those folios to replay recorded data with the initiating tool. pmchart uses these concepts when providing its Record mode functionality.

3.8.8.1.  pmRecordAddHost Function

int pmRecordAddHost(const char *host, int isdefault, pmRecordHost **rhp)
Python:
(int status, pmRecordHost* rhp) = pmRecordAddHost("host string", 1, "configure string")
The pmRecordAddHost function adds hosts once pmRecordSetup has established a new recording session. The pmRecordAddHost function along with the pmRecordSetup and pmRecordControl functions are used to create a PCP archive.
pmRecordAddHost is called for each host that is to be included in the recording session. A new pmRecordHost structure is returned via rhp. It is assumed that PMCD is running on the host as this is how pmlogger retrieves the required performance metrics.
If this host is the default host for the recording session, isdefault is nonzero. This ensures that the corresponding archive appears first in the PCP archive folio. Hence the tools used to replay the archive folio make the correct determination of the archive associated with the default host. At most one host per recording session may be nominated as the default host.
The calling application writes the desired pmlogger configuration onto the stdio stream returned via the f_config field in the pmRecordHost structure.
pmRecordAddHost returns 0 on success and a value less than 0 suitable for decoding with pmErrStr on failure. The value EINVAL has the same interpretation as errno being set to EINVAL.