--- name: "__pmControlLog" section: "3" platform: "linux" package: "pcp" version: "7.2.2-2" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/__pmControlLog" --- # \_\_pmControlLog(3) enable, disable or enquire about logging of performance metrics ## NAME **\_\_pmControlLog** - enable, disable or enquire about logging of performance metrics ## C SYNOPSIS **#include "pmapi.h"**\ **#include "libpcp.h"** **int \_\_pmControlLog(int** *fd***,** **const pmResult \****request***,** **int** *control***,** **int** *state***,** **int** *delta***,** **pmResult \*\****status***);** **cc ... -lpcp** ## CAVEAT This documentation is intended for internal Performance Co-Pilot (PCP) developer use. These interfaces are not part of the PCP APIs that are guaranteed to remain fixed across releases, and they may not work, or may provide different semantics at some point in the future. ## DESCRIPTION **\_\_pmControlLog** may be used to enable or disable the archiving for particular performance metrics, as identified by the *request* parameter; see [**pmFetch**(3)](/pmFetch/3.md) for an explanation of the *pmResult* structure. The application must have previously issued a call to [**\_\_pmConnectLogger**(3)](/__pmConnectLogger/3.md) to establish a control-port connection to the [**pmlogger**(1)](/pmlogger/1.md) instance to whom the control request is to be directed, and *fd* (the result from [**\_\_pmConnectLogger**(3)](/__pmConnectLogger/3.md)) identifies this connection. Within *request*, only the details of the performance metrics and their associated instances will be used, i.e. the values of the metrics, if any, will be ignored. *request* would typically be constructed as the result of an earlier call to [**pmFetch**(3)](/pmFetch/3.md). For metrics with a singular value (having an instance domain of **PM\_INDOM\_NULL**) the corresponding *pmValueSet* should have the value one in the *numval* field and **PM\_IN\_NULL** as the *inst* field of the single *pmValue* supplied. If multiple explicit instances are to be logged, the *numval* field of the *pmValueSet* should contain the number of instances supplied and the *inst* fields of the *pmValue* structures should contain specific instance identifiers (which may not have the reserved value **PM\_IN\_NULL**). If the *numval* field within any of the *pmValueSet* structures in *request* has a value of zero, it indicates that all available instances of the metric should be used. Enumeration of the instance domain is deferred until the logger fetches the metric prior to writing it to the archive, rather than being performed when the **\_\_pmControlLog** request is received. This is useful for metrics with instance domains that change over time. It is an error to specify *numval* equal to zero if the corresponding metric has a singular value (no instance domain). There are several sorts of logging control available, namely mandatory or advisory, as defined by the *control* argument, and on, off or maybe as defined by the *state* argument. These different types of control may be used to ensure that some performance metrics can be guaranteed to always be in the archive, while others may be dynamically enabled or disabled as determined by the level and type of system activity. The actual action to be performed is defined by the combination of *control* and *state* as follows. If *control* is **PM\_LOG\_MANDATORY** and *state* is **PM\_LOG\_ON**, then logging is enabled. If *control* is **PM\_LOG\_MANDATORY** and *state* is **PM\_LOG\_OFF**, then logging is disabled. If *control* is **PM\_LOG\_MANDATORY** and *state* is **PM\_LOG\_MAYBE**, then subsequent advisory controls will be honored. If the logging state prior to the request was mandatory (on or off), the state is changed to advisory off. If the logging state was already advisory (either on or off), it remains unchanged. If *control* is **PM\_LOG\_ADVISORY** and the last mandatory control for the metric was **PM\_LOG\_MAYBE**, then logging is enabled or disabled as specified by the *state* argument, i.e. **PM\_LOG\_ON** or **PM\_LOG\_OFF**. When the arguments *state* and *control* specify a request to change the logging behavior, the argument *delta* defines the logging interval in milliseconds to be applied to all metrics and instances identified in *request*. The result argument *status* returns the current logging state for each of the nominated performance metrics. There is a 1:1 correspondence between the elements of *request* and *status.* For metrics in *request* that have *pmValueSet*s with *numval* equal to zero, the corresponding *pmValueSet* in *result* will contain a value for each available instance at the time of the call. Each metric value in *status* will have the current logging state encoded in it. The detailed outcome of the operation for each metric can be determined by comparing these values to that requested via *control*, *state* and *delta*. Macros defined in **libpcp.h** may be used to extract the state and logging interval from the returned metric values. **PMLC\_GET\_ON** returns true if logging is on, or false if it is off; **PMLC\_GET\_MAND** returns true if logging is mandatory, or false if it is advisory; **PMLC\_GET\_INLOG** returns true if the metric has been logged at least once, or false otherwise; **PMLC\_GET\_AVAIL** returns true if the metric was available from its source the last time it was supposed to be logged, or false if it was unavailable; and **PMLC\_GET\_DELTA** returns the current logging interval for the metric (in milliseconds). **PMLC\_MAX\_DELTA** defines the greatest *delta* that can be returned in an encoded metric value. As a special case, when *control* is **PM\_LOG\_ENQUIRE**, *state* and *delta* are ignored, and *status* returns the current logging state of the nominated performance metrics (this variant makes no changes to the logging state). If the value of the logging interval is 0, either for *delta* in a request to change state to **PM\_LOG\_ON**, or encoded in the value returned from **PM\_LOG\_ENQUIRE**, then this corresponds to the special \`\`once only'' logging of metrics that appear once in the archive, and are never logged again. **\_\_pmControlLog** returns zero on success. ## NOTE This routine is not thread-safe as there is no serialization on the use of the communication channel between the sending of the request and receiving the reply. It is assumed that the caller is single-threaded, which is true for the only current user of this routine, namely [**pmlc**(1)](/pmlc/1.md). ## DIAGNOSTICS - **PM\_ERR\_TOOSMALL** The number of metrics in *request* is less than one. - **PM\_ERR\_VALUE** One or more of the *pmValueSet*s in *request* had *numval* (the number of instances) less than one. - **EINVAL** An invalid combination of *control* and *state* was specified, or *delta* was negative. ## SEE ALSO [**pmlc**(1)](/pmlc/1.md), [**pmlogger**(1)](/pmlogger/1.md), [**PMAPI**(3)](/PMAPI/3.md), [**pmFetch**(3)](/pmFetch/3.md) and [**\_\_pmConnectLogger**(3)](/__pmConnectLogger/3.md).