Silvi
Create(opens in a new tab)

Metrics

PreviousNext

Named measures with one definition in metrics.ts, used by name in every report, so two reports cannot disagree.

When a measure appears in several reports, such as a conversion rate, give it a name and one definition. Every report then uses it by name, and they cannot disagree.

metrics.ts

The metrics are one file, app/src/metrics/metrics.ts: one entry each, under its name in camelCase (conversionRate). The kit starts with none.

app/src/metrics/metrics.ts
export const METRICS = {
  conversionRate: {
    name: "conversionRate",
    label: "Conversion rate",
    type: "ratio",
    numerator: "orders",
    denominator: "sessions",
    format: "percent",
    scale: 100,
    decimals: 1,
    better: "higher",
    definition: "Sessions that ended in an order, as a share of all sessions.",
  },
} as const satisfies Record<string, Metric>
Key Required Means
name yes The name reports use, camelCase, the same as the entry’s key
label yes The name people read
type yes ratio, sum, count, mean or change
numerator, denominator for ratio, mean, change The columns added up above and below the line (a change is numerator minus denominator, over denominator)
column for sum, count The column added up
format yes number, percent, percent0, decimal or millions
scale no Multiplies a ratio, such as 100 for percent
decimals no Rounds the value
better yes higher or lower: which way is good
definition yes One line saying what it is

The SQL still returns the columns; the metric says how they combine. A wrong key or value fails the type check.

Using a metric

Ask:

“Make a conversion rate metric, and use it in the Orders report.”

A component names it with metric="conversionRate", and so can a table column or a tile. The label, the format and the definition in the “(i)” then come from metrics.ts.

report.tsx
<k.Line key="conversion" series="weekly" x="week" xFormat="week" metric="conversionRate" title="Conversion" />

In a report’s dialog, <Definition> quotes the definition instead of restating it:

report.tsx
import { Definition, Info } from "~/components/report-kit/info"

// in defineReport({ … })
page: {
  info: () => (
    <Info>
      <Definition name="conversionRate" />
    </Info>
  ),
},

Every metric is in the wiki

The wiki’s Metrics page (/wiki/reference/metrics) writes out every metric from metrics.ts, with its formula and how it is shown. It follows the file by itself: there is nothing to keep in step.