зарегистрировать имя и определение метрики, производное от контекста (register a per-context derived metric name and definition)
Имя (Name)
pmAddDerived, pmAddDerivedMetric - register a per-context
derived metric name and definition
Синопсис C (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).
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), pmRegisterDerivedMetric(3) and
pmRegisterLoadConfig(3) 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) 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.
There is no ``unregister'' method, so 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).
Диагностика (Diagnostic)
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) 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) to release the space allocated for errmsg.
Смотри также (See also)
PCPIntro(1), PMAPI(3), pmDerivedErrStr(3), pmDestroyContext(3),
pmLoadDerivedConfig(3), pmNewContext(3), pmRegisterDerived(3),
pmRegisterDerivedMetric(3) and PMNS(5).
