Custom Metrics¶

ubTrace ships with a set of built-in dashboard metrics (Total Needs, Traceability Coverage, Orphan Count, Schema Violations). The Metrics Builder lets you define your own, on top of any property in your needs data, without writing code.

A custom metric is a saved configuration on a dashboard widget. It combines:

a set of filters that narrow down which needs are considered,
an aggregation (count, sum, ratio, distribution, …),
a chart type (line, bar, or pie), chosen on the widget itself.

Custom metrics live inside the dashboard widget that owns them. When you share the dashboard, recipients see the metric exactly as you configured it.

When to use a custom metric¶

Use a custom metric when the built-in presets do not answer your question. Typical examples:

“How many requirements per status, in the latest release?”
“What is the ratio of verified to total safety requirements over the last five releases?”
“Average story-point estimate per release.”
“Trend of open defects over time, restricted to a given component.”

For everything that the presets already cover, prefer the preset – it is faster to configure and easier to recognise across dashboards.

Opening the Metrics Builder¶

The builder is opened from a dashboard widget:

Open a dashboard and either add a new line, bar, or pie widget, or open the configuration panel of an existing one.
In the right-hand sidebar, switch to the Custom tab. (Pie widgets are preset-only and do not expose this tab.)
Build the metric in the panel that appears, then save the widget.

The chart type is determined by the widget you create – the builder itself does not have a separate visualization picker. To change chart type, change the widget type.

Versions¶

Every custom metric is evaluated against a bounded set of versions:

Line and bar widgets compare 2 to 5 versions at once.
Pie widgets always operate on a single version.

The version list is selected in the Preset tab (under Versions to Compare) and is reused by the builder. There is a hard cap of five versions per request to keep response times predictable on projects with many releases.

If a property only exists in some of the selected versions, the property picker indicates this (e.g. available in 3 of 5).

Filters¶

Filters narrow the set of needs the aggregation runs over. Each filter is a single row of property / operator / value; rows are combined with logical AND.

The following operators are supported:

Operator	Meaning	Example
`eq`	Equal to	`status eq "open"`
`neq`	Not equal to	`status neq "closed"`
`in`	In a set of values	`status in ["open", "in_progress"]`
`notIn`	Not in a set	`type notIn ["spec", "info"]`
`gt`	Greater than	`priority gt 2`
`gte`	Greater than or equal	`priority gte 1`
`lt`	Less than	`effort lt 8`
`lte`	Less than or equal	`effort lte 13`
`exists`	Property is set on the need	`assignee exists`
`notExists`	Property is not set on the need	`deprecated_at notExists`

For string properties whose values are well-defined (e.g. status, type), the value field is a dropdown populated from your data. Free-form text properties show a plain text input.

Numeric and date properties accept the comparison operators (gt, gte, lt, lte); in / notIn are reserved for set- typed properties.

Aggregations¶

The aggregation defines the question you are asking about the filtered needs. Pick the function that matches your intent; the builder greys out functions that are not compatible with the chosen property (for example, avg over a string field).

count¶

Counts the number of needs that match the filters. The simplest and most common aggregation – use it for “how many requirements …?” questions. No property needed.

sum¶

Adds up a numeric property across the matching needs. Typical use: total story points, total effort, total cost.

avg¶

Average of a numeric property over the matching needs. Typical use: average estimate, average lead time.

min / max¶

Smallest / largest value of a numeric or date property in the matching set. Useful for “earliest open defect”, “highest severity”, etc.

ratio¶

The fraction of needs that match a numerator filter set, out of all needs that match the base filters. Typical use:

“Verified vs. total safety requirements”
“Implemented vs. specified features”

In the builder, the base filters define the denominator and an additional filter row defines the numerator.

distribution¶

A grouped count over a property – for each distinct value of the group-by property, the count of matching needs. Typical use: “needs by status”, “needs by type”. Pairs naturally with bar and pie charts.

trend¶

A time-series count or value across the selected versions. Each selected version becomes a point on the chart. Typical use: “open defects over the last five releases”, “coverage trend”.

Choosing a chart type¶

The chart type is fixed by the widget you put the metric on. Use this table as a rough guide:

Aggregation	Recommended chart	Why
`count`, `sum`, `avg`, `min`, `max`	line or bar	One value per version, easy to compare across releases.
`ratio`	line or bar	Same shape; line is better when trend matters.
`distribution`	bar or pie	One slice per group; pie for share, bar for absolute counts.
`trend`	line	Time-ordered series; line emphasises the shape of change.

Worked example: covered vs. total requirements¶

Goal: show what fraction of safety requirements are covered by at least one verification, across the last five releases.

Open the dashboard, add a line widget.
In the sidebar, on the Preset tab, select the five versions you want to compare under Versions to Compare.
Switch to the Custom tab.
In the Label field, enter Coverage of safety requirements.
Add a base filter:
- property type, operator eq, value requirement
- property category, operator eq, value safety
Pick aggregation ratio.
As the numerator, add a filter row: verified eq true.
Optionally set a Unit (e.g. %) for the chart axis label.
Save the widget.

The widget then renders the ratio per release, recomputed each time the dashboard is opened (results are cached for ~15 minutes – see Caching below).

Caching and freshness¶

Both property discovery and metric execution are cached for about 15 minutes in Redis. In practice this means:

Reopening a dashboard within that window returns instantly without re-running the underlying queries.
New data ingested in the meantime becomes visible after the cache expires, or sooner if a different metric on the same versions triggers a refresh.
A user without access to certain projects or versions never sees cached results computed for someone with broader access – caches are partitioned by access scope.

If a result is needed immediately after ingestion, give it a few minutes or trigger another query that invalidates the cache key.

Permissions and visibility¶

Custom metrics respect the same artifact-level permissions as the rest of ubTrace. The chart shows only the needs the viewer is allowed to see; if their access is narrower than the metric author’s, the chart may report a partial result. This is reflected in the chart’s tooltip / metadata where applicable.