effect 4.0.0-beta.66 → 4.0.0-beta.67

package/dist/Metric.js

@@ -1,47 +1,54 @@
 /**
- * @since 2.0.0
- *
- * The `Metric` module provides a comprehensive system for collecting, aggregating, and observing
- * application metrics in Effect applications. It offers type-safe, concurrent metrics that can
- * be used to monitor performance, track business metrics, and gain insights into application behavior.
- *
- * ## Key Features
- *
- * - **Five Metric Types**: Counters, Gauges, Frequencies, Histograms, and Summaries
- * - **Type Safety**: Fully typed metrics with compile-time guarantees
- * - **Concurrency Safe**: Thread-safe metrics that work with Effect's concurrency model
- * - **Attributes**: Tag metrics with key-value attributes for filtering and grouping
- * - **Snapshots**: Take point-in-time snapshots of all metrics for reporting
- * - **Runtime Integration**: Automatic fiber runtime metrics collection
- *
- * ## Metric Types
- *
- * ### Counter
- * Tracks cumulative values that only increase or can be reset to zero.
- * Perfect for counting events, requests, errors, etc.
- *
- * ### Gauge
- * Represents a single numerical value that can go up or down.
- * Ideal for current resource usage, temperature, queue sizes, etc.
- *
- * ### Frequency
- * Counts occurrences of discrete string values.
- * Useful for tracking categorical data like HTTP status codes, user actions, etc.
- *
- * ### Histogram
- * Records observations in configurable buckets to analyze distribution.
- * Great for response times, request sizes, and other measured values.
- *
- * ### Summary
- * Calculates quantiles over a sliding time window.
- * Provides statistical insights into value distributions over time.
- *
- * ## Basic Usage
+ * The `Metric` module provides tools for defining, updating, tagging, and
+ * reading application metrics from Effect programs. A `Metric<Input, State>`
+ * accepts typed input values and aggregates them into a typed state that can be
+ * read directly or exported from a snapshot.
+ *
+ * **Mental model**
+ *
+ * - A metric has an identifier, a type, an optional description, optional attributes, and mutable aggregate state
+ * - Use counters for cumulative values such as requests, errors, retries, or bytes processed
+ * - Use gauges for point-in-time values that can rise or fall, such as active connections or queue size
+ * - Use frequencies to count occurrences of discrete string values, such as status codes or action names
+ * - Use histograms to bucket numeric observations and inspect count, min, max, and sum
+ * - Use summaries to calculate quantiles over a bounded, time-based observation window
+ * - Metrics are updated from effects with {@link update} and {@link modify}, and read with {@link value}
+ * - Attributes tag metrics with key-value dimensions so the same logical metric can be grouped by service, endpoint, method, or other labels
+ * - Snapshots capture the currently registered metrics and their aggregate states for reporting or export
+ *
+ * **Common tasks**
+ *
+ * - Create counters: {@link counter}
+ * - Create gauges: {@link gauge}
+ * - Create frequencies: {@link frequency}
+ * - Create histograms: {@link histogram}, {@link linearBoundaries}, {@link exponentialBoundaries}
+ * - Create summaries: {@link summary}, {@link summaryWithTimestamp}
+ * - Measure effect duration: {@link timer}
+ * - Update a metric: {@link update}
+ * - Apply relative updates where supported: {@link modify}
+ * - Read one metric: {@link value}
+ * - Tag a metric: {@link withAttributes}
+ * - Transform accepted input values: {@link mapInput}
+ * - Record a constant input for repeated events: {@link withConstantInput}
+ * - Inspect all registered metrics: {@link snapshot}, {@link dump}
+ * - Enable fiber runtime metrics: {@link enableRuntimeMetrics}
+ *
+ * **Gotchas**
+ *
+ * - Counter and gauge metrics can use `number` inputs by default or `bigint` inputs with the `bigint` option
+ * - Incremental counters ignore negative updates; use non-incremental counters only when decreases are meaningful
+ * - {@link update} sets a gauge to an absolute value, while {@link modify} changes it relative to its current value
+ * - Histogram buckets are cumulative and depend on the boundaries supplied when the metric is created
+ * - Summary quantiles are calculated from the configured sliding window, so old observations expire
+ * - Prefer low-cardinality attributes; using unbounded values such as request IDs can create too many metric series
+ *
+ * **Quickstart**
+ *
+ * **Example** (Creating and updating metrics)
  *
  * ```ts
  * import { Effect, Metric } from "effect"
  *
- * // Create metrics
  * const requestCount = Metric.counter("http_requests_total", {
  *   description: "Total number of HTTP requests"
  * })
@@ -51,31 +58,7 @@
  *   boundaries: Metric.linearBoundaries({ start: 0, width: 50, count: 20 })
  * })
  *
- * // Use metrics in your application
  * const handleRequest = Effect.gen(function*() {
- *   yield* Metric.update(requestCount, 1)
- *
- *   const startTime = yield* Effect.clockWith((clock) => clock.currentTimeMillis)
- *
- *   // Process request...
- *   yield* Effect.sleep("100 millis")
- *
- *   const endTime = yield* Effect.clockWith((clock) => clock.currentTimeMillis)
- *   yield* Metric.update(responseTime, endTime - startTime)
- * })
- * ```
- *
- * ## Attributes and Tagging
- *
- * ```ts
- * import { Effect, Metric } from "effect"
- *
- * const requestCount = Metric.counter("requests", {
- *   description: "Number of requests by endpoint and method"
- * })
- *
- * const program = Effect.gen(function*() {
- *   // Add attributes to metrics
  *   yield* Metric.update(
  *     Metric.withAttributes(requestCount, {
  *       endpoint: "/api/users",
@@ -84,57 +67,21 @@
  *     1
  *   )
  *
- *   // Or use withAttributes for compile-time attributes
- *   const taggedCounter = Metric.withAttributes(requestCount, {
- *     endpoint: "/api/posts",
- *     method: "POST"
- *   })
- *   yield* Metric.update(taggedCounter, 1)
- * })
- * ```
- *
- * ## Advanced Examples
- *
- * ```ts
- * import { Effect, Metric } from "effect"
- *
- * // Business metrics
- * const userSignups = Metric.counter("user_signups_total")
- * const activeUsers = Metric.gauge("active_users_current")
- * const featureUsage = Metric.frequency("feature_usage")
+ *   yield* Metric.update(responseTime, 125)
  *
- * // Performance metrics
- * const dbQueryTime = Metric.summary("db_query_duration", {
- *   maxAge: "5 minutes",
- *   maxSize: 1000,
- *   quantiles: [0.5, 0.9, 0.95, 0.99]
+ *   return yield* Metric.value(requestCount)
  * })
+ * ```
  *
- * const program = Effect.gen(function*() {
- *   // Track user signup
- *   yield* Metric.update(userSignups, 1)
- *
- *   // Update active user count
- *   yield* Metric.update(activeUsers, 1250)
- *
- *   // Record feature usage
- *   yield* Metric.update(featureUsage, "dashboard_view")
- *
- *   // Measure database query time
- *   yield* Effect.timed(performDatabaseQuery).pipe(
- *     Effect.tap(([duration]) => Metric.update(dbQueryTime, duration))
- *   )
- * })
+ * **See also**
  *
- * // Get metric snapshots
- * const getMetrics = Effect.gen(function*() {
- *   const snapshots = yield* Metric.snapshot
+ * - {@link counter} / {@link gauge} / {@link frequency} for common metric types
+ * - {@link histogram} / {@link summary} for distribution metrics
+ * - {@link update} / {@link modify} / {@link value} for working with metric state
+ * - {@link withAttributes} for adding dimensions
+ * - {@link snapshot} for exporting all registered metric values
  *
- *   for (const metric of snapshots) {
- *     console.log(`${metric.id}: ${JSON.stringify(metric.state)}`)
- *   }
- * })
- * ```
+ * @since 2.0.0
  */
 import * as Arr from "./Array.js";
 import * as Context from "./Context.js";
@@ -150,7 +97,8 @@ import * as _String from "./String.js";
 /**
  * Service key for the current metric attributes context.
  *
- * @example
+ * **Example** (Using the current attributes key)
+ *
  * ```ts
  * import { Data, Effect, Metric } from "effect"
  *
@@ -192,14 +140,21 @@ import * as _String from "./String.js";
  * })
  * ```
  *
- * @since 4.0.0
  * @category References
+ * @since 4.0.0
  */
 export const CurrentMetricAttributesKey = "effect/Metric/CurrentMetricAttributes";
 /**
- * Service class for managing the current metric attributes context.
+ * `Context.Reference` for metric attributes applied from the current Effect
+ * context.
+ *
+ * **Details**
+ * The default value is an empty attribute set. Metric reads and updates merge
+ * these contextual attributes with the metric's own attributes to select the
+ * metric series being accessed.
+ *
+ * **Example** (Providing current metric attributes)
  *
- * @example
  * ```ts
  * import { Data, Effect, Metric } from "effect"
  *
@@ -227,18 +182,22 @@ export const CurrentMetricAttributesKey = "effect/Metric/CurrentMetricAttributes
  * })
  * ```
  *
- * @since 4.0.0
  * @category References
+ * @since 4.0.0
  */
 export const CurrentMetricAttributes = /*#__PURE__*/Context.Reference(CurrentMetricAttributesKey, {
   defaultValue: () => ({})
 });
 const MetricRegistryKey = "~effect/observability/Metric/MetricRegistryKey";
 /**
- * Service class for accessing the current metric registry.
+ * `Context.Reference` for the metric registry in the current context.
+ *
+ * **Details**
+ * The default registry is an empty `Map`. Metrics register their metadata and
+ * hooks lazily in this map when they are read or updated.
  *
- * @since 4.0.0
  * @category References
+ * @since 4.0.0
  */
 export const MetricRegistry = /*#__PURE__*/Context.Reference(MetricRegistryKey, {
   defaultValue: () => new Map()
@@ -548,7 +507,8 @@ class MetricTransform extends Metric$ {
  * This function is useful for runtime type checking and ensuring that a value
  * conforms to the Metric interface before performing metric operations.
  *
- * @example
+ * **Example** (Checking metric values)
+ *
  * ```ts
  * import { Metric } from "effect"
  *
@@ -562,8 +522,8 @@ class MetricTransform extends Metric$ {
  * console.log(Metric.isMetric(null)) // false
  * ```
  *
- * @since 4.0.0
  * @category Guards
+ * @since 4.0.0
  */
 export const isMetric = u => Predicate.hasProperty(u, "~effect/Metric") && u["~effect/Metric"] === "~effect/Metric";
 /**
@@ -579,7 +539,8 @@ export const isMetric = u => Predicate.hasProperty(u, "~effect/Metric") && u["~e
  * - `incremental` - Set to `true` to create a `Counter` that can only ever be
  *                   incremented.
  *
- * @example
+ * **Example** (Creating counter metrics)
+ *
  * ```ts
  * import { Data, Effect, Metric } from "effect"
  *
@@ -621,8 +582,8 @@ export const isMetric = u => Predicate.hasProperty(u, "~effect/Metric") && u["~e
  * })
  * ```
  *
- * @since 2.0.0
  * @category Constructors
+ * @since 2.0.0
  */
 export const counter = (name, options) => new CounterMetric(name, options);
 /**
@@ -638,7 +599,8 @@ export const counter = (name, options) => new CounterMetric(name, options);
  * - `attributes`  - The attributes to associate with the `Gauge`.
  * - `bigint`      - Indicates if the `Gauge` should use the `bigint` type.
  *
- * @example
+ * **Example** (Creating gauge metrics)
+ *
  * ```ts
  * import { Data, Effect, Metric } from "effect"
  *
@@ -685,8 +647,8 @@ export const counter = (name, options) => new CounterMetric(name, options);
  * })
  * ```
  *
- * @since 2.0.0
  * @category Constructors
+ * @since 2.0.0
  */
 export const gauge = (name, options) => new GaugeMetric(name, options);
 /**
@@ -703,7 +665,8 @@ export const gauge = (name, options) => new GaugeMetric(name, options);
  * - `preregisteredWords` - Occurrences which are pre-registered with the
  *                          `Frequency` metric occurrences.
  *
- * @example
+ * **Example** (Creating frequency metrics)
+ *
  * ```ts
  * import { Data, Effect, Metric } from "effect"
  *
@@ -761,8 +724,8 @@ export const gauge = (name, options) => new GaugeMetric(name, options);
  * })
  * ```
  *
- * @since 2.0.0
  * @category Constructors
+ * @since 2.0.0
  */
 export const frequency = (name, options) => new FrequencyMetric(name, options);
 /**
@@ -777,7 +740,8 @@ export const frequency = (name, options) => new FrequencyMetric(name, options);
  * - `attributes`  - The attributes to associate with the `Histogram`.
  * - `boundaries`  - The bucket boundaries of the `Histogram`
  *
- * @example
+ * **Example** (Creating histogram metrics)
+ *
  * ```ts
  * import { Data, Effect, Metric } from "effect"
  *
@@ -832,8 +796,8 @@ export const frequency = (name, options) => new FrequencyMetric(name, options);
  * })
  * ```
  *
- * @since 2.0.0
  * @category Constructors
+ * @since 2.0.0
  */
 export const histogram = (name, options) => new HistogramMetric(name, options);
 /**
@@ -851,7 +815,8 @@ export const histogram = (name, options) => new HistogramMetric(name, options);
  * - `maxSize`     - The maximum number of observations to keep.
  * - `quantiles`   - An array of quantiles to calculate (e.g., [0.5, 0.9]).
  *
- * @example
+ * **Example** (Creating summary metrics)
+ *
  * ```ts
  * import { Data, Duration, Effect, Metric } from "effect"
  *
@@ -877,13 +842,10 @@ export const histogram = (name, options) => new HistogramMetric(name, options);
  *     attributes: { service: "upload-service" }
  *   })
  *
- *   // Simulate recording various response times over time
- *   for (let i = 0; i < 20; i++) {
- *     const responseTime = 50 + Math.random() * 200 // 50-250ms
+ *   // Record deterministic response times
+ *   const responseTimes = [82, 96, 104, 118, 135, 170, 210, 240]
+ *   for (const responseTime of responseTimes) {
  *     yield* Metric.update(responseTimeSummary, responseTime)
- *
- *     // Wait a bit to simulate different timestamps
- *     yield* Effect.sleep(Duration.millis(100))
  *   }
  *
  *   // Record some payload sizes
@@ -896,28 +858,37 @@ export const histogram = (name, options) => new HistogramMetric(name, options);
  *   const responseStats = yield* Metric.value(responseTimeSummary)
  *   const payloadStats = yield* Metric.value(payloadSizeSummary)
  *
- *   // responseStats will contain:
- *   // - quantiles: [[0.5, Some(125)], [0.9, Some(220)], [0.95, Some(235)], [0.99, Some(245)]]
- *   // - count: 20, min: ~50, max: ~250, sum: ~2500
- *   // - Only observations from the last 5 minutes are included
+ *   console.log({
+ *     count: responseStats.count,
+ *     min: responseStats.min,
+ *     max: responseStats.max,
+ *     sum: responseStats.sum
+ *   }) // { count: 8, min: 82, max: 240, sum: 1155 }
+ *
+ *   console.log({
+ *     count: payloadStats.count,
+ *     min: payloadStats.min,
+ *     max: payloadStats.max,
+ *     sum: payloadStats.sum
+ *   }) // { count: 4, min: 1.2, max: 15.6, sum: 26 }
  *
- *   // payloadStats will contain quantile information for recent payload sizes
- *   // Older observations automatically age out based on maxAge setting
+ *   // Both summaries include quantile information for their configured windows.
  *
  *   return { responseStats, payloadStats }
  * })
  * ```
  *
- * @since 2.0.0
  * @category Constructors
+ * @since 2.0.0
  */
 export const summary = (name, options) => mapInput(summaryWithTimestamp(name, options), (input, context) => [input, Context.get(context, InternalEffect.ClockRef).currentTimeMillisUnsafe()]);
 /**
- * Creates a `Summary` metric that records observations and calculates quantiles
- * which takes a value and the current timestamp as input.
+ * Creates a `Summary` metric that records observations with explicit
+ * timestamps and calculates quantiles.
  *
- * Summary metrics are most suitable for providing statistical information about
- * a set of values, including quantiles.
+ * Summary metrics are most suitable for statistical information about a set of
+ * values. Inputs to this metric are `[value, timestamp]` pairs; the current
+ * clock is used when reading quantiles against the configured `maxAge`.
  *
  * **Options**
  *
@@ -927,7 +898,8 @@ export const summary = (name, options) => mapInput(summaryWithTimestamp(name, op
  * - `maxSize`     - The maximum number of observations to keep.
  * - `quantiles`   - An array of quantiles to calculate (e.g., [0.5, 0.9]).
  *
- * @example
+ * **Example** (Creating summaries with explicit timestamps)
+ *
  * ```ts
  * import { Metric } from "effect"
  *
@@ -942,8 +914,8 @@ export const summary = (name, options) => mapInput(summaryWithTimestamp(name, op
  * )
  * ```
  *
- * @since 2.0.0
  * @category Constructors
+ * @since 2.0.0
  */
 export const summaryWithTimestamp = (name, options) => new SummaryMetric(name, options);
 /**
@@ -956,7 +928,8 @@ export const summaryWithTimestamp = (name, options) => new SummaryMetric(name, o
  * If `options.boundaries` is not provided, the boundaries will be computed
  * using `Metric.exponentialBoundaries({ start: 0.5, factor: 2, count: 35 })`.
  *
- * @example
+ * **Example** (Recording durations with a timer)
+ *
  * ```ts
  * import { Data, Duration, Effect, Metric } from "effect"
  *
@@ -970,19 +943,23 @@ export const summaryWithTimestamp = (name, options) => new SummaryMetric(name, o
  *   attributes: { service: "user-api" }
  * })
  *
- * // Simulate an API operation and measure its duration
+ * // Record a measured API operation duration
  * const apiOperation = Effect.gen(function*() {
- *   const start = Date.now()
- *   yield* Effect.sleep(Duration.millis(100)) // Simulate work
- *   const duration = Duration.millis(Date.now() - start)
- *
- *   // Update the timer with the measured duration
+ *   const duration = Duration.millis(120)
  *   yield* Metric.update(apiRequestTimer, duration)
+ *
+ *   const state = yield* Metric.value(apiRequestTimer)
+ *   console.log({
+ *     count: state.count,
+ *     min: state.min,
+ *     max: state.max,
+ *     sum: state.sum
+ *   }) // { count: 1, min: 120, max: 120, sum: 120 }
  * })
  * ```
  *
- * @since 2.0.0
  * @category Constructors
+ * @since 2.0.0
  */
 export const timer = (name, options) => {
   const boundaries = Predicate.isNotUndefined(options?.boundaries) ? options.boundaries : exponentialBoundaries({
@@ -1003,15 +980,17 @@ export const timer = (name, options) => {
 /**
  * Retrieves the current state of the specified `Metric`.
  *
- * This function returns an Effect that, when executed, will provide the current
- * aggregated state of the metric. The state type depends on the metric type:
- * - Counter: `{ count: number | bigint }`
- * - Gauge: `{ value: number | bigint }`
- * - Frequency: `{ occurrences: Map<string, number> }`
- * - Histogram: `{ buckets: Array<[number, number]>, count: number, min: number, max: number, sum: number }`
- * - Summary: `{ quantiles: Array<[number, number | undefined]>, count: number, min: number, max: number, sum: number }`
+ * **Details**
+ * The returned state depends on the metric type:
+ *
+ * - Counter: `CounterState<number | bigint>` with `count` and `incremental`
+ * - Gauge: `GaugeState<number | bigint>` with `value`
+ * - Frequency: `FrequencyState` with `occurrences`
+ * - Histogram: `HistogramState` with buckets, count, min, max, and sum
+ * - Summary: `SummaryState` with quantiles, count, min, max, and sum
+ *
+ * **Example** (Reading metric state)
  *
- * @example
  * ```ts
  * import { Effect, Metric } from "effect"
  *
@@ -1039,8 +1018,8 @@ export const timer = (name, options) => {
  * })
  * ```
  *
- * @since 2.0.0
  * @category Utilities
+ * @since 2.0.0
  */
 export const value = self => InternalEffect.flatMap(InternalEffect.context(), context => InternalEffect.sync(() => self.valueUnsafe(context)));
 /**
@@ -1053,7 +1032,8 @@ export const value = self => InternalEffect.flatMap(InternalEffect.context(), co
  * - **Histogram**: Same as `update` - records the input value in the appropriate bucket
  * - **Summary**: Same as `update` - records the input observation
  *
- * @example
+ * **Example** (Modifying metric values)
+ *
  * ```ts
  * import { Effect, Metric } from "effect"
  *
@@ -1080,8 +1060,8 @@ export const value = self => InternalEffect.flatMap(InternalEffect.context(), co
  * })
  * ```
  *
- * @since 2.0.0
  * @category Utilities
+ * @since 2.0.0
  */
 export const modify = /*#__PURE__*/dual(2, (self, input) => InternalEffect.flatMap(InternalEffect.context(), context => InternalEffect.sync(() => self.modifyUnsafe(input, context))));
 /**
@@ -1094,7 +1074,8 @@ export const modify = /*#__PURE__*/dual(2, (self, input) => InternalEffect.flatM
  * - **Histogram**: Records the input value in the appropriate bucket
  * - **Summary**: Records the input value as a new observation
  *
- * @example
+ * **Example** (Updating metric values)
+ *
  * ```ts
  * import { Effect, Metric } from "effect"
  *
@@ -1130,8 +1111,8 @@ export const modify = /*#__PURE__*/dual(2, (self, input) => InternalEffect.flatM
  * })
  * ```
  *
- * @since 2.0.0
  * @category Utilities
+ * @since 2.0.0
  */
 export const update = /*#__PURE__*/dual(2, (self, input) => InternalEffect.contextWith(services => InternalEffect.sync(() => self.updateUnsafe(input, services))));
 /**
@@ -1139,7 +1120,8 @@ export const update = /*#__PURE__*/dual(2, (self, input) => InternalEffect.conte
  * of the specified new type, which must be transformable to the input type of
  * this metric.
  *
- * @example
+ * **Example** (Mapping metric inputs)
+ *
  * ```ts
  * import { Data, Effect, Metric } from "effect"
  *
@@ -1169,8 +1151,8 @@ export const update = /*#__PURE__*/dual(2, (self, input) => InternalEffect.conte
  * })
  * ```
  *
- * @since 2.0.0
  * @category Mapping
+ * @since 2.0.0
  */
 export const mapInput = /*#__PURE__*/dual(2, (self, f) => new MetricTransform(self, context => self.valueUnsafe(context), (input, context) => self.updateUnsafe(f(input, context), context), (input, context) => self.modifyUnsafe(f(input, context), context)));
 /**
@@ -1178,7 +1160,8 @@ export const mapInput = /*#__PURE__*/dual(2, (self, f) => new MetricTransform(se
  * of any type, and translates them to updates with the specified constant
  * update value.
  *
- * @example
+ * **Example** (Ignoring inputs with a constant value)
+ *
  * ```ts
  * import { Data, Effect, Metric } from "effect"
  *
@@ -1205,8 +1188,8 @@ export const mapInput = /*#__PURE__*/dual(2, (self, f) => new MetricTransform(se
  * })
  * ```
  *
- * @since 2.0.0
  * @category Input
+ * @since 2.0.0
  */
 export const withConstantInput = /*#__PURE__*/dual(2, (self, input) => mapInput(self, () => input));
 /**
@@ -1216,7 +1199,8 @@ export const withConstantInput = /*#__PURE__*/dual(2, (self, input) => mapInput(
  * enabling filtering, grouping, and more detailed analysis. Each combination
  * of attribute values creates a separate metric series.
  *
- * @example
+ * **Example** (Applying metric attributes)
+ *
  * ```ts
  * import { Effect, Metric } from "effect"
  *
@@ -1261,8 +1245,8 @@ export const withConstantInput = /*#__PURE__*/dual(2, (self, input) => mapInput(
  * })
  * ```
  *
- * @since 4.0.0
  * @category Attributes
+ * @since 4.0.0
  */
 export const withAttributes = /*#__PURE__*/dual(2, (self, attributes) => new MetricTransform(self, context => self.valueUnsafe(addAttributesToContext(context, attributes)), (input, context) => self.updateUnsafe(input, addAttributesToContext(context, attributes)), (input, context) => self.modifyUnsafe(input, addAttributesToContext(context, attributes))));
 // Metric Snapshots
@@ -1272,7 +1256,8 @@ export const withAttributes = /*#__PURE__*/dual(2, (self, attributes) => new Met
  * Returns an array of metric snapshots, each containing the metric's metadata
  * (name, description, type) and current state (values, counts, etc.).
  *
- * @example
+ * **Example** (Capturing metric snapshots)
+ *
  * ```ts
  * import { Console, Data, Effect, Metric } from "effect"
  *
@@ -1311,8 +1296,8 @@ export const withAttributes = /*#__PURE__*/dual(2, (self, attributes) => new Met
  * })
  * ```
  *
- * @since 2.0.0
  * @category Snapshotting
+ * @since 2.0.0
  */
 export const snapshot = /*#__PURE__*/InternalEffect.map(/*#__PURE__*/InternalEffect.context(), context => snapshotUnsafe(context));
 /**
@@ -1323,7 +1308,8 @@ export const snapshot = /*#__PURE__*/InternalEffect.map(/*#__PURE__*/InternalEff
  * in an easy-to-read table showing names, descriptions, types, attributes,
  * and current state values.
  *
- * @example
+ * **Example** (Dumping metrics as text)
+ *
  * ```ts
  * import { Console, Data, Effect, Metric } from "effect"
  *
@@ -1366,8 +1352,8 @@ export const snapshot = /*#__PURE__*/InternalEffect.map(/*#__PURE__*/InternalEff
  * })
  * ```
  *
- * @since 2.0.0
  * @category Debugging
+ * @since 2.0.0
  */
 export const dump = /*#__PURE__*/InternalEffect.flatMap(/*#__PURE__*/InternalEffect.context(), context => {
   const metrics = snapshotUnsafe(context);
@@ -1403,7 +1389,8 @@ export const dump = /*#__PURE__*/InternalEffect.flatMap(/*#__PURE__*/InternalEff
  * manual handling of the services context. Use the safe `snapshot` function for normal
  * application code.
  *
- * @example
+ * **Example** (Capturing snapshots from a context)
+ *
  * ```ts
  * import { Data, Effect, Metric } from "effect"
  *
@@ -1430,13 +1417,14 @@ export const dump = /*#__PURE__*/InternalEffect.flatMap(/*#__PURE__*/InternalEff
  *
  *   // Use snapshotUnsafe for direct, synchronous access
  *   const snapshots = Metric.snapshotUnsafe(services)
+ *   const exportBatchCreatedAt = 1_700_000_000_000
  *
  *   // Process snapshots immediately (useful for exporters, debugging tools)
  *   const exportData = snapshots.map((snapshot) => ({
  *     name: snapshot.id,
  *     type: snapshot.type,
  *     value: snapshot.state,
- *     timestamp: Date.now()
+ *     timestamp: exportBatchCreatedAt
  *   }))
  *
  *   // This is synchronous and doesn't involve Effect overhead
@@ -1452,8 +1440,8 @@ export const dump = /*#__PURE__*/InternalEffect.flatMap(/*#__PURE__*/InternalEff
  * })
  * ```
  *
- * @since 2.0.0
  * @category Snapshotting
+ * @since 2.0.0
  */
 export const snapshotUnsafe = context => {
   const registry = Context.get(context, MetricRegistry);
@@ -1529,7 +1517,8 @@ const attributesToString = attributes => {
  * non-positive values, and automatically appending positive infinity as the
  * final boundary.
  *
- * @example
+ * **Example** (Creating boundaries from values)
+ *
  * ```ts
  * import { Data, Effect, Metric } from "effect"
  *
@@ -1583,18 +1572,22 @@ const attributesToString = attributes => {
  * })
  * ```
  *
- * @since 2.0.0
  * @category Boundaries
+ * @since 2.0.0
  */
 export const boundariesFromIterable = iterable => Arr.append(Arr.filter(new Set(iterable), n => n > 0), Number.POSITIVE_INFINITY);
 /**
- * A helper method to create histogram bucket boundaries with linearly
- * increasing values.
+ * Creates histogram bucket boundaries from a linear sequence and appends
+ * positive infinity.
+ *
+ * **Details**
+ * Generates `count - 1` finite boundaries using `start + width + index` for
+ * each zero-based index, then applies the same normalization as
+ * `boundariesFromIterable`: non-positive values are removed, duplicates are
+ * collapsed, and `Infinity` is appended.
  *
- * Creates evenly-spaced boundaries starting from a base value and incrementing
- * by a fixed width. Automatically adds positive infinity as the final boundary.
+ * **Example** (Creating linear boundaries)
  *
- * @example
  * ```ts
  * import { Data, Effect, Metric } from "effect"
  *
@@ -1603,13 +1596,12 @@ export const boundariesFromIterable = iterable => Arr.append(Arr.filter(new Set(
  * }> {}
  *
  * // Create boundaries for response time histogram
- * // Buckets: 0-100ms, 100-200ms, 200-300ms, 300-400ms, 400ms+
  * const responseBoundaries = Metric.linearBoundaries({
  *   start: 0, // Starting point
- *   width: 100, // 100ms intervals
+ *   width: 100, // Offset used for the first boundary
  *   count: 5 // Creates 4 boundaries + infinity
  * })
- * console.log(responseBoundaries) // [100, 200, 300, 400, Infinity]
+ * console.log(responseBoundaries) // [100, 101, 102, 103, Infinity]
  *
  * // Create a histogram using these boundaries
  * const responseTimeHistogram = Metric.histogram("api_response_time", {
@@ -1619,17 +1611,17 @@ export const boundariesFromIterable = iterable => Arr.append(Arr.filter(new Set(
  *
  * const program = Effect.gen(function*() {
  *   // Record some response times
- *   yield* Metric.update(responseTimeHistogram, 85) // Goes in 0-100ms bucket
- *   yield* Metric.update(responseTimeHistogram, 250) // Goes in 200-300ms bucket
- *   yield* Metric.update(responseTimeHistogram, 450) // Goes in 400ms+ bucket
+ *   yield* Metric.update(responseTimeHistogram, 85)
+ *   yield* Metric.update(responseTimeHistogram, 101)
+ *   yield* Metric.update(responseTimeHistogram, 450)
  *
  *   const value = yield* Metric.value(responseTimeHistogram)
  *   return value
  * })
  * ```
  *
- * @since 2.0.0
  * @category Boundaries
+ * @since 2.0.0
  */
 export const linearBoundaries = options => boundariesFromIterable(Arr.makeBy(options.count - 1, n => options.start + n + options.width));
 /**
@@ -1639,7 +1631,8 @@ export const linearBoundaries = options => boundariesFromIterable(Arr.makeBy(opt
  * Creates boundaries that grow exponentially, useful for metrics that span
  * multiple orders of magnitude. Each boundary is calculated as start * factor^i.
  *
- * @example
+ * **Example** (Creating exponential boundaries)
+ *
  * ```ts
  * import { Data, Effect, Metric } from "effect"
  *
@@ -1680,8 +1673,8 @@ export const linearBoundaries = options => boundariesFromIterable(Arr.makeBy(opt
  * })
  * ```
  *
- * @since 2.0.0
  * @category Boundaries
+ * @since 2.0.0
  */
 export const exponentialBoundaries = options => boundariesFromIterable(Arr.makeBy(options.count - 1, i => options.start * Math.pow(options.factor, i)));
 // Fiber Runtime Metrics
@@ -1703,7 +1696,8 @@ const fiberFailures = /*#__PURE__*/counter("child_fiber_failures", {
 /**
  * Service key for the fiber runtime metrics service.
  *
- * @example
+ * **Example** (Using the fiber runtime metrics key)
+ *
  * ```ts
  * import { Data, Effect, Layer, Metric } from "effect"
  *
@@ -1733,14 +1727,20 @@ const fiberFailures = /*#__PURE__*/counter("child_fiber_failures", {
  * })
  * ```
  *
- * @since 4.0.0
  * @category Runtime Metrics
+ * @since 4.0.0
  */
 export const FiberRuntimeMetricsKey = InternalMetric.FiberRuntimeMetricsKey;
 /**
- * Service class for managing fiber runtime metrics collection.
+ * `Context.Reference` for the optional fiber runtime metrics service.
+ *
+ * **Details**
+ * When provided, the runtime can notify the service about child-fiber start and
+ * end events. When the reference is `undefined`, automatic fiber runtime metric
+ * collection is disabled.
+ *
+ * **Example** (Accessing the fiber runtime metrics service)
  *
- * @example
  * ```ts
  * import { Data, Effect, Metric } from "effect"
  *
@@ -1779,8 +1779,8 @@ export const FiberRuntimeMetricsKey = InternalMetric.FiberRuntimeMetricsKey;
  * })
  * ```
  *
- * @since 4.0.0
  * @category Runtime Metrics
+ * @since 4.0.0
  */
 export const FiberRuntimeMetrics = /*#__PURE__*/Context.Reference(InternalMetric.FiberRuntimeMetricsKey, {
   defaultValue: constUndefined
@@ -1788,7 +1788,8 @@ export const FiberRuntimeMetrics = /*#__PURE__*/Context.Reference(InternalMetric
 /**
  * Default implementation of the fiber runtime metrics service.
  *
- * @example
+ * **Example** (Using the default fiber metrics implementation)
+ *
  * ```ts
  * import { Data, Effect, Layer, Metric } from "effect"
  *
@@ -1826,8 +1827,8 @@ export const FiberRuntimeMetrics = /*#__PURE__*/Context.Reference(InternalMetric
  * })
  * ```
  *
- * @since 4.0.0
  * @category Runtime Metrics
+ * @since 4.0.0
  */
 export const FiberRuntimeMetricsImpl = {
   recordFiberStart(context) {
@@ -1852,7 +1853,8 @@ export const FiberRuntimeMetricsImpl = {
  * the recommended approach for production applications that need comprehensive
  * fiber monitoring.
  *
- * @example
+ * **Example** (Enabling runtime metrics with a layer)
+ *
  * ```ts
  * import { Console, Data, Effect, Layer, Metric } from "effect"
  *
@@ -1937,14 +1939,15 @@ export const FiberRuntimeMetricsImpl = {
  * )
  * ```
  *
- * @since 4.0.0
  * @category Runtime Metrics
+ * @since 4.0.0
  */
 export const enableRuntimeMetricsLayer = /*#__PURE__*/Layer.succeed(FiberRuntimeMetrics)(FiberRuntimeMetricsImpl);
 /**
  * A Layer that disables automatic collection of fiber runtime metrics.
  *
- * @example
+ * **Example** (Disabling runtime metrics with a layer)
+ *
  * ```ts
  * import { Data, Effect, Metric } from "effect"
  *
@@ -1976,8 +1979,8 @@ export const enableRuntimeMetricsLayer = /*#__PURE__*/Layer.succeed(FiberRuntime
  * })
  * ```
  *
- * @since 4.0.0
  * @category Runtime Metrics
+ * @since 4.0.0
  */
 export const disableRuntimeMetricsLayer = /*#__PURE__*/Layer.succeed(FiberRuntimeMetrics)(undefined);
 /**
@@ -1987,7 +1990,8 @@ export const disableRuntimeMetricsLayer = /*#__PURE__*/Layer.succeed(FiberRuntim
  * started fibers, successful completions, and failures. These metrics provide valuable
  * insights into the concurrency patterns and health of your Effect application.
  *
- * @example
+ * **Example** (Enabling runtime metrics for an effect)
+ *
  * ```ts
  * import { Console, Data, Effect, Layer, Metric } from "effect"
  *
@@ -2056,8 +2060,8 @@ export const disableRuntimeMetricsLayer = /*#__PURE__*/Layer.succeed(FiberRuntim
  * )
  * ```
  *
- * @since 4.0.0
  * @category Runtime Metrics
+ * @since 4.0.0
  */
 export const enableRuntimeMetrics = /*#__PURE__*/InternalEffect.provideService(FiberRuntimeMetrics, FiberRuntimeMetricsImpl);
 /**
@@ -2067,7 +2071,8 @@ export const enableRuntimeMetrics = /*#__PURE__*/InternalEffect.provideService(F
  * parts of your application while keeping them enabled elsewhere, or when you need
  * to avoid the overhead of metrics collection in performance-critical sections.
  *
- * @example
+ * **Example** (Disabling runtime metrics for an effect)
+ *
  * ```ts
  * import { Console, Data, Effect, Layer, Metric } from "effect"
  *
@@ -2095,7 +2100,7 @@ export const enableRuntimeMetrics = /*#__PURE__*/InternalEffect.provideService(F
  *         (_, i) =>
  *           Effect.gen(function*() {
  *             // Simulate intensive computation
- *             const result = i * i + Math.random()
+ *             const result = i * i + (i % 10) / 10
  *             return result
  *           })
  *       )
@@ -2137,8 +2142,8 @@ export const enableRuntimeMetrics = /*#__PURE__*/InternalEffect.provideService(F
  * )
  * ```
  *
- * @since 4.0.0
  * @category Runtime Metrics
+ * @since 4.0.0
  */
 export const disableRuntimeMetrics = /*#__PURE__*/InternalEffect.provideService(FiberRuntimeMetrics, undefined);
 // Utilities