effect 4.0.0-beta.66 → 4.0.0-beta.68

package/src/Metric.ts

@@ -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")
+ * **See also**
  *
- *   // Measure database query time
- *   yield* Effect.timed(performDatabaseQuery).pipe(
- *     Effect.tap(([duration]) => Metric.update(dbQueryTime, duration))
- *   )
- * })
+ * - {@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
  *
- * // Get metric snapshots
- * const getMetrics = Effect.gen(function*() {
- *   const snapshots = yield* Metric.snapshot
- *
- *   for (const metric of snapshots) {
- *     console.log(`${metric.id}: ${JSON.stringify(metric.state)}`)
- *   }
- * })
- * ```
+ * @since 2.0.0
  */
 
 import * as Arr from "./Array.ts"
@@ -170,7 +117,8 @@ import type { Contravariant, Covariant } from "./Types.ts"
  *   - Histograms
  *   - Summaries
  *
- * @example
+ * **Example** (Using multiple metric types)
+ *
  * ```ts
  * import { Data, Effect, Metric } from "effect"
  *
@@ -224,8 +172,8 @@ import type { Contravariant, Covariant } from "./Types.ts"
  * })
  * ```
  *
+ * @category models
  * @since 2.0.0
- * @category Models
  */
 export interface Metric<in Input, out State> extends Pipeable {
   readonly [TypeId]: typeof TypeId
@@ -246,7 +194,8 @@ export interface Metric<in Input, out State> extends Pipeable {
  * Counters are useful for tracking monotonically increasing values like request counts,
  * bytes processed, errors encountered, or any value that accumulates over time.
  *
- * @example
+ * **Example** (Using counter metrics)
+ *
  * ```ts
  * import { Data, Effect, Metric } from "effect"
  *
@@ -300,15 +249,16 @@ export interface Metric<in Input, out State> extends Pipeable {
  * })
  * ```
  *
- * @since 2.0.0
  * @category Metrics
+ * @since 2.0.0
  */
 export interface Counter<in Input extends number | bigint> extends Metric<Input, CounterState<Input>> {}
 
 /**
  * State interface for Counter metrics containing the current count and increment mode.
  *
- * @example
+ * **Example** (Reading counter state)
+ *
  * ```ts
  * import { Data, Effect, Metric } from "effect"
  *
@@ -361,8 +311,8 @@ export interface Counter<in Input extends number | bigint> extends Metric<Input,
  * })
  * ```
  *
- * @since 2.0.0
  * @category Counter
+ * @since 4.0.0
  */
 export interface CounterState<in Input extends number | bigint> {
   readonly count: Input extends bigint ? bigint : number
@@ -376,7 +326,8 @@ export interface CounterState<in Input extends number | bigint> {
  * how many times specific string values occur, such as HTTP status codes, user actions,
  * error types, or any discrete string-based events.
  *
- * @example
+ * **Example** (Using frequency metrics)
+ *
  * ```ts
  * import { Data, Effect, Metric } from "effect"
  *
@@ -446,15 +397,16 @@ export interface CounterState<in Input extends number | bigint> {
  * })
  * ```
  *
- * @since 2.0.0
  * @category Metrics
+ * @since 2.0.0
  */
 export interface Frequency extends Metric<string, FrequencyState> {}
 
 /**
  * State interface for Frequency metrics containing occurrence counts for discrete string values.
  *
- * @example
+ * **Example** (Reading frequency state)
+ *
  * ```ts
  * import { Data, Effect, Metric } from "effect"
  *
@@ -530,8 +482,8 @@ export interface Frequency extends Metric<string, FrequencyState> {}
  * })
  * ```
  *
- * @since 2.0.0
  * @category Metrics
+ * @since 4.0.0
  */
 export interface FrequencyState {
   readonly occurrences: ReadonlyMap<string, number>
@@ -543,7 +495,8 @@ export interface FrequencyState {
  * Gauges are useful for tracking current state values like memory usage, CPU load,
  * active connections, queue sizes, or any value that represents a current level.
  *
- * @example
+ * **Example** (Using gauge metrics)
+ *
  * ```ts
  * import { Data, Effect, Metric } from "effect"
  *
@@ -590,15 +543,16 @@ export interface FrequencyState {
  * })
  * ```
  *
- * @since 2.0.0
  * @category Metrics
+ * @since 2.0.0
  */
 export interface Gauge<in Input extends number | bigint> extends Metric<Input, GaugeState<Input>> {}
 
 /**
  * State interface for Gauge metrics containing the current instantaneous value.
  *
- * @example
+ * **Example** (Reading gauge state)
+ *
  * ```ts
  * import { Data, Effect, Metric } from "effect"
  *
@@ -658,8 +612,8 @@ export interface Gauge<in Input extends number | bigint> extends Metric<Input, G
  * })
  * ```
  *
- * @since 2.0.0
  * @category Metrics
+ * @since 4.0.0
  */
 export interface GaugeState<in Input extends number | bigint> {
   readonly value: Input extends bigint ? bigint : number
@@ -671,7 +625,8 @@ export interface GaugeState<in Input extends number | bigint> {
  * Histograms are ideal for measuring request durations, response sizes, and other continuous values
  * where you need to understand the distribution of values rather than just aggregates.
  *
- * @example
+ * **Example** (Using histogram metrics)
+ *
  * ```ts
  * import { Data, Effect, Metric } from "effect"
  *
@@ -746,15 +701,16 @@ export interface GaugeState<in Input extends number | bigint> {
  * })
  * ```
  *
- * @since 2.0.0
  * @category Metrics
+ * @since 2.0.0
  */
 export interface Histogram<Input> extends Metric<Input, HistogramState> {}
 
 /**
  * State interface for Histogram metrics containing bucket distributions and aggregate statistics.
  *
- * @example
+ * **Example** (Reading histogram state)
+ *
  * ```ts
  * import { Data, Effect, Metric } from "effect"
  *
@@ -832,8 +788,8 @@ export interface Histogram<Input> extends Metric<Input, HistogramState> {}
  * })
  * ```
  *
- * @since 2.0.0
  * @category Metrics
+ * @since 4.0.0
  */
 export interface HistogramState {
   readonly buckets: ReadonlyArray<[number, number]>
@@ -850,7 +806,8 @@ export interface HistogramState {
  * (percentiles) such as median (50th), 95th percentile, 99th percentile, etc. They're ideal for
  * understanding performance characteristics like response time distributions.
  *
- * @example
+ * **Example** (Using summary metrics)
+ *
  * ```ts
  * import { Data, Effect, Metric } from "effect"
  *
@@ -935,15 +892,16 @@ export interface HistogramState {
  * })
  * ```
  *
- * @since 2.0.0
  * @category Metrics
+ * @since 2.0.0
  */
 export interface Summary<Input> extends Metric<Input, SummaryState> {}
 
 /**
  * State interface for Summary metrics containing quantile calculations and aggregate statistics.
  *
- * @example
+ * **Example** (Reading summary state)
+ *
  * ```ts
  * import { Data, Effect, Metric } from "effect"
  *
@@ -1016,8 +974,8 @@ export interface Summary<Input> extends Metric<Input, SummaryState> {}
  * })
  * ```
  *
- * @since 2.0.0
  * @category Metrics
+ * @since 4.0.0
  */
 export interface SummaryState {
   readonly quantiles: ReadonlyArray<readonly [number, number | undefined]>
@@ -1031,7 +989,8 @@ export interface SummaryState {
  * The `Metric` namespace provides a comprehensive system for collecting, aggregating, and observing
  * application metrics in Effect applications.
  *
- * @example
+ * **Example** (Collecting application metrics)
+ *
  * ```ts
  * import { Data, Effect, Metric } from "effect"
  *
@@ -1070,13 +1029,13 @@ export interface SummaryState {
  * ```
  *
  * @since 2.0.0
- * @category models
  */
 export declare namespace Metric {
   /**
    * Union type representing all available metric types in the Effect metrics system.
    *
-   * @example
+   * **Example** (Inspecting metric types)
+   *
    * ```ts
    * import { Data, Effect, Metric } from "effect"
    *
@@ -1148,15 +1107,16 @@ export declare namespace Metric {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category types
+   * @since 4.0.0
    */
   export type Type = "Counter" | "Frequency" | "Gauge" | "Histogram" | "Summary"
 
   /**
    * Union type for metric attributes that can be provided as either an object or array of tuples.
    *
-   * @example
+   * **Example** (Providing attributes in different formats)
+   *
    * ```ts
    * import { Data, Effect, Metric } from "effect"
    *
@@ -1223,15 +1183,16 @@ export declare namespace Metric {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category types
+   * @since 4.0.0
    */
   export type Attributes = AttributeSet | ReadonlyArray<[string, string]>
 
   /**
    * Type for metric attributes as a readonly record of string key-value pairs.
    *
-   * @example
+   * **Example** (Combining metric attribute sets)
+   *
    * ```ts
    * import { Data, Effect, Metric } from "effect"
    *
@@ -1300,15 +1261,16 @@ export declare namespace Metric {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category types
+   * @since 4.0.0
    */
   export type AttributeSet = Readonly<Record<string, string>>
 
   /**
    * Utility type to extract the Input type from a Metric type.
    *
-   * @example
+   * **Example** (Extracting metric input types)
+   *
    * ```ts
    * import { Metric } from "effect"
    *
@@ -1349,8 +1311,8 @@ export declare namespace Metric {
    * // Metric.update(stringFrequency, 404)   // ✗ Type error
    * ```
    *
-   * @since 2.0.0
    * @category types
+   * @since 4.0.0
    */
   export type Input<A> = A extends Metric<infer _Input, infer _State> ? _Input
     : never
@@ -1358,7 +1320,8 @@ export declare namespace Metric {
   /**
    * Utility type to extract the State type from a Metric type.
    *
-   * @example
+   * **Example** (Extracting metric state types)
+   *
    * ```ts
    * import { Effect, Metric } from "effect"
    *
@@ -1408,8 +1371,8 @@ export declare namespace Metric {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category types
+   * @since 4.0.0
    */
   export type State<A> = A extends Metric<infer _Input, infer _State> ? _State
     : never
@@ -1417,7 +1380,8 @@ export declare namespace Metric {
   /**
    * Interface defining the core hooks for metric operations: get, update, and modify.
    *
-   * @example
+   * **Example** (Using metric hooks)
+   *
    * ```ts
    * import { Data, Effect, Metric } from "effect"
    *
@@ -1453,8 +1417,8 @@ export declare namespace Metric {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category interfaces
+   * @since 4.0.0
    */
   export interface Hooks<in Input, out State> {
     readonly get: (context: Context.Context<never>) => State
@@ -1465,7 +1429,8 @@ export declare namespace Metric {
   /**
    * Interface containing complete metadata information about a metric.
    *
-   * @example
+   * **Example** (Inspecting metric metadata)
+   *
    * ```ts
    * import { Data, Effect, Metric } from "effect"
    *
@@ -1518,8 +1483,8 @@ export declare namespace Metric {
    * })
    * ```
    *
-   * @since 4.0.0
    * @category interfaces
+   * @since 4.0.0
    */
   export interface Metadata<in Input, out State> {
     readonly id: string
@@ -1532,7 +1497,8 @@ export declare namespace Metric {
   /**
    * Protocol interface for metric snapshots containing metadata and current state.
    *
-   * @example
+   * **Example** (Inspecting metric snapshot protocols)
+   *
    * ```ts
    * import { Data, Effect, Metric } from "effect"
    *
@@ -1590,8 +1556,8 @@ export declare namespace Metric {
    * })
    * ```
    *
-   * @since 4.0.0
    * @category interfaces
+   * @since 4.0.0
    */
   export interface SnapshotProto<T extends Type, State> {
     readonly id: string
@@ -1604,7 +1570,8 @@ export declare namespace Metric {
   /**
    * Union type representing all possible metric snapshot types with their corresponding states.
    *
-   * @example
+   * **Example** (Analyzing metric snapshots)
+   *
    * ```ts
    * import { Data, Effect, Metric } from "effect"
    *
@@ -1666,8 +1633,8 @@ export declare namespace Metric {
    * })
    * ```
    *
-   * @since 4.0.0
    * @category types
+   * @since 4.0.0
    */
   export type Snapshot =
     | SnapshotProto<"Counter", CounterState<number | bigint>>
@@ -1680,7 +1647,8 @@ export declare namespace Metric {
 /**
  * Service key for the current metric attributes context.
  *
- * @example
+ * **Example** (Using the current attributes key)
+ *
  * ```ts
  * import { Data, Effect, Metric } from "effect"
  *
@@ -1722,15 +1690,22 @@ export declare namespace Metric {
  * })
  * ```
  *
+ * @category references
  * @since 4.0.0
- * @category References
  */
 export const CurrentMetricAttributesKey = "effect/Metric/CurrentMetricAttributes" as const
 
 /**
- * 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"
  *
@@ -1758,8 +1733,8 @@ export const CurrentMetricAttributesKey = "effect/Metric/CurrentMetricAttributes
  * })
  * ```
  *
+ * @category references
  * @since 4.0.0
- * @category References
  */
 export const CurrentMetricAttributes = Context.Reference<Metric.AttributeSet>(CurrentMetricAttributesKey, {
   defaultValue: () => ({})
@@ -1768,10 +1743,14 @@ export const CurrentMetricAttributes = Context.Reference<Metric.AttributeSet>(Cu
 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.
  *
+ * @category references
  * @since 4.0.0
- * @category References
  */
 export const MetricRegistry = Context.Reference<Map<string, Metric.Metadata<any, any>>>(
   MetricRegistryKey,
@@ -2150,7 +2129,8 @@ class MetricTransform<in Input, out State, in Input2> extends Metric$<Input2, St
  * 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"
  *
@@ -2164,8 +2144,8 @@ class MetricTransform<in Input, out State, in Input2> extends Metric$<Input2, St
  * console.log(Metric.isMetric(null)) // false
  * ```
  *
+ * @category guards
  * @since 4.0.0
- * @category Guards
  */
 export const isMetric = (u: unknown): u is Metric<unknown, never> =>
   Predicate.hasProperty(u, "~effect/Metric") && u["~effect/Metric"] === "~effect/Metric"
@@ -2183,7 +2163,8 @@ export const isMetric = (u: unknown): u is Metric<unknown, never> =>
  * - `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"
  *
@@ -2225,8 +2206,8 @@ export const isMetric = (u: unknown): u is Metric<unknown, never> =>
  * })
  * ```
  *
+ * @category constructors
  * @since 2.0.0
- * @category Constructors
  */
 export const counter: {
   /**
@@ -2242,7 +2223,8 @@ export const counter: {
    * - `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"
    *
@@ -2284,8 +2266,8 @@ export const counter: {
    * })
    * ```
    *
+   * @category constructors
    * @since 2.0.0
-   * @category Constructors
    */
   (
     name: string,
@@ -2309,7 +2291,8 @@ export const counter: {
    * - `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"
    *
@@ -2351,8 +2334,8 @@ export const counter: {
    * })
    * ```
    *
+   * @category constructors
    * @since 2.0.0
-   * @category Constructors
    */
   (
     name: string,
@@ -2378,7 +2361,8 @@ export const counter: {
  * - `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"
  *
@@ -2425,8 +2409,8 @@ export const counter: {
  * })
  * ```
  *
+ * @category constructors
  * @since 2.0.0
- * @category Constructors
  */
 export const gauge: {
   /**
@@ -2442,7 +2426,8 @@ export const gauge: {
    * - `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"
    *
@@ -2489,8 +2474,8 @@ export const gauge: {
    * })
    * ```
    *
+   * @category constructors
    * @since 2.0.0
-   * @category Constructors
    */
   (
     name: string,
@@ -2513,7 +2498,8 @@ export const gauge: {
    * - `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"
    *
@@ -2560,8 +2546,8 @@ export const gauge: {
    * })
    * ```
    *
+   * @category constructors
    * @since 2.0.0
-   * @category Constructors
    */
   (
     name: string,
@@ -2587,7 +2573,8 @@ export const gauge: {
  * - `preregisteredWords` - Occurrences which are pre-registered with the
  *                          `Frequency` metric occurrences.
  *
- * @example
+ * **Example** (Creating frequency metrics)
+ *
  * ```ts
  * import { Data, Effect, Metric } from "effect"
  *
@@ -2645,8 +2632,8 @@ export const gauge: {
  * })
  * ```
  *
+ * @category constructors
  * @since 2.0.0
- * @category Constructors
  */
 export const frequency = (name: string, options?: {
   readonly description?: string | undefined
@@ -2666,7 +2653,8 @@ export const frequency = (name: string, 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"
  *
@@ -2721,8 +2709,8 @@ export const frequency = (name: string, options?: {
  * })
  * ```
  *
+ * @category constructors
  * @since 2.0.0
- * @category Constructors
  */
 export const histogram = (name: string, options: {
   readonly description?: string | undefined
@@ -2745,7 +2733,8 @@ export const histogram = (name: string, 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"
  *
@@ -2771,13 +2760,10 @@ export const histogram = (name: string, 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
@@ -2790,20 +2776,28 @@ export const histogram = (name: string, 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 }
  *
- *   // payloadStats will contain quantile information for recent payload sizes
- *   // Older observations automatically age out based on maxAge setting
+ *   console.log({
+ *     count: payloadStats.count,
+ *     min: payloadStats.min,
+ *     max: payloadStats.max,
+ *     sum: payloadStats.sum
+ *   }) // { count: 4, min: 1.2, max: 15.6, sum: 26 }
+ *
+ *   // Both summaries include quantile information for their configured windows.
  *
  *   return { responseStats, payloadStats }
  * })
  * ```
  *
+ * @category constructors
  * @since 2.0.0
- * @category Constructors
  */
 export const summary = (name: string, options: {
   readonly description?: string | undefined
@@ -2819,11 +2813,12 @@ export const summary = (name: string, options: {
     ] as [number, number])
 
 /**
- * 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**
  *
@@ -2833,7 +2828,8 @@ export const summary = (name: string, 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 summaries with explicit timestamps)
+ *
  * ```ts
  * import { Metric } from "effect"
  *
@@ -2848,8 +2844,8 @@ export const summary = (name: string, options: {
  * )
  * ```
  *
- * @since 2.0.0
- * @category Constructors
+ * @category constructors
+ * @since 4.0.0
  */
 export const summaryWithTimestamp = (name: string, options: {
   readonly description?: string | undefined
@@ -2869,7 +2865,8 @@ export const summaryWithTimestamp = (name: string, options: {
  * 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"
  *
@@ -2883,19 +2880,23 @@ export const summaryWithTimestamp = (name: string, options: {
  *   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 }
  * })
  * ```
  *
+ * @category constructors
  * @since 2.0.0
- * @category Constructors
  */
 export const timer = (name: string, options?: {
   readonly description?: string | undefined
@@ -2913,15 +2914,17 @@ export const timer = (name: string, 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"
  *
@@ -2949,8 +2952,8 @@ export const timer = (name: string, options?: {
  * })
  * ```
  *
+ * @category utils
  * @since 2.0.0
- * @category Utilities
  */
 export const value = <Input, State>(
   self: Metric<Input, State>
@@ -2970,7 +2973,8 @@ export const value = <Input, State>(
  * - **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"
  *
@@ -2997,8 +3001,8 @@ export const value = <Input, State>(
  * })
  * ```
  *
- * @since 2.0.0
- * @category Utilities
+ * @category utils
+ * @since 3.6.5
  */
 export const modify: {
   /**
@@ -3011,7 +3015,8 @@ export const modify: {
    * - **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"
    *
@@ -3038,8 +3043,8 @@ export const modify: {
    * })
    * ```
    *
-   * @since 2.0.0
-   * @category Utilities
+   * @category utils
+   * @since 3.6.5
    */
   <Input>(input: Input): <State>(self: Metric<Input, State>) => Effect<void>
   /**
@@ -3052,7 +3057,8 @@ export const modify: {
    * - **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"
    *
@@ -3079,8 +3085,8 @@ export const modify: {
    * })
    * ```
    *
-   * @since 2.0.0
-   * @category Utilities
+   * @category utils
+   * @since 3.6.5
    */
   <Input, State>(self: Metric<Input, State>, input: Input): Effect<void>
 } = dual<
@@ -3094,7 +3100,8 @@ export const modify: {
    * - **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"
    *
@@ -3121,8 +3128,8 @@ export const modify: {
    * })
    * ```
    *
-   * @since 2.0.0
-   * @category Utilities
+   * @category utils
+   * @since 3.6.5
    */
   <Input>(input: Input) => <State>(self: Metric<Input, State>) => Effect<void>,
   /**
@@ -3135,7 +3142,8 @@ export const modify: {
    * - **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"
    *
@@ -3162,8 +3170,8 @@ export const modify: {
    * })
    * ```
    *
-   * @since 2.0.0
-   * @category Utilities
+   * @category utils
+   * @since 3.6.5
    */
   <Input, State>(self: Metric<Input, State>, input: Input) => Effect<void>
 >(2, (self, input) =>
@@ -3182,7 +3190,8 @@ export const modify: {
  * - **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"
  *
@@ -3218,8 +3227,8 @@ export const modify: {
  * })
  * ```
  *
+ * @category utils
  * @since 2.0.0
- * @category Utilities
  */
 export const update: {
   /**
@@ -3232,7 +3241,8 @@ export const update: {
    * - **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"
    *
@@ -3268,8 +3278,8 @@ export const update: {
    * })
    * ```
    *
+   * @category utils
    * @since 2.0.0
-   * @category Utilities
    */
   <Input>(input: Input): <State>(self: Metric<Input, State>) => Effect<void>
   /**
@@ -3282,7 +3292,8 @@ export const update: {
    * - **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"
    *
@@ -3318,8 +3329,8 @@ export const update: {
    * })
    * ```
    *
+   * @category utils
    * @since 2.0.0
-   * @category Utilities
    */
   <Input, State>(self: Metric<Input, State>, input: Input): Effect<void>
 } = dual<
@@ -3333,7 +3344,8 @@ export const update: {
    * - **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"
    *
@@ -3369,8 +3381,8 @@ export const update: {
    * })
    * ```
    *
+   * @category utils
    * @since 2.0.0
-   * @category Utilities
    */
   <Input>(input: Input) => <State>(self: Metric<Input, State>) => Effect<void>,
   /**
@@ -3383,7 +3395,8 @@ export const update: {
    * - **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"
    *
@@ -3419,8 +3432,8 @@ export const update: {
    * })
    * ```
    *
+   * @category utils
    * @since 2.0.0
-   * @category Utilities
    */
   <Input, State>(self: Metric<Input, State>, input: Input) => Effect<void>
 >(
@@ -3434,7 +3447,8 @@ export const update: {
  * 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"
  *
@@ -3464,8 +3478,8 @@ export const update: {
  * })
  * ```
  *
+ * @category mapping
  * @since 2.0.0
- * @category Mapping
  */
 export const mapInput: {
   /**
@@ -3473,7 +3487,8 @@ export const mapInput: {
    * 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"
    *
@@ -3503,8 +3518,8 @@ export const mapInput: {
    * })
    * ```
    *
+   * @category mapping
    * @since 2.0.0
-   * @category Mapping
    */
   <Input, Input2 extends Input>(f: (input: Input2, context: Context.Context<never>) => Input): <State>(self: Metric<Input, State>) => Metric<Input2, State>
   /**
@@ -3512,7 +3527,8 @@ export const mapInput: {
    * 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"
    *
@@ -3542,8 +3558,8 @@ export const mapInput: {
    * })
    * ```
    *
+   * @category mapping
    * @since 2.0.0
-   * @category Mapping
    */
   <Input, State, Input2>(
     self: Metric<Input, State>,
@@ -3555,7 +3571,8 @@ export const mapInput: {
    * 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"
    *
@@ -3585,8 +3602,8 @@ export const mapInput: {
    * })
    * ```
    *
+   * @category mapping
    * @since 2.0.0
-   * @category Mapping
    */
   <Input, Input2 extends Input>(f: (input: Input2, context: Context.Context<never>) => Input) => <State>(self: Metric<Input, State>) => Metric<Input2, State>,
   /**
@@ -3594,7 +3611,8 @@ export const mapInput: {
    * 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"
    *
@@ -3624,8 +3642,8 @@ export const mapInput: {
    * })
    * ```
    *
+   * @category mapping
    * @since 2.0.0
-   * @category Mapping
    */
   <Input, State, Input2>(
     self: Metric<Input, State>,
@@ -3647,7 +3665,8 @@ export const mapInput: {
  * 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"
  *
@@ -3674,8 +3693,8 @@ export const mapInput: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category Input
+ * @since 2.0.0
  */
 export const withConstantInput: {
   /**
@@ -3683,7 +3702,8 @@ export const withConstantInput: {
    * 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"
    *
@@ -3710,8 +3730,8 @@ export const withConstantInput: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category Input
+   * @since 2.0.0
    */
   <Input>(input: Input): <State>(self: Metric<Input, State>) => Metric<unknown, State>
   /**
@@ -3719,7 +3739,8 @@ export const withConstantInput: {
    * 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"
    *
@@ -3746,8 +3767,8 @@ export const withConstantInput: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category Input
+   * @since 2.0.0
    */
   <Input, State>(self: Metric<Input, State>, input: Input): Metric<unknown, State>
 } = dual<
@@ -3756,7 +3777,8 @@ export const withConstantInput: {
    * 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"
    *
@@ -3783,8 +3805,8 @@ export const withConstantInput: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category Input
+   * @since 2.0.0
    */
   <Input>(input: Input) => <State>(self: Metric<Input, State>) => Metric<unknown, State>,
   /**
@@ -3792,7 +3814,8 @@ export const withConstantInput: {
    * 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"
    *
@@ -3819,8 +3842,8 @@ export const withConstantInput: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category Input
+   * @since 2.0.0
    */
   <Input, State>(self: Metric<Input, State>, input: Input) => Metric<unknown, State>
 >(2, (self, input) => mapInput(self, () => input))
@@ -3832,7 +3855,8 @@ export const withConstantInput: {
  * 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"
  *
@@ -3877,8 +3901,8 @@ export const withConstantInput: {
  * })
  * ```
  *
- * @since 4.0.0
  * @category Attributes
+ * @since 4.0.0
  */
 export const withAttributes: {
   /**
@@ -3888,7 +3912,8 @@ export const withAttributes: {
    * 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"
    *
@@ -3933,8 +3958,8 @@ export const withAttributes: {
    * })
    * ```
    *
-   * @since 4.0.0
    * @category Attributes
+   * @since 4.0.0
    */
   (attributes: Metric.Attributes): <Input, State>(self: Metric<Input, State>) => Metric<Input, State>
   /**
@@ -3944,7 +3969,8 @@ export const withAttributes: {
    * 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"
    *
@@ -3989,8 +4015,8 @@ export const withAttributes: {
    * })
    * ```
    *
-   * @since 4.0.0
    * @category Attributes
+   * @since 4.0.0
    */
   <Input, State>(self: Metric<Input, State>, attributes: Metric.Attributes): Metric<Input, State>
 } = dual<
@@ -4001,7 +4027,8 @@ export const withAttributes: {
    * 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"
    *
@@ -4046,8 +4073,8 @@ export const withAttributes: {
    * })
    * ```
    *
-   * @since 4.0.0
    * @category Attributes
+   * @since 4.0.0
    */
   (attributes: Metric.Attributes) => <Input, State>(self: Metric<Input, State>) => Metric<Input, State>,
   /**
@@ -4057,7 +4084,8 @@ export const withAttributes: {
    * 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"
    *
@@ -4102,8 +4130,8 @@ export const withAttributes: {
    * })
    * ```
    *
-   * @since 4.0.0
    * @category Attributes
+   * @since 4.0.0
    */
   <Input, State>(self: Metric<Input, State>, attributes: Metric.Attributes) => Metric<Input, State>
 >(2, <Input, State>(
@@ -4125,7 +4153,8 @@ export const withAttributes: {
  * 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"
  *
@@ -4164,8 +4193,8 @@ export const withAttributes: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category Snapshotting
+ * @since 2.0.0
  */
 export const snapshot: Effect<ReadonlyArray<Metric.Snapshot>> = InternalEffect.map(
   InternalEffect.context(),
@@ -4180,7 +4209,8 @@ export const snapshot: Effect<ReadonlyArray<Metric.Snapshot>> = InternalEffect.m
  * 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"
  *
@@ -4223,8 +4253,8 @@ export const snapshot: Effect<ReadonlyArray<Metric.Snapshot>> = InternalEffect.m
  * })
  * ```
  *
- * @since 2.0.0
  * @category Debugging
+ * @since 4.0.0
  */
 export const dump: Effect<string> = InternalEffect.flatMap(InternalEffect.context(), (context) => {
   const metrics = snapshotUnsafe(context)
@@ -4269,7 +4299,8 @@ export const dump: Effect<string> = InternalEffect.flatMap(InternalEffect.contex
  * 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"
  *
@@ -4296,13 +4327,14 @@ export const dump: Effect<string> = InternalEffect.flatMap(InternalEffect.contex
  *
  *   // 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
@@ -4318,8 +4350,8 @@ export const dump: Effect<string> = InternalEffect.flatMap(InternalEffect.contex
  * })
  * ```
  *
- * @since 2.0.0
  * @category Snapshotting
+ * @since 4.0.0
  */
 export const snapshotUnsafe = (context: Context.Context<never>): ReadonlyArray<Metric.Snapshot> => {
   const registry = Context.get(context, MetricRegistry)
@@ -4398,7 +4430,8 @@ const attributesToString = (attributes: Metric.AttributeSet): string => {
  * 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"
  *
@@ -4452,20 +4485,24 @@ const attributesToString = (attributes: Metric.AttributeSet): string => {
  * })
  * ```
  *
- * @since 2.0.0
  * @category Boundaries
+ * @since 4.0.0
  */
 export const boundariesFromIterable = (iterable: Iterable<number>): ReadonlyArray<number> =>
   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.
  *
- * Creates evenly-spaced boundaries starting from a base value and incrementing
- * by a fixed width. Automatically adds positive infinity as the final boundary.
+ * **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.
+ *
+ * **Example** (Creating linear boundaries)
  *
- * @example
  * ```ts
  * import { Data, Effect, Metric } from "effect"
  *
@@ -4474,13 +4511,12 @@ export const boundariesFromIterable = (iterable: Iterable<number>): ReadonlyArra
  * }> {}
  *
  * // 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", {
@@ -4490,17 +4526,17 @@ export const boundariesFromIterable = (iterable: Iterable<number>): ReadonlyArra
  *
  * 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 4.0.0
  */
 export const linearBoundaries = (options: {
   readonly start: number
@@ -4516,7 +4552,8 @@ export const linearBoundaries = (options: {
  * 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"
  *
@@ -4557,8 +4594,8 @@ export const linearBoundaries = (options: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category Boundaries
+ * @since 4.0.0
  */
 export const exponentialBoundaries = (options: {
   readonly start: number
@@ -4588,7 +4625,8 @@ const fiberFailures = 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"
  *
@@ -4618,8 +4656,8 @@ const fiberFailures = counter("child_fiber_failures", {
  * })
  * ```
  *
- * @since 4.0.0
  * @category Runtime Metrics
+ * @since 4.0.0
  */
 export const FiberRuntimeMetricsKey: "effect/observability/Metric/FiberRuntimeMetricsKey" =
   InternalMetric.FiberRuntimeMetricsKey
@@ -4627,11 +4665,11 @@ export const FiberRuntimeMetricsKey: "effect/observability/Metric/FiberRuntimeMe
 /**
  * Interface for the fiber runtime metrics service that tracks fiber lifecycle events.
  *
- * @example
+ * **Example** (Providing a custom fiber metrics service)
+ *
  * ```ts
- * import type { Context } from "effect"
  * import { Data, Effect, Layer, Metric } from "effect"
- * import type { Exit } from "effect/Exit"
+ * import type { Context, Exit } from "effect"
  *
  * class MetricsError extends Data.TaggedError("MetricsError")<{
  *   readonly operation: string
@@ -4645,7 +4683,7 @@ export const FiberRuntimeMetricsKey: "effect/observability/Metric/FiberRuntimeMe
  *   },
  *   recordFiberEnd: (
  *     context: Context.Context<never>,
- *     exit: Exit<unknown, unknown>
+ *     exit: Exit.Exit<unknown, unknown>
  *   ) => {
  *     console.log("Fiber completed with exit:", exit)
  *     // Custom logic for tracking fiber completion based on exit status
@@ -4660,8 +4698,8 @@ export const FiberRuntimeMetricsKey: "effect/observability/Metric/FiberRuntimeMe
  * })
  * ```
  *
- * @since 4.0.0
  * @category Runtime Metrics
+ * @since 4.0.0
  */
 export interface FiberRuntimeMetricsService {
   readonly recordFiberStart: (context: Context.Context<never>) => void
@@ -4669,9 +4707,15 @@ export interface FiberRuntimeMetricsService {
 }
 
 /**
- * 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"
  *
@@ -4710,8 +4754,8 @@ export interface FiberRuntimeMetricsService {
  * })
  * ```
  *
- * @since 4.0.0
  * @category Runtime Metrics
+ * @since 4.0.0
  */
 export const FiberRuntimeMetrics = Context.Reference<FiberRuntimeMetricsService | undefined>(
   InternalMetric.FiberRuntimeMetricsKey,
@@ -4721,7 +4765,8 @@ export const FiberRuntimeMetrics = Context.Reference<FiberRuntimeMetricsService
 /**
  * Default implementation of the fiber runtime metrics service.
  *
- * @example
+ * **Example** (Using the default fiber metrics implementation)
+ *
  * ```ts
  * import { Data, Effect, Layer, Metric } from "effect"
  *
@@ -4759,8 +4804,8 @@ export const FiberRuntimeMetrics = Context.Reference<FiberRuntimeMetricsService
  * })
  * ```
  *
- * @since 4.0.0
  * @category Runtime Metrics
+ * @since 4.0.0
  */
 export const FiberRuntimeMetricsImpl: FiberRuntimeMetricsService = {
   recordFiberStart(context: Context.Context<never>) {
@@ -4786,7 +4831,8 @@ export const FiberRuntimeMetricsImpl: FiberRuntimeMetricsService = {
  * 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"
  *
@@ -4871,15 +4917,16 @@ export const FiberRuntimeMetricsImpl: FiberRuntimeMetricsService = {
  * )
  * ```
  *
- * @since 4.0.0
  * @category Runtime Metrics
+ * @since 4.0.0
  */
 export const enableRuntimeMetricsLayer = 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"
  *
@@ -4911,8 +4958,8 @@ export const enableRuntimeMetricsLayer = Layer.succeed(FiberRuntimeMetrics)(Fibe
  * })
  * ```
  *
- * @since 4.0.0
  * @category Runtime Metrics
+ * @since 4.0.0
  */
 export const disableRuntimeMetricsLayer = Layer.succeed(FiberRuntimeMetrics)(undefined)
 
@@ -4923,7 +4970,8 @@ export const disableRuntimeMetricsLayer = Layer.succeed(FiberRuntimeMetrics)(und
  * 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"
  *
@@ -4992,8 +5040,8 @@ export const disableRuntimeMetricsLayer = Layer.succeed(FiberRuntimeMetrics)(und
  * )
  * ```
  *
- * @since 4.0.0
  * @category Runtime Metrics
+ * @since 4.0.0
  */
 export const enableRuntimeMetrics: <A, E, R>(self: Effect<A, E, R>) => Effect<A, E, R> = InternalEffect.provideService(
   FiberRuntimeMetrics,
@@ -5007,7 +5055,8 @@ export const enableRuntimeMetrics: <A, E, R>(self: Effect<A, E, R>) => Effect<A,
  * 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"
  *
@@ -5035,7 +5084,7 @@ export const enableRuntimeMetrics: <A, E, R>(self: Effect<A, E, R>) => Effect<A,
  *         (_, i) =>
  *           Effect.gen(function*() {
  *             // Simulate intensive computation
- *             const result = i * i + Math.random()
+ *             const result = i * i + (i % 10) / 10
  *             return result
  *           })
  *       )
@@ -5077,8 +5126,8 @@ export const enableRuntimeMetrics: <A, E, R>(self: Effect<A, E, R>) => Effect<A,
  * )
  * ```
  *
- * @since 4.0.0
  * @category Runtime Metrics
+ * @since 4.0.0
  */
 export const disableRuntimeMetrics: <A, E, R>(self: Effect<A, E, R>) => Effect<A, E, R> = InternalEffect.provideService(
   FiberRuntimeMetrics,