How do you read a value from Go's runtime/metrics package, such as the live goroutine count?

## What runtime/metrics is `runtime/metrics` is the Go runtime's own self-description: a flat namespace of numbers the runtime already maintains — allocation totals, GC cycle counts, GC pause distributions, goroutine counts, memory class breakdowns — exposed through one stable API instead of a hand-written struct per release. It reports the *runtime*, never your application: there is no request counter or queue depth in there, because the runtime has no idea what a request is. ## The name grammar Every metric name starts with `/` and ends with `:unit`. `/gc/heap/allocs:bytes` is a byte count of everything ever allocated; `/gc/cycles/total:gc-cycles` counts GC cycles; `/gc/pauses:seconds` is a distribution measured in seconds; `/sched/goroutines:goroutines` counts goroutines. The path segment tells you the subsystem, the suffix after the colon tells you the unit, and the two together are the whole identifier — there is no separate unit field to look up. Names are case-sensitive strings, so a typo is not a compile error. ## The three types involved ``` type Sample struct { Name string Value Value } ``` `Sample` is what you own. You fill `Name`; `Read` fills `Value`. `Value` is an opaque wrapper with a `Kind()` and three accessors: - `KindUint64` -> `Value.Uint64()` - `KindFloat64` -> `Value.Float64()` - `KindFloat64Histogram` -> `Value.Float64Histogram()` - `KindBad` -> nothing to read; this Go version has no such metric Calling an accessor that does not match the kind panics, which is why real code switches on `Kind()` rather than assuming. `Description`, returned in a slice by `metrics.All()`, is the catalogue entry: `Name`, a human-readable `Description`, the `Kind` you should expect, and `Cumulative`, which says whether the number only ever grows since process start. `Cumulative` is the field that decides how you export the value — a cumulative number is a counter you diff, a non-cumulative one is a gauge you report as-is. ## The call itself `metrics.Read(samples)` takes the slice and mutates it in place. It returns nothing. Two consequences follow. First, the package explicitly encourages you to build the slice once — typically at start-up in a small reporting daemon — and reuse it on every tick, rather than allocating a fresh slice each time. Second, because `Read` writes into the slice you handed it, anything you keep from a previous read must be copied out before the next call; that matters most for histograms, whose `Counts` slice can be overwritten in place. ## Discovering versus hardcoding The supported set of metrics is a property of the Go toolchain that built the binary, and it grows across releases. That is exactly why the API pairs `All()` with `KindBad`: a program can enumerate what this build supports at start-up, log the names it wanted but did not get, and carry on. Hardcoding a list and assuming every entry resolves is the common beginner mistake — it does not panic, it silently reports nothing, because a `KindBad` sample is easy to skip past without noticing. ## A typical first program Declare the names you care about, read once, and print. Then wrap that in a ticker inside a goroutine and you have the shape of every runtime-metrics reporter: one slice, one `Read` per tick, one loop over the samples that fans the numbers out to wherever they are being collected. The batching is not cosmetic — one `Read` with six names does strictly less work than six `Read` calls with one name each, because the runtime computes the shared underlying aggregates once per call. ## What it is not It is not a push system, not a time series database and not a history: `Read` gives you the value *now*. Rates, deltas and percentiles are yours to compute from successive reads. And it is not a replacement for instrumenting your own code — the cheapest way to count something your program does is a counter your program increments.