Cube' Derived Metrics  (CubeLib 4.4.4, revision 18494)
Introduction in CubePL and Performance Analysis using Cube's Derived Metrics
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.


Cube Writer Library    Copyright © 1998–2017 Forschungszentrum Jülich GmbH, Jülich Supercomputing Centre
Copyright © 2009–2015 German Research School for Simulation Sciences GmbH, Laboratory for Parallel Programming