Introduction into Cube Derived Metrics

# Introduction

With Cube 4.1.0 derived metrics are introduced and provide a powerful tool for performance data processing.

Unlike normal metrics of the cube, derived metrics do not store any data inside of the cube report, but derive their value according to an expression, formulated using CubePL (Cube Processing Language) syntax ( 'Syntax of CubePL' ).

Cube supports different kinds ( 'The three kinds of derived metrics' ) of derived metrics. Derived metric can be a child metric of any metric of cube or other derived metrics.

Derived metrics are naturally metrics with the value `DOUBLE`

# Creation of a derived metric in Cube

Derived metrics play the very same role as a normal metric in cube, therefore one proceeds with creation of derived metrics as usual. The only difference is the specification of the CubePL expression.

## Using the C writer

To create a derived metric in a C program, one calls `cube_metric_set_expression(...)` subsequently to `cube_def_met(...)`. Here is a code example:

cube_metric * met = cube_def_met(cube,
"Derived metric",
"derivedmetric1",
"DOUBLE",
"sec",
"",
"https://doc.web.org/metrics.html#derived",
"Average execution time",
NULL,
CUBE_METRIC_PREDERIVED_EXCLUSIVE
);
cube_metric_set_expression(met, "metric::time(i)/metric::visits(e)");

Derived metric specification allows to define an CubePL expression, which will be execuded only once before the actual metric expression is executed. To specify an initalization expression, one uses the call `cube_metric_set_init_expression(...)`.

Prederived metrics allow to redefine operators "+" and "-" in the aggregation formula by any user defined expression using same CubePL syntax.

Any such expression should be a formula of "arg1" and "arg2" parameters. E.g. `max(arg1, arg2)`.

To specify an expression for an aggregation operator one uses the call `cube_metric_set_aggr_expression(metric,operator,expression)`, where operator can be `CUBE_METRIC_AGGR_PLUS` or `CUBE_METRIC_AGGR_MINUS`

## Using the C++ library

To create a derived metric in C++ programs, one specifies the expression as the last parameter of the metric definition. This parameter can be omitted, in this case the derived metric returns always 0.

Here is a code example:

Metric * met = cube.def_met(
"Derived metric",
"derivedmetric1",
"DOUBLE",
"sec",
"",
"https://doc.web.org/metrics.html#derived",
"Average execution time",
NULL,
CUBE_METRIC_PREDERIVED_EXCLUSIVE,
"\${unit}*metric::time(i)/metric::visits(e)",
"{ \${unit}=1000; }",
"min(arg1,arg2)",
""
);

`CUBE_METRIC_PREDERIVED_EXCLUSIVE` defines the kind of the derived metric (see 'The three kinds of derived metrics' below).

Derived metric specification allows to define an CubePL expression, which will be execuded only once before the actual metric expression is executed. This expression is the last argument in the parameter `{ \${unit}=1000; }`.

Operator "+" is redefined like `min(arg1,arg2)`.

Note, that the CubePL expression should be valid at the time of execution. It means, if there is a reference to metric, this metric should be defined before.

# The three kinds of derived metrics

Cube provides an API to calculate different inclusive and exclusive values aggregated over different dimensions.

In the context of derived metrics it is sometimes useful, when evaluation of the expression is done after the aggregation of the metrics in the expression, sometimes it is needed to aggregate values of the derived metrics.

Therefor Cube provides three kinds of derived metrics:

1. Prederived exclusive metric - metric, which value of which expression is observed as "being stored" inside of cube report and it behaves as a usual exclusive (along call tree) metric.

One specifies this type of metric using constant

`CUBE_METRIC_PREDERIVED_EXCLUSIVE`

For this metric one can redefine only operator "+". Operator "-" will be ignored.

2. Prederived inclusive metric - metric, which value of which expression is observed as "being stored" inside of cube report and it behaves as a usual inclusive (along call tree) metric.

One specifies this type of metric using constant

`CUBE_METRIC_PREDERIVED_INCLUSIVE`

For this metric one can redefine both operators, "+" and "-".

3. Postderived metric - metric, which expression evaluated only after metrics, which were used inside of the expression, get aggregated according to the aggregation context (along system tree or along call tree).

If expression doesn't contain references to another metrics, no aggregation is done. In this case the expression gets calculated and its value returned.

One specifies this type of metric using constant

`CUBE_METRIC_POSTDERIVE`

This metric doesn't allow to redefine anyoperators, because calculation of this metric is performed AFTER aggregation within another metric.