Skip to content

k4bench.metrics

k4bench.metrics

The metrics k4Bench shares across views, and what is intrinsic to each.

Scope: every metric the regression report records, plus those a shared view (dashboard tab, e-group mail, analysis figure) names, formats or ranks. It is not an exhaustive schema of the results files: raw diagnostics that no shared view displays (e.g. major_page_faults, voluntary_ctx_switches) and view-local derived statistics (e.g. Event Memory's median_rss_mb) are not listed, and fall back to their raw name like any unknown column.

One :class:MetricSpec per metric holds what does not depend on who displays it: the human name, the stored unit, how a value of it reads (a memory size, a fraction, a count) and which direction is better. The consumers above read these facts from here, so a metric they share is named and unit-labelled once.

Decisions that belong to one view or one policy stay with that view or policy: which metrics are judged or reported-only and their regression family (:mod:k4bench.regression.report_builder), which metrics a tab plots and in what order, a tab's statistic panel titles, short control labels.

Like :mod:k4bench.labels this is a leaf module: its consumers sit in layers that must not import each other, so it imports nothing from k4bench. An unrecognized column falls back to its raw name and no unit rather than failing.

MetricSpec dataclass 

MetricSpec(label: str, unit: str = '', kind: MetricKind = 'quantity', lower_is_better: bool | None = True)

Intrinsic description of one measured column.

metric_label 

metric_label(metric: str) -> str

Human-readable name of metric, or the raw column name if unknown.

Source code in k4bench/metrics.py 
77
78
79
80
def metric_label(metric: str) -> str:
    """Human-readable name of *metric*, or the raw column name if unknown."""
    spec = METRICS.get(metric)
    return spec.label if spec else metric

metric_unit 

metric_unit(metric: str) -> str

Stored unit of metric; empty if dimensionless or unknown.

Source code in k4bench/metrics.py 
83
84
85
86
def metric_unit(metric: str) -> str:
    """Stored unit of *metric*; empty if dimensionless or unknown."""
    spec = METRICS.get(metric)
    return spec.unit if spec else ""

metric_title 

metric_title(metric: str, unit: str | None = None) -> str

Axis or panel title such as Wall time (s). unit overrides the stored unit, for a view that rescales (e.g. memory shown in GB).

Source code in k4bench/metrics.py 
89
90
91
92
93
94
def metric_title(metric: str, unit: str | None = None) -> str:
    """Axis or panel title such as ``Wall time (s)``. *unit* overrides the
    stored unit, for a view that rescales (e.g. memory shown in GB)."""
    unit = metric_unit(metric) if unit is None else unit
    label = metric_label(metric)
    return f"{label} ({unit})" if unit else label

is_megabytes 

is_megabytes(metric: str) -> bool

Whether metric is a size stored in MB, which a view may show in GB.

Source code in k4bench/metrics.py 
 97
 98
 99
100
def is_megabytes(metric: str) -> bool:
    """Whether *metric* is a size stored in MB, which a view may show in GB."""
    spec = METRICS.get(metric)
    return spec is not None and spec.kind == "megabytes"

pretty_metric 

pretty_metric(metric: str, sub_detector: str | None = None) -> str

Human-readable metric name, suffixed with the sub-detector for a region-level row, e.g. ("mean_rss_mb", "EMEC_turbine") -> Mean event RSS · EMEC_turbine.

The sub-detector keeps its raw name: it is a DD4hep DetElement identifier, which is what the dashboard labels the series with and what someone searching the geometry types.

Source code in k4bench/metrics.py 
103
104
105
106
107
108
109
110
111
112
def pretty_metric(metric: str, sub_detector: str | None = None) -> str:
    """Human-readable metric name, suffixed with the sub-detector for a
    region-level row, e.g. ``("mean_rss_mb", "EMEC_turbine")`` ->
    ``Mean event RSS · EMEC_turbine``.

    The sub-detector keeps its raw name: it is a DD4hep DetElement identifier,
    which is what the dashboard labels the series with and what someone
    searching the geometry types."""
    name = metric_label(metric)
    return f"{name} · {sub_detector}" if sub_detector else name