@zio.dev/zio-blocks 0.0.51 → 0.0.56

package/reference/telemetry/tracing/span-builder.md

@@ -0,0 +1,57 @@
+---
+id: span-builder
+title: "SpanBuilder"
+description: "Mutable builder for creating spans with explicit kind, start timestamp, links, or parent context outside the normal Tracer.span lifecycle."
+keywords:
+  - "Distributed Tracing"
+  - "Manual Span Creation"
+  - "Explicit Span Configuration"
+  - "SpanBuilder"
+sidebar_label: "SpanBuilder"
+---
+
+`SpanBuilder` is a mutable builder for creating a [`Span`](./span.md) by hand, outside the automatic [`trace.span`](./index.md) lifecycle, with control the `span(name, kind, attributes)` overloads cannot express: an explicit start timestamp, links to spans in other traces, or a non-default parent context. 
+
+Crucially, a span it starts bypasses the [`Tracer`](./tracer.md)'s [`Sampler`](./sampler.md) and [`SpanProcessor`](./span-processor.md) list — nothing samples it, no `onStart`/`onEnd` fires, and **it is never exported to a backend**. The span lives only in memory, readable via `toSpanData`, and you must `end()` it yourself. Use `SpanBuilder` for tests or local inspection; for any span that should reach your tracing pipeline, use `trace.span`.
+
+```scala
+object SpanBuilder {
+  def apply(name: String): SpanBuilder
+}
+
+final class SpanBuilder {
+  // Configuration
+  def setKind(kind: SpanKind): SpanBuilder
+  def setParent(parentContext: SpanContext): SpanBuilder
+  def setAttribute[A](key: AttributeKey[A], value: A): SpanBuilder
+  def addLink(link: SpanLink): SpanBuilder
+  def setStartTimestamp(nanos: Long): SpanBuilder
+  def setResource(resource: Resource): SpanBuilder
+  def setInstrumentationScope(scope: InstrumentationScope): SpanBuilder
+
+  // Finalization
+  def startSpan(): Span                                  // parent's trace ID, or a random one at the root
+  def startSpan(traceIdHi: Long, traceIdLo: Long): Span  // explicit trace ID
+}
+```
+
+## Usage
+
+Obtain a pre-configured builder from `Tracer.spanBuilder` — it fills in the tracer's `Resource` and `InstrumentationScope` — set the metadata the `span` overloads cannot, then `startSpan()` and `end()` the span in a `try`/`finally`:
+
+```scala
+import zio.blocks.telemetry._
+
+val tracer = TracerProvider.builder.build().get("com.example")
+
+val span = tracer.spanBuilder("enqueue-message")
+  .setKind(SpanKind.Producer)
+  .addLink(SpanLink(SpanContext.invalid, Attributes.empty)) // in practice, an upstream context
+  .setStartTimestamp(System.nanoTime())
+  .startSpan()
+
+try span.setAttribute("message.id", "msg-456")
+finally span.end()
+```
+
+`SpanBuilder(name)` also builds one standalone, without a tracer. It is rarely what you want — the span it produces is attributed to `Resource.empty` and the scope name `"default"` rather than to your service and component, on top of reaching no sampler or processor. Reach for it only where no tracer exists yet, such as bridging a span in from another system. Note also that `startSpan()` marks the span sampled whenever there is no valid parent, so a standalone span always claims the sampled bit.

package/reference/telemetry/tracing/span-context.md

@@ -0,0 +1,39 @@
+---
+id: span-context
+title: "SpanContext"
+description: "Propagatable span identity: 128-bit trace ID (two Longs), SpanId, TraceFlags, trace state, and isRemote."
+keywords:
+  - "Distributed Tracing"
+  - "Context Propagation"
+  - "Trace Identity"
+  - "SpanContext"
+sidebar_label: "SpanContext"
+---
+
+`SpanContext` is the propagatable identity of a span — the 128-bit trace ID (split into two `Long` fields to avoid boxing), the `SpanId`, the `TraceFlags`, a W3C trace-state string, and an `isRemote` flag that marks contexts extracted from an upstream request. It exists so telemetry from one request can be correlated across services and signals.
+
+You rarely touch it directly: [`Tracer`](./tracer.md) generates one per span and logging stamps the active context onto every record automatically. Crossing a process boundary is explicit — a `Propagator` from the otel module injects it into outgoing headers and extracts it on the way in — so reach for it when you cross a boundary yourself. `SpanContext.invalid` is the sentinel for "no active span".
+
+```scala
+final case class SpanContext(
+  traceIdHi:   Long,        // high 64 bits of the 128-bit trace ID
+  traceIdLo:   Long,        // low  64 bits of the 128-bit trace ID
+  spanId:      SpanId,      // AnyVal wrapping a Long
+  traceFlags:  TraceFlags,  // AnyVal wrapping a Byte
+  traceState:  String,      // W3C tracestate header value
+  isRemote:    Boolean      // true when extracted from an incoming request
+) {
+  def isValid:    Boolean   // true only when BOTH the trace ID and span ID are non-zero
+  def isSampled:  Boolean   // true when the sampled bit of traceFlags is set
+  def traceIdHex: String    // 32-char lowercase hex trace ID
+}
+
+object SpanContext {
+  val invalid: SpanContext  // sentinel: all-zero IDs, not sampled, not remote
+  def create(traceIdHi: Long, traceIdLo: Long, spanId: SpanId, traceFlags: TraceFlags,
+             traceState: String, isRemote: Boolean): SpanContext
+}
+```
+
+
+`SpanContext` is read from `ContextStorage` by `Tracer.currentSpan` and by the logger on every emit for automatic trace–log correlation. [`SpanData`](./span-data.md) carries two of them: the span's own context and its parent's, where `SpanContext.invalid` marks a root span with no parent.

package/reference/telemetry/tracing/span-data.md

@@ -0,0 +1,32 @@
+---
+id: span-data
+title: "SpanData"
+description: "Immutable snapshot of a finished span — the read-only record a SpanProcessor exports."
+keywords:
+  - "Distributed Tracing"
+  - "Span Export"
+  - "Immutable Span Snapshot"
+  - "SpanData"
+sidebar_label: "SpanData"
+---
+
+`SpanData` is an immutable, fully-populated snapshot of a finished span — its name, timing, attributes, events, status, and identity, captured when the span ends. You rarely handle it directly: it is the read-only record a [`SpanProcessor`](./span-processor.md) receives (`onEnd`) and serializes to a backend, and the value `trace.collectedSpans` returns for test assertions. You produce spans with [`trace.span`](./index.md), never `SpanData` itself.
+
+```scala
+final case class SpanData(
+  name:                 String,
+  kind:                 SpanKind,
+  spanContext:          SpanContext,
+  parentSpanContext:    SpanContext,        // SpanContext.invalid for a root span
+  startTimeNanos:       Long,
+  endTimeNanos:         Long,               // 0L if snapshotted before end()
+  attributes:           Attributes,
+  events:               List[SpanEvent],
+  links:                List[SpanLink],
+  status:               SpanStatus,
+  resource:             Resource,
+  instrumentationScope: InstrumentationScope
+)
+```
+
+Each field mirrors what the span recorded; a `SpanProcessor` or exporter reads them to ship the span to a backend (OTLP or another format).

package/reference/telemetry/tracing/span-kind.md

@@ -0,0 +1,55 @@
+---
+id: span-kind
+title: "SpanKind"
+description: "SpanKind — the sealed enumeration classifying a span's role in a trace (Internal, Server, Client, Producer, Consumer) in the telemetry module's tracing area."
+keywords:
+  - "Distributed Tracing"
+  - "Span Classification"
+  - "SpanKind"
+sidebar_label: "SpanKind"
+---
+
+`SpanKind` is a sealed enumeration that classifies a span by its role in a trace — internal work, the client or server side of a synchronous RPC, or the producer or consumer side of an asynchronous message. It aligns with the [OpenTelemetry SpanKind specification](https://opentelemetry.io/docs/specs/otel/trace/api/#spankind), and a [`Tracer`](./tracer.md) records it on each [`Span`](./span.md) so backends can reconstruct client↔server and producer↔consumer relationships across services.
+
+```scala
+sealed trait SpanKind
+object SpanKind {
+  case object Internal extends SpanKind
+  case object Server   extends SpanKind
+  case object Client   extends SpanKind
+  case object Producer extends SpanKind
+  case object Consumer extends SpanKind
+}
+```
+
+Each kind describes what the span covers and how it relates to a span in another process:
+
+| Kind       | Represents                                                                                                                       | Relationship in a trace                                   |
+|------------|----------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------|
+| `Internal` | Work performed internally in the application. The default when no kind is given.                                                 | No remote parent or child.                                |
+| `Server`   | The server side of a synchronous RPC — begins when the server starts processing the request and ends when it sends the response. | Usually the child of a remote `Client` span.              |
+| `Client`   | The client side of a synchronous RPC — begins when the request is sent and ends when the response arrives.                       | Usually the parent of a remote `Server` span.             |
+| `Producer` | The producer side of an asynchronous message — begins when the message is sent and ends once it is dispatched.                   | Parent that often completes before the `Consumer` begins. |
+| `Consumer` | The consumer side of an asynchronous message — begins when the message is received and ends when processing finishes.            | Child of a `Producer` span.                               |
+
+## Usage
+
+Pass a `SpanKind` as the second argument to [`trace.span`](./index.md) (or `Tracer#span`) to classify a span; omit it to accept the `Internal` default.
+
+```scala
+import zio.blocks.telemetry._
+
+// Server span: handling an inbound request
+trace.span("handle-order", SpanKind.Server) { _ =>
+  // Client span: an outbound call made while handling it
+  trace.span("charge-payment", SpanKind.Client)(_ => ())
+}
+```
+
+Setting the kind accurately lets a tracing backend pair a `Client` span in one service with the `Server` span it triggers in another, and a `Producer` span with the `Consumer` that eventually handles its message.
+
+## See Also
+
+- [Span](./span.md) — the unit of work a `SpanKind` classifies.
+- [Tracing](./index.md) — the tracing overview and the `trace` entry point.
+- [OpenTelemetry SpanKind specification](https://opentelemetry.io/docs/specs/otel/trace/api/#spankind) — the cross-language semantics this enumeration follows.

package/reference/telemetry/tracing/span-processor.md

@@ -0,0 +1,53 @@
+---
+id: span-processor
+title: "SpanProcessor"
+description: "Hook for span lifecycle events (onStart, onEnd) in the telemetry module's tracing area. Implement to export or collect spans."
+keywords:
+  - "Distributed Tracing"
+  - "Span Export"
+  - "Lifecycle Hook"
+  - "SpanProcessor"
+sidebar_label: "SpanProcessor"
+---
+
+`SpanProcessor` is the extension point exporter authors implement to do something with finished spans — ship them to a backend, buffer them, or collect them for tests. A [`Tracer`](./tracer.md) calls `onStart` when a recorded span begins — `RecordOnly` as well as `RecordAndSample` — and `onEnd` with the immutable [`SpanData`](./span-data.md) snapshot when it finishes. You rarely implement this directly: `SpanProcessor.noop` and the built-in in-memory collector cover development and testing, so you write one only to bridge spans to an export target such as OTLP.
+
+```scala
+trait SpanProcessor extends AutoCloseable {
+  def onStart(span: Span): Unit         // span still mutable; RecordOnly + RecordAndSample
+  def onEnd(spanData: SpanData): Unit   // immutable snapshot — export from here
+  def shutdown(): Unit                  // flush and release; called by TracerProvider.shutdown()
+  def forceFlush(): Unit                // flush buffered data now
+  override def close(): Unit = shutdown()
+}
+
+object SpanProcessor {
+  val noop: SpanProcessor  // ignores every event
+}
+```
+
+## Implementing a Processor
+
+A custom processor forwards each `SpanData` to an export target. Register it on the provider with `addSpanProcessor`; when several are registered, they receive callbacks in insertion order.
+
+`onEnd` runs synchronously, on the thread that just ended the span — so whatever it does lands in that request's latency. Keep it to handing the snapshot off to a queue or buffer, and let a background thread do the network call:
+
+```scala
+import zio.blocks.telemetry._
+
+val exporter = new SpanProcessor {
+  def onStart(span: Span): Unit       = ()
+  def onEnd(spanData: SpanData): Unit = println(s"[EXPORT] ${spanData.name}")
+  def shutdown(): Unit                = ()
+  def forceFlush(): Unit              = ()
+}
+
+val provider = TracerProvider.builder.addSpanProcessor(exporter).build()
+trace.install(provider)
+trace.span("checkout") { _ => () } // prints: [EXPORT] checkout
+provider.shutdown()
+```
+
+## Integration
+
+The global `trace` object's default provider already registers an `InMemorySpanProcessor`, so `trace.collectedSpans` and `trace.clearSpans` are available for test assertions without any additional setup.

package/reference/telemetry/tracing/span-status.md

@@ -0,0 +1,47 @@
+---
+id: span-status
+title: "SpanStatus"
+description: "SpanStatus — the sealed enumeration recording a span's completion outcome (Unset, Ok, Error) in the telemetry module's tracing area."
+keywords:
+  - "Distributed Tracing"
+  - "Span Outcome"
+  - "Completion Status"
+  - "SpanStatus"
+sidebar_label: "SpanStatus"
+---
+
+`SpanStatus` records the outcome of the operation a [`Span`](./span.md) represents. The default is `SpanStatus.Unset`; instrumentation sets `Ok` on success or `Error(description)` on failure before the span's `end()`.
+
+```scala
+sealed trait SpanStatus
+object SpanStatus {
+  case object Unset                           extends SpanStatus  // default; outcome unknown or normal
+  case object Ok                              extends SpanStatus  // explicit success
+  final case class Error(description: String) extends SpanStatus  // explicit failure with description
+}
+```
+
+Set the status on the live span with `Span#setStatus` at any point before it ends:
+
+```scala
+import zio.blocks.telemetry._
+
+val provider = TracerProvider.builder.build()
+val tracer   = provider.get("com.example")
+
+tracer.span("process-payment") { span =>
+  val ok = true // result of processing
+  if (ok) span.setStatus(SpanStatus.Ok)
+  else span.setStatus(SpanStatus.Error("payment-gateway-timeout"))
+}
+
+provider.shutdown()
+```
+
+`SpanStatus` becomes part of the exported [`SpanData`](./span-data.md) (`SpanData.status`) and is read by [`SpanProcessor`](./span-processor.md) implementations and test assertions.
+
+## See Also
+
+- [Span](./span.md) — the unit of work whose outcome `SpanStatus` records.
+- [SpanKind](./span-kind.md) — the companion classification, set once at span creation.
+- [Tracing](./index.md) — the tracing overview.

package/reference/telemetry/tracing/span.md

@@ -0,0 +1,117 @@
+---
+id: span
+title: "Span"
+description: "A mutable, thread-safe unit of work in a distributed trace."
+keywords:
+  - "Distributed Tracing"
+  - "Span Lifecycle"
+  - "Unit of Work"
+  - "Span"
+---
+
+`Span` is a mutable, thread-safe unit of work in a distributed trace — it records the name, kind, attributes, events, and outcome of one operation. You obtain a live `Span` from the higher-order [`trace.span`](./index.md) (or `Tracer#span`), which creates it, samples it, and ends it for you — you rarely create one directly.
+
+Here is the full interface; the sections below cover the methods you reach for day to day:
+
+```scala
+trait Span {
+  // Identity — fixed at creation
+  def spanContext: SpanContext
+  def name: String
+  def kind: SpanKind
+
+  // Annotate — no-ops once the span has ended
+  def setAttribute[A](key: AttributeKey[A], value: A): Unit
+  def setAttribute(key: String, value: String): Unit
+  def setAttribute(key: String, value: Long): Unit
+  def setAttribute(key: String, value: Double): Unit
+  def setAttribute(key: String, value: Boolean): Unit
+  def addEvent(name: String): Unit
+  def addEvent(name: String, attributes: Attributes): Unit
+  def addEvent(name: String, timestamp: Long, attributes: Attributes): Unit
+  def setStatus(status: SpanStatus): Unit
+
+  // Lifecycle — managed for you by trace.span
+  def isRecording: Boolean
+  def end(): Unit
+  def end(endTimeNanos: Long): Unit
+  def toSpanData: SpanData
+}
+```
+
+## Usage
+
+Open a span with `trace.span`: it hands your block a live `Span` and ends it automatically when the block returns. Inside, annotate the span with attributes, events, and a status:
+
+```scala
+import zio.blocks.telemetry._
+
+trace.span("http.request", SpanKind.Server) { span =>
+  span.setAttribute("http.method", "GET")
+  span.setAttribute("http.status_code", 200L)
+  span.addEvent("auth.passed")
+  span.setStatus(SpanStatus.Ok)
+}
+```
+
+`trace.span` manages the lifecycle: it ends the span when the block returns, and on end the span becomes an immutable [`SpanData`](./span-data.md) snapshot that `SpanProcessor`s receive (end-user code seldom reads it via `toSpanData` directly). For the rare cases `trace.span` can't cover — a custom start timestamp, links, or crossing an async boundary — [`SpanBuilder`](./span-builder.md) starts a span you `end()` yourself; it bypasses the sampler and processors, so prefer `trace.span`.
+
+## Annotating a Span
+
+The four convenience overloads cover the common value types; the typed `setAttribute[A](key, value)` form accepts any [`AttributeKey`](../common/attribute-key.md), including the sequence-valued ones (`AttributeKey.stringSeq` and friends) that have no shorthand.
+
+Everything you do with a span happens inside the `trace.span` block, before it ends. Once the span ends, every `setAttribute`, `addEvent`, and `setStatus` call is silently ignored. If the sampler dropped the span you receive `Span.NoOp` — a no-op you can still call freely, so no guards are needed; check `isRecording` only to skip expensive annotation work for a dropped or ended span. Reading from a `NoOp` gives you blanks rather than errors: an invalid `spanContext`, an empty `name`, `SpanKind.Internal`, and `isRecording = false`.
+
+### Attributes
+
+Attach typed key-value pairs with `setAttribute` — there are convenience overloads for `String`, `Long`, `Double`, and `Boolean`. Setting the same key twice replaces the value:
+
+```scala
+import zio.blocks.telemetry._
+
+trace.span("db.query") { span =>
+  span.setAttribute("db.system", "postgresql")
+  span.setAttribute("db.rows", 12L)
+  span.setAttribute("db.cached", false)
+  span.setAttribute("db.latency_ms", 3.14)
+}
+```
+
+### Events
+
+Record a named point-in-time event with `addEvent`, optionally with its own attributes:
+
+```scala
+import zio.blocks.telemetry._
+
+trace.span("payment.process") { span =>
+  span.addEvent("validation.passed")
+  span.addEvent("retry", Attributes.of(AttributeKey.long("attempt"), 2L))
+}
+```
+
+### Status
+
+Mark the outcome with `setStatus` — `SpanStatus.Ok` on success, `SpanStatus.Error(reason)` on failure (the default is `SpanStatus.Unset`):
+
+```scala
+import zio.blocks.telemetry._
+
+trace.span("charge") { span =>
+  val paid = true
+  if (paid) span.setStatus(SpanStatus.Ok)
+  else span.setStatus(SpanStatus.Error("gateway timeout"))
+}
+```
+
+## Identity
+
+A span's `name`, `kind`, and [`spanContext`](./span-context.md) are set at creation and never change. `spanContext` is the span's identity — the trace and span IDs that let all the telemetry from one request be tied together.
+
+You rarely touch it. Log correlation happens for you: logging stamps the active span's IDs onto every record automatically. Carrying the identity to another service is an explicit step — a `Propagator` from the otel module writes it into outgoing headers. Reach for `span.spanContext.traceIdHex` directly only in the low-level case — correlating with a system that isn't wired in, or crossing a boundary the instrumentation doesn't cover.
+
+## Ending a Span
+
+`trace.span` ends the span for you, including when the block throws — the span is closed on the way out and the exception propagates. Nothing sets an error status for you, though: a span whose block threw still reports `SpanStatus.Unset` unless you call `setStatus(SpanStatus.Error(...))` yourself.
+
+Ending is idempotent. The first `end()` wins and any later call is silently ignored, so a `finally` block that ends a span already ended by `trace.span` is harmless. The `end(endTimeNanos)` overload exists for when you are replaying or bridging spans and need to state the finish time rather than take the clock's.

package/reference/telemetry/tracing/tracer-provider.md

@@ -0,0 +1,91 @@
+---
+id: tracer-provider
+title: "TracerProvider"
+description: "Root factory for distributed tracing: produces Tracer instances sharing a Resource, Sampler, SpanProcessors, and ContextStorage."
+keywords:
+  - "Distributed Tracing"
+  - "Tracing Configuration"
+  - "Tracer Factory"
+  - "TracerProvider"
+---
+
+`TracerProvider` exists so tracing is configured once, in a single place. You set the service identity ([`Resource`](../common/resource.md)), the sampling policy ([`Sampler`](./sampler.md)), and where finished spans go ([`SpanProcessor`](./span-processor.md)s) when you build it at startup; from then on every [`Tracer`](./tracer.md) it hands out — and every span they create — shares that one configuration, so all your telemetry carries a consistent identity and policy. You build it once, install it, and rarely touch it again.
+
+```scala
+final class TracerProvider private[telemetry] (...) extends AutoCloseable {
+  def get(name: String, version: String = ""): Tracer  // a Tracer for a named scope
+
+  def shutdown(): Unit        // shut down every processor; call once at exit
+  def forceFlush(): Unit      // ask processors to export buffered spans now
+  override def close(): Unit  // alias for shutdown() — satisfies AutoCloseable
+}
+
+object TracerProvider {
+  def builder: TracerProviderBuilder
+}
+
+final class TracerProviderBuilder private[telemetry] (...) {
+  def setResource(resource: Resource): TracerProviderBuilder
+  def setSampler(sampler: Sampler): TracerProviderBuilder
+  def addSpanProcessor(processor: SpanProcessor): TracerProviderBuilder
+  def setContextStorage(contextStorage: ContextStorage[Option[SpanContext]]): TracerProviderBuilder
+  def build(): TracerProvider
+}
+```
+
+## Usage
+
+Build a provider once at startup, set only what you need — a `Resource` for your service identity, a `Sampler`, and the `SpanProcessor`s that export your spans — then `get` a `Tracer` from it. Unset fields take defaults: `Resource.default` (whose `service.name` is the placeholder `unknown_service`) and `AlwaysOnSampler`, which records every span.
+
+Do add a processor, though. The default processor list is **empty**, so a provider you build yourself samples spans and then discards them — nothing keeps or exports them. The in-memory buffer behind `trace.collectedSpans` belongs to the global `trace` object's own provider, not to yours:
+
+```scala
+import zio.blocks.telemetry._
+
+val provider = TracerProvider.builder
+  .setResource(Resource.create(Attributes.of(Attributes.ServiceName, "payments")))
+  .setSampler(ParentBasedSampler(AlwaysOnSampler))
+  .addSpanProcessor(SpanProcessor.noop) // replace with an OTLP exporter
+  .build()
+
+val tracer = provider.get("com.example.payments")
+tracer.span("process-payment") { span =>
+  span.setAttribute("payment.id", "pay-001")
+}
+
+provider.shutdown()
+```
+
+Most applications never hold the provider directly. Install it once on the global `trace` object at startup and use [`trace.span`](./index.md) everywhere, removing the setup burden from individual call sites:
+
+```scala
+import zio.blocks.telemetry._
+
+val provider = TracerProvider.builder
+  .setResource(Resource.create(Attributes.of(Attributes.ServiceName, "catalog")))
+  .addSpanProcessor(SpanProcessor.noop) // replace with your exporter
+  .build()
+
+trace.install(provider)
+```
+
+Each `get` builds a new `Tracer` — there is no caching — so take one per component at startup and hold it, rather than calling `get` inside a request. Passing a `version` alongside the name records it on the scope, which is how you tell spans from two releases of the same library apart.
+
+## Lifecycle
+
+Call `shutdown()` once when the app exits — it forwards to every registered processor so each can flush what it is holding and release its resources. `forceFlush()` does the flushing without the release, for when you want buffered spans exported now.
+
+`shutdown()` does not disable the provider: it still hands out tracers and still records spans afterwards, they just reach processors that have already been shut down. Treat it as the last thing you call, not a switch you can toggle. Since a provider is `AutoCloseable` — `close()` is an alias for `shutdown()` — you can also let the language make that call:
+
+```scala
+import zio.blocks.telemetry._
+import scala.util.Using
+
+Using.resource(TracerProvider.builder.addSpanProcessor(SpanProcessor.noop).build()) { provider =>
+  provider.get("com.example").span("startup")(_ => ())
+}
+```
+
+## Trace–Log Correlation
+
+Logs emitted inside a span are correlated with it automatically: a `TracerProvider` and a `LoggerProvider` share the same default context storage, so every log record carries that span's trace and span IDs with no wiring. (Override `setContextStorage` on both only to isolate correlation — e.g. in tests.) See the [Telemetry module index](../index.md).

package/reference/telemetry/tracing/tracer.md

@@ -0,0 +1,52 @@
+---
+id: tracer
+title: "Tracer"
+description: "Reference page for Tracer, the span-creation engine in the telemetry module's tracing area."
+keywords:
+  - "Distributed Tracing"
+  - "Span Creation"
+  - "Trace Instrumentation"
+  - "Tracer"
+---
+
+`Tracer` creates spans within a single instrumentation scope — a named library or component. Call `Tracer#span` to wrap a block of work in a timed, attributed span; the tracer consults the configured [`Sampler`](./sampler.md), propagates the parent context so nested spans inherit the right trace, and notifies each [`SpanProcessor`](./span-processor.md) as spans start and end. 
+
+Library code takes a `Tracer` — obtained from a [`TracerProvider`](./tracer-provider.md) — to tag its spans with its own scope; application code usually prefers the global [`trace.span`](./index.md), which manages a tracer for you. A `Tracer` is always produced by a `TracerProvider` and cannot be constructed directly.
+
+```scala
+final class Tracer private[telemetry] (...) {
+  val instrumentationScope: InstrumentationScope
+  val resource: Resource
+
+  // Wrap a block in a span — three progressive overloads
+  def span[A](name: String)(f: Span => A): A
+  def span[A](name: String, kind: SpanKind)(f: Span => A): A
+  def span[A](name: String, kind: SpanKind, attributes: Attributes)(f: Span => A): A
+
+  // Manual span creation (advanced)
+  def spanBuilder(name: String): SpanBuilder
+
+  // The active span context, or None outside any span
+  def currentSpan: Option[SpanContext]
+}
+```
+
+## Usage
+
+Obtain a `Tracer` from a provider (or `trace.get` in application code), then wrap work in `span`. The three overloads add control progressively: `span(name)` defaults to `SpanKind.Internal`, `span(name, kind)` sets the kind, and `span(name, kind, attributes)` also seeds initial attributes. Nested `span` calls inherit the parent trace automatically:
+
+```scala
+import zio.blocks.telemetry._
+
+val tracer = TracerProvider.builder.build().get("com.example.orders")
+
+tracer.span("process-order", SpanKind.Server) { span =>
+  span.setAttribute("order.id", "ord-123")
+
+  tracer.span("persist-order", SpanKind.Client) { inner =>
+    inner.setAttribute("db.system", "postgresql")
+  }
+}
+```
+
+For advanced needs — a manual span lifecycle via [`SpanBuilder`](./span-builder.md) (local-only, never exported) or reading the active context with `currentSpan` (a [`SpanContext`](./span-context.md)) — see those pages. For all normal work, `span` is enough.

package/reference/typeid.md

@@ -2527,22 +2527,6 @@ cd zio-blocks
 Demonstrates deriving TypeIds for case classes, accessing their properties (name, fullName, owner, arity), using predefined TypeIds for built-in types, and implicit derivation:
 
 ```scala title="schema-examples/src/main/scala/typeid/TypeIdBasicExample.scala" 
-/*
- * Copyright 2024-2026 John A. De Goes and the ZIO Contributors
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *     http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-
 package typeid
 
 import zio.blocks.typeid.*
@@ -2789,22 +2773,6 @@ sbt "schema-examples/runMain typeid.TypeIdBasicExample"
 Demonstrates subtype checking with `isSubtypeOf`, `isSupertypeOf`, and `isEquivalentTo`, including direct inheritance, transitive inheritance, sealed trait cases, and variance-aware subtyping for applied types like `List[Dog] <: List[Animal]`:
 
 ```scala title="schema-examples/src/main/scala/typeid/TypeIdSubtypingExample.scala" 
-/*
- * Copyright 2024-2026 John A. De Goes and the ZIO Contributors
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *     http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-
 package typeid
 
 import zio.blocks.typeid._
@@ -2912,22 +2880,6 @@ sbt "schema-examples/runMain typeid.TypeIdSubtypingExample"
 Demonstrates type alias handling, normalization to underlying types, structural equality, and building type-indexed registries using erased TypeIds:
 
 ```scala title="schema-examples/src/main/scala/typeid/TypeIdNormalizationExample.scala" 
-/*
- * Copyright 2024-2026 John A. De Goes and the ZIO Contributors
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *     http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-
 package typeid
 
 import zio.blocks.typeid._
@@ -3044,22 +2996,6 @@ sbt "schema-examples/runMain typeid.TypeIdNormalizationExample"
 Demonstrates how TypeId preserves the semantic distinction of opaque types, enabling runtime type safety that pure Scala reflection cannot provide. Shows building type-indexed validator registries keyed by opaque type identity:
 
 ```scala title="schema-examples/src/main/scala/typeid/OpaqueTypesExample.scala" 
-/*
- * Copyright 2024-2026 John A. De Goes and the ZIO Contributors
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *     http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-
 package typeid
 
 import zio.blocks.typeid._