@zio.dev/zio-blocks 0.0.33 → 0.0.55

package/reference/telemetry/otel/custom-exporter.md

@@ -0,0 +1,216 @@
+---
+id: custom-exporter
+title: "Building an Exporter"
+sidebar_label: "Building an Exporter"
+description: "Encode telemetry into OTLP JSON, send it yourself, and interpret the result — the public pieces of the export path and how they fit together."
+keywords:
+  - "OTLP JSON"
+  - "Custom Exporter"
+  - "Telemetry Export"
+  - "Export Result"
+---
+
+The exporters that ship with this module are internal, but the pieces they are built from are not. `OtlpJsonEncoder` turns recorded signals into OTLP JSON bytes, [`HttpSender`](./index.md) puts bytes on the wire, and `ExportResult` classifies what came back. Together they are enough to export telemetry today, without waiting for a public exporter API. Supporting types: `NamedMetric`, `HttpResponse`. The public surface of the export path:
+
+```scala
+object OtlpJsonEncoder {
+  def encodeTraces(spans: Seq[SpanData], resource: Resource, scope: InstrumentationScope): Array[Byte]
+  def encodeMetrics(metrics: Seq[NamedMetric], resource: Resource, scope: InstrumentationScope): Array[Byte]
+  def encodeLogs(logs: Seq[LogRecord], resource: Resource, scope: InstrumentationScope): Array[Byte]
+}
+
+sealed trait ExportResult
+
+object ExportResult {
+  case object Success                                           extends ExportResult
+  final case class Failure(retryable: Boolean, message: String) extends ExportResult
+
+  def fromHttpResponse(response: HttpResponse): ExportResult
+}
+```
+
+## Motivation
+
+`OtlpJsonTraceExporter`, `OtlpJsonLogExporter`, `OtlpJsonMetricExporter`, and the `BatchProcessor` behind them are all `private[otel]`, so there is no supported way to construct one. That is a real limitation, and the [module overview](./index.md) says so.
+
+What it does not mean is that you cannot export. Three of the four pieces an exporter needs are public: the encoder that produces the payload, the sender that transmits it, and the result type that says whether to retry. Only the batching and retry loop is missing, and for many deployments that loop is a scheduled task you already have — a periodic flush from whatever scheduler your application runs.
+
+Writing it yourself also buys control the internal exporter does not offer: your own retry policy, your own queue semantics, metrics about the exporter itself, and a payload you can inspect before it leaves the process.
+
+## The Encoder
+
+`OtlpJsonEncoder` produces the OTLP protobuf-JSON mapping directly into a `StringBuilder`, with no JSON library involved. Each method takes the signals plus the `Resource` and `InstrumentationScope` that describe their origin, and returns UTF-8 bytes ready to POST.
+
+### Encoding Rules
+
+The output follows the protobuf JSON mapping rather than a naive rendering, which matters if you plan to compare payloads or write assertions against them:
+
+| Wire concern              | Encoding                                       |
+| ------------------------- | ---------------------------------------------- |
+| `traceId`, `spanId` bytes | Lowercase hex strings                           |
+| `int64` / `uint64`        | Quoted strings, not JSON numbers                |
+| Enums                     | Integers                                        |
+| Field names               | camelCase                                       |
+| Control characters        | `\uXXXX` escapes, including lone surrogates      |
+
+The quoted-integer rule is the one that surprises people: OTLP timestamps are `uint64`, so they appear as `"1755990000000000000"` rather than a bare number. A collector expects that; a hand-written comparison usually does not.
+
+### Encoding Traces
+
+`OtlpJsonEncoder.encodeTraces` takes `SpanData` values — the same records the core module's in-memory processor collects:
+
+```scala
+import zio.blocks.telemetry._
+import zio.blocks.telemetry.otel._
+
+val payload: Array[Byte] = OtlpJsonEncoder.encodeTraces(
+  trace.collectedSpans,
+  Resource.empty,
+  InstrumentationScope("checkout-service", Some("1.4.0"))
+)
+```
+
+`trace.collectedSpans` returns everything recorded so far, so a real exporter tracks what it has already sent rather than re-encoding the whole list on every flush.
+
+### Encoding Logs
+
+`OtlpJsonEncoder.encodeLogs` takes `LogRecord` values, and is otherwise identical in shape:
+
+```scala
+import zio.blocks.telemetry._
+import zio.blocks.telemetry.otel._
+
+def exportLogs(records: Seq[LogRecord]): Array[Byte] =
+  OtlpJsonEncoder.encodeLogs(records, Resource.empty, InstrumentationScope("checkout-service"))
+```
+
+### Encoding Metrics
+
+Metrics need one extra step, because the encoder wants a name and the reader does not supply one. `NamedMetric` pairs the descriptor with the data:
+
+```scala
+final case class NamedMetric(
+  name: String,
+  description: String,
+  unit: String,
+  data: MetricData
+)
+```
+
+`MetricReader#collectAllMetrics` returns `Seq[MetricData]`, and `MetricData` — `SumData`, `HistogramData`, or `GaugeData` — carries only data points. The name, description, and unit are not on it:
+
+```scala
+import zio.blocks.telemetry._
+import zio.blocks.telemetry.otel._
+
+val collected: Seq[MetricData] = metric.reader.collectAllMetrics()
+
+val named: Seq[NamedMetric] =
+  collected.map(data => NamedMetric("http.server.duration", "Request duration", "ms", data))
+
+val payload = OtlpJsonEncoder.encodeMetrics(named, Resource.empty, InstrumentationScope("checkout-service"))
+```
+
+:::warning[`MetricData` does not carry its own name]
+`MetricReader#collectAllMetrics` returns metric data with no identifying name, and there is no public way to recover which instrument produced which element. Attaching the right name means tracking the correspondence yourself — record the instruments you created in the same order you read them back, or collect per-instrument rather than in bulk. Mapping a whole batch to one name, as above, is only correct when you registered exactly one instrument.
+:::
+
+`OtlpJsonEncoder.NamedMetric` is a type alias and value alias for the same case class, so either spelling compiles.
+
+## Interpreting the Response
+
+`ExportResult` classifies an HTTP response into "delivered", "retry this", and "drop this". `ExportResult.fromHttpResponse` applies the standard OTLP rules, so you do not need to remember which status codes are worth a second attempt:
+
+```scala
+import zio.blocks.telemetry.otel._
+
+def result(status: Int): ExportResult =
+  ExportResult.fromHttpResponse(HttpResponse(status, Array.emptyByteArray, Map.empty))
+```
+
+Any `2xx` is a success:
+
+```scala
+result(200)
+// res3: ExportResult = Success
+result(204)
+// res4: ExportResult = Success
+```
+
+Four status codes are treated as retryable — `429`, `502`, `503`, and `504` — because each means "not now" rather than "not ever":
+
+```scala
+result(429)
+// res5: ExportResult = Failure(retryable = true, message = "HTTP 429")
+result(503)
+// res6: ExportResult = Failure(retryable = true, message = "HTTP 503")
+```
+
+Everything else is a permanent failure, and retrying it only wastes the batch. A `400` means the collector rejected the payload itself, so the same bytes will be rejected again:
+
+```scala
+result(400)
+// res7: ExportResult = Failure(retryable = false, message = "HTTP 400")
+result(401)
+// res8: ExportResult = Failure(retryable = false, message = "HTTP 401")
+```
+
+The `message` is a short diagnostic rather than the response body, so log the body separately when you need to know *why* a `400` was rejected.
+
+A rejected export arrives as a non-`2xx` `HttpResponse`, not as an exception. A connection that never completes is different: `HttpSender.jdk` lets `IOException` out, so a custom loop must catch throwables and treat them as retryable itself — `ExportResult.fromHttpResponse` never sees them.
+
+:::tip[Honour `Retry-After`]
+`HttpResponse#firstHeader` looks a header up case-insensitively, which is what a `429` or `503` needs. `ExportResult` does not read it, so a retry loop that ignores `Retry-After` will keep hammering a collector that just asked it to wait.
+:::
+
+## Putting It Together
+
+A minimal exporter is a flush function: take what has accumulated, encode it, send it, and act on the result. This is the whole shape, with the retry decision made from `ExportResult`:
+
+```scala
+import zio.blocks.telemetry._
+import zio.blocks.telemetry.otel._
+import java.time.Duration
+
+val config = ExporterConfig(
+  endpoint = "https://otlp.example.com:4318",
+  headers = Map("Authorization" -> "Bearer <token>"),
+  timeout = Duration.ofSeconds(10)
+)
+
+val sender = HttpSender.jdk(config.timeout)
+val scope  = InstrumentationScope("checkout-service", Some("1.4.0"))
+
+def flushTraces(spans: Seq[SpanData]): ExportResult =
+  if (spans.isEmpty) ExportResult.Success
+  else {
+    val body = OtlpJsonEncoder.encodeTraces(spans, Resource.empty, scope)
+    try ExportResult.fromHttpResponse(
+      sender.send(config.endpoint + "/v1/traces", config.headers + ("Content-Type" -> "application/json"), body)
+    )
+    catch {
+      case e: java.io.IOException => ExportResult.Failure(retryable = true, message = e.getMessage)
+    }
+  }
+```
+
+Three details in there are easy to get wrong. The signal path is appended to the endpoint — `/v1/traces`, `/v1/logs`, or `/v1/metrics` — because `ExporterConfig#endpoint` is a base URL. `Content-Type: application/json` must be set, since the payload is the JSON mapping rather than protobuf. And the `IOException` catch is not optional: without it, a collector that is simply unreachable takes down whatever thread the flush runs on.
+
+Call `HttpSender#shutdown` when the process is stopping. The JDK sender holds nothing that needs releasing, but a custom sender may, and a flush that never runs at shutdown loses whatever was still queued.
+
+## What You Are Reimplementing
+
+The internal `BatchProcessor` does four things a hand-rolled flush does not, and they are worth deciding about explicitly rather than discovering later:
+
+- **Bounded queueing.** It caps the queue at `ExporterConfig#maxQueueSize` and evicts the oldest record when full, so recording never blocks and memory never grows without bound. A naive accumulator has neither property.
+- **Chunking.** It splits a drained queue into `ExporterConfig#maxBatchSize` pieces, so one flush after a traffic spike becomes several right-sized requests instead of one oversized one.
+- **Interval flushing.** It flushes every `ExporterConfig#flushIntervalMillis` regardless of how full the batch is, which is what bounds how stale exported data can be.
+- **Retry on retryable failures.** It re-queues a batch whose `ExportResult` was `Failure(retryable = true)` and drops one that was not.
+
+`ExporterConfig` carries all three sizing fields even though nothing public reads them, so use them as the source of truth for your own loop rather than inventing separate numbers. See [the module overview](./index.md) for what each field means.
+
+## Integration Points
+
+This page uses only public API: `OtlpJsonEncoder`, `NamedMetric`, `ExportResult`, `HttpResponse`, `HttpSender`, and `ExporterConfig` from this module, and `SpanData`, `LogRecord`, `MetricData`, `Resource`, and `InstrumentationScope` from the core telemetry module.
+
+The signals themselves come from the core module's recording APIs — [`trace`](../tracing/index.md) for spans, [`log`](../logging/index.md) for records, and [`metric`](../metrics/index.md) for measurements. For trace context across service boundaries rather than export, see [the module overview](./index.md).

package/reference/telemetry/otel/index.md

@@ -0,0 +1,212 @@
+---
+id: index
+title: "OTLP Export"
+description: "Send recorded telemetry out of your process to an OpenTelemetry collector, and carry trace context across service boundaries."
+keywords:
+  - "OpenTelemetry Protocol"
+  - "Telemetry Export"
+  - "Trace Propagation"
+  - "OTLP"
+---
+
+The core telemetry module records signals inside your process. This module gets them out: it speaks OTLP over HTTP, so anything that accepts OpenTelemetry data — a collector, Jaeger, Tempo, a vendor's endpoint — can receive your traces, logs, and metrics.
+
+It also carries trace context *between* processes. A trace that stops at your service boundary isn't much use, so a propagator reads and writes the standard headers that let two services contribute spans to the same trace.
+
+## Installation
+
+Add the module to your build file:
+
+```scala
+libraryDependencies += "dev.zio" %% "zio-blocks-telemetry-otel" % "0.0.55"
+```
+
+## Configuring the Endpoint and Batching
+
+One `ExporterConfig` answers two questions for an exporter: where to send data, and how much to hold before sending it. Both matter for the same reason — a collector is a network hop away, so sending one span per request would add a round trip to every request you were trying to measure. Records accumulate and go out in batches instead.
+
+```scala
+final case class ExporterConfig(
+  endpoint: String             = "http://localhost:4318",
+  headers: Map[String, String] = Map.empty,
+  timeout: Duration            = Duration.ofSeconds(30),
+  maxQueueSize: Int            = 2048,
+  maxBatchSize: Int            = 512,
+  flushIntervalMillis: Long    = 5000
+)
+```
+
+Every field has a default, so `ExporterConfig()` is valid and points at a collector on localhost — the usual local development setup. `endpoint` is the collector's base URL, `headers` carries whatever it needs to accept you (typically an API key or bearer token), and `timeout` bounds a single send attempt:
+
+```scala
+import zio.blocks.telemetry.otel._
+import java.time.Duration
+
+val config = ExporterConfig(
+  endpoint = "https://otlp.example.com:4318",
+  headers = Map("Authorization" -> "Bearer <token>"),
+  timeout = Duration.ofSeconds(10)
+)
+```
+
+Headers are treated as sensitive: `toString` prints their count, never their contents, so a config logged at startup can't leak a token.
+
+The three batching fields trade latency against overhead. `flushIntervalMillis` is how long a partial batch waits before going out anyway — lower it to see data sooner, raise it to send fewer, larger requests. `maxBatchSize` is how many records go in one request; filling a batch does not trigger a send, it only chunks what the next flush drains, so the interval is what determines when data leaves. `maxQueueSize` is how many records may be waiting at once: once the queue is over that limit each new record evicts the oldest one still queued, so recording never blocks and the queue never grows without bound. The defaults suit a service with steady moderate traffic; a high-throughput one should raise `maxQueueSize` before it starts dropping.
+
+## Sending the Bytes
+
+`HttpSender` is the one piece of the export path that actually touches the network. An exporter hands it a URL, headers, and a body of OTLP bytes; it performs the request and returns the response.
+
+It's a separate trait so the network is replaceable. Real deployments need things a fixed HTTP client can't know about — an outbound proxy, request signing, a corporate TLS setup — and tests need the opposite: no network at all.
+
+```scala
+trait HttpSender {
+  def send(url: String, headers: Map[String, String], body: Array[Byte]): HttpResponse
+  def shutdown(): Unit
+}
+
+object HttpSender {
+  def jdk(timeout: Duration = Duration.ofSeconds(30)): HttpSender
+}
+
+final case class HttpResponse(statusCode: Int, body: Array[Byte], headers: Map[String, Seq[String]]) {
+  def firstHeader(name: String): Option[String]
+}
+```
+
+`HttpSender.jdk` wraps `java.net.http.HttpClient`, which ships with the JVM, so nothing is added to your dependencies. The timeout applies to both connecting and completing a request. `shutdown()` is where a sender releases what it holds — the JDK one holds nothing that needs closing, so its implementation does nothing:
+
+```scala
+import zio.blocks.telemetry.otel._
+import java.time.Duration
+
+val sender = HttpSender.jdk(Duration.ofSeconds(10))
+```
+
+`send` reports a rejected export as an `HttpResponse` with a non-`2xx` status rather than as an exception, so an exporter can decide whether a failure is worth retrying. A connection that never completes still throws — `HttpSender.jdk` lets `IOException` out — and the batching layer treats such a throw as a retryable failure. Its `firstHeader(name)` looks a header up case-insensitively, which is what you need for a `Retry-After` on a `429` or `503`.
+
+To write your own, implement the two methods: return a `2xx` status for a send the exporter should treat as delivered, anything else to mark it failed. Most custom senders are wrappers rather than replacements — sign the request, pick a proxy, count attempts, then delegate to `HttpSender.jdk(...)` and pass its response back.
+
+## Propagating Context Across Services
+
+One request usually touches several services. Your API calls an inventory service, which calls a database proxy — and you want that whole journey to read as *one* trace, not three unrelated ones.
+
+That doesn't happen by itself. Each service starts a fresh trace unless the caller tells it which trace it is already part of, and an HTTP call carries nothing but headers. So the caller writes the current trace's identity into a header, and the receiver reads it back out and continues that trace instead of beginning its own.
+
+A propagator does that writing and reading. The identity travels as text in a standard header, which is what lets it cross between services written in different languages:
+
+```scala
+trait Propagator {
+  def extract[C](carrier: C, getter: (C, String) => Option[String]): Option[SpanContext]
+  def inject[C](spanContext: SpanContext, carrier: C, setter: (C, String, String) => C): C
+  def fields: Seq[String]
+}
+```
+
+The carrier is whatever holds your headers — a `Map`, your framework's request type — and you supply the accessor, so no HTTP library is assumed. `fields` names the headers a propagator touches, which is what you pass to a CORS or header-allowlist configuration.
+
+Use `W3CTraceContextPropagator` unless something upstream requires otherwise: it implements the W3C `traceparent` standard, which is what OpenTelemetry emits by default and what most backends expect. `B3Propagator` covers Zipkin's format in two shapes — `B3Propagator.single` puts everything in one `b3` header, `B3Propagator.multi` splits it across `X-B3-TraceId`, `X-B3-SpanId`, `X-B3-Sampled`, `X-B3-ParentSpanId`, and `X-B3-Flags`.
+
+On the way out, take the active span's context and write it into a header map:
+
+```scala
+import zio.blocks.telemetry._
+import zio.blocks.telemetry.otel._
+
+val tracer = trace.get("api-service")
+
+tracer.span("call-inventory", SpanKind.Client) { span =>
+  val headers = W3CTraceContextPropagator.inject(
+    span.spanContext,
+    Map.empty[String, String],
+    (carrier: Map[String, String], k: String, v: String) => carrier + (k -> v)
+  )
+  // headers now holds "traceparent" -> "00-<traceId>-<spanId>-01"
+  headers
+}
+```
+
+On the way in, `extract` returns `None` when the header is absent or malformed, so a request without trace context simply starts its own trace. An extracted context is marked `isRemote = true`, which is how you tell a continued trace from one that started locally.
+
+Extracting isn't enough on its own, though — the context has to be *active* while your handler runs, or the span you open won't attach to it. Hold the `ContextStorage` you gave the provider and scope the remote context around the work:
+
+```scala
+import zio.blocks.telemetry._
+import zio.blocks.telemetry.otel._
+
+val storage = ContextStorage.create[Option[SpanContext]](None)
+trace.install(TracerProvider.builder.setContextStorage(storage).build())
+
+val tracer = trace.get("api-service")
+
+val parent: Option[SpanContext] =
+  W3CTraceContextPropagator.extract(
+    Map("traceparent" -> "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01"),
+    (m: Map[String, String], k: String) => m.get(k)
+  )
+
+storage.scoped(parent) {
+  tracer.span("handle-checkout", SpanKind.Server) { span =>
+    span.setAttribute("http.route", "/checkout")
+  }
+}
+```
+
+Create the storage yourself: a provider's own is internal, so there's no reaching it after the fact. Note also that `trace.get` binds to whichever provider is installed when it runs, so take your tracers after `trace.install`.
+
+## Exporting Traces, Logs, and Metrics
+
+The exporters that carry each signal to a collector are internal to this module: `OtlpJsonTraceExporter`, `OtlpJsonLogExporter`, and `OtlpJsonMetricExporter` are `private[otel]`, as is the `BatchProcessor` that batches records before a send. There is no public way to construct one yet.
+
+The pieces they are built from *are* public, though, so exporting does not have to wait for that entry point. `OtlpJsonEncoder` produces OTLP JSON bytes from recorded signals, `HttpSender` transmits them, and `ExportResult` says whether a failed send is worth retrying — see [Building an Exporter](./custom-exporter.md) for the encoder, the result type, and a worked flush function.
+
+For development and testing, the core module's in-process destinations avoid the network entirely: [`log.writer`](../logging/index.md) for formatted output, [`trace.collectedSpans`](../tracing/index.md) for recorded spans, and [`metric.reader`](../metrics/index.md) for measurement snapshots. The [Telemetry Guide](../../../guides/telemetry-guide.md) sketches the intended shape of the wiring once a public exporter lands.
+
+## Threading Context Through `Context[R]`
+
+`Propagator` moves trace context between processes. `OtelContext` moves it *within* one, across code that threads dependencies through `Context[R]` rather than reading an ambient storage:
+
+```scala
+final case class OtelContext(spanContext: Option[SpanContext])
+
+object OtelContext {
+  def current(storage: ContextStorage[Option[SpanContext]]): OtelContext
+  def withSpan[A](span: Span, storage: ContextStorage[Option[SpanContext]])(f: => A): A
+}
+```
+
+`OtelContext.current` snapshots whatever span context is active in a storage, giving a plain value that can be placed into a `Context[R & OtelContext]` and passed along like any other dependency:
+
+```scala
+import zio.blocks.telemetry._
+import zio.blocks.telemetry.otel._
+
+val storage = ContextStorage.create[Option[SpanContext]](None)
+val snapshot = OtelContext.current(storage)
+```
+
+`OtelContext.withSpan` is the inverse: it makes a span's context active for the duration of a block and restores the previous value afterwards, including when the block throws:
+
+```scala
+import zio.blocks.telemetry._
+import zio.blocks.telemetry.otel._
+
+val storage = ContextStorage.create[Option[SpanContext]](None)
+val tracer  = trace.get("api-service")
+
+tracer.span("handle-request", SpanKind.Server) { span =>
+  OtelContext.withSpan(span, storage) {
+    // anything reading `storage` here sees this span's context
+    OtelContext.current(storage)
+  }
+}
+```
+
+An `IsNominalType[OtelContext]` instance is provided, which is what lets the type be used as a `Context` key.
+
+## See Also
+
+- [Building an Exporter](./custom-exporter.md) — `OtlpJsonEncoder`, `ExportResult`, and a worked flush function
+- [AttributeValue](../common/any-value.md) — the eight attribute kinds this exporter maps onto OTLP's `AnyValue` JSON shape
+- [Tracing](../tracing/index.md) — opening the spans this module exports, and [`SpanContext`](../tracing/span-context.md), the identity a propagator moves
+- [Telemetry Reference](../index.md) — the core module that records what this one exports

package/reference/telemetry/tracing/index.md

@@ -0,0 +1,155 @@
+---
+id: index
+title: "Tracing"
+description: "Tracing index: the trace entry point, TracerProvider, Tracer, Span, and supporting types for distributed tracing in the telemetry module."
+keywords:
+  - "Distributed Tracing"
+  - "Trace Correlation"
+  - "Tracing Overview"
+  - "TracerProvider"
+sidebar_label: "Tracing"
+---
+
+Tracing follows a single request as it moves through your application — and across services — recording each step as a **span**: a timed unit of work with a name, attributes, and an outcome. Spans nest into a **trace**, a parent/child tree that shows where a request spent its time and where it failed. Because one trace can stretch across several services, it's how you answer "why was this request slow?" when the answer is three network hops away.
+
+You create spans through the `trace` object: `trace.span("handle-request") { span => … }` wraps a block of work — it opens a span, runs the block, and closes the span automatically when the block returns. A `trace.span` opened inside another automatically becomes its child, so the tree builds itself with no manual wiring. Inside the block you annotate the span with attributes, events, and a status, and classify its role with a [`SpanKind`](./span-kind.md) when it crosses a service boundary.
+
+With no setup, `trace` records every span into an in-memory buffer — the default for development and tests, where `trace.collectedSpans` hands back what was recorded. For production, call `trace.install(provider)` once at startup to send spans to a real backend (Jaeger, OTLP, …); a [`Sampler`](./sampler.md) then decides which spans to keep so you aren't exporting everything under load. The types behind `trace` — [`TracerProvider`](./tracer-provider.md), [`Tracer`](./tracer.md), [`Span`](./span.md), and the [`SpanProcessor`](./span-processor.md)s — are configured once at startup; day to day you just call `trace.span`.
+
+## Open a Span and Record Work
+
+Wrap a unit of work in `trace.span(name) { span => … }`.
+
+```scala
+object trace {
+  def span[A](name: String)(f: Span => A): A
+}
+```
+
+The block receives a live `Span`; set attributes, add timeline events, and set the completion status on it. The span closes automatically when the block returns.
+
+```scala
+import zio.blocks.telemetry._
+
+trace.span("handle-request") { span =>
+  span.setAttribute("http.route", "/orders")
+  span.setAttribute("http.status_code", 200L)
+  span.addEvent("validated")
+  span.setStatus(SpanStatus.Ok)
+}
+```
+
+## Classify a Span and Pre-Set Attributes
+
+Two overloads add a [`SpanKind`](./span-kind.md) and, optionally, initial [`Attributes`](../common/attributes.md).
+
+```scala
+object trace {
+  def span[A](name: String, kind: SpanKind)(f: Span => A): A
+  def span[A](name: String, kind: SpanKind, attributes: Attributes)(f: Span => A): A
+}
+```
+
+`SpanKind` marks a span's role in a trace (`Server`, `Client`, `Producer`, `Consumer`, or the default `Internal`), and the `Attributes` set stamps values known at creation.
+
+```scala
+import zio.blocks.telemetry._
+
+trace.span("db-query", SpanKind.Client, Attributes.of(AttributeKey.string("db.system"), "postgresql")) { span =>
+  span.setAttribute("db.statement", "SELECT * FROM orders")
+}
+```
+
+## Nest Spans into a Trace Tree
+
+A `trace.span` opened inside another automatically attaches to the enclosing span as its parent through the shared `ContextStorage`, so nested calls build a parent/child tree with no manual context passing.
+
+```scala
+import zio.blocks.telemetry._
+
+trace.span("checkout", SpanKind.Server) { _ =>
+  trace.span("load-cart") { child =>
+    child.setAttribute("cart.items", 3L)
+  }
+  trace.span("charge-card")(_ => ())
+}
+```
+
+## Scope Spans to an Instrumentation Library
+
+Every span records which code produced it. Spans opened with `trace.span(...)` are all attributed to one scope named `"default"`, which is fine for an application tracing its own work — but it means spans from a library you depend on arrive indistinguishable from your own. `trace.get(name)` returns a [`Tracer`](./tracer.md) that stamps a name of your choosing on every span it records instead, so a backend can group them and someone debugging a slow request can see which component the time went to:
+
+```scala
+object trace {
+  def get(name: String): Tracer
+}
+```
+
+Calling this is the application's job, at startup: name the scope after the component it's for, then pass the `Tracer` to that component as a constructor parameter. A library should accept a `Tracer` rather than reach for the global `trace` itself — that keeps it testable in isolation and free of global state. Otherwise the two behave the same for opening spans: same overloads, same automatic parent nesting, same sampler and exporters.
+
+```scala
+import zio.blocks.telemetry._
+
+val tracer: Tracer = trace.get("com.example.orders")
+
+trace.clearSpans()
+tracer.span("reserve-inventory")(_ => ())
+trace.span("unscoped-work")(_ => ())
+
+// the scope each span was recorded under
+trace.collectedSpans.foreach(sd => println(sd.instrumentationScope.name))
+// com.example.orders
+// default
+```
+
+Order matters here. A `Tracer` is bound to whichever provider was installed when `trace.get` ran, while `trace.span` looks up the current provider on every call. Get your tracers *after* `trace.install(...)`, or a tracer created during startup will keep recording into the default in-memory buffer and its spans will never reach the exporter you installed afterwards.
+
+## Inspect Recorded Spans
+
+Until you install a provider, finished spans stay in memory where a test can read them back:
+
+```scala
+object trace {
+  def collectedSpans: List[SpanData]
+  def clearSpans(): Unit
+}
+```
+
+`collectedSpans` returns each completed span as [`SpanData`](./span-data.md), oldest first, and `clearSpans()` empties the buffer — call it at the start of a test so you assert on that test's spans alone.
+
+Two limits are worth knowing before you rely on this. The buffer is a ring of 1024 spans, so a long run silently overwrites its oldest entries; assert as you go rather than at the end of a large suite. And both methods read the buffer belonging to the **default** provider, so once you call `trace.install(...)`, they stop seeing new spans — a test that installs a provider has to collect through that provider's own processors instead.
+
+## Install a Provider and Reset
+
+`trace.install(provider)` swaps in a production `TracerProvider` — configured with a [`Resource`](../common/resource.md), a `Sampler`, and one or more `SpanProcessor` exporters.
+
+```scala
+object trace {
+  def install(provider: TracerProvider): Unit
+  def removeAll(): Unit
+}
+```
+
+Build the provider once at startup and install it before any span is opened — name your service in the `Resource` so exported spans can be told apart from other services, and pick a `Sampler` to decide how many spans to keep:
+
+```scala
+import zio.blocks.telemetry._
+
+trace.install(
+  TracerProvider.builder
+    .setResource(Resource.create(Attributes.of(Attributes.ServiceName, "order-service")))
+    .setSampler(AlwaysOnSampler)
+    .build()
+)
+
+// every trace.span in the application now records through this provider
+trace.span("handle-request", SpanKind.Server)(_.setAttribute("http.route", "/orders"))
+```
+
+`trace.removeAll()` swaps in a provider whose sampler drops everything. Your `trace.span` blocks still run — they just receive a no-op `Span` that records nothing — so removing tracing never changes what your code does, only what it reports. Note that it leaves the in-memory buffer untouched; use `clearSpans()` to empty that.
+
+## See Also
+
+- [Telemetry Guide](../../../guides/telemetry-guide.md) — tracing data flow, sampling, and production patterns
+- [Telemetry Reference](../index.md) — module overview and all three pillars
+- [Common Types](../common/index.md) — `Attributes`, `AttributeKey`, `Resource`, and `InstrumentationScope`

package/reference/telemetry/tracing/sampler.md

@@ -0,0 +1,89 @@
+---
+id: sampler
+title: "Sampler"
+description: "Decides per-span whether to drop, record-only, or record-and-sample."
+keywords:
+  - "Distributed Tracing"
+  - "Trace Sampling"
+  - "Head-Based Sampling"
+  - "Custom Sampler"
+  - "Sampler"
+sidebar_label: "Sampler"
+---
+
+`Sampler` is the policy that decides, for every new span, whether to record it with the sampled flag set (`RecordAndSample`), record it with the flag cleared (`RecordOnly`), or drop it (`Drop`). Both recording decisions reach every `SpanProcessor` identically; `RecordOnly` differs only in the cleared flag, which is the signal a downstream exporter or service uses to leave the span unexported. It exists to keep tracing volume under control: the sampler runs once per span in the hot path, before any recording work happens. You rarely implement one — the three built-ins cover the common strategies — and you configure a sampler once on the [`TracerProvider`](./tracer-provider.md) rather than calling it yourself. When the decision is `Drop`, [`Tracer`](./tracer.md) hands your block a `Span.NoOp` that records nothing and reaches no processor.
+
+```scala
+trait Sampler {
+  def shouldSample(
+    parentContext: Option[SpanContext],
+    traceIdHi:     Long,
+    traceIdLo:     Long,
+    name:          String,
+    kind:          SpanKind,
+    attributes:    Attributes,
+    links:         Seq[SpanLink]
+  ): SamplingResult
+
+  def description: String
+}
+
+final case class SamplingResult(
+  decision:   SamplingDecision,  // Drop | RecordOnly | RecordAndSample
+  attributes: Attributes,        // extra attributes injected into the span
+  traceState: String
+)
+```
+
+## Predefined Samplers
+
+Three built-in samplers cover the strategies most services need, so a custom implementation is rarely necessary:
+
+| Sampler                             | Behaviour                                                                          |
+|-------------------------------------|------------------------------------------------------------------------------------|
+| `AlwaysOnSampler`                   | Always returns `RecordAndSample`. Default for `TracerProvider.builder`.            |
+| `AlwaysOffSampler`                  | Always returns `Drop`, reusing one cached `SamplingResult`.                        |
+| `ParentBasedSampler(root: Sampler)` | Follows the parent span's sampled flag; delegates to `root` when no parent exists. |
+
+Set one on the provider at startup — this configures OpenTelemetry-compatible head sampling:
+
+```scala
+import zio.blocks.telemetry._
+
+val provider = TracerProvider.builder
+  .setSampler(ParentBasedSampler(AlwaysOnSampler))
+  .build()
+
+provider.shutdown()
+```
+
+## Custom Samplers
+
+When the built-ins do not fit — for example, sampling only premium tenants or at a probabilistic rate — implement `Sampler` yourself. Cache the `SamplingResult` values so the hot path stays allocation-free:
+
+```scala
+import zio.blocks.telemetry._
+
+object TenantSampler extends Sampler {
+  private val sampled = SamplingResult(SamplingDecision.RecordAndSample, Attributes.empty, "")
+  private val dropped = SamplingResult(SamplingDecision.Drop, Attributes.empty, "")
+
+  def shouldSample(
+    parentContext: Option[SpanContext],
+    traceIdHi: Long, traceIdLo: Long,
+    name: String, kind: SpanKind, attributes: Attributes,
+    links: Seq[SpanLink]
+  ): SamplingResult =
+    if (attributes.get(AttributeKey.string("tenant")).contains("premium")) sampled
+    else dropped
+
+  def description: String = "TenantSampler"
+}
+
+val provider = TracerProvider.builder.setSampler(TenantSampler).build()
+provider.shutdown()
+```
+
+The `attributes` your sampler sees are only the ones passed at creation — `trace.span(name, kind, attributes)` or `tracer.span(name, kind, attributes)`. Anything you set on the span *inside* the block happens after the decision, so a sampler can never route on it. A span started through [`SpanBuilder`](./span-builder.md) never consults a sampler at all.
+
+A dropped span is not nothing. The block still runs with a no-op span, and a valid trace id is still put in scope with the sampled bit cleared — so a nested `trace.span` under `ParentBasedSampler` is dropped too, and an outgoing request still carries the trace with flags `00`. That's what lets a downstream service honor the decision you made at the edge.