@zio.dev/zio-blocks 0.0.51 → 0.0.55

package/reference/telemetry/index.md

@@ -0,0 +1,311 @@
+---
+id: index
+title: "Telemetry"
+description: "Module reference index for the telemetry module: tracing, logging, and metrics with a unified provider API."
+keywords:
+  - "Observability"
+  - "Distributed Tracing"
+  - "Structured Logging"
+  - "Application Metrics"
+  - "Trace Correlation"
+---
+
+The telemetry module provides the three pillars of modern observability — distributed tracing, structured logging, and dimensional metrics — with a single coherent API aligned to the OpenTelemetry data model. 
+
+Three global entry points (`trace`, `log`, `metric`) work without any configuration. `trace` and `metric` delegate to an installed provider (`TracerProvider`, `MeterProvider`) that produces scope-specific instances (`Tracer`, `Meter`); `log` holds an installed `Logger` directly, which a `LoggerProvider` is one way to build. 
+
+The same metadata types — `Attributes`, `AttributeKey`, `Resource`, and `InstrumentationScope` — describe signals in all three pillars, and a shared `ContextStorage` enables automatic trace–log correlation out of the box.
+
+The three-pillar structure mirrors the following shape:
+
+```scala
+// Global entry points — work without any setup
+object trace  { /* span creation, provider install */ }
+object log    { /* structured log emission, writer config */ }
+object metric { /* instrument factories, reader access */ }
+
+// Provider layer — configure and install once at application startup
+final class TracerProvider private[telemetry] (...) extends AutoCloseable
+final class LoggerProvider private[telemetry] (...) extends AutoCloseable
+final class MeterProvider  private[telemetry] (...) extends AutoCloseable
+
+// Scope-specific instances — created by providers on demand
+final class Tracer private[telemetry] (...)
+final class Logger private[telemetry] (...)
+final class Meter  private[telemetry] (...)
+```
+
+## Motivation
+
+Modern services produce three distinct kinds of observability data. Traces capture the causal shape of a request as it traverses services and threads. Logs capture structured events at discrete points in time, ideally correlated to the active trace. Metrics capture aggregated numerical measurements — request counts, latencies, queue depths — that accumulate over time. The telemetry module covers all three in one library that pulls in no third-party dependencies and cross-compiles for the JVM and Scala.js.
+
+## Installation
+
+```scala
+// Core: logging, tracing, metrics
+libraryDependencies += "dev.zio" %% "zio-blocks-telemetry" % "0.0.55"
+
+// Optional: OTLP JSON export over HTTP (JVM only)
+libraryDependencies += "dev.zio" %% "zio-blocks-telemetry-otel" % "0.0.55"
+```
+
+For Scala.js (telemetry core only):
+
+```scala
+libraryDependencies += "dev.zio" %%% "zio-blocks-telemetry" % "0.0.55"
+```
+
+Supports Scala 2.13.x and 3.x.
+
+
+## Overview
+
+The module is organized into three areas — tracing, logging, and metrics — that map directly to the OTel signal types, plus the metadata types all three rely on.
+
+### Tracing
+
+[Tracing](./tracing/index.md) covers the full span lifecycle. `TracerProvider` is a factory that shares a `Resource`, a `Sampler`, and a set of `SpanProcessor` hooks across all `Tracer` instances it creates. A `Tracer` opens and closes `Span` scopes, consulting the `Sampler` on each new span and calling `SpanProcessor.onStart` and `SpanProcessor.onEnd` for exporting or in-memory collection. Supporting types — `SpanContext`, `SpanData`, `SpanKind`, `SpanStatus`, `SpanId`, `TraceId`, and `TraceFlags` — capture the identity and state of a span.
+
+### Logging
+
+[Logging](./logging/index.md) covers structured, severity-leveled log emission. `LoggerProvider` is a factory that shares a `Resource` and a set of `LogRecordProcessor` hooks across all `Logger` instances it creates. A `Logger` emits `LogRecord` snapshots through configured processors; processors can write formatted output via a `LogFormatter` and `LogWriter`, export records to an external system, or gate emission by `Severity`. The macro-generated methods on the global `log` object capture source location at compile time and automatically stamp the active span context into every emitted record.
+
+### Metrics
+
+[Metrics](./metrics/index.md) covers dimensional cumulative and instantaneous measurements. `MeterProvider` is a factory for `Meter` instances; each `Meter` creates and registers instruments — `Counter`, `UpDownCounter`, `Histogram`, and `Gauge` — and each instrument keeps one series per `Attributes` set it sees. Instruments themselves are not cached by name; build each once and hold it. A `MetricReader` collects all registered instruments into `MetricData` snapshots on demand for export or inspection.
+
+### Common Types
+
+A span, a log record, and a measurement are different kinds of data, but they answer the same three questions: what happened, which service produced it, and which component inside that service. Four types carry those answers, and because all three pillars use the same four, whatever you learn about them applies everywhere:
+
+- [`Attributes`](./common/attributes.md) — the detail on a signal, as typed key-value pairs: the route on a span, the order id on a log record, the labels on a measurement.
+- [`AttributeKey`](./common/attribute-key.md) — a name paired with the type of its value, so reading an attribute back gives you a `String` or a `Long` rather than something to cast.
+- [`Resource`](./common/resource.md) — which service produced the signal, attached to every one the provider emits. Give all three providers the same one.
+- [`InstrumentationScope`](./common/instrumentation-scope.md) — which library or component produced it, taken from the name you pass to `TracerProvider.get`, `LoggerProvider.get`, or `MeterProvider.get`.
+
+## How They Work Together
+
+All three pillars follow the same structural pattern: a global singleton wraps a provider that acts as a factory for lightweight, scope-specific instances. The provider holds the shared configuration — `Resource`, processor lists, and `ContextStorage` — and creates instances on demand. Signals are enriched by `Attributes` and labeled by `InstrumentationScope`. The `ContextStorage[Option[SpanContext]]` instance that `TracerProvider` and `LoggerProvider` share is what makes trace–log correlation automatic. Give all three providers the *same* `Resource` rather than one each — identical service-identity attributes on every signal are what let a backend line up traces, logs, and metrics as one service.
+
+```
+  Global entry points          Provider layer                 Scope instances
+                             ┌─────────────────────────┐   ┌──────────────────┐
+                             │  TracerProvider         │──▶│  Tracer          │──▶ Span
+  ┌──────────────────────┐   │  · Resource             │   └──────────────────┘    │ SpanProcessor
+  │  trace  (object)     │──▶│  · Sampler              │         ContextStorage ◀╴╴┤
+  └──────────────────────┘   │  · SpanProcessors       │                           │ (shared)
+                             │  · ContextStorage ╶╶╶╶╶╶┼╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╯
+                             └─────────────────────────┘   ┌──────────────────┐
+                             ┌─────────────────────────┐   │  Logger          │
+  ┌──────────────────────┐   │  LoggerProvider         │   │  (traceId+spanId │──▶ LogRecord
+  │  log    (object)     │──▶│  · Resource             │──▶│   from storage)  │    LogRecordProcessor
+  └──────────────────────┘   │  · LogRecordProcessor   │   └──────────────────┘
+                             │  · ContextStorage ╶╶╶╶╶╶┼╶╶╶╶╶╶╶(same instance)
+                             └─────────────────────────┘
+                             ┌─────────────────────────┐   ┌──────────────────┐
+  ┌──────────────────────┐   │  MeterProvider          │   │  Meter           │──▶ Counter
+  │  metric (object)     │──▶│  · Resource             │──▶│  · counterBuilder│    Histogram
+  └──────────────────────┘   │  · MeterRegistry        │   │  · histogramBld. │    Gauge
+                             └─────────────────────────┘   └──────────────────┘    UpDownCounter
+                                                                    │
+                                                              MetricReader ──▶ MetricData
+
+  ──────────────── Shared across all three pillars ─────────────────────────────────
+        Attributes  ·  AttributeKey  ·  Resource  ·  InstrumentationScope
+```
+
+The following sub-sections walk through the data flow for each pillar and explain the correlation mechanism.
+
+### Tracing Data Flow
+
+When application code calls `trace.span("operation")`, the following sequence occurs:
+
+1. The global `trace` object delegates to the active `TracerProvider`, which creates or retrieves a `Tracer` for the `"default"` instrumentation scope.
+2. The `Tracer` consults its `Sampler` via `shouldSample`. If the decision is `RecordAndSample`, a `RecordingSpan` is constructed via `SpanBuilder.startSpan` and `SpanProcessor.onStart` is called; if `Drop`, a `Span.NoOp` is returned — the span records nothing and reaches no processor, though a `SpanContext` is still allocated and scoped so nested spans and log records stay on the same trace.
+3. The active `SpanContext` is stored into `ContextStorage` for the duration of the user block so that nested spans can read it as their parent.
+4. On exit, `Span.end()` is called, `SpanData` is snapshotted, and `SpanProcessor.onEnd` fires — delivering the completed span to exporters or the in-memory test processor.
+
+The following example shows a minimal production tracing configuration:
+
+```scala
+import zio.blocks.telemetry._
+
+val tracerProvider = TracerProvider.builder
+  .setResource(Resource.create(Attributes.of(Attributes.ServiceName, "order-service")))
+  .setSampler(AlwaysOnSampler)
+  .build()
+
+trace.install(tracerProvider)
+
+trace.span("process-order", SpanKind.Server) { span =>
+  span.setAttribute("order.id", "ord-123")
+  span.addEvent("validation-passed")
+}
+```
+
+### Logging Data Flow
+
+When application code calls `log.info("message", ...)`, the macro captures the call site's source file, enclosing class, method name, and line number at compile time. At runtime the severity is compared against the configured minimum; if the call passes the threshold, the captured source-location attributes are written into an `AttributesBuilder`, the current `SpanContext` is read from the shared `ContextStorage`, and `traceIdHi`, `traceIdLo`, `spanId`, and `traceFlags` are stamped into the record as unboxed primitives before being dispatched to all configured processors.
+
+The following example routes log output to standard output in human-readable text format:
+
+```scala
+import zio.blocks.telemetry._
+
+log.writer(TextLogFormatter, StdoutWriter)
+log.info("order placed", "orderId" -> "ord-123", "amount" -> 99L)
+```
+
+### Metrics Data Flow
+
+When a `Counter`, `Histogram`, `Gauge`, or `UpDownCounter` is created via `Meter.counterBuilder("name").build()`, the instrument is registered in the owning `Meter`'s internal instrument list. The `MeterProvider.reader` property returns a `MetricReader` that, on each `collectAllMetrics()` call, iterates every registered `Meter` and invokes `collect()` on each instrument, aggregating the results into a sequence of `MetricData` variants for export or inspection.
+
+The following example records request counts and then reads the aggregated snapshot:
+
+```scala
+import zio.blocks.telemetry._
+
+val requests = metric.counter("http.requests")
+requests.add(1, "method" -> "GET", "status" -> "200")
+
+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))
+}
+```
+
+### Trace–Log Correlation
+
+`TracerProvider` and `LoggerProvider` share the same `ContextStorage[Option[SpanContext]]` instance. When a `Tracer` opens a span it stores the `SpanContext` in that storage; when `Logger` emits a record it reads the same storage and stamps `traceIdHi`, `traceIdLo`, `spanId`, and `traceFlags` into the `LogRecord` fields as primitives — no boxing, no formatting until a `LogFormatter` runs. Because both providers default to the same internal `defaultSpanContextStorage` singleton, correlation is automatic when both are installed with their default settings.
+
+To use an explicit shared `ContextStorage` — for example, to isolate correlation in tests — create one instance and pass it to both builders:
+
+```scala
+import zio.blocks.telemetry._
+
+val sharedStorage = ContextStorage.create[Option[SpanContext]](None)
+
+val tp = TracerProvider.builder.setContextStorage(sharedStorage).build()
+val lp = LoggerProvider.builder.setContextStorage(sharedStorage).build()
+
+trace.install(tp)
+log.install(lp.get("com.example"))
+```
+
+## Common Patterns
+
+The following patterns appear consistently across services that use this module. Each fits into a shared startup and request-handling lifecycle.
+
+### Zero-Setup Global API
+
+All three global entry points work immediately after import: `trace` buffers spans in memory, `log` prints readable text to stdout, and `metric` writes to an in-process `MeterProvider`. The following import is the only requirement for development and testing:
+
+```scala
+import zio.blocks.telemetry._
+
+trace.span("bootstrap") { span =>
+  span.setAttribute("step", "init")
+}
+
+log.writer(TextLogFormatter, StdoutWriter)
+log.info("server started", "port" -> 8080L)
+
+metric.counter("startup.count").add(1)
+```
+
+### Production Provider Installation
+
+At application startup we configure all three providers once and install them before serving any requests. Sharing a common `Resource` propagates the service identity through all signals:
+
+```scala
+import zio.blocks.telemetry._
+
+val serviceResource = Resource.default.merge(
+  Resource.create(Attributes.of(Attributes.ServiceName, "payments"))
+)
+
+val tp = TracerProvider.builder
+  .setResource(serviceResource)
+  .setSampler(ParentBasedSampler(AlwaysOnSampler))
+  .build()
+
+val lp = LoggerProvider.builder.setResource(serviceResource).build()
+val mp = MeterProvider.builder.setResource(serviceResource).build()
+
+trace.install(tp)
+log.install(lp.get("com.example.payments"))
+metric.install(mp)
+```
+
+### Library Dependency-Injection Pattern
+
+Library code should accept `Tracer` and `Logger` as constructor parameters rather than using the global singletons. This makes the library testable in isolation and avoids coupling to global state. The `Logger.info` method on the class itself takes `(String, AttributeValue)` pairs rather than the macro enrichment tuples used by the global `log` object:
+
+```scala
+import zio.blocks.telemetry._
+
+final class OrderService(tracer: Tracer, logger: Logger) {
+  def placeOrder(id: String): Unit =
+    tracer.span("orders.place") { span =>
+      span.setAttribute("order.id", id)
+      logger.info("order placed", "orderId" -> AttributeValue.StringValue(id))
+    }
+}
+```
+
+Application startup code injects instances by calling `trace.get("com.example.orders")` and `loggerProvider.get("com.example.orders")`.
+
+### Scoped Log Annotations
+
+`log.annotated` propagates key-value pairs to every `log.*` call within the block. Annotations are scoped to the enclosing thread and do not leak outside it:
+
+```scala
+import zio.blocks.telemetry._
+
+def handleRequest(requestId: String): Unit =
+  log.annotated("requestId" -> requestId, "env" -> "prod") {
+    log.info("processing started")
+    log.info("processing done")
+  }
+```
+
+### Rate-Limited Logging
+
+The `*Every` family of log methods emits at most once every N invocations per call site. The counter is keyed by the call site's file and line, so sites with the same interval value are normally independent — though the keys index a fixed 4096-slot table, so two sites can collide and share one counter:
+
+```scala
+import zio.blocks.telemetry._
+
+def heartbeat(): Unit =
+  log.infoEvery(100, "heartbeat tick")
+```
+
+### Labeled Instruments
+
+`Meter.labeledCounter`, `Meter.labeledHistogram`, and `Meter.labeledGauge` declare label names once and accept positional string values at recording time, matching the Prometheus-style label pattern:
+
+```scala
+import zio.blocks.telemetry._
+
+val meter    = metric.get("com.example")
+val requests = meter.labeledCounter("http.requests", "method", "status")
+
+requests.add(1, "GET",  "200")
+requests.add(1, "POST", "500")
+```
+
+## Integration Points
+
+Scoped, thread-safe propagation of `SpanContext` through call stacks is handled by the module's own `ContextStorage`, which is backed by JDK `ScopedValue` on the JVM and by a saved-and-restored variable on Scala.js. At the build level the module depends only on the `context` and `chunk` blocks and requires no external libraries.
+
+`SpanProcessor` and `LogRecordProcessor` are open traits. External exporters — for example, an OpenTelemetry SDK bridge — implement these traits to receive span and log data and forward it to collection infrastructure such as OTLP endpoints. Plug a custom `SpanProcessor` into `TracerProvider.builder.addSpanProcessor(...)` or a custom `LogRecordProcessor` into `LoggerProvider.builder.addLogRecordProcessor(...)`.
+
+`LogEnrichment` is a typeclass resolved at compile time by the macro-generated `log.*` methods. Built-in instances cover `Throwable`, `Attributes`, `Severity`, and `(String, A)` pairs for `A ∈ {String, Long, Int, Double, Boolean}`. Adding support for a custom enrichment type requires only a new `implicit val LogEnrichment[MyType]` in scope at the `log.*` call site.
+
+## See Also
+
+- [Telemetry Guide](../../guides/telemetry-guide.md) — architecture, design trade-offs, and real-world usage patterns
+- [Common Types](./common/index.md) — `Attributes`, `AttributeKey`, `Resource`, and `InstrumentationScope` shared across all three pillars
+- [Context](../context.md) — `Context[R]`, which the otel module's `OtelContext` carries an active `SpanContext` through

package/reference/telemetry/logging/index.md

@@ -0,0 +1,197 @@
+---
+id: index
+title: "Logging"
+description: "Logging index: the log entry point, LoggerProvider, Logger, LogRecord, and supporting types for structured logging in the telemetry module."
+keywords:
+  - "Structured Logging"
+  - "Trace Correlation"
+  - "Logging Overview"
+  - "LoggerProvider"
+sidebar_label: "Logging"
+---
+
+Logging records what your application did as it runs, so you can understand its behavior and diagnose problems after the fact. Unlike a plain `println`, these logs are **structured** — each entry carries typed key/value fields (an order id, a duration) you can search and filter on, not just a line of text — and **severity-leveled**, tagged `trace`, `debug`, `info`, `warn`, `error`, or `fatal` so you can keep production quiet and turn up detail only when debugging. Each log is also tied back to the trace that produced it, so from one log line you can pull up the whole request it belongs to. 
+
+You write logs through the `log` object: call `log.info("order placed")` (or `debug`, `warn`, `error`, …) anywhere in your code and it works immediately, with no setup. Behind each call, `log` automatically records where the log came from — the file, class, method, and line — and stamps it with the trace and span of whatever [`trace.span`](../tracing/index.md) you happen to be inside. That stamping is what lets logs and traces line up later: no need to thread a request id through your code by hand.
+
+Out of the box those records print to stdout as readable text, so `log.info(...)` shows up on your console with nothing configured. When you want a different destination you add one once, at application startup: `log.writer(...)` adds a channel with a formatter of your choosing — JSON, say — through a [`LogWriter`](./log-writer.md), while `log.addProcessor(...)` wires up a pipeline that ships records to a backend for storage and search. Those two are additive, so the default console output stays alongside whatever you add. `log.install(...)` is the replacing move: it swaps in a whole logger, dropping the default console processor, any writers added earlier, and any per-package severity overrides.
+
+After the message you attach context, and this is where structured logging pays off. The common case is key/value pairs — `log.info("order placed", "orderId" -> "ord-123", "amount" -> 99L)` — which become searchable fields on that entry instead of being buried in the text, so later you can query "all logs where `orderId = ord-123`". Pass a `Throwable` and its type, message, and stack trace are captured for you.
+
+A few other values mean something specific rather than becoming a field: a [`Severity`](./severity.md) overrides the entry's level, an [`Attributes`](../common/attributes.md) set adds many fields at once, and a plain `String` replaces the message body. And when you want to log one of your own types directly, give it a [`LogEnrichment`](./log-enrichment.md) instance that tells `log` how to turn it into fields.
+
+
+## Example Usage
+
+Logging's core job is to **emit structured, correlated logs**. Point `log` at a writer once, then emit records inside your spans; each record carries its typed key-value context and the active trace and span IDs automatically.
+
+```scala
+import zio.blocks.telemetry._
+
+trace.install(TracerProvider.builder.build())
+log.writer(TextLogFormatter, StdoutWriter)
+
+trace.span("checkout") { _ =>
+  log.info("order placed", "orderId" -> "ord-123", "amount" -> 99L)
+  log.warn("inventory low", "sku" -> "sku-42", "remaining" -> 3L)
+}
+```
+
+## Emit Structured, Severity-Leveled Records
+
+Six severities — `trace`, `debug`, `info`, `warn`, `error`, `fatal` — cover the whole scale.
+
+```scala
+object log {
+  def trace(message: String, enrichments: Any*): Unit
+  def debug(message: String, enrichments: Any*): Unit
+  def info(message: String, enrichments: Any*): Unit
+  def warn(message: String, enrichments: Any*): Unit
+  def error(message: String, enrichments: Any*): Unit
+  def fatal(message: String, enrichments: Any*): Unit
+}
+```
+
+Pass typed key/value pairs for structured attributes, a `Throwable` to capture an exception, or an `Attributes` set to merge many values at once.
+
+```scala
+import zio.blocks.telemetry._
+
+log.info("order placed", "orderId" -> "ord-123", "amount" -> 99L, "express" -> true)
+log.debug("cache lookup", "hit" -> false)
+
+try throw new RuntimeException("payment declined")
+catch { case e: Throwable => log.error("charge failed", "orderId" -> "ord-123", e) }
+```
+
+## Limit Log Volume at Hot Call Sites
+
+Two rate-limiting families, each spanning all six severities, keep high-frequency sites quiet.
+
+```scala
+object log {
+  def <level>Every(every: Int, message: String, enrichments: Any*): Unit
+  def <level>AtMost(intervalMillis: Long, message: String, enrichments: Any*): Unit
+}
+```
+
+The `Every` family is count-based — `<level>Every(every, message, enrichments*)` emits on every Nth call at that site. The `AtMost` family is time-based — `<level>AtMost(intervalMillis, message, enrichments*)` emits at most once per interval at that site. Each site gets its own counter and clock, keyed by its file and line into a fixed table of 4096 slots; two distant sites can land in the same slot, in which case they share a counter and one of them logs less often than its `every` suggests.
+
+```scala
+import zio.blocks.telemetry._
+
+// Count-based: one line for every 100th retry
+log.warnEvery(100, "retrying upstream call", "endpoint" -> "/inventory")
+
+// Time-based: at most one line per 5 seconds, whatever the call rate
+log.infoAtMost(5000L, "processing batch", "size" -> 512L)
+log.errorAtMost(1000L, "connection pool exhausted")
+```
+
+## Attach Scoped Annotations
+
+Attach key/value pairs to every record emitted inside a block with `annotated`.
+
+```scala
+object log {
+  def annotated[A](annotations: (String, String)*)(f: => A): A
+}
+```
+
+The pairs reach every record from the block, including calls in nested methods, without threading them through each `log.*` call.
+
+```scala
+import zio.blocks.telemetry._
+
+log.annotated("requestId" -> "req-42", "tenant" -> "acme") {
+  log.info("started")   // both annotations attached
+  log.info("finished")  // both annotations attached
+}
+```
+
+## Correlate Logs with the Active Span
+
+When a `log.*` call runs inside a `trace.span`, the record is stamped with the enclosing span's trace and span IDs automatically, because logging and tracing share the same `ContextStorage`. No extra wiring is required.
+
+```scala
+import zio.blocks.telemetry._
+
+trace.span("checkout") { _ =>
+  log.info("order validated", "orderId" -> "ord-123") // carries the checkout span's IDs
+}
+```
+
+## Filter by Severity
+
+Every log carries a `Severity`, and a **minimum-severity floor** decides which ones actually get recorded: anything below the floor is dropped — cheaply, before the record is even built. The floor starts at `Trace`, so everything passes until you raise it. You use this to control noise: run production at `Info` (dropping the `trace`/`debug` chatter) and turn detail back up only where and when you need it.
+
+```scala
+object log {
+  def setMinSeverity(severity: Severity): Unit
+  def setMinSeverity(prefix: String, severity: Severity): Unit
+  def clearMinSeverity(prefix: String): Unit
+  def clearAllOverrides(): Unit
+  def withMinSeverity[A](severity: Severity)(f: => A): A
+}
+```
+
+`setMinSeverity(severity)` sets one floor for the whole application. `setMinSeverity(prefix, severity)` overrides it for a package — matched against the call site's namespace — and works both ways: raise the floor on a chatty dependency to quiet it, or lower it on the package you're debugging to see more, without touching the rest of the app. `clearMinSeverity(prefix)` removes one override and `clearAllOverrides()` removes them all, back to the global floor. Set the global floor first: `setMinSeverity(severity)` also discards every prefix override, so calling it after the overrides silently wipes them.
+
+When several prefixes match a call site, the longest one wins — so `"com.example"` at `Warn` plus `"com.example.orders"` at `Debug` gives you debug logs from the orders package and warnings from everything else under `com.example`. Matching is a plain string prefix on the enclosing class name, not a package-boundary check, so `"com.acme"` also matches `com.acmecorp`.
+
+```scala
+import zio.blocks.telemetry._
+
+log.setMinSeverity(Severity.Info)                       // drop trace/debug globally
+log.setMinSeverity("com.acme.noisy", Severity.Warn)     // quiet a chatty dependency
+log.setMinSeverity("com.example.orders", Severity.Debug) // more detail where you're debugging
+```
+
+These floors stay in effect until you change them. When you only need extra detail around a specific operation, `withMinSeverity(severity) { … }` lowers the floor for just that block and restores it afterward — no cleanup needed.
+
+```scala
+import zio.blocks.telemetry._
+
+log.withMinSeverity(Severity.Trace) {
+  log.trace("visible only inside this block")
+}
+```
+
+## Route Output
+
+A record isn't useful until it leaves the process. Routing decides two things: how each record becomes text — a [`LogFormatter`](./log-formatter.md), plain lines or JSON — and where those bytes go — a `LogWriter`, such as stdout, stderr, or a file. There are two ways to wire this up: a simple console writer for local development, or a processor pipeline for production.
+
+```scala
+object log {
+  def writer(formatter: LogFormatter, logWriter: LogWriter): Unit
+  def clearWriters(): Unit
+  def install(logger: Logger, minSeverity: Severity = Severity.Trace): Unit
+  def addProcessor(processor: LogRecordProcessor): Unit
+  def removeAll(): Unit
+}
+```
+
+`log.writer(formatter, writer)` is the simple path: pair a formatter with a writer to add one console sink. It's additive — call it again to send the same records to a second destination (say, human-readable text to stdout and JSON to stderr) — and `log.clearWriters()` removes them all.
+
+For production you usually want a pipeline that batches records and ships them to a backend for storage and search. `log.install(logger)` swaps in a fully configured [`Logger`](./logger.md) (built from a `LoggerProvider` with its export processors) in place of whatever was registered before — including the default console output, any writers, and any prefix overrides — `log.addProcessor(processor)` appends a single [`LogRecordProcessor`](./log-record-processor.md) to the current backend without disturbing the rest, and `log.removeAll()` detaches everything — `log.*` calls become no-ops until you add an output again.
+
+```scala
+import zio.blocks.telemetry._
+
+// Human-readable text to stdout, JSON to stderr
+log.writer(TextLogFormatter, StdoutWriter)
+log.writer(JsonLogFormatter, StderrWriter)
+
+// Or install a processor-based backend
+val logger = LoggerProvider.builder
+  .addLogRecordProcessor(new ConsoleLogRecordProcessor)
+  .build()
+  .get("com.example")
+log.install(logger, Severity.Info)
+```
+
+## See Also
+
+- [Telemetry Guide](../../../guides/telemetry-guide.md) — logging data flow, rate limiting, 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/logging/log-enrichment.md

@@ -0,0 +1,72 @@
+---
+id: log-enrichment
+title: "LogEnrichment"
+description: "Typeclass that lets a log.* call accept a domain value directly"
+keywords:
+  - "Structured Logging"
+  - "Log Enrichment"
+  - "Compile-Time Typeclass"
+  - "LogEnrichment"
+sidebar_label: "LogEnrichment"
+---
+
+`LogEnrichment[A]` is what lets you pass a value of your own type straight into a [`log`](./index.md) call and have it become part of the [`LogRecord`](./log-record.md). When the macro behind `log.info("msg", value)` meets an argument whose type it does not handle natively, it looks for an implicit `LogEnrichment[A]`, calls `enrich` to fold the value into the record, and fails to compile if none is in scope. You rarely name the typeclass directly — the built-in instances below cover the everyday types — you define one only to log a domain value without unpacking it by hand at every call site.
+
+```scala
+trait LogEnrichment[A] {
+  def enrich(record: LogRecord, value: A): LogRecord
+}
+```
+
+`enrich` takes the record built so far and returns a copy with the value folded in — adding attributes, replacing the body, or setting the severity, depending on `A`.
+
+## Built-in Instances
+
+| Type                                                                                               | Effect on the record                                                                                         |
+|----------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------|
+| `String`                                                                                           | Replaces the message body.                                                                                   |
+| `Throwable`                                                                                        | Adds `exception.type` and `exception.message` attributes and stores the throwable for stack-trace rendering. |
+| `Attributes`                                                                                       | Merges the whole set into the record's attributes.                                                           |
+| `Severity`                                                                                         | Overrides the recorded severity — but not the one used for filtering (see below).                            |
+| `(String, String)` / `(String, Long)` / `(String, Int)` / `(String, Double)` / `(String, Boolean)` | Adds one typed key-value attribute (`Int` is widened to `Long`).                                             |
+
+These common types are also recognized directly by the `log.*` macro, so passing them costs nothing at runtime:
+
+```scala
+import zio.blocks.telemetry._
+
+val ex: Throwable = new RuntimeException("connection refused")
+
+log.error(
+  "payment failed",
+  ex,                        // Throwable — attaches type, message, stack trace
+  "orderId"   -> "ord-123",  // (String, String)
+  "amount"    -> 99L,        // (String, Long)
+  "retryable" -> false       // (String, Boolean)
+)
+```
+
+Passing a `Severity` is the one case that behaves unexpectedly. It changes the severity written into the record, but filtering already happened using the severity of the method you called — so `log.warn("slow query", Severity.Debug)` is recorded as DEBUG even under an `Info` floor, and `log.info("charge failed", Severity.Error)` is dropped by a `Warn` floor despite arriving as an error. Call the method matching the level you want filtered on.
+
+Types outside the table are rejected at compile time, which is what a missing `LogEnrichment` error means. `Float`, `Short`, `Byte`, `Char`, `UUID`, and `Instant` are the ones people hit first: convert them at the call site (`.toDouble`, `.toLong`, `.toString`) or give the type an instance of its own.
+
+## Custom Instances
+
+Define a `LogEnrichment[MyType]` in implicit scope to accept your own type at a `log.*` call. The macro resolves it at that call site and threads the record through your `enrich`:
+
+```scala
+import zio.blocks.telemetry._
+
+final case class RequestId(value: String)
+
+implicit val requestIdEnrichment: LogEnrichment[RequestId] = new LogEnrichment[RequestId] {
+  def enrich(record: LogRecord, value: RequestId): LogRecord =
+    record.copy(attributes = record.attributes ++ Attributes.of(AttributeKey.string("request.id"), value.value))
+}
+
+log.info("handling request", RequestId("req-001")) // adds request.id="req-001"
+```
+
+## Integration
+
+Resolution happens entirely at compile time, so there is no runtime cost for type dispatch. An argument whose type has neither native macro handling nor an implicit `LogEnrichment[A]` is a compile error, which keeps unloggable values out of the call. A custom instance must be in implicit scope wherever the `log.*` call appears.