@zio.dev/zio-blocks 0.0.33 → 0.0.55

package/reference/telemetry/metrics/index.md

@@ -0,0 +1,150 @@
+---
+id: index
+title: "Metrics"
+description: "Record how your application behaves over time — request rates, latencies, queue depths — as labeled counters, histograms, and gauges."
+keywords:
+  - "Application Metrics"
+  - "Dimensional Metrics"
+  - "Metrics Overview"
+  - "MeterProvider"
+sidebar_label: "Metrics"
+---
+
+Metrics are the running numbers that tell you how your application is behaving over time — request rate, error count, latency, queue depth — the data you put on dashboards and alerts. They're **dimensional**: each measurement carries labels (like `method=GET`, `status=200`), and a metric splits into a separate series per label combination, so you can break "requests" down by endpoint or status. You record through four [instruments](./instruments.md), each for a different shape of number — a `Counter` for a total that only climbs, an `UpDownCounter` for one that rises and falls, a `Histogram` for a distribution of values, and a `Gauge` for the latest reading.
+
+You record through the `metric` object: `metric.counter("http.requests").add(1)` works immediately, with no setup — it creates the named instrument and records the measurement. Pick the factory that matches what you're measuring — `metric.counter`, `metric.upDownCounter`, `metric.histogram`, or `metric.gauge` — and pass dimension labels as you record.
+
+Measurements accumulate in memory, and reading them out is a pull: `metric.reader.collectAllMetrics()` returns [`MetricData`](./metric-data.md) snapshots — handy for tests and assertions, and the same call an exporter makes. Metrics have no push pipeline the way tracing and logging do: there is no processor hook on `MeterProvider`, so shipping them means scheduling that pull yourself and handing the snapshots to your backend. `metric.install(provider)` swaps in a provider configured with your own `Resource`.
+
+Day to day you only need `metric.*`, but it helps to know what sits underneath, because each piece is where you go when you want more control. A [`MeterProvider`](./meter-provider.md) is what you build at startup: it holds your service identity as a `Resource` and vends everything else. (Unlike spans and log records, collected metric data does not carry that `Resource`, so an exporter has to attach the service identity itself.) A [`Meter`](./meter.md) is a named handle you take with `metric.get("com.example.orders")` when measurements should be attributed to one component, or when you want to declare an instrument's unit and description, or pre-declare label names for a hot path.
+
+The other two are the recording and reading ends. The four [instruments](./instruments.md) are what you actually record through, however you obtained them. And the `MetricReader` behind `metric.reader` is what turns everything recorded so far into `MetricData` snapshots — the thing you call in tests, and the thing an exporter pulls from in production.
+
+## Usage
+
+Metrics' core job is to **record and export application metrics**. Create instruments from `metric`, record measurements with dimension labels as work happens, then read aggregated snapshots (or `metric.install(...)` a provider to export them):
+
+```scala
+import zio.blocks.telemetry._
+
+val requests = metric.counter("http.requests")
+requests.add(1, "method" -> "GET", "status" -> "200")
+
+val latency = metric.histogram("http.latency.ms")
+latency.record(12.5, "route" -> "/orders")
+
+val snapshots = metric.reader.collectAllMetrics()
+snapshots.foreach {
+  case MetricData.SumData(points)       => points.foreach(p => println(p.value))
+  case MetricData.HistogramData(points) => points.foreach(p => println(p.count))
+  case MetricData.GaugeData(points)     => points.foreach(p => println(p.value))
+}
+```
+
+## Record Measurements with the Four Instruments
+
+Each factory creates a new instrument on the default meter. Nothing is cached by name, so build each one once and hold it — calling `metric.counter("http.requests")` twice gives you two independent counters and two entries in the collected snapshot.
+
+```scala
+object metric {
+  def counter(name: String): Counter
+  def upDownCounter(name: String): UpDownCounter
+  def histogram(name: String): Histogram
+  def gauge(name: String): Gauge
+}
+```
+
+The four instruments differ by what they measure: a `Counter` sums a monotonic total, an `UpDownCounter` tracks a value that rises and falls, a `Histogram` builds a distribution of recorded values, and a `Gauge` holds the latest instantaneous reading. Every recording call accepts dimension labels as `(String, Any)*` pairs, which split the metric into separately-aggregated series.
+
+```scala
+import zio.blocks.telemetry._
+
+metric.counter("http.requests").add(1, "method" -> "GET", "status" -> "200")
+metric.upDownCounter("queue.depth").add(-1, "queue" -> "orders")
+metric.histogram("http.latency.ms").record(12.5, "route" -> "/orders")
+metric.gauge("cache.entries").record(4096.0, "cache" -> "sessions")
+```
+
+Note the two verbs. `add(delta: Long)` takes a *change* and the instrument keeps the running total — a `Counter` ignores a negative delta, while an `UpDownCounter` accepts one, so `add(1)`/`add(-1)` tracks queue depth. `record(value: Double)` takes the *measurement itself*: a `Histogram` files each value into buckets, and a `Gauge` keeps only the newest.
+
+## Scope a Meter and Pre-Declare Labels
+
+`metric.get(name)` returns a `Meter` bound to a named instrumentation scope.
+
+```scala
+object metric {
+  def get(name: String): Meter
+}
+```
+
+Its builders attach a description and unit, and its labeled variants pre-declare label names so a hot path records positionally instead of naming a key at every call.
+
+```scala
+import zio.blocks.telemetry._
+
+val meter: Meter = metric.get("com.example.orders")
+
+val payments: Counter =
+  meter.counterBuilder("payments.total").setUnit("{payment}").setDescription("Payments processed").build()
+payments.add(1, "currency" -> "USD")
+
+val byRoute: LabeledCounter = meter.labeledCounter("http.requests", "method", "status")
+byRoute.add(1, "GET", "200")
+```
+
+`setUnit` labels what the numbers mean, so a dashboard can axis-label `http.latency` as milliseconds rather than guessing. Use the UCUM codes OpenTelemetry expects — `"ms"`, `"s"`, `"By"` for bytes — and for a plain count of things, the thing in braces: `"{payment}"`, `"{request}"`. It's metadata attached to the instrument, not part of any measurement, and it stays on the instrument: the snapshots `metric.reader` returns carry only data points, so a unit reaches a backend through an exporter, not through `MetricData`.
+
+## Read Aggregated Snapshots
+
+Read every registered instrument as a `MetricData` snapshot — a fresh value each call, though a histogram point hands you its `boundaries` and `bucketCounts` arrays directly, so treat them as read-only.
+
+```scala
+object metric {
+  def reader: MetricReader
+}
+```
+
+`metric.reader.collectAllMetrics()` aggregates them — `SumData` for counters, `HistogramData` for histograms, `GaugeData` for gauges — for inspection in tests or manual export.
+
+```scala
+import zio.blocks.telemetry._
+
+val snapshots: Seq[MetricData] = metric.reader.collectAllMetrics()
+snapshots.foreach {
+  case MetricData.SumData(points)       => points.foreach(p => println(p.value))
+  case MetricData.HistogramData(points) => points.foreach(p => println(p.count))
+  case MetricData.GaugeData(points)     => points.foreach(p => println(p.value))
+}
+```
+
+## Install a Provider and Reset
+
+`metric.install(provider)` swaps in a `MeterProvider` configured with your own [`Resource`](../common/resource.md). The builder takes nothing else — there is no exporter or reader hook — so instruments created after the swap register on the new provider's meters and are read back through `metric.reader`.
+
+```scala
+object metric {
+  def install(provider: MeterProvider): Unit
+  def removeAll(): Unit
+}
+```
+
+Install before creating any instruments. Both calls replace the provider along with its registry, so an instrument built beforehand stays registered with the old one and won't appear in `metric.reader` snapshots. `metric.removeAll()` restores a fresh default provider.
+
+```scala
+import zio.blocks.telemetry._
+
+metric.install(
+  MeterProvider.builder
+    .setResource(Resource.create(Attributes.of(Attributes.ServiceName, "order-service")))
+    .build()
+)
+
+// later, at shutdown
+metric.removeAll()
+```
+
+## See Also
+
+- [Telemetry Guide](../../../guides/telemetry-guide.md) — metrics data flow and labeled instrument patterns
+- [Telemetry Reference](../index.md) — module overview and all three pillars
+- [Common Types](../common/index.md) — `Attributes` used as metric dimension labels

package/reference/telemetry/metrics/instruments.md

@@ -0,0 +1,183 @@
+---
+id: instruments
+title: "Metric Instruments"
+description: "The four synchronous metric instruments: monotonic Counter, bidirectional UpDownCounter, bucketed Histogram, and last-value Gauge."
+keywords:
+  - "Application Metrics"
+  - "Synchronous Instruments"
+  - "Measurement Recording"
+  - "Metric Instruments"
+sidebar_label: "Instruments"
+---
+
+The four synchronous instruments are what application code actually calls to record measurements. They differ by what they measure: a `Counter` sums a monotonic total, an `UpDownCounter` tracks a value that rises and falls, a `Histogram` builds a distribution of observations, and a `Gauge` holds the latest reading. Reach for them through [`metric`](./index.md) (`metric.counter("…")`) or a [`Meter`](./meter.md) builder — either path registers the instrument so `MetricReader.collectAllMetrics()` collects it into a [`MetricData`](./metric-data.md) snapshot.
+
+All four share the same recording shape: `add` (counters) or `record` (histogram, gauge) takes a value plus optional dimension labels, either as an [`Attributes`](../common/attributes.md) set or as `(String, Any)*` tuples — a label value may be a `String`, `Long`, `Int` (widened to `Long`), `Double`, or `Boolean`, and anything else is recorded as its `toString`; `bind` pre-attaches a label set for hot-path reuse; and `collect` snapshots the accumulated data into a [`MetricData`](./metric-data.md) variant.
+
+## Counter
+
+A `Counter` records monotonically increasing values — negative deltas are ignored, so it only ever climbs. Use it for totals like requests served, errors, or bytes sent.
+
+```scala
+final class Counter private[telemetry] (
+  val name: String, val description: String, val unit: String
+) {
+  def add(value: Long, attributes: Attributes): Unit
+  def add(value: Long, attrs: (String, Any)*): Unit  // convenience vararg overload
+  def bind(attributes: Attributes): BoundCounter      // pre-attributed for hot-path reuse
+  def collect(): MetricData                           // snapshot → MetricData.SumData
+}
+```
+
+Record with labels, then read the per-label totals from the collected `SumData`:
+
+```scala
+import zio.blocks.telemetry._
+
+val calls = metric.counter("db.calls")
+calls.add(1L, "table" -> "orders")
+calls.add(2L, "table" -> "items")
+
+val tableKey = AttributeKey.string("table")
+metric.reader.collectAllMetrics().foreach {
+  case MetricData.SumData(points) =>
+    points.foreach(p => println(s"${p.attributes.get(tableKey)}: ${p.value}"))
+  case _ => ()
+}
+```
+
+## UpDownCounter
+
+An `UpDownCounter` records bidirectional deltas — the same API as `Counter`, but negative values count. Use it for a running total that both rises and falls, such as active connections or queue depth.
+
+```scala
+final class UpDownCounter private[telemetry] (
+  val name: String, val description: String, val unit: String
+) {
+  def add(value: Long, attributes: Attributes): Unit
+  def add(value: Long, attrs: (String, Any)*): Unit
+  def bind(attributes: Attributes): BoundUpDownCounter
+  def collect(): MetricData
+}
+```
+
+Add positive and negative deltas; the running total nets out:
+
+```scala
+import zio.blocks.telemetry._
+
+val active = metric.upDownCounter("active.connections")
+active.add(1L)   // new connection
+active.add(-1L)  // connection closed
+
+metric.reader.collectAllMetrics().foreach {
+  case MetricData.SumData(points) => println(points.head.value)  // 0
+  case _ => ()
+}
+```
+
+## Histogram
+
+A `Histogram` distributes `Double` observations into buckets and accumulates their count, sum, min, and max per label set. Use it for value distributions like request latency or payload size. Observations fall into a fixed set of bucket boundaries, defaulting to `[0, 5, 10, 25, 50, 75, 100, 250, 500, 750, 1000, 2500, 5000, 7500, 10000]`.
+
+Each boundary is the **inclusive** upper bound of its bucket, so with boundaries `[5, 10]` a value of exactly `5` lands in the first bucket, not the second, and anything above the last boundary falls into one final overflow bucket. Note that the default set starts at `0`, so its first bucket holds only values at or below zero.
+
+For different boundaries, construct the histogram directly — the builder has no setter for them:
+
+```scala
+import zio.blocks.telemetry._
+
+val latency = Histogram("http.latency.ms", "Request latency", "ms", Array(10.0, 50.0, 100.0, 500.0))
+latency.record(42.0, "route" -> "/orders")
+
+val snapshot = latency.collect()
+```
+
+That path trades away registration: an instrument you build yourself belongs to no meter, so `collectAllMetrics()` never returns it and you have to call `collect()` on the instrument yourself.
+
+```scala
+final class Histogram private[telemetry] (
+  val name: String, val description: String, val unit: String,
+  val boundaries: Array[Double]
+) {
+  def record(value: Double, attributes: Attributes): Unit
+  def record(value: Double, attrs: (String, Any)*): Unit
+  def bind(attributes: Attributes): BoundHistogram
+  def collect(): MetricData                            // snapshot → MetricData.HistogramData
+}
+```
+
+Record observations, then read `count` and `sum` from the collected `HistogramData`:
+
+```scala
+import zio.blocks.telemetry._
+
+val latency = metric.histogram("request.latency")
+latency.record(42.5, "endpoint" -> "/api/orders")
+latency.record(1500.0, "endpoint" -> "/api/reports")
+
+metric.reader.collectAllMetrics().foreach {
+  case MetricData.HistogramData(points) =>
+    points.foreach(p => println(s"count=${p.count} sum=${p.sum}"))
+  case _ => ()
+}
+```
+
+## Gauge
+
+A `Gauge` holds the most recent `Double` value per label set — each `record` overwrites the previous one. Use it for an instantaneous reading like CPU temperature or a current queue-depth snapshot.
+
+```scala
+final class Gauge private[telemetry] (
+  val name: String, val description: String, val unit: String
+) {
+  def record(value: Double, attributes: Attributes): Unit
+  def record(value: Double, attrs: (String, Any)*): Unit
+  def bind(attributes: Attributes): BoundGauge
+  def collect(): MetricData                            // snapshot → MetricData.GaugeData
+}
+```
+
+Each `record` overwrites the last; the snapshot holds the latest value:
+
+```scala
+import zio.blocks.telemetry._
+
+val temp = metric.gauge("cpu.temperature")
+temp.record(72.5)
+temp.record(74.1)  // overwrites the previous value
+
+metric.reader.collectAllMetrics().foreach {
+  case MetricData.GaugeData(points) => println(points.head.value)  // 74.1
+  case _ => ()
+}
+```
+
+## Choosing an Instrument
+
+| Instrument      | Delta constraint | Use when                                |
+|-----------------|------------------|-----------------------------------------|
+| `Counter`       | Non-negative     | Counting requests, errors, events       |
+| `UpDownCounter` | Any              | Active connections, queue-depth changes |
+| `Histogram`     | Any `Double`     | Latency, payload-size distributions     |
+| `Gauge`         | Any `Double`     | CPU temperature, queue-depth snapshot   |
+
+## Bound Instruments
+
+When one label combination is recorded repeatedly on a hot path, `bind(attrs)` returns a `Bound*` instrument pre-associated with that label set, so recording skips rebuilding `Attributes` on every call:
+
+```scala
+import zio.blocks.telemetry._
+
+val bound = metric.counter("rpc.calls").bind(Attributes.of(AttributeKey.string("method"), "OrderService.place"))
+bound.add(1L)
+bound.add(1L)  // no Attributes construction per call
+```
+
+One caveat on a histogram: `bind` creates the per-label state immediately, so a label set you bind but never record collects as `count = 0` with `min` and `max` at their sentinel extremes (`Double.MaxValue` and `Double.MinValue`). Skip zero-count points when plotting, or bind only where you will record.
+
+For a name-based label API — declare label names once, then pass values positionally — see [Labeled Instruments](./labeled-instruments.md).
+
+## Collection
+
+`MetricReader.collectAllMetrics()` calls each registered instrument's `collect()`, producing one `MetricData` per instrument: `SumData` for `Counter` and `UpDownCounter`, `HistogramData` for `Histogram`, and `GaugeData` for `Gauge`. Pattern-match to read the data points — see [MetricData](./metric-data.md) for the point structure. Only instruments obtained from `metric.*` or a `Meter` builder are registered; do not construct an instrument directly, as an unregistered one never reaches `collectAllMetrics()`.

package/reference/telemetry/metrics/labeled-instruments.md

@@ -0,0 +1,74 @@
+---
+id: labeled-instruments
+title: "Labeled Instruments"
+description: "Metric instruments with pre-declared label names. Record values positionally; runtime arity validation prevents label mismatches."
+keywords:
+  - "Application Metrics"
+  - "Dimensional Metrics"
+  - "Prometheus-Style Labels"
+  - "Labeled Instruments"
+sidebar_label: "Labeled Instruments"
+---
+
+A labeled instrument is an ordinary counter, histogram, or gauge that already knows its label *names*. You declare them once — `"method"`, `"status"` — and then pass only values: `add(1, "GET", "200")`.
+
+It exists to keep call sites short and consistent: the names live in one place, so every recording site is guaranteed to use the same label keys in the same order, and reading `add(1, "GET", "200")` is quicker than reading a line of repeated pairs.
+
+Do not reach for it as an optimization. The pair form (`add(1, "method" -> "GET", …)`) builds its `Attributes` through a pooled, thread-local builder, while the labeled form allocates a fresh builder and a fresh `Attributes` on every call — so labeled recording allocates more, not less. What you give up is safety: passing the wrong *number* of values throws right at the recording call, but passing them in the wrong *order* records silently — swap two and you get a plausible-looking series that's simply wrong. When a label combination really is hot, `bind` is the answer: it resolves the attribute set once and hands back a `Bound*` that writes straight to the accumulator. A [`Meter`](./meter.md) creates labeled instruments, through `labeledCounter`, `labeledHistogram`, and `labeledGauge`.
+
+```scala
+final class LabeledCounter private[telemetry] (...) {
+  val labelNames: Array[String]
+  def add(value: Long, labelValues: Any*): Unit
+  def bind(labelValues: Any*): BoundCounter
+  def collect(): MetricData
+}
+
+final class LabeledHistogram private[telemetry] (...) {
+  val labelNames: Array[String]
+  def record(value: Double, labelValues: Any*): Unit
+  def bind(labelValues: Any*): BoundHistogram
+  def collect(): MetricData
+}
+
+final class LabeledGauge private[telemetry] (...) {
+  val labelNames: Array[String]
+  def record(value: Double, labelValues: Any*): Unit
+  def bind(labelValues: Any*): BoundGauge
+  def collect(): MetricData
+}
+```
+
+## Usage
+
+Declare the label names once, then supply values in that same order on each call. The count of `labelValues` must match the declared `labelNames`; a mismatch throws `IllegalArgumentException` at the recording call site (not at construction), so a wrong arity surfaces immediately in tests.
+
+```scala
+import zio.blocks.telemetry._
+
+val meter = MeterProvider.builder.build().get("com.example")
+
+// "GET" → "method", "200" → "status"
+val reqs = meter.labeledCounter("http.requests", "method", "status")
+reqs.add(1L, "GET", "200")
+reqs.add(1L, "POST", "500")
+
+val lat = meter.labeledHistogram("request.latency", "route")
+lat.record(15.0, "/orders")
+
+val depth = meter.labeledGauge("queue.depth", "queue")
+depth.record(7.0, "orders")
+```
+
+For a set of label values recorded over and over, `bind(labelValues*)` builds the `Attributes` once and returns a bound instrument that skips that work on each later call:
+
+```scala
+import zio.blocks.telemetry._
+
+val reqs  = MeterProvider.builder.build().get("com.example").labeledCounter("rpc.calls", "service", "method")
+val bound = reqs.bind("OrderService", "place")
+bound.add(1L)
+bound.add(1L)
+```
+
+Values flow through the wrapped `Counter`, `Histogram`, or `Gauge` and are collected by `MetricReader.collectAllMetrics()` like any other instrument — see [MetricData](./metric-data.md).

package/reference/telemetry/metrics/meter-provider.md

@@ -0,0 +1,76 @@
+---
+id: meter-provider
+title: "MeterProvider"
+description: "Configure metrics once for a service: name what produced them, hand out meters per component, and read every measurement back through one reader."
+keywords:
+  - "Application Metrics"
+  - "Metrics Configuration"
+  - "Meter Factory"
+  - "MeterProvider"
+---
+
+A `MeterProvider` is where metrics get configured, once, at startup. You build one, and it hands out the [`Meter`](./meter.md)s your components take.
+
+It exists because two things can't be decided per instrument. The first is **identity**: an exported measurement has to say what produced it, or a backend shows a number with no owner — and repeating that on every counter would be both tedious and inconsistent. You set it once as a [`Resource`](../common/resource.md) on the provider. Unlike spans and log records, collected metric data does not carry it, so read `provider.resource` when you export and attach it there.
+
+The second is **one place to read from**. Instruments end up scattered across components, and nothing useful happens until something collects them all together. The provider keeps the registry every meter joins, so a single `reader.collectAllMetrics()` returns every measurement from every scope beneath it — you never assemble a list of instruments yourself.
+
+Most applications never hold one: they hand a provider to `metric.install(...)` at startup and use the global [`metric`](./index.md) everywhere after. Build one yourself when you want a `Resource` of your own, or a scope you can collect and shut down independently of the global one.
+
+## Configuring Metrics for Your Service
+
+Build the provider with a `Resource` naming your service:
+
+```scala
+import zio.blocks.telemetry._
+
+val provider = MeterProvider.builder
+  .setResource(Resource.create(Attributes.of(Attributes.ServiceName, "payments")))
+  .build()
+```
+
+Do set the name. Skipping it doesn't fail — the default `Resource` supplies `service.name = "unknown_service"` alongside SDK version attributes — but that placeholder is what a backend will show for every measurement you export.
+
+## Getting a Meter per Component
+
+Ask for a meter by the component's name; that name is what attributes its measurements:
+
+```scala
+import zio.blocks.telemetry._
+
+val provider = MeterProvider.builder.build()
+
+val meter: Meter = provider.get("com.example.payments")
+```
+
+The full signature is `get(name: String, version: String = "")`; passing a version records it on the scope, which is how you tell measurements from two releases of the same library apart. Asking twice for the same name *and* version returns the same meter, so components take theirs independently without coordinating. The provider also exposes the `Resource` you built it with as `provider.resource`. See [Meter](./meter.md) for what to do with a meter.
+
+## Reading Everything Back
+
+`reader` is a single [`MetricReader`](./metric-data.md) for the provider's whole lifetime, created at `build()` — there is nothing to register, and no second reader to keep in sync:
+
+```scala
+import zio.blocks.telemetry._
+
+val provider = MeterProvider.builder.build()
+provider.get("com.example").counterBuilder("ops").build().add(1L)
+
+val snapshots: Seq[MetricData] = provider.reader.collectAllMetrics()
+```
+
+Each call aggregates what has accumulated so far into [`MetricData`](./metric-data.md) — one value per registered instrument, across every meter. This is a pull: nothing is sent anywhere until you or an exporter asks.
+
+## Shutting Down
+
+A provider is `AutoCloseable`, with `close()` calling `shutdown()`, so it fits `scala.util.Using.resource`:
+
+```scala
+import zio.blocks.telemetry._
+import scala.util.Using
+
+Using.resource(MeterProvider.builder.build()) { provider =>
+  provider.reader.collectAllMetrics()
+}
+```
+
+Unlike logging, there is nothing buffered here waiting to be flushed — metrics are read on demand, so the built-in reader's shutdown does no work today. Call it anyway at exit: it costs nothing, and it's what an export pipeline would hook into.

package/reference/telemetry/metrics/meter.md

@@ -0,0 +1,98 @@
+---
+id: meter
+title: "Meter"
+description: "Create the counters, histograms, and gauges one component records through — scoped to that component, and registered so collection finds them."
+keywords:
+  - "Application Metrics"
+  - "Instrument Registration"
+  - "Metric Instruments"
+  - "Meter"
+---
+
+A `Meter` is where one component's [instruments](./instruments.md) come from. You take a meter under your component's name, create counters and histograms from it, and record through those.
+
+It exists to answer a question a bare instrument name can't: *whose measurement is this?* A meter carries a scope name, so the instruments one component builds are grouped under it, and a reader can tell your `requests` counter from the one a library you depend on registered. (The two were never merged into one series — each instrument aggregates on its own — but without scopes there is nothing in the code that says which is which.)
+
+The second problem it solves is reachability. Recording a number is useless if nothing can read it back, and an instrument only reaches collection if something registered it. A meter is that something: it is registered with its [`MeterProvider`](./meter-provider.md) when you obtain it, and it registers every instrument you build from it, so a measurement's path to `reader.collectAllMetrics()` is complete the moment you call `build()` — with no wiring step you could forget.
+
+## Taking a Meter
+
+Ask a provider for one by name, or `metric.get(name)` in application code. Use the component's package as the name:
+
+```scala
+import zio.blocks.telemetry._
+
+val meter: Meter = MeterProvider.builder.build().get("com.example.server")
+```
+
+Asking twice for the same name gives you back the *same* meter, not a second one — meters are cached per scope. So separate call sites in one component can each take their meter without coordinating, and their instruments still land under a single scope.
+
+## Creating an Instrument
+
+Each of the four instrument kinds has a builder. Name it, optionally describe it and give it a unit, then `build()`:
+
+```scala
+import zio.blocks.telemetry._
+
+val meter = MeterProvider.builder.build().get("com.example.server")
+
+val requests = meter.counterBuilder("http.requests")
+  .setDescription("Total HTTP requests")
+  .setUnit("1")
+  .build()
+requests.add(1L, "method" -> "GET", "status" -> "200")
+
+val latency = meter.histogramBuilder("request.latency").setUnit("ms").build()
+latency.record(42.5, "route" -> "/api/orders")
+```
+
+The description and unit stay on the instrument — `collect()` returns data points only — so they reach a dashboard through whatever exporter reads the instrument, which is what lets it label an axis in milliseconds instead of showing bare numbers. Build each instrument once and hold the result — a `val` on the component that records through it. Building the same name twice gives you two registered instruments, which splits one logical metric into two series that no consumer can merge back together.
+
+## Recording on a Hot Path
+
+When the same label *names* repeat on every call, declaring them once keeps every call site consistent and short. `labeledCounter`, `labeledHistogram`, and `labeledGauge` fix the names at construction so callers pass just the values, positionally:
+
+```scala
+import zio.blocks.telemetry._
+
+val meter = MeterProvider.builder.build().get("com.example")
+
+val byRoute = meter.labeledCounter("http.requests", "method", "status")
+byRoute.add(1L, "GET", "200")
+```
+
+See [Labeled Instruments](./labeled-instruments.md) for the trade-offs; for ordinary recording the tuple form above is simpler.
+
+## Reporting a Value You Don't Push
+
+Some numbers aren't events you count — they're state you can read at any time, like a cache's size or a pool's idle connections. Instead of pushing an update whenever it changes, `buildWithCallback` on the counter, up-down counter, and gauge builders makes an instrument that asks *you* for the value at collection time:
+
+```scala
+import zio.blocks.telemetry._
+
+val meter = MeterProvider.builder.build().get("com.example")
+val cache = scala.collection.mutable.Map("k" -> "v")
+
+meter.gaugeBuilder("cache.entries").buildWithCallback { observer =>
+  observer.record(cache.size.toDouble, Attributes.empty)
+}
+```
+
+The block doesn't run when you build it — it runs once per collection, reading `cache.size` fresh each time, so the value can't go stale and you need no hook at every mutation. Keep it cheap and side-effect-free; it runs on the collecting thread. You can discard the returned instrument — the meter registered it, so collection finds it — and hold it only if you want to call its own `collect()` directly.
+
+`buildWithCallback` returns an `ObservableCounter`, `ObservableUpDownCounter`, or `ObservableGauge` depending on the builder, and hands your block an `ObservableCallback` to record through. Histograms have no callback form, since a distribution has to see every observation as it happens.
+
+Watch the type on the counters: both observable counters round what you report to a whole number, so a callback recording `1.5` is collected as `2`. Only `ObservableGauge` keeps the `Double` as given.
+
+## Two Ways to Lose Measurements
+
+Both come from an instrument that records into nothing:
+
+1. **Constructing an instrument directly.** `Counter("http.requests", "", "")` compiles, because the companion `apply` is public. It records perfectly well into an object no meter registered, so `collectAllMetrics()` never sees it. Go through a meter or `metric.*` — the one case that justifies direct construction is a [histogram with custom bucket boundaries](./instruments.md), where you accept the loss of registration and call `collect()` yourself.
+2. **Crossing providers.** An instrument reaches only the reader of the provider whose meter built it. `metric.install(...)` swaps in a provider with an empty registry, so take your meters and build your instruments *after* installing.
+
+## See Also
+
+- [Instruments](./instruments.md) — the recording API of each instrument kind
+- [MeterProvider](./meter-provider.md) — where meters come from, and what configures them
+- [MetricData](./metric-data.md) — what collection hands back

package/reference/telemetry/metrics/metric-data.md

@@ -0,0 +1,57 @@
+---
+id: metric-data
+title: "MetricData"
+description: "Aggregated metric snapshot produced by MetricReader.collectAllMetrics(). Three variants: SumData, HistogramData, GaugeData."
+keywords:
+  - "Application Metrics"
+  - "Metric Export"
+  - "Aggregated Snapshot"
+  - "MetricData"
+---
+
+`MetricData` is an aggregated snapshot of one instrument at one collect cycle — its accumulated points, keyed by label set. You rarely build it directly: it is what `MetricReader.collectAllMetrics()` returns, one value per registered instrument, for a test to assert on or an export pipeline to serialize. Each collection builds fresh points, though a histogram point exposes its `boundaries` and `bucketCounts` arrays as-is, so read them and don't write to them.
+
+One thing it does *not* carry is the instrument's name, description, or unit — a snapshot is only points and their label sets. So `collectAllMetrics()` hands back a `Seq[MetricData]` with no way to tell which instrument each entry came from, which is why an export pipeline pairs them with names of its own before serializing. In a test, collect from a single instrument with its own `collect()` when you need to know the source.
+
+Its three variants line up with the instrument that produced them:
+
+- `SumData` — from a [`Counter`](./instruments.md) or an `UpDownCounter`
+- `HistogramData` — from a `Histogram`
+- `GaugeData` — from a `Gauge`
+
+So a `match` on `MetricData` tells you both the shape of the numbers and the kind of instrument they came from.
+
+```scala
+sealed trait MetricData
+
+object MetricData {
+  final case class SumData(points: List[SumDataPoint])             extends MetricData
+  final case class HistogramData(points: List[HistogramDataPoint]) extends MetricData
+  final case class GaugeData(points: List[GaugeDataPoint])         extends MetricData
+}
+
+final case class SumDataPoint(
+  attributes:     Attributes,
+  startTimeNanos: Long,
+  timeNanos:      Long,
+  value:          Long          // cumulative sum
+)
+
+final case class HistogramDataPoint(
+  attributes:     Attributes,
+  startTimeNanos: Long,
+  timeNanos:      Long,
+  count:          Long,         // total number of observations
+  sum:            Double,       // sum of all observations
+  min:            Double,       // smallest observation
+  max:            Double,       // largest observation
+  bucketCounts:   Array[Long],  // count per bucket (length == boundaries.length + 1)
+  boundaries:     Array[Double] // the bucket upper boundaries
+)
+
+final case class GaugeDataPoint(
+  attributes: Attributes,
+  timeNanos:  Long,
+  value:      Double            // most recently recorded value
+)
+```