pmiSetImportProgram - Man Page

#include <pcp/pmapi.h>
#include <pcp/import.h>

int pmiSetImportProgram(const char *tool, const char *version, const char *args, const char *archive);

cc ... -lpcp_import -lpcp

As part of the Performance Co-Pilot Log Import API (see LOGIMPORT(3)), pmiSetImportProgram registers the running import tool with pmdapmimport(1) so that its status is visible through the pmimport.* metric family.

The function writes a sidecar status file to PCP_IMPORTRUN_DIR (typically /run/pmimport) named after tool. The file is a simple key=value text format containing a subset of the following fields:

pid=

The process ID of the import tool, written only when the PMI_PROCESS flag was passed to pmiStart(3). Long-running daemons should use this flag so that pmdapmimport(1) can detect and suppress stale entries left by an unclean exit. One-shot tools (e.g. those invoked periodically from a cron job) should omit the flag; their sidecar files persist between invocations and are always considered live.

version=

The version string supplied by the caller (skipped if NULL or empty).

args=

The args string supplied by the caller (skipped if NULL or empty). Typically a summary of the subsystems or data sources being imported, for display by pcp(1).

archive=

The archive base path supplied by the caller (skipped if NULL or empty).

The sidecar file is removed automatically when pmiEnd(3) is called, so no explicit cleanup is required on a clean exit.

pmiSetImportProgram should be called once after pmiStart(3) and before the first call to pmiWrite(3). Calling it again with updated arguments (e.g. after an archive rotation) is permitted and overwrites the existing sidecar file.

Returns zero on success. PM_ERR_NOCONTEXT is returned if there is no current import context. PM_ERR_CONV is returned if tool is NULL or empty. Any error opening or writing the sidecar file causes the corresponding negated errno(3) value to be returned.

$PCP_IMPORTRUN_DIR/<tool>

Sidecar status file for the named import tool.

LOGIMPORT(3), pcp(1), pmdapmimport(1), pmiEnd(3), pmiErrStr(3), pmiStart(3), pmiWrite(3) and pmiWriteNow(3).