@zio.dev/zio-blocks 0.0.51 → 0.0.55

package/reference/telemetry/logging/log-formatter.md

@@ -0,0 +1,100 @@
+---
+id: log-formatter
+title: "LogFormatter"
+description: "How a LogRecord is rendered to text: the built-in human-readable and OTLP-JSON formatters behind log.writer."
+keywords:
+  - "Structured Logging"
+  - "Log Formatting"
+  - "Text and JSON Output"
+  - "LogFormatter"
+sidebar_label: "LogFormatter"
+---
+
+`LogFormatter` renders a [`LogRecord`](./log-record.md) into text; its partner, the [`LogWriter`](./log-writer.md), routes that text to a destination. You rarely name a formatter directly — you hand a formatter/writer pair to [`log.writer`](./index.md), and the two built-ins below cover the common cases. Implement the trait yourself when your pipeline expects a shape neither produces.
+
+## Built-in Formatters
+
+Two singletons cover the usual output formats — both safe to share across threads, with `TextLogFormatter` caching its timestamp prefix for the current second:
+
+| Formatter          | Output                                                                                                                                       |
+|--------------------|----------------------------------------------------------------------------------------------------------------------------------------------|
+| `TextLogFormatter` | Human-readable — `2026-07-29T10:00:00.000Z INFO  [Svc.doWork:42] message {key=val}`                                                          |
+| `JsonLogFormatter` | OTLP-compatible JSON — `{"timeUnixNano":"...","severityNumber":9,"severityText":"INFO","body":{"stringValue":"message"},"attributes":[...]}` |
+
+Both render the record's timestamp, severity, source location (from the `code.*` attributes), message body, and an attached throwable's stack trace. They differ in what else they carry: `TextLogFormatter` prints the remaining attributes as a compact `{key=value}` list and drops the trace and span IDs, while `JsonLogFormatter` emits every attribute — including the four `code.*` entries — plus `traceId` and `spanId` when the record was written inside a span.
+
+## Example Usage
+
+Choosing a formatter is choosing who reads your logs. In development that's you, so pick `TextLogFormatter` — one aligned line per record, easy to scan in a terminal. In production it's a log collector, so pick `JsonLogFormatter` — every attribute stays a separate field the collector can index and query. Select it once at startup, alongside a [`LogWriter`](./log-writer.md) for the destination:
+
+```scala
+import zio.blocks.telemetry._
+
+val isDevelopment = sys.env.get("ENV").forall(_ != "production")
+
+if (isDevelopment) log.writer(TextLogFormatter, StdoutWriter)  // readable in a terminal
+else log.writer(JsonLogFormatter, StdoutWriter)                // queryable by a collector
+
+log.info("server ready", "port" -> 8080L)
+```
+
+You can also register both — `log.writer` is additive, so each call adds another channel and every record goes to all of them. That's how you keep readable console output while also emitting machine-readable JSON:
+
+```scala
+import zio.blocks.telemetry._
+
+log.writer(TextLogFormatter, StdoutWriter)  // for the developer watching the terminal
+log.writer(JsonLogFormatter, StderrWriter)  // for the collector tailing stderr
+
+log.info("server ready", "port" -> 8080L)   // written to both channels
+```
+
+## Custom Formatter
+
+Sometimes neither built-in shape fits — an existing ingest pipeline expects logfmt, or a report wants CSV. Implement the trait yourself and pass your formatter to `log.writer` like any built-in. Two methods are abstract, but only one of them is yours to write:
+
+```scala
+trait LogFormatter {
+  def format(
+    sb: StringBuilder, timestampNanos: Long, severity: Severity, severityText: String,
+    body: String, builder: Attributes.AttributesBuilder,
+    traceIdHi: Long, traceIdLo: Long, spanId: Long, traceFlags: Byte,
+    throwable: Option[Throwable]
+  ): Unit
+
+  def formatRecord(sb: StringBuilder, record: LogRecord): Unit
+}
+```
+
+`formatRecord` is the one that runs: a channel registered with `log.writer` renders each finished [`LogRecord`](./log-record.md) through it. Put your format there.
+
+`format` serves a lower-allocation path that skips building a `LogRecord`, and the library uses it only for its own default console output — no formatter you register ever reaches it. You still have to define it to satisfy the trait, so mirror the scalar fields and move on; it cannot render attributes anyway, since the accessors for reading them off the builder are internal.
+
+Both methods receive a fresh, empty `StringBuilder` from the caller, which writes it out and discards it. Append your output and return — the caller handles writing.
+
+A CSV formatter — three comma-separated fields in `formatRecord`, with `format` mirroring them:
+
+```scala
+import zio.blocks.telemetry._
+
+object CsvFormatter extends LogFormatter {
+  def formatRecord(sb: StringBuilder, record: LogRecord): Unit =
+    sb.append(record.timestampNanos).append(',').append(record.severityText).append(',').append(record.body.value)
+
+  def format(
+    sb: StringBuilder, timestampNanos: Long, severity: Severity, severityText: String,
+    body: String, builder: Attributes.AttributesBuilder,
+    traceIdHi: Long, traceIdLo: Long, spanId: Long, traceFlags: Byte,
+    throwable: Option[Throwable]
+  ): Unit = sb.append(timestampNanos).append(',').append(severityText).append(',').append(body)
+}
+
+log.writer(CsvFormatter, StdoutWriter)
+log.info("order placed")
+// 2026-07-31T13:23:25.137Z INFO  [Main$.main:20] order placed  <- default console output
+// 1785504205137002324,INFO,order placed                        <- your channel
+```
+
+Two lines, because `log.writer` adds a channel rather than replacing one, and the default console output is still registered.
+
+To render attributes too, pass an `AttributeVisitor` to `record.attributes.accept` — it fires once per attribute with the raw unboxed value, so nothing is boxed on the way out. Only the four scalar methods are abstract; the seq variants default to no-ops. Source location arrives among those attributes as `code.filepath`, `code.namespace`, `code.function`, and `code.lineno`. Decide which convention you want: `TextLogFormatter` lifts them into its `[Svc.doWork:42]` prefix and then skips those keys, while `JsonLogFormatter` emits them as ordinary attributes. Skip any key starting with `code.` if you render the location separately.

package/reference/telemetry/logging/log-record-processor.md

@@ -0,0 +1,56 @@
+---
+id: log-record-processor
+title: "LogRecordProcessor"
+description: "A destination for log records — each registered processor receives every log your application emits, to print, export, or discard."
+keywords:
+  - "Structured Logging"
+  - "Log Export"
+  - "Log Destinations"
+  - "LogRecordProcessor"
+sidebar_label: "LogRecordProcessor"
+---
+
+A `LogRecordProcessor` is a destination for your logs. Every time you call `log.info(...)`, the finished [`LogRecord`](./log-record.md) is handed to each registered processor, and what happens next is entirely up to that processor: print it, ship it to a backend, forward it into another logging library, or drop it.
+
+The type exists because where logs belong depends on your deployment, which the library can't know. Registering destinations is how you tell it — and you can register several, each receiving the same record, which is how logs reach your console and a remote backend at once.
+
+Most applications never implement one, because the module ships the common destinations. `ConsoleLogRecordProcessor` prints readable text to stdout — the default, and also the fastest path: when it's the only processor registered, the `Logger` skips building a `LogRecord` and formats straight from the raw values. `LogRecordProcessor.noop` accepts every record and discards it, for tests or as a placeholder. And for formatted output — JSON, a file, your own shape — [`log.writer(formatter, writer)`](./index.md) builds a processor for you out of a [`LogFormatter`](./log-formatter.md) and a [`LogWriter`](./log-writer.md), which is less code than implementing this trait.
+
+Write your own to reach somewhere the module doesn't cover — an OTLP collector, a vendor's API, or an existing logging framework you're migrating from.
+
+```scala
+trait LogRecordProcessor extends AutoCloseable {
+  def onEmit(logRecord: LogRecord): Unit   // fires for every record the Logger lets through
+  def shutdown(): Unit                     // flush and release; called by LoggerProvider.shutdown()
+  def forceFlush(): Unit                   // flush buffered records now
+  override def close(): Unit = shutdown()
+
+  def minimumLevel: Int = 1                // lowest Severity.number accepted; default accepts all
+}
+
+object LogRecordProcessor {
+  val noop: LogRecordProcessor  // ignores every record
+}
+```
+
+`onEmit` is the method that matters — it runs once per log, **on the thread that logged**, before your code continues. So keep it quick. If you send each record over the network from inside `onEmit`, every `log.info` in your application waits for that round trip; buffer records instead and ship them in batches from a background thread, then flush what's left when `shutdown` or `forceFlush` is called.
+
+`minimumLevel` lets a processor say "only send me warnings and worse" as a `Severity` number. It's a volume hint, not a filter applied per processor: the `Logger` takes the lowest `minimumLevel` across every registered processor and, for anything below it, doesn't even build a `LogRecord` — so a debug line no destination wants costs almost nothing. Anything above that shared floor is delivered to every processor, including ones whose own `minimumLevel` is higher, so a processor that must not see debug records has to re-check `record.severity` in `onEmit`.
+
+Your own processor implements those three methods — with nothing buffered, `shutdown` and `forceFlush` can stay empty — and registers on the global [`log`](./index.md):
+
+```scala
+import zio.blocks.telemetry._
+
+val exporter = new LogRecordProcessor {
+  def onEmit(r: LogRecord): Unit = println(s"[EXPORT] ${r.severity.text} ${r.body.value}")
+  def shutdown(): Unit           = ()
+  def forceFlush(): Unit         = ()
+}
+
+log.addProcessor(exporter)
+log.info("checkout complete")
+```
+
+`log.addProcessor` is the easiest route: your processor joins the destinations already registered, with nothing to rebuild — when you build a provider yourself, pass processors to `LoggerProvider.builder.addLogRecordProcessor(...)` instead. Either way, an exception your processor throws is caught and printed to stderr, and the remaining processors still receive the record, so one broken destination can't take down your logging.
+

package/reference/telemetry/logging/log-record.md

@@ -0,0 +1,44 @@
+---
+id: log-record
+title: "LogRecord"
+description: "Immutable snapshot of a single log emission — the read-only value a LogRecordProcessor receives and a LogFormatter renders."
+keywords:
+  - "Structured Logging"
+  - "Trace Correlation"
+  - "Immutable Log Snapshot"
+  - "LogRecord"
+sidebar_label: "LogRecord"
+---
+
+A `LogRecord` is one log entry as a value — everything a single `log.info(...)` call captured, bundled together: the message, its severity, when it happened, the key/value fields attached to it, and which request it belongs to.
+
+The type exists because a log entry has to travel. From the call site it may go to your console, to a file, and to a backend that indexes it, and each of those destinations needs the whole story in one self-contained package — a bare string wouldn't carry the severity or the trace it came from. Because a record is immutable, every destination can read the same one safely.
+
+You never build a `LogRecord` in normal use; the global [`log`](./index.md) (or a [`Logger`](./logger.md)) builds one for you on every call. You meet it when you extend the pipeline: it's the value handed to a [`LogRecordProcessor`](./log-record-processor.md)'s `onEmit` and to a [`LogFormatter`](./log-formatter.md), so writing either means reading fields off a record.
+
+```scala
+final case class LogRecord(
+  timestampNanos:         Long,
+  observedTimestampNanos: Long,
+  severity:               Severity,
+  severityText:           String,
+  body:                   LogMessage,           // LogMessage.Simple(text), or a lazy template
+  attributes:             Attributes,           // code.* source location + caller-supplied attrs
+  traceIdHi:              Long,                 // 0L when no span is active
+  traceIdLo:              Long,                 // 0L when no span is active
+  spanId:                 Long,                 // 0L when no span is active
+  traceFlags:             Byte,                 // 0x00 when not sampled
+  resource:               Resource,
+  instrumentationScope:   InstrumentationScope,
+  throwable:              Option[Throwable] = None
+) {
+  def hasTraceId: Boolean  // traceIdHi != 0L || traceIdLo != 0L
+  def hasSpanId:  Boolean  // spanId != 0L
+}
+
+object LogRecord {
+  def builder: LogRecordBuilder
+}
+```
+
+Each field mirrors what the emission recorded. The source location the macro captured arrives inside `attributes`, as the `code.filepath`, `code.namespace`, `code.function`, and `code.lineno` keys. The trace and span IDs are what tie this entry back to the request that produced it: they're filled in when the call ran inside an active span, and left as `0` when it didn't — so check `hasTraceId`/`hasSpanId` rather than comparing to zero yourself.

package/reference/telemetry/logging/log-writer.md

@@ -0,0 +1,64 @@
+---
+id: log-writer
+title: "LogWriter"
+description: "The sink that routes formatted log text to a destination: the built-in stdout, stderr, and no-op writers behind log.writer."
+keywords:
+  - "Structured Logging"
+  - "Log Output"
+  - "Output Sink"
+  - "LogWriter"
+sidebar_label: "LogWriter"
+---
+
+`LogWriter` is the sink half of console log output: it takes text that has already been formatted and pushes it to a destination — stdout, stderr, a file. Its partner is the [`LogFormatter`](./log-formatter.md), which turns a [`LogRecord`](./log-record.md) into that text. You rarely name a writer directly — you hand a formatter/writer pair to [`log.writer`](./index.md), and the built-ins below cover the usual destinations. Reach for a custom one only to send output somewhere the built-ins don't.
+
+```scala
+trait LogWriter {
+  def write(content: CharSequence): Unit
+  def flush(): Unit = ()
+  def close(): Unit = ()
+}
+```
+
+`write` receives one fully-formatted line; `flush` and `close` default to no-ops, so a simple writer overrides only `write`.
+
+## Built-in Writers
+
+Three singletons cover the common destinations:
+
+| Writer | Destination |
+|--------|-------------|
+| `StdoutWriter` | `System.out` |
+| `StderrWriter` | `System.err` |
+| `NoopWriter` | Discards output — for benchmarking the formatting path |
+
+## Example Usage
+
+Pair a writer with a formatter and hand both to `log.writer`. It is additive — each call adds another channel, and every record is sent to all of them:
+
+```scala
+import zio.blocks.telemetry._
+
+log.writer(TextLogFormatter, StdoutWriter)  // human-readable text to stdout
+log.writer(JsonLogFormatter, StderrWriter)  // OTLP JSON to stderr
+
+log.info("server ready", "port" -> 8080L)   // written to both channels
+```
+
+## Custom Writer
+
+Implement the trait to send formatted output somewhere the built-ins don't — a file, say. Override `write`, plus `flush`/`close` if the destination holds resources:
+
+```scala
+import zio.blocks.telemetry._
+import java.io.PrintWriter
+
+val fileWriter = new LogWriter {
+  private val out = new PrintWriter("app.log")
+  def write(content: CharSequence): Unit = out.println(content)
+  override def flush(): Unit             = out.flush()
+  override def close(): Unit             = out.close()
+}
+
+log.writer(TextLogFormatter, fileWriter)
+```

package/reference/telemetry/logging/logger-provider.md

@@ -0,0 +1,142 @@
+---
+id: logger-provider
+title: "LoggerProvider"
+description: "Root factory for structured logging: produces Logger instances sharing a Resource, LogRecordProcessor pipeline, and ContextStorage."
+keywords:
+  - "Structured Logging"
+  - "Logging Configuration"
+  - "Logger Factory"
+  - "LoggerProvider"
+---
+
+A `LoggerProvider` is what makes [`Logger`](./logger.md)s. You build one at startup, and it hands out every logger your application uses.
+
+It exists so that two questions get answered once instead of at every call site: *who is logging* — your service's identity, a [`Resource`](../common/resource.md) — and *where the logs go* — the [`LogRecordProcessor`](./log-record-processor.md)s that render or ship each record. Every logger the provider creates inherits both, so pointing your whole application at a different destination is a one-line change at startup rather than an edit everywhere you log.
+
+Most applications never hold a provider directly: build one, hand a logger from it to `log.install(...)`, and use the global [`log`](./index.md) from then on. Reach for the provider itself when you need that startup configuration under your own control.
+
+```scala
+final class LoggerProvider private[telemetry] (...) extends AutoCloseable {
+  def get(name: String, version: String = ""): Logger  // a Logger for a named scope
+
+  def shutdown(): Unit        // shut down every processor; call once at exit
+  override def close(): Unit  // alias for shutdown() — satisfies AutoCloseable
+}
+
+object LoggerProvider {
+  def builder: LoggerProviderBuilder
+}
+
+final class LoggerProviderBuilder private[telemetry] (...) {
+  def setResource(resource: Resource): LoggerProviderBuilder
+  def addLogRecordProcessor(processor: LogRecordProcessor): LoggerProviderBuilder
+  def setContextStorage(contextStorage: ContextStorage[Option[SpanContext]]): LoggerProviderBuilder
+  def build(): LoggerProvider
+}
+```
+
+## Usage
+
+Build a provider once at startup, set only what you need — a `Resource` for your service identity and the `LogRecordProcessor`s that handle your records — then `get` a `Logger` from it. Anything left unset takes a sensible default (`Resource.default`, and an empty pipeline until you add a processor):
+
+```scala
+import zio.blocks.telemetry._
+
+val provider = LoggerProvider.builder
+  .setResource(Resource.create(Attributes.of(Attributes.ServiceName, "payments")))
+  .addLogRecordProcessor(LogRecordProcessor.noop) // replace with a console writer or OTLP exporter
+  .build()
+
+val logger = provider.get("com.example.payments")
+logger.info("order placed", "orderId" -> AttributeValue.StringValue("ord-001"))
+
+provider.shutdown()
+```
+
+Note that `get` builds a logger rather than looking one up: call it twice with the same name and you get two separate `Logger` objects that behave identically. So call it once where a component is created and keep the result in a `val`, not inside a request handler that runs thousands of times a second — per-request calls produce the same log output, they just make throwaway objects for the garbage collector:
+
+```scala
+import zio.blocks.telemetry._
+
+class PaymentService(provider: LoggerProvider) {
+  private val logger = provider.get("com.example.payments")   // once, at construction
+
+  def handle(orderId: String): Unit =
+    logger.info("handling payment", "orderId" -> AttributeValue.StringValue(orderId))
+}
+```
+
+The name you pass is what identifies where a log came from, so one logger per component — a service, a module — is the usual granularity.
+
+Passing a `Logger` down through every constructor gets tedious, though. Register one on the global [`log`](./index.md) at startup instead, and the rest of your code can log without knowing a provider exists:
+
+```scala
+import zio.blocks.telemetry._
+
+val provider = LoggerProvider.builder
+  .setResource(Resource.create(Attributes.of(Attributes.ServiceName, "catalog")))
+  .addLogRecordProcessor(LogRecordProcessor.noop)
+  .build()
+
+log.install(provider.get("com.example.catalog"))
+
+log.info("server started")
+```
+
+## Lifecycle
+
+Logs don't always leave your process the moment you write them. A processor that ships records to a backend usually batches them, so at any instant the most recent logs may still be sitting in a buffer — and if the process exits right then, they're gone. Those are exactly the logs you want when something went wrong at shutdown.
+
+`provider.shutdown()` prevents that. It walks the registered processors in the order you added them and shuts each one down, which is a processor's cue to flush whatever it's holding and release what it owns — a file handle, a network connection. Call it once, on the way out:
+
+```scala
+import zio.blocks.telemetry._
+
+val provider = LoggerProvider.builder
+  .addLogRecordProcessor(LogRecordProcessor.noop)
+  .build()
+
+try log.install(provider.get("com.example"))
+finally provider.shutdown()   // last logs flushed, resources released
+```
+
+That `finally` is the easy part to forget. So a provider implements `AutoCloseable` — the standard interface for "something that must be closed when you're done with it," the same one files and sockets use — with `close()` simply calling `shutdown()`. That lets you hand the cleanup to the language rather than writing it yourself. In Scala, `scala.util.Using.resource` does the calling:
+
+```scala
+import zio.blocks.telemetry._
+import scala.util.Using
+
+Using.resource(LoggerProvider.builder.addLogRecordProcessor(LogRecordProcessor.noop).build()) { provider =>
+  log.install(provider.get("com.example"))
+  log.info("server started")
+}   // close() — and so shutdown() — runs here, even if the block throws
+```
+
+The block marks how long the provider lives, and cleanup happens on the way out whether the code finishes normally or raises an exception. From Java the same interface makes a provider usable in try-with-resources.
+
+## Trace–Log Correlation
+
+This is the part you get for free. Write a log inside a span and it carries that span's trace and span IDs — no request id to thread through your functions, no logger to pass around, nothing to configure. A `LoggerProvider` and a [`TracerProvider`](../tracing/tracer-provider.md) read the same ambient context by default, so each is aware of the span the other opened:
+
+```scala
+import zio.blocks.telemetry._
+
+trace.install(TracerProvider.builder.build())
+log.install(
+  LoggerProvider.builder
+    .addLogRecordProcessor(new ConsoleLogRecordProcessor)  // a provider with no processor emits nothing
+    .build()
+    .get("com.example")
+)
+
+trace.span("checkout") { _ =>
+  log.info("order validated", "orderId" -> "ord-123")  // stamped with the checkout span's IDs
+  log.warn("inventory low", "sku" -> "sku-42")         // same trace, same span
+}
+```
+
+That stamping is what makes a log backend useful: filter on one trace id and you have every log line from that single request, in order, across every component that touched it — and from any one of those lines you can open the trace it belongs to.
+
+If you ever need to control that shared context yourself — isolating correlation between test cases, or fitting a custom runtime — pass one `ContextStorage` to `setContextStorage` on both providers.
+
+For the full picture of how `LoggerProvider`, `TracerProvider`, and `MeterProvider` interconnect, see the [Telemetry module index](../index.md).

package/reference/telemetry/logging/logger.md

@@ -0,0 +1,83 @@
+---
+id: logger
+title: "Logger"
+description: "Instance-level structured logger bound to one instrumentation scope; library code takes one, application code prefers the global log."
+keywords:
+  - "Structured Logging"
+  - "Trace Correlation"
+  - "Log Emission"
+  - "Logger"
+---
+
+A `Logger` writes logs. It's tied to one name — the component or library it belongs to, like `"com.example.OrderService"` — and a [`LoggerProvider`](./logger-provider.md) hands you one; you never construct it yourself.
+
+That name travels with every record, marking which part of the system produced it. It's what lets you tell your own logs from a library's and turn one noisy component down without touching the rest. Records also arrive tied to the trace they happened in, so any line leads back to the request that caused it.
+
+Most application code shouldn't use a `Logger` directly — the global [`log`](./index.md) is easier and does more. A `Logger` earns its place when a library accepts one as a parameter: then it's an ordinary dependency, and a test can pass in one whose records it inspects.
+
+```scala
+final class Logger {
+  // One method per severity: trace, debug, info, warn, error, fatal
+  def info(body: String, attrs: (String, AttributeValue)*): Unit
+  // def trace/debug/warn/error/fatal are identical, just with different severity
+
+  def emit(logRecord: LogRecord): Unit           // send a pre-built record
+  def currentSpanContext(): Option[SpanContext]  // active span, or None
+}
+```
+
+## Emitting a Log
+
+This is what a `Logger` is for. Pick the method matching the severity, pass a message, and add any attributes worth searching on later — the scope name and the active span's identity are attached for you:
+
+```scala
+import zio.blocks.telemetry._
+
+val provider = LoggerProvider.builder
+  .addLogRecordProcessor(LogRecordProcessor.noop)
+  .build()
+
+val logger = provider.get("com.example.OrderService", "1.0.0")
+
+logger.info("order placed", "orderId" -> AttributeValue.StringValue("ord-001"))
+logger.warn("payment delayed", "durationMs" -> AttributeValue.LongValue(250L))
+logger.error("checkout failed", "code" -> AttributeValue.LongValue(503L))
+
+provider.shutdown()
+```
+
+Attributes must be wrapped: `AttributeValue.StringValue`, `LongValue`, `DoubleValue`, `BooleanValue`, or one of their `*SeqValue` forms for arrays. That verbosity is the cost of a bare `Logger` — the global [`log`](./index.md) accepts the same values as plain literals.
+
+## Forwarding a Record You Already Have
+
+`emit(record)` sends a [`LogRecord`](./log-record.md) you built yourself, as-is. Where `info(...)` fills in the timestamp, scope name, and span identity, `emit` adds nothing, so a hand-built record without span identity won't correlate with any trace. Use it to forward another framework's logs into the same destinations:
+
+```scala
+import zio.blocks.telemetry._
+
+val logger = LoggerProvider.builder
+  .addLogRecordProcessor(new ConsoleLogRecordProcessor)  // a provider with no processor emits nothing
+  .build()
+  .get("com.example.Bridge")
+
+logger.emit(
+  LogRecord.builder
+    .setSeverity(Severity.Warn)
+    .setBody("from the legacy logger")
+    .build
+)
+```
+
+## Reading the Active Span
+
+`currentSpanContext()` returns the span you're inside, or `None` if there isn't one. Correlation is automatic, so you only need this to carry trace IDs across a boundary yourself — an outgoing HTTP header, a queue message, an error response:
+
+```scala
+import zio.blocks.telemetry._
+
+val logger = LoggerProvider.builder.build().get("com.example.Client")
+
+val traceHeader: Option[String] = logger.currentSpanContext().map(_.traceIdHex)
+```
+
+To configure where these logs go, see [`LoggerProvider`](./logger-provider.md).

package/reference/telemetry/logging/severity.md

@@ -0,0 +1,62 @@
+---
+id: severity
+title: "Severity"
+description: "The 24-level log severity scale following the OpenTelemetry log data model: Trace, Debug, Info, Warn, Error, Fatal, four levels each."
+keywords:
+  - "Structured Logging"
+  - "Severity Levels"
+  - "Log Filtering"
+  - "Severity"
+sidebar_label: "Severity"
+---
+
+`Severity` is the level attached to every [`LogRecord`](./log-record.md) — it says how important the message is and drives which records a severity filter keeps. It follows the OpenTelemetry log data model: 24 numeric levels grouped into six named categories with four gradations each, fine enough for detailed instrumentation yet compatible with the familiar five-level `TRACE`/`DEBUG`/`INFO`/`WARN`/`ERROR` scale. Every level shares its category's `text` (all four `Trace` levels report `"TRACE"`), so backends that expect the coarse names still work.
+
+```scala
+sealed trait Severity {
+  def number: Int    // 1 to 24
+  def text:   String // the category name: "TRACE", "DEBUG", "INFO", "WARN", "ERROR", "FATAL"
+}
+
+object Severity {
+  case object Trace extends Severity  // number = 1; then Trace2, Trace3, Trace4 (2-4)
+  case object Debug extends Severity  // number = 5; then Debug2, Debug3, Debug4 (6-8)
+  case object Info  extends Severity  // number = 9; then Info2, Info3, Info4 (10-12)
+  case object Warn  extends Severity  // number = 13; then Warn2, Warn3, Warn4 (14-16)
+  case object Error extends Severity  // number = 17; then Error2, Error3, Error4 (18-20)
+  case object Fatal extends Severity  // number = 21; then Fatal2, Fatal3, Fatal4 (22-24)
+
+  def fromNumber(n: Int): Option[Severity]      // Some when 1 <= n <= 24
+  def fromText(text: String): Option[Severity]  // case-insensitive; the six category names
+}
+```
+
+The six category objects (`Trace`, `Debug`, `Info`, `Warn`, `Error`, `Fatal`) are what you name day to day; the numbered gradations exist for instrumentation that needs finer distinctions.
+
+## Filtering by Severity
+
+The main use of `Severity` is to set a floor below which records are dropped before any `LogRecord` is built. Set a global floor with `log.setMinSeverity`, or a per-namespace override that takes precedence for matching call sites:
+
+```scala
+import zio.blocks.telemetry._
+
+log.setMinSeverity(Severity.Warn)              // globally drop Trace, Debug, Info
+log.setMinSeverity("com.example.db", Severity.Debug) // but keep Debug for the query layer
+
+log.debug("suppressed by the global floor")
+log.warn("emitted")
+```
+
+`fromText` and `fromNumber` parse a level from an external source — an environment variable or an OTLP protobuf field — returning `None` for anything out of range:
+
+```scala
+import zio.blocks.telemetry._
+
+val level = Severity.fromText("ERROR").getOrElse(Severity.Info) // Severity.Error, number 17
+log.setMinSeverity(level)
+```
+
+## See Also
+
+- [LogRecord](./log-record.md) — the record whose level `Severity` sets.
+- [Logging](./index.md) — the `log.*` emit methods and the full filtering API.