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

package/dist/Metric.d.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")
- *
- *   // 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 Context from "./Context.ts";
 import * as Duration from "./Duration.ts";
@@ -160,7 +107,8 @@ import type { Contravariant, Covariant } from "./Types.ts";
  *   - Histograms
  *   - Summaries
  *
- * @example
+ * **Example** (Using multiple metric types)
+ *
  * ```ts
  * import { Data, Effect, Metric } from "effect"
  *
@@ -214,8 +162,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;
@@ -235,7 +183,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"
  *
@@ -289,15 +238,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"
  *
@@ -350,8 +300,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;
@@ -364,7 +314,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"
  *
@@ -434,15 +385,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"
  *
@@ -518,8 +470,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>;
@@ -530,7 +482,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"
  *
@@ -577,15 +530,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"
  *
@@ -645,8 +599,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;
@@ -657,7 +611,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"
  *
@@ -732,15 +687,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"
  *
@@ -818,8 +774,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]>;
@@ -835,7 +791,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"
  *
@@ -920,15 +877,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"
  *
@@ -1001,8 +959,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]>;
@@ -1015,7 +973,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"
  *
@@ -1054,13 +1013,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"
      *
@@ -1132,14 +1091,15 @@ export declare namespace Metric {
      * })
      * ```
      *
-     * @since 2.0.0
      * @category types
+     * @since 4.0.0
      */
     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"
      *
@@ -1206,14 +1166,15 @@ export declare namespace Metric {
      * })
      * ```
      *
-     * @since 2.0.0
      * @category types
+     * @since 4.0.0
      */
     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"
      *
@@ -1282,14 +1243,15 @@ export declare namespace Metric {
      * })
      * ```
      *
-     * @since 2.0.0
      * @category types
+     * @since 4.0.0
      */
     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"
      *
@@ -1330,14 +1292,15 @@ export declare namespace Metric {
      * // Metric.update(stringFrequency, 404)   // ✗ Type error
      * ```
      *
-     * @since 2.0.0
      * @category types
+     * @since 4.0.0
      */
     type Input<A> = A extends Metric<infer _Input, infer _State> ? _Input : never;
     /**
      * Utility type to extract the State type from a Metric type.
      *
-     * @example
+     * **Example** (Extracting metric state types)
+     *
      * ```ts
      * import { Effect, Metric } from "effect"
      *
@@ -1387,14 +1350,15 @@ export declare namespace Metric {
      * })
      * ```
      *
-     * @since 2.0.0
      * @category types
+     * @since 4.0.0
      */
     type State<A> = A extends Metric<infer _Input, infer _State> ? _State : never;
     /**
      * Interface defining the core hooks for metric operations: get, update, and modify.
      *
-     * @example
+     * **Example** (Using metric hooks)
+     *
      * ```ts
      * import { Data, Effect, Metric } from "effect"
      *
@@ -1430,8 +1394,8 @@ export declare namespace Metric {
      * })
      * ```
      *
-     * @since 2.0.0
      * @category interfaces
+     * @since 4.0.0
      */
     interface Hooks<in Input, out State> {
         readonly get: (context: Context.Context<never>) => State;
@@ -1441,7 +1405,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"
      *
@@ -1494,8 +1459,8 @@ export declare namespace Metric {
      * })
      * ```
      *
-     * @since 4.0.0
      * @category interfaces
+     * @since 4.0.0
      */
     interface Metadata<in Input, out State> {
         readonly id: string;
@@ -1507,7 +1472,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"
      *
@@ -1565,8 +1531,8 @@ export declare namespace Metric {
      * })
      * ```
      *
-     * @since 4.0.0
      * @category interfaces
+     * @since 4.0.0
      */
     interface SnapshotProto<T extends Type, State> {
         readonly id: string;
@@ -1578,7 +1544,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"
      *
@@ -1640,15 +1607,16 @@ export declare namespace Metric {
      * })
      * ```
      *
-     * @since 4.0.0
      * @category types
+     * @since 4.0.0
      */
     type Snapshot = SnapshotProto<"Counter", CounterState<number | bigint>> | SnapshotProto<"Gauge", GaugeState<number | bigint>> | SnapshotProto<"Frequency", FrequencyState> | SnapshotProto<"Histogram", HistogramState> | SnapshotProto<"Summary", SummaryState>;
 }
 /**
  * Service key for the current metric attributes context.
  *
- * @example
+ * **Example** (Using the current attributes key)
+ *
  * ```ts
  * import { Data, Effect, Metric } from "effect"
  *
@@ -1690,14 +1658,21 @@ export declare namespace Metric {
  * })
  * ```
  *
+ * @category references
  * @since 4.0.0
- * @category References
  */
 export declare 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"
  *
@@ -1725,15 +1700,19 @@ export declare const CurrentMetricAttributesKey: "effect/Metric/CurrentMetricAtt
  * })
  * ```
  *
+ * @category references
  * @since 4.0.0
- * @category References
  */
 export declare const CurrentMetricAttributes: Context.Reference<Readonly<Record<string, string>>>;
 /**
- * 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 declare const MetricRegistry: Context.Reference<Map<string, Metric.Metadata<any, any>>>;
 declare const TypeId = "~effect/observability/Metric";
@@ -1743,7 +1722,8 @@ declare const TypeId = "~effect/observability/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"
  *
@@ -1757,8 +1737,8 @@ declare const TypeId = "~effect/observability/Metric";
  * console.log(Metric.isMetric(null)) // false
  * ```
  *
+ * @category guards
  * @since 4.0.0
- * @category Guards
  */
 export declare const isMetric: (u: unknown) => u is Metric<unknown, never>;
 /**
@@ -1774,7 +1754,8 @@ export declare 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"
  *
@@ -1816,8 +1797,8 @@ export declare const isMetric: (u: unknown) => u is Metric<unknown, never>;
  * })
  * ```
  *
+ * @category constructors
  * @since 2.0.0
- * @category Constructors
  */
 export declare const counter: {
     /**
@@ -1833,7 +1814,8 @@ export declare 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"
      *
@@ -1875,8 +1857,8 @@ export declare const counter: {
      * })
      * ```
      *
+     * @category constructors
      * @since 2.0.0
-     * @category Constructors
      */
     (name: string, options?: {
         readonly description?: string | undefined;
@@ -1897,7 +1879,8 @@ export declare 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"
      *
@@ -1939,8 +1922,8 @@ export declare const counter: {
      * })
      * ```
      *
+     * @category constructors
      * @since 2.0.0
-     * @category Constructors
      */
     (name: string, options: {
         readonly description?: string | undefined;
@@ -1962,7 +1945,8 @@ export declare 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"
  *
@@ -2009,8 +1993,8 @@ export declare const counter: {
  * })
  * ```
  *
+ * @category constructors
  * @since 2.0.0
- * @category Constructors
  */
 export declare const gauge: {
     /**
@@ -2026,7 +2010,8 @@ export declare 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"
      *
@@ -2073,8 +2058,8 @@ export declare const gauge: {
      * })
      * ```
      *
+     * @category constructors
      * @since 2.0.0
-     * @category Constructors
      */
     (name: string, options?: {
         readonly description?: string | undefined;
@@ -2094,7 +2079,8 @@ export declare 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"
      *
@@ -2141,8 +2127,8 @@ export declare const gauge: {
      * })
      * ```
      *
+     * @category constructors
      * @since 2.0.0
-     * @category Constructors
      */
     (name: string, options: {
         readonly description?: string | undefined;
@@ -2164,7 +2150,8 @@ export declare 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"
  *
@@ -2222,8 +2209,8 @@ export declare const gauge: {
  * })
  * ```
  *
+ * @category constructors
  * @since 2.0.0
- * @category Constructors
  */
 export declare const frequency: (name: string, options?: {
     readonly description?: string | undefined;
@@ -2242,7 +2229,8 @@ export declare 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"
  *
@@ -2297,8 +2285,8 @@ export declare const frequency: (name: string, options?: {
  * })
  * ```
  *
+ * @category constructors
  * @since 2.0.0
- * @category Constructors
  */
 export declare const histogram: (name: string, options: {
     readonly description?: string | undefined;
@@ -2320,7 +2308,8 @@ export declare 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"
  *
@@ -2346,13 +2335,10 @@ export declare 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
@@ -2365,20 +2351,28 @@ export declare 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 }
+ *
+ *   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 }
  * })
  * ```
  *
+ * @category constructors
  * @since 2.0.0
- * @category Constructors
  */
 export declare const summary: (name: string, options: {
     readonly description?: string | undefined;
@@ -2388,11 +2382,12 @@ export declare const summary: (name: string, options: {
     readonly quantiles: ReadonlyArray<number>;
 }) => Summary<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**
  *
@@ -2402,7 +2397,8 @@ export declare 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"
  *
@@ -2417,8 +2413,8 @@ export declare const summary: (name: string, options: {
  * )
  * ```
  *
- * @since 2.0.0
- * @category Constructors
+ * @category constructors
+ * @since 4.0.0
  */
 export declare const summaryWithTimestamp: (name: string, options: {
     readonly description?: string | undefined;
@@ -2437,7 +2433,8 @@ export declare 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"
  *
@@ -2451,19 +2448,23 @@ export declare 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 declare const timer: (name: string, options?: {
     readonly description?: string | undefined;
@@ -2473,15 +2474,17 @@ export declare 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"
  *
@@ -2509,8 +2512,8 @@ export declare const timer: (name: string, options?: {
  * })
  * ```
  *
+ * @category utils
  * @since 2.0.0
- * @category Utilities
  */
 export declare const value: <Input, State>(self: Metric<Input, State>) => Effect<State>;
 /**
@@ -2523,7 +2526,8 @@ export declare const value: <Input, State>(self: Metric<Input, State>) => Effect
  * - **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"
  *
@@ -2550,8 +2554,8 @@ export declare const value: <Input, State>(self: Metric<Input, State>) => Effect
  * })
  * ```
  *
- * @since 2.0.0
- * @category Utilities
+ * @category utils
+ * @since 3.6.5
  */
 export declare const modify: {
     /**
@@ -2564,7 +2568,8 @@ export declare 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"
      *
@@ -2591,8 +2596,8 @@ export declare const modify: {
      * })
      * ```
      *
-     * @since 2.0.0
-     * @category Utilities
+     * @category utils
+     * @since 3.6.5
      */
     <Input>(input: Input): <State>(self: Metric<Input, State>) => Effect<void>;
     /**
@@ -2605,7 +2610,8 @@ export declare 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"
      *
@@ -2632,8 +2638,8 @@ export declare const modify: {
      * })
      * ```
      *
-     * @since 2.0.0
-     * @category Utilities
+     * @category utils
+     * @since 3.6.5
      */
     <Input, State>(self: Metric<Input, State>, input: Input): Effect<void>;
 };
@@ -2647,7 +2653,8 @@ export declare 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"
  *
@@ -2683,8 +2690,8 @@ export declare const modify: {
  * })
  * ```
  *
+ * @category utils
  * @since 2.0.0
- * @category Utilities
  */
 export declare const update: {
     /**
@@ -2697,7 +2704,8 @@ export declare 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"
      *
@@ -2733,8 +2741,8 @@ export declare const update: {
      * })
      * ```
      *
+     * @category utils
      * @since 2.0.0
-     * @category Utilities
      */
     <Input>(input: Input): <State>(self: Metric<Input, State>) => Effect<void>;
     /**
@@ -2747,7 +2755,8 @@ export declare 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"
      *
@@ -2783,8 +2792,8 @@ export declare const update: {
      * })
      * ```
      *
+     * @category utils
      * @since 2.0.0
-     * @category Utilities
      */
     <Input, State>(self: Metric<Input, State>, input: Input): Effect<void>;
 };
@@ -2793,7 +2802,8 @@ export declare 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"
  *
@@ -2823,8 +2833,8 @@ export declare const update: {
  * })
  * ```
  *
+ * @category mapping
  * @since 2.0.0
- * @category Mapping
  */
 export declare const mapInput: {
     /**
@@ -2832,7 +2842,8 @@ export declare 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"
      *
@@ -2862,8 +2873,8 @@ export declare 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>;
     /**
@@ -2871,7 +2882,8 @@ export declare 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"
      *
@@ -2901,8 +2913,8 @@ export declare const mapInput: {
      * })
      * ```
      *
+     * @category mapping
      * @since 2.0.0
-     * @category Mapping
      */
     <Input, State, Input2>(self: Metric<Input, State>, f: (input: Input2, context: Context.Context<never>) => Input): Metric<Input2, State>;
 };
@@ -2911,7 +2923,8 @@ export declare 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"
  *
@@ -2938,8 +2951,8 @@ export declare const mapInput: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category Input
+ * @since 2.0.0
  */
 export declare const withConstantInput: {
     /**
@@ -2947,7 +2960,8 @@ export declare 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"
      *
@@ -2974,8 +2988,8 @@ export declare const withConstantInput: {
      * })
      * ```
      *
-     * @since 2.0.0
      * @category Input
+     * @since 2.0.0
      */
     <Input>(input: Input): <State>(self: Metric<Input, State>) => Metric<unknown, State>;
     /**
@@ -2983,7 +2997,8 @@ export declare 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"
      *
@@ -3010,8 +3025,8 @@ export declare const withConstantInput: {
      * })
      * ```
      *
-     * @since 2.0.0
      * @category Input
+     * @since 2.0.0
      */
     <Input, State>(self: Metric<Input, State>, input: Input): Metric<unknown, State>;
 };
@@ -3022,7 +3037,8 @@ export declare 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"
  *
@@ -3067,8 +3083,8 @@ export declare const withConstantInput: {
  * })
  * ```
  *
- * @since 4.0.0
  * @category Attributes
+ * @since 4.0.0
  */
 export declare const withAttributes: {
     /**
@@ -3078,7 +3094,8 @@ export declare 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"
      *
@@ -3123,8 +3140,8 @@ export declare const withAttributes: {
      * })
      * ```
      *
-     * @since 4.0.0
      * @category Attributes
+     * @since 4.0.0
      */
     (attributes: Metric.Attributes): <Input, State>(self: Metric<Input, State>) => Metric<Input, State>;
     /**
@@ -3134,7 +3151,8 @@ export declare 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"
      *
@@ -3179,8 +3197,8 @@ export declare const withAttributes: {
      * })
      * ```
      *
-     * @since 4.0.0
      * @category Attributes
+     * @since 4.0.0
      */
     <Input, State>(self: Metric<Input, State>, attributes: Metric.Attributes): Metric<Input, State>;
 };
@@ -3190,7 +3208,8 @@ export declare 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"
  *
@@ -3229,8 +3248,8 @@ export declare const withAttributes: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category Snapshotting
+ * @since 2.0.0
  */
 export declare const snapshot: Effect<ReadonlyArray<Metric.Snapshot>>;
 /**
@@ -3241,7 +3260,8 @@ export declare const snapshot: Effect<ReadonlyArray<Metric.Snapshot>>;
  * 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"
  *
@@ -3284,8 +3304,8 @@ export declare const snapshot: Effect<ReadonlyArray<Metric.Snapshot>>;
  * })
  * ```
  *
- * @since 2.0.0
  * @category Debugging
+ * @since 4.0.0
  */
 export declare const dump: Effect<string>;
 /**
@@ -3296,7 +3316,8 @@ export declare const dump: Effect<string>;
  * 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"
  *
@@ -3323,13 +3344,14 @@ export declare const dump: Effect<string>;
  *
  *   // 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
@@ -3345,8 +3367,8 @@ export declare const dump: Effect<string>;
  * })
  * ```
  *
- * @since 2.0.0
  * @category Snapshotting
+ * @since 4.0.0
  */
 export declare const snapshotUnsafe: (context: Context.Context<never>) => ReadonlyArray<Metric.Snapshot>;
 /**
@@ -3357,7 +3379,8 @@ export declare const snapshotUnsafe: (context: Context.Context<never>) => Readon
  * 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"
  *
@@ -3411,18 +3434,22 @@ export declare const snapshotUnsafe: (context: Context.Context<never>) => Readon
  * })
  * ```
  *
- * @since 2.0.0
  * @category Boundaries
+ * @since 4.0.0
  */
 export declare const boundariesFromIterable: (iterable: Iterable<number>) => ReadonlyArray<number>;
 /**
- * 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"
  *
@@ -3431,13 +3458,12 @@ export declare const boundariesFromIterable: (iterable: Iterable<number>) => Rea
  * }> {}
  *
  * // 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", {
@@ -3447,17 +3473,17 @@ export declare const boundariesFromIterable: (iterable: Iterable<number>) => Rea
  *
  * 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 declare const linearBoundaries: (options: {
     readonly start: number;
@@ -3471,7 +3497,8 @@ export declare 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"
  *
@@ -3512,8 +3539,8 @@ export declare const linearBoundaries: (options: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category Boundaries
+ * @since 4.0.0
  */
 export declare const exponentialBoundaries: (options: {
     readonly start: number;
@@ -3523,7 +3550,8 @@ export declare const exponentialBoundaries: (options: {
 /**
  * Service key for the fiber runtime metrics service.
  *
- * @example
+ * **Example** (Using the fiber runtime metrics key)
+ *
  * ```ts
  * import { Data, Effect, Layer, Metric } from "effect"
  *
@@ -3553,18 +3581,18 @@ export declare const exponentialBoundaries: (options: {
  * })
  * ```
  *
- * @since 4.0.0
  * @category Runtime Metrics
+ * @since 4.0.0
  */
 export declare const FiberRuntimeMetricsKey: "effect/observability/Metric/FiberRuntimeMetricsKey";
 /**
  * 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
@@ -3578,7 +3606,7 @@ export declare const FiberRuntimeMetricsKey: "effect/observability/Metric/FiberR
  *   },
  *   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
@@ -3593,17 +3621,23 @@ export declare const FiberRuntimeMetricsKey: "effect/observability/Metric/FiberR
  * })
  * ```
  *
- * @since 4.0.0
  * @category Runtime Metrics
+ * @since 4.0.0
  */
 export interface FiberRuntimeMetricsService {
     readonly recordFiberStart: (context: Context.Context<never>) => void;
     readonly recordFiberEnd: (context: Context.Context<never>, exit: Exit<unknown, unknown>) => void;
 }
 /**
- * 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"
  *
@@ -3642,14 +3676,15 @@ export interface FiberRuntimeMetricsService {
  * })
  * ```
  *
- * @since 4.0.0
  * @category Runtime Metrics
+ * @since 4.0.0
  */
 export declare const FiberRuntimeMetrics: Context.Reference<FiberRuntimeMetricsService | undefined>;
 /**
  * Default implementation of the fiber runtime metrics service.
  *
- * @example
+ * **Example** (Using the default fiber metrics implementation)
+ *
  * ```ts
  * import { Data, Effect, Layer, Metric } from "effect"
  *
@@ -3687,8 +3722,8 @@ export declare const FiberRuntimeMetrics: Context.Reference<FiberRuntimeMetricsS
  * })
  * ```
  *
- * @since 4.0.0
  * @category Runtime Metrics
+ * @since 4.0.0
  */
 export declare const FiberRuntimeMetricsImpl: FiberRuntimeMetricsService;
 /**
@@ -3700,7 +3735,8 @@ export declare 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"
  *
@@ -3785,14 +3821,15 @@ export declare const FiberRuntimeMetricsImpl: FiberRuntimeMetricsService;
  * )
  * ```
  *
- * @since 4.0.0
  * @category Runtime Metrics
+ * @since 4.0.0
  */
 export declare const enableRuntimeMetricsLayer: Layer.Layer<never, never, never>;
 /**
  * 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"
  *
@@ -3824,8 +3861,8 @@ export declare const enableRuntimeMetricsLayer: Layer.Layer<never, never, never>
  * })
  * ```
  *
- * @since 4.0.0
  * @category Runtime Metrics
+ * @since 4.0.0
  */
 export declare const disableRuntimeMetricsLayer: Layer.Layer<never, never, never>;
 /**
@@ -3835,7 +3872,8 @@ export declare const disableRuntimeMetricsLayer: Layer.Layer<never, never, never
  * 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"
  *
@@ -3904,8 +3942,8 @@ export declare const disableRuntimeMetricsLayer: Layer.Layer<never, never, never
  * )
  * ```
  *
- * @since 4.0.0
  * @category Runtime Metrics
+ * @since 4.0.0
  */
 export declare const enableRuntimeMetrics: <A, E, R>(self: Effect<A, E, R>) => Effect<A, E, R>;
 /**
@@ -3915,7 +3953,8 @@ export declare const enableRuntimeMetrics: <A, E, R>(self: Effect<A, E, R>) => E
  * 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"
  *
@@ -3943,7 +3982,7 @@ export declare const enableRuntimeMetrics: <A, E, R>(self: Effect<A, E, R>) => E
  *         (_, i) =>
  *           Effect.gen(function*() {
  *             // Simulate intensive computation
- *             const result = i * i + Math.random()
+ *             const result = i * i + (i % 10) / 10
  *             return result
  *           })
  *       )
@@ -3985,8 +4024,8 @@ export declare const enableRuntimeMetrics: <A, E, R>(self: Effect<A, E, R>) => E
  * )
  * ```
  *
- * @since 4.0.0
  * @category Runtime Metrics
+ * @since 4.0.0
  */
 export declare const disableRuntimeMetrics: <A, E, R>(self: Effect<A, E, R>) => Effect<A, E, R>;
 export {};