@zio.dev/zio-blocks 0.0.51 → 0.0.56

package/reference/telemetry/common/any-value.md

@@ -0,0 +1,90 @@
+---
+id: any-value
+title: "AttributeValue"
+description: "Boxed existential wrapper for the eight attribute kinds — the value type accepted by Logger, Span#setAttribute, and metric label maps when the type isn't known ahead of time."
+keywords:
+  - "Telemetry Metadata"
+  - "Attribute Value"
+  - "OTLP AnyValue"
+  - "AttributeValue"
+---
+
+`AttributeValue` is the closed set of eight kinds an attribute can hold — one case class per kind, so code that accepts "any attribute value" can pattern match on which one it got. It exists at the boundary of the telemetry API: `Attributes` itself never stores one (see [Attributes](./attributes.md) for the unboxed parallel-array representation it uses instead), but constructing or reading one at a boundary — a log call, a span attribute buffer, a metric label map, an exporter — needs a single type that can be any of the eight, and `AttributeValue` is it. Its eight variants:
+
+```scala
+sealed trait AttributeValue
+
+object AttributeValue {
+  final case class StringValue(value: String)           extends AttributeValue
+  final case class BooleanValue(value: Boolean)         extends AttributeValue
+  final case class LongValue(value: Long)               extends AttributeValue
+  final case class DoubleValue(value: Double)           extends AttributeValue
+  final case class StringSeqValue(value: Seq[String])   extends AttributeValue
+  final case class LongSeqValue(value: Seq[Long])       extends AttributeValue
+  final case class DoubleSeqValue(value: Seq[Double])   extends AttributeValue
+  final case class BooleanSeqValue(value: Seq[Boolean]) extends AttributeValue
+}
+```
+
+The name in this page's title is the Scala identifier; the file uses `any-value` because the type's own doc comment describes it as mirroring OpenTelemetry's `AnyValue` protobuf message, which supports the same eight shapes: a string, a boolean, a 64-bit integer, a double, and an array of each.
+
+## Where It Shows Up
+
+`AttributeValue` is the value type wherever an attribute is accepted without a pre-declared [`AttributeKey`](./attribute-key.md). The `Logger` API is the clearest example — every logging method takes a variadic list of name/value pairs typed against it:
+
+```scala
+import zio.blocks.telemetry._
+
+val provider = LoggerProvider.builder.build()
+val logger   = provider.get("com.example")
+
+logger.info(
+  "order placed",
+  "orderId" -> AttributeValue.StringValue("ord_123"),
+  "total"   -> AttributeValue.DoubleValue(49.99),
+  "rush"    -> AttributeValue.BooleanValue(true)
+)
+
+provider.shutdown()
+```
+
+The same ADT appears on the reading side of `Attributes` — `Attributes#foreach` and `Attributes#toMap` box each stored value into an `AttributeValue` so you can match on its kind, which [Attributes](./attributes.md#iterating) covers in full, including why `Attributes#accept` is the zero-allocation alternative for a hot path. `Span#setAttribute`, `Tracer`'s span-creation attribute maps, and the label maps `Counter`/`Histogram`/`Gauge`/`UpDownCounter` accept all convert through `AttributeValue` the same way `Logger` does — construct or match on one of the eight cases, never a ninth.
+
+## Relationship to AttributeType
+
+Each `AttributeValue` variant corresponds to exactly one [`AttributeType`](./attribute-key.md) discriminator and one `AttributeKey` factory — the three are the same eight-way split viewed from three angles: the runtime value, the compile-time type tag, and the typed key constructor:
+
+| `AttributeValue` variant | `AttributeType` | `AttributeKey` factory |
+| ------------------------- | ---------------- | ------------------------ |
+| `StringValue(String)`             | `StringType`      | `AttributeKey.string`      |
+| `BooleanValue(Boolean)`           | `BooleanType`     | `AttributeKey.boolean`     |
+| `LongValue(Long)`                 | `LongType`        | `AttributeKey.long`        |
+| `DoubleValue(Double)`             | `DoubleType`      | `AttributeKey.double`      |
+| `StringSeqValue(Seq[String])`     | `StringSeqType`   | `AttributeKey.stringSeq`   |
+| `LongSeqValue(Seq[Long])`         | `LongSeqType`     | `AttributeKey.longSeq`     |
+| `DoubleSeqValue(Seq[Double])`     | `DoubleSeqType`   | `AttributeKey.doubleSeq`   |
+| `BooleanSeqValue(Seq[Boolean])`   | `BooleanSeqType`  | `AttributeKey.booleanSeq`  |
+
+`AttributeType` never appears on its own in application code — it's the tag `AttributeKey[A]#type` carries so a key and a stored value can be checked against each other without reflecting on `A` itself.
+
+## OTLP JSON Mapping
+
+The [OTLP exporter](../otel/index.md) converts every `Attributes` set to OTLP's `AnyValue` JSON shape by boxing each entry into an `AttributeValue` and matching on it. The eight cases map onto four wire keys, with sequences nesting under `arrayValue`:
+
+| `AttributeValue` variant | OTLP JSON field | Notes |
+| -------------------------- | ------------------ | ------- |
+| `StringValue`     | `"stringValue"`                              | plain JSON string |
+| `BooleanValue`    | `"boolValue"`                                | plain JSON boolean |
+| `LongValue`       | `"intValue"`                                 | JSON string, per OTLP's `int64` mapping — `42L` becomes `"42"` |
+| `DoubleValue`     | `"doubleValue"`                              | plain JSON number |
+| `StringSeqValue`  | `"arrayValue":{"values":[{"stringValue":...}, ...]}` | one wrapped element per entry |
+| `LongSeqValue`    | `"arrayValue":{"values":[{"intValue":"..."}, ...]}`  | each element quoted, same as scalar `LongValue` |
+| `DoubleSeqValue`  | `"arrayValue":{"values":[{"doubleValue":...}, ...]}` | |
+| `BooleanSeqValue` | `"arrayValue":{"values":[{"boolValue":...}, ...]}`   | |
+
+## See Also
+
+- [Attributes](./attributes.md#iterating) — `Attributes#foreach`/`Attributes#toMap` (which box into `AttributeValue`) versus `Attributes#accept` (which doesn't)
+- [AttributeKey](./attribute-key.md) — the typed key that pairs with a specific `AttributeValue` variant for allocation-free reads
+- [OTLP Export](../otel/index.md) — where `AttributeValue` becomes OTLP's `AnyValue` JSON representation
+- [Common Types](./index.md) — the types every telemetry pillar uses

package/reference/telemetry/common/attribute-key.md

@@ -0,0 +1,87 @@
+---
+id: attribute-key
+title: "AttributeKey"
+description: "Type-safe key for Attributes storage. Binds a string name to a specific value type A (String, Boolean, Long, Double, and their Seq variants)."
+keywords:
+  - "Telemetry Metadata"
+  - "Type-Safe Key"
+  - "Typed Attributes"
+  - "AttributeKey"
+---
+
+`AttributeKey[A]` is the type-safe key type for reading and writing entries in an `Attributes` collection. It binds a string name to a specific value type `A` via an `AttributeType` discriminator, so `Attributes#get[A](key)` returns `Option[A]` without casting. There are eight supported value types, each with its own factory method on the companion object.
+
+```scala
+sealed trait AttributeKey[A] {
+  def name: String           // the string label used as the key
+  def `type`: AttributeType  // discriminator: StringType, LongType, DoubleType, BooleanType, + 4 Seq variants
+}
+
+object AttributeKey {
+  // Scalar factory methods
+  def string(name: String):     AttributeKey[String]
+  def boolean(name: String):    AttributeKey[Boolean]
+  def long(name: String):       AttributeKey[Long]
+  def double(name: String):     AttributeKey[Double]
+
+  // Sequence factory methods
+  def stringSeq(name: String):  AttributeKey[Seq[String]]
+  def longSeq(name: String):    AttributeKey[Seq[Long]]
+  def doubleSeq(name: String):  AttributeKey[Seq[Double]]
+  def booleanSeq(name: String): AttributeKey[Seq[Boolean]]
+}
+```
+
+## Usage
+
+```scala
+import zio.blocks.telemetry._
+
+// Typed factory methods
+val envKey      = AttributeKey.string("environment")
+val retryKey    = AttributeKey.long("retry.count")
+val debugKey    = AttributeKey.boolean("debug.enabled")
+val latencyKey  = AttributeKey.double("latency.ms")
+val tagsKey     = AttributeKey.stringSeq("tags")
+
+// Build an Attributes collection using typed keys
+val attrs = Attributes.builder
+  .put(envKey, "production")
+  .put(retryKey, 3L)
+  .put(debugKey, false)
+  .put(latencyKey, 12.5)
+  .put(tagsKey, Seq("important", "v2"))
+  .build
+```
+
+## Passing to Span and Metric APIs
+
+`AttributeKey` is used directly in `Span#setAttribute` and `Attributes.of`:
+
+```scala
+import zio.blocks.telemetry._
+
+val provider = TracerProvider.builder.build()
+val tracer   = provider.get("com.example")
+
+val dbSystem = AttributeKey.string("db.system")
+val rowCount = AttributeKey.long("db.rows")
+
+tracer.span("db.query", SpanKind.Client) { span =>
+  span.setAttribute(dbSystem, "postgresql")
+  span.setAttribute(rowCount, 42L)
+}
+
+provider.shutdown()
+```
+
+## Predefined Constants
+
+`Attributes.ServiceName` and `Attributes.ServiceVersion` are predefined `AttributeKey[String]` constants for the standard OTel `"service.name"` and `"service.version"` attribute names. Use them instead of string literals to avoid typos:
+
+```scala
+import zio.blocks.telemetry._
+
+val attrs = Attributes.of(Attributes.ServiceName, "order-service")
+assert(attrs.get(Attributes.ServiceName) == Some("order-service"))
+```

package/reference/telemetry/common/attributes.md

@@ -0,0 +1,118 @@
+---
+id: attributes
+title: "Attributes"
+description: "Typed key-value metadata attached to spans, log records, and measurements — built once, read by key, and cheap enough for a hot path."
+keywords:
+  - "Telemetry Metadata"
+  - "Typed Key-Value Pairs"
+  - "Boxing-Free Collection"
+  - "Attributes"
+---
+
+`Attributes` is the metadata carried alongside a signal — the `http.route` on a span, the `orderId` on a log record, the `method=GET` on a measurement. It's a set of key-value pairs, and every signal the telemetry module emits has one.
+
+It exists because a signal without detail can't answer questions. "A request was slow" is useless; "a `GET` on `/orders` that returned `503` was slow" is something you can search for, filter on, and group by. Attributes are what carry that detail into your backend.
+
+Two properties shape the type. Values are reached through a typed [`AttributeKey`](./attribute-key.md), so reading one gives you back a `String` or a `Long` rather than something you must cast. And because a set is built on every span and every measurement — the hottest paths in an instrumented application — primitives are stored without boxing, and a finished set is immutable, so it can be shared rather than copied.
+
+## Building a Set
+
+Three ways in, depending on how many pairs you have:
+
+```scala
+import zio.blocks.telemetry._
+
+val none = Attributes.empty
+
+val one = Attributes.of(Attributes.ServiceName, "payments")
+
+val several = Attributes.builder
+  .put(AttributeKey.string("http.route"), "/orders")
+  .put("http.status_code", 200L)
+  .put("cache.hit", false)
+  .build
+```
+
+`of` takes exactly one pair, so reach for `builder` as soon as you have two. The builder accepts either a typed key or a plain name with a `String`, `Long`, `Double`, or `Boolean` value, and putting the same key twice keeps the last value. `Attributes.ServiceName` and `ServiceVersion` are predefined keys for the conventional OpenTelemetry names; define your own with [`AttributeKey`](./attribute-key.md).
+
+## Reading a Value
+
+`get` takes a key and returns the value at that key's declared type:
+
+```scala
+import zio.blocks.telemetry._
+
+val route = AttributeKey.string("http.route")
+val attrs = Attributes.of(route, "/orders")
+
+val found: Option[String] = attrs.get(route)               // Some("/orders")
+val missing = attrs.get(AttributeKey.string("db.system"))  // None
+```
+
+The `Option` covers a key that isn't there. `size` and `isEmpty` report how many pairs a set holds without reading any of them.
+
+## Merging Two Sets
+
+`++` combines sets, which is how a signal's own attributes join those of its surroundings:
+
+```scala
+import zio.blocks.telemetry._
+
+val env = AttributeKey.string("deployment.environment")
+
+val base = Attributes.of(env, "staging")
+val merged = base ++ Attributes.of(env, "production")
+
+merged.get(env)  // Some("production") — the right side wins
+```
+
+Merging appends rather than deduplicates, so a key on both sides stays in the set twice: the right side wins every lookup, but `size` counts it twice and anything iterating the set — an exporter included — sees it twice. Where two sets may share a key, build one set with a builder instead.
+
+## Iterating
+
+Reading a whole set back — to export it, or to check it in a test — comes in two forms, and the difference is worth understanding before you pick one.
+
+A `Long` you store here is kept as a plain number, not as an object. Handing it to code that accepts *any* kind of value means wrapping it in an object first — **boxing** — and that wrapper is a small allocation, per attribute, every time. Fine once in a test; not fine on a path that runs on every request.
+
+`accept` avoids it by asking you for one method per kind of value. Each method's parameter is that exact type, so the number is passed as a number and nothing is wrapped:
+
+```scala
+import zio.blocks.telemetry._
+
+val attrs = Attributes.builder.put("http.route", "/orders").put("http.status_code", 200L).build
+
+attrs.accept(new AttributeVisitor {
+  def visitString(key: String, value: String): Unit   = println(s"$key=$value")
+  def visitLong(key: String, value: Long): Unit       = println(s"$key=$value")
+  def visitDouble(key: String, value: Double): Unit   = println(s"$key=$value")
+  def visitBoolean(key: String, value: Boolean): Unit = println(s"$key=$value")
+})
+```
+
+Those four are the only methods you must write. There are four more for sequence values, and they already do nothing — so if you store a sequence attribute and don't override its method, `accept` passes over it in silence. Nothing fails; the attribute simply never reaches your exporter.
+
+The other form is for when convenience matters more than a few allocations, which is most code outside an exporter. `foreach` and `toMap` do the wrapping for you, handing each value over as an [`AttributeValue`](./any-value.md) — one wrapper per kind, so you can match on which kind you got:
+
+```scala
+import zio.blocks.telemetry._
+
+val attrs = Attributes.of(Attributes.ServiceName, "payments")
+
+attrs.foreach { (key, value) =>
+  value match {
+    case AttributeValue.StringValue(s) => println(s"$key is text: $s")
+    case other                         => println(s"$key is $other")
+  }
+}
+
+val asMap: Map[String, AttributeValue] = attrs.toMap
+```
+
+Two sets holding the same pairs are equal regardless of the order they were built in, so a test can compare an expected set directly against a recorded one.
+
+## See Also
+
+- [AttributeKey](./attribute-key.md) — defining typed keys
+- [AttributeValue](./any-value.md) — the boxed wrapper `foreach`/`toMap` hand back
+- [Resource](./resource.md) — service identity, itself an `Attributes` set
+- [Common Types](./index.md) — the types every pillar uses

package/reference/telemetry/common/index.md

@@ -0,0 +1,39 @@
+---
+id: index
+title: "Common Types"
+description: "The four types every signal carries — Attributes and AttributeKey for its detail, Resource and InstrumentationScope for what produced it."
+keywords:
+  - "Telemetry Metadata"
+  - "Signal Attributes"
+  - "Service Identity"
+  - "Common Types"
+sidebar_label: "Common Types"
+---
+
+These four types describe every signal, across all three telemetry pillars — tracing, logging, and metrics. Every span, log record, and metric data point is annotated with `Attributes`; every provider accepts a `Resource`; every scope instance is tagged with an `InstrumentationScope`. Understanding these four types unlocks the rest of the module.
+
+## Types
+
+| Type | Description |
+|------|-------------|
+| [Attributes](./attributes.md) | Immutable, unboxed parallel-array collection of typed key-value pairs. Carried by every signal: `Span`, `LogRecord`, `Counter`, `Resource`, and `InstrumentationScope`. |
+| [AttributeKey](./attribute-key.md) | Typed key for an `Attributes` entry. Binds a string name to one of eight value types (`String`, `Long`, `Double`, `Boolean`, and their `Seq` variants). |
+| [AttributeValue](./any-value.md) | Boxed existential wrapper for the same eight kinds, used at API boundaries — `Logger`'s vararg attributes, `Span#setAttribute`, metric label maps — where the type isn't known ahead of time. |
+| [Resource](./resource.md) | Immutable `Attributes` wrapper that describes the entity producing telemetry (service name, SDK version, deployment environment). Shared across all three providers. |
+| [InstrumentationScope](./instrumentation-scope.md) | Named and versioned identity for the library or component that created a signal. Set when calling `TracerProvider.get`, `LoggerProvider.get`, or `MeterProvider.get`. |
+
+## Design
+
+All four types are designed for hot-path telemetry code:
+
+- **`Attributes`** stores `Long`, `Double`, and `Boolean` values unboxed in a parallel primitive array via bit-casting. Reading a value back boxes it — through `get`, `foreach`, or a conversion to `Map` — so hot paths that only write stay allocation-free.
+- **`AttributeKey`** is a small case class carrying the name and the value type, so a typo in a name or a mismatched type is a compile error rather than a silently separate series.
+- **`Resource`** is immutable and stamped onto a signal when it is created, not at export: `Tracer` puts it on every span and `Logger` on every log record. Metric instruments do not carry it — a `MeterProvider` holds a `Resource`, but the `Meter` and the collected `MetricData` never see it.
+- **`InstrumentationScope`** is constructed once per scope by the provider and referenced from all signals that scope creates.
+
+## See Also
+
+- [Telemetry](../index.md) — module overview and the three-pillar architecture
+- [Tracing](../tracing/index.md) — span lifecycle types that use `Attributes` and `Resource`
+- [Logging](../logging/index.md) — structured log record types that carry `Attributes`
+- [Metrics](../metrics/index.md) — dimensional measurement types that use `Attributes` as labels

package/reference/telemetry/common/instrumentation-scope.md

@@ -0,0 +1,24 @@
+---
+id: instrumentation-scope
+title: "InstrumentationScope"
+description: "Identifies the library or component that produced a signal, so a backend can tell your telemetry apart from a dependency's."
+keywords:
+  - "Telemetry Metadata"
+  - "Signal Origin"
+  - "Instrumentation Identity"
+  - "InstrumentationScope"
+sidebar_label: "InstrumentationScope"
+---
+
+`InstrumentationScope` records which library or component produced a signal. It's what lets a backend tell spans from your own code apart from spans emitted by a dependency, and group or filter by either.
+
+```scala
+final case class InstrumentationScope(
+  name:       String,
+  version:    Option[String] = None,
+  attributes: Attributes     = Attributes.empty
+)
+```
+
+You rarely name the type: it's built for you from the name you pass to `TracerProvider#get`, `LoggerProvider#get`, or `MeterProvider#get`, and every [`Span`](../tracing/span.md), [`SpanData`](../tracing/span-data.md), [`LogRecord`](../logging/log-record.md), [`Tracer`](../tracing/tracer.md), and [`Meter`](../metrics/meter.md) then carries it.
+

package/reference/telemetry/common/resource.md

@@ -0,0 +1,34 @@
+---
+id: resource
+title: "Resource"
+description: "Describes the entity producing telemetry (service, container, host). An immutable wrapper around Attributes shared by TracerProvider, LoggerProvider, and MeterProvider."
+keywords:
+  - "Telemetry Metadata"
+  - "Resource Attributes"
+  - "Semantic Conventions"
+  - "Resource"
+---
+
+`Resource` is an immutable wrapper around `Attributes` that describes the entity producing telemetry — the service, container, host, or runtime. It is stamped on every span and every log record so that a backend can group signals by their origin. All three provider types (`TracerProvider`, `LoggerProvider`, `MeterProvider`) accept a `Resource` at configuration time; `Tracer` and `Logger` propagate it onto the signals they emit, while metric instruments do not carry it — collected `MetricData` holds only the per-measurement `Attributes`.
+
+```scala
+final case class Resource(attributes: Attributes)
+
+object Resource {
+  val empty:   Resource                       // no attributes
+  val default: Resource                       // service.name + telemetry.sdk.* attributes
+  def create(attrs: Attributes): Resource
+
+  // merge comes from an implicit class on the companion
+  implicit class ResourceOps(val self: Resource) {
+    def merge(other: Resource): Resource      // other's attributes take precedence on duplicate keys
+  }
+}
+```
+
+## Predefined Instances
+
+| Instance           | Description                                                                                                                                                          |
+|--------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `Resource.empty`   | A `Resource` with no attributes. Use as a neutral base.                                                                                                              |
+| `Resource.default` | Pre-populated with `service.name = "unknown_service"`, `telemetry.sdk.name = "zio-blocks"`, `telemetry.sdk.language = "scala"`, and the SDK version from build info. |