---
name: "pmAddDerivedMetric"
section: "3"
platform: "linux"
package: "pcp"
version: "7.2.2-2"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/pmAddDerived"
---

# pmAddDerivedMetric(3)

register a per-context derived metric name and definition

Part of [pmAddDerived(3)](/pmAddDerived/3.md).

## NAME

**pmAddDerived**, **pmAddDerivedMetric**  - register a per-context derived metric name and definition

## C SYNOPSIS

**#include \<pcp/pmapi.h\>**

**char \*pmAddDerived(char \****name***, char \****expr***);**\
 **int pmAddDerivedMetric(char \****name***,** **char \****expr***,** **char \*\****errmsg***);**

**cc ... -lpcp**

## DESCRIPTION

Derived metrics provide a way of extending the Performance Metrics Name Space (PMNS) with new metrics defined at the PCP client-side using expressions over the existing performance metrics.

The **pmAddDerived** and **pmAddDerivedMetric** routines may be used to create per-context derived metrics, and can only be used after the current PMAPI context has been created with [**pmNewContext**(3)](/pmNewContext/3.md).

Per-context derived metrics are similar in all aspects except scope to global derived metrics. The latter are defined across all PMAPI contexts and are created with the associated [**pmRegisterDerived**(3)](/pmRegisterDerived/3.md), [**pmRegisterDerivedMetric**(3)](/pmRegisterDerivedMetric/3.md) and [**pmLoadDerivedConfig**(3)](/pmLoadDerivedConfig/3.md) routines.

The arguments to **pmAddDerived** are the *name* of the new derived metric and *expr* is an expression defining how the values of *name* should be computed.

**pmAddDerivedMetric** is the exact functional equivalent to **pmAddDerived** except that it provides a simplified model of error handling, where a formatted message is returned via the *errmsg* parameter.

Refer to the [**pmRegisterDerived**(3)](/pmRegisterDerived/3.md) man page for a complete description of the syntactic rules for *name*, the syntactic and semantic rules for *expr*, return values and the associated error reporting mechanisms, and the expression evaluation rules.

Note that for per-context derived metrics, all syntactic and semantic checks are performed at the time **pmAddDerived** or **pmAddDerivedMetric** is called. This is different to global derived metrics where the semantic checks are delayed until the metric is used in a specific PMAPI context.

Once registered a per-context derived metric persists for the life of the PMAPI context, but it is destroyed as a side-effect of [**pmDestroyContext**(3)](/pmDestroyContext/3.md).

To undefine a derived metric by name, refer to [**pmUnregisterDerived**(3)](/pmUnregisterDerived/3.md) which removes all instances of the derived metric in all contexts, irrespective of how the derived metric was defined.

## DIAGNOSTICS

On success, **pmAddDerived** returns NULL.

If a syntactic error is found at the time of calling, the value returned by **pmAddDerived** is a pointer into *expr* indicating **where** the error was found. To identify **what** the error was, the application should call [**pmDerivedErrStr**(3)](/pmDerivedErrStr/3.md) to retrieve the corresponding parser error message.

**pmAddDerivedMetric** returns 0 and *errmsg* is undefined if the parsing is successful.

If the given *expr* does not conform to the required syntax **pmAddDerivedMetric** returns -1 and a dynamically allocated error message string in *errmsg*. The error message is terminated with a newline and includes both the input *name* and *expr*, along with an indicator of the position at which the error was detected. e.g.\
 Error: pmAddDerivedMetric("my.disk.rates", ...) syntax error\
 *4rat(disk.dev.read)*\
     *^*

The position indicator line may be followed by an additional diagnostic line describing the nature of the error, when available.

In the case of an error, the caller is responsible for calling [**free**(3)](/free/3.md) to release the space allocated for *errmsg*.

## SEE ALSO

[**PCPIntro**(1)](/PCPIntro/1.md), [**PMAPI**(3)](/PMAPI/3.md), [**pmDerivedErrStr**(3)](/pmDerivedErrStr/3.md), [**pmDestroyContext**(3)](/pmDestroyContext/3.md), [**pmLoadDerivedConfig**(3)](/pmLoadDerivedConfig/3.md), [**pmNewContext**(3)](/pmNewContext/3.md), [**pmRegisterDerived**(3)](/pmRegisterDerived/3.md), [**pmRegisterDerivedMetric**(3)](/pmRegisterDerivedMetric/3.md), [**pmUnregisterDerived**(3)](/pmUnregisterDerived/3.md) and [**PMNS**(5)](/PMNS/5.md).