Metrics

A metric is a number you keep a running tally of — how many requests you've served, how many people are online right now, how much memory is in use. Where a trace is one timed event and a log is one line of text, a metric is a total that moves up and down over the life of your app.

There are a few flavours, and picking the right one is most of the job:

counts that only go up — "requests served", "orders placed". You add to them.
levels that rise and fall — "memory in use", "players online". You set them.
counts of distinct things — how many different users showed up. Seeing the same user twice still counts as one.

The useful property: because a metric is stored as data that merges cleanly, re-sending it after a dropped connection can never accidentally count something twice.

Record a metric

// A count that only goes up — re-sending after a dropped connection can't double-count.
val requests = MetricKey("server.requests", MetricKind.SUM, mapOf("handler" to "/api/v1"))
telemetry.metrics.incrementSum(requests, by = 1L)

// A count of *distinct* things — the same user seen twice is still one.
val users = MetricKey("unique.users", MetricKind.CARDINALITY)
telemetry.metrics.addCardinality(users, "user-abc")
telemetry.metrics.addCardinality(users, "user-abc") // ignored — already counted

Where they go

Recording is only the first step. Your metrics are held safely on the device, survive being offline, and reach your dashboard with no duplicates. That whole journey is on Device to dashboard.

Starting over with a clean slate

You can throw away everything recorded so far while the app is still running — see Device to dashboard.

Metrics carry the one caveat worth reading before you rely on it. Counts, readings, and latency summaries can only be forgotten on this device: sync with a device that still remembers them and the old numbers come back. A number that any device can raise, and that everyone must agree on without coordinating, can never be lowered again. If this device doesn't share its metrics — the ordinary case — the distinction never comes up.

16 August 2026