effect 4.0.0-beta.73 → 4.0.0-beta.75

package/src/Metric.ts

@@ -253,7 +253,7 @@ export interface Metric<in Input, out State> extends Pipeable {
  * })
  * ```
  *
- * @category Metrics
+ * @category metrics
  * @since 2.0.0
  */
 export interface Counter<in Input extends number | bigint> extends Metric<Input, CounterState<Input>> {}
@@ -403,7 +403,7 @@ export interface CounterState<in Input extends number | bigint> {
  * })
  * ```
  *
- * @category Metrics
+ * @category metrics
  * @since 2.0.0
  */
 export interface Frequency extends Metric<string, FrequencyState> {}
@@ -488,7 +488,7 @@ export interface Frequency extends Metric<string, FrequencyState> {}
  * })
  * ```
  *
- * @category Metrics
+ * @category metrics
  * @since 4.0.0
  */
 export interface FrequencyState {
@@ -551,7 +551,7 @@ export interface FrequencyState {
  * })
  * ```
  *
- * @category Metrics
+ * @category metrics
  * @since 2.0.0
  */
 export interface Gauge<in Input extends number | bigint> extends Metric<Input, GaugeState<Input>> {}
@@ -620,7 +620,7 @@ export interface Gauge<in Input extends number | bigint> extends Metric<Input, G
  * })
  * ```
  *
- * @category Metrics
+ * @category metrics
  * @since 4.0.0
  */
 export interface GaugeState<in Input extends number | bigint> {
@@ -711,7 +711,7 @@ export interface GaugeState<in Input extends number | bigint> {
  * })
  * ```
  *
- * @category Metrics
+ * @category metrics
  * @since 2.0.0
  */
 export interface Histogram<Input> extends Metric<Input, HistogramState> {}
@@ -798,7 +798,7 @@ export interface Histogram<Input> extends Metric<Input, HistogramState> {}
  * })
  * ```
  *
- * @category Metrics
+ * @category metrics
  * @since 4.0.0
  */
 export interface HistogramState {
@@ -904,7 +904,7 @@ export interface HistogramState {
  * })
  * ```
  *
- * @category Metrics
+ * @category metrics
  * @since 2.0.0
  */
 export interface Summary<Input> extends Metric<Input, SummaryState> {}
@@ -986,7 +986,7 @@ export interface Summary<Input> extends Metric<Input, SummaryState> {}
  * })
  * ```
  *
- * @category Metrics
+ * @category metrics
  * @since 4.0.0
  */
 export interface SummaryState {
@@ -1765,8 +1765,8 @@ const MetricRegistryKey = "~effect/observability/Metric/MetricRegistryKey"
  *
  * **When to use**
  *
- * Use to provide a custom metric registry when a program or test needs metrics
- * isolated from the default registry.
+ * Use when you need a custom metric registry for an isolated program or test
+ * instead of the default registry.
  *
  * **Details**
  *
@@ -2193,11 +2193,10 @@ export const isMetric = (u: unknown): u is Metric<unknown, never> =>
  *
  * **Details**
  *
- * - `description` - A description of the `Counter`.
- * - `attributes`  - The attributes to associate with the `Counter`.
- * - `bigint`      - Indicates if the `Counter` should use the `bigint` type.
- * - `incremental` - Set to `true` to create a `Counter` that can only ever be
- *                   incremented.
+ * The optional `description` describes the counter, and `attributes` attach
+ * dimensions to it. Set `bigint` to create a counter that accepts `bigint`
+ * inputs. Set `incremental` to `true` to create a counter that can only ever be
+ * incremented.
  *
  * **Example** (Creating counter metrics)
  *
@@ -2253,11 +2252,10 @@ export const counter: {
    *
    * **Details**
    *
-   * - `description` - A description of the `Counter`.
-   * - `attributes`  - The attributes to associate with the `Counter`.
-   * - `bigint`      - Indicates if the `Counter` should use the `bigint` type.
-   * - `incremental` - Set to `true` to create a `Counter` that can only ever be
-   *                   incremented.
+   * The optional `description` describes the counter, and `attributes` attach
+   * dimensions to it. Set `bigint` to create a counter that accepts `bigint`
+   * inputs. Set `incremental` to `true` to create a counter that can only ever be
+   * incremented.
    *
    * **Example** (Creating counter metrics)
    *
@@ -2321,11 +2319,10 @@ export const counter: {
    *
    * **Details**
    *
-   * - `description` - A description of the `Counter`.
-   * - `attributes`  - The attributes to associate with the `Counter`.
-   * - `bigint`      - Indicates if the `Counter` should use the `bigint` type.
-   * - `incremental` - Set to `true` to create a `Counter` that can only ever be
-   *                   incremented.
+   * The optional `description` describes the counter, and `attributes` attach
+   * dimensions to it. Set `bigint` to create a counter that accepts `bigint`
+   * inputs. Set `incremental` to `true` to create a counter that can only ever be
+   * incremented.
    *
    * **Example** (Creating counter metrics)
    *
@@ -2390,14 +2387,14 @@ export const counter: {
  *
  * **When to use**
  *
- * Use when gauges are most suitable for metrics that represent instantaneous values,
- * such as memory usage or CPU load.
+ * Use when you need a metric for instantaneous values, such as memory usage or
+ * CPU load.
  *
  * **Details**
  *
- * - `description` - A description of the `Gauge`.
- * - `attributes`  - The attributes to associate with the `Gauge`.
- * - `bigint`      - Indicates if the `Gauge` should use the `bigint` type.
+ * The optional `description` describes the gauge, and `attributes` attach
+ * dimensions to it. Set `bigint` to create a gauge that accepts `bigint`
+ * inputs.
  *
  * **Example** (Creating gauge metrics)
  *
@@ -2457,14 +2454,14 @@ export const gauge: {
    *
    * **When to use**
    *
-   * Use when gauges are most suitable for metrics that represent instantaneous values,
-   * such as memory usage or CPU load.
+   * Use when you need a metric for instantaneous values, such as memory usage or
+   * CPU load.
    *
    * **Details**
    *
-   * - `description` - A description of the `Gauge`.
-   * - `attributes`  - The attributes to associate with the `Gauge`.
-   * - `bigint`      - Indicates if the `Gauge` should use the `bigint` type.
+   * The optional `description` describes the gauge, and `attributes` attach
+   * dimensions to it. Set `bigint` to create a gauge that accepts `bigint`
+   * inputs.
    *
    * **Example** (Creating gauge metrics)
    *
@@ -2531,14 +2528,14 @@ export const gauge: {
    *
    * **When to use**
    *
-   * Use when gauges are most suitable for metrics that represent instantaneous values,
-   * such as memory usage or CPU load.
+   * Use when you need a metric for instantaneous values, such as memory usage or
+   * CPU load.
    *
    * **Details**
    *
-   * - `description` - A description of the `Gauge`.
-   * - `attributes`  - The attributes to associate with the `Gauge`.
-   * - `bigint`      - Indicates if the `Gauge` should use the `bigint` type.
+   * The optional `description` describes the gauge, and `attributes` attach
+   * dimensions to it. Set `bigint` to create a gauge that accepts `bigint`
+   * inputs.
    *
    * **Example** (Creating gauge metrics)
    *
@@ -2607,15 +2604,14 @@ export const gauge: {
  *
  * **When to use**
  *
- * Use when frequency metrics are most suitable for counting the number of times a
- * specific event or incident occurs.
+ * Use when you need a metric for counting how often a specific event or
+ * incident occurs.
  *
  * **Details**
  *
- * - `description` - A description of the `Frequency`.
- * - `attributes`  - The attributes to associate with the `Frequency`.
- * - `preregisteredWords` - Occurrences which are pre-registered with the
- *                          `Frequency` metric occurrences.
+ * The optional `description` describes the frequency, and `attributes` attach
+ * dimensions to it. Use `preregisteredWords` to initialize occurrence counts
+ * for known string values before updates arrive.
  *
  * **Example** (Creating frequency metrics)
  *
@@ -2690,14 +2686,14 @@ export const frequency = (name: string, options?: {
  *
  * **When to use**
  *
- * Use when histogram metrics are most suitable for measuring the distribution of values
- * within a range.
+ * Use when you need a metric for measuring the distribution of values within a
+ * range.
  *
  * **Details**
  *
- * - `description` - A description of the `Histogram`.
- * - `attributes`  - The attributes to associate with the `Histogram`.
- * - `boundaries`  - The bucket boundaries of the `Histogram`
+ * The optional `description` describes the histogram, and `attributes` attach
+ * dimensions to it. The required `boundaries` option defines the histogram
+ * bucket boundaries.
  *
  * **Example** (Creating histogram metrics)
  *
@@ -2770,16 +2766,15 @@ export const histogram = (name: string, options: {
  *
  * **When to use**
  *
- * Use when summary metrics are most suitable for providing statistical information about
- * a set of values, including quantiles.
+ * Use when you need a metric that records statistical information about a set
+ * of values, including quantiles.
  *
  * **Details**
  *
- * - `description` - An description of the `Summary`.
- * - `attributes`  - The attributes to associate with the `Summary`.
- * - `maxAge`      - The maximum age of observations to retain.
- * - `maxSize`     - The maximum number of observations to keep.
- * - `quantiles`   - An array of quantiles to calculate (e.g., [0.5, 0.9]).
+ * The optional `description` describes the summary, and `attributes` attach
+ * dimensions to it. `maxAge` controls how long observations are retained,
+ * `maxSize` controls how many observations are kept, and `quantiles` lists the
+ * quantiles to calculate, such as `[0.5, 0.9]`.
  *
  * **Example** (Creating summary metrics)
  *
@@ -2866,19 +2861,18 @@ export const summary = (name: string, options: {
  *
  * **When to use**
  *
- * Use when summary metrics are most suitable for statistical information about a set of
- * values.
+ * Use when you need a metric that records statistical information about a set
+ * of values together with timestamps.
  *
  * **Details**
  *
  * Inputs to this metric are `[value, timestamp]` pairs; the current clock is
  * used when reading quantiles against the configured `maxAge`.
  *
- * - `description` - An description of the `Summary`.
- * - `attributes`  - The attributes to associate with the `Summary`.
- * - `maxAge`      - The maximum age of observations to retain.
- * - `maxSize`     - The maximum number of observations to keep.
- * - `quantiles`   - An array of quantiles to calculate (e.g., [0.5, 0.9]).
+ * The optional `description` describes the summary, and `attributes` attach
+ * dimensions to it. `maxAge` controls how long observations are retained,
+ * `maxSize` controls how many observations are kept, and `quantiles` lists the
+ * quantiles to calculate, such as `[0.5, 0.9]`.
  *
  * **Example** (Creating summaries with explicit timestamps)
  *
@@ -2970,13 +2964,12 @@ export const timer = (name: string, options?: {
  *
  * **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
+ * The returned state depends on the metric type. Counters return
+ * `CounterState<number | bigint>` with `count` and `incremental`, gauges return
+ * `GaugeState<number | bigint>` with `value`, frequencies return
+ * `FrequencyState` with `occurrences`, histograms return `HistogramState` with
+ * buckets, count, min, max, and sum, and summaries return `SummaryState` with
+ * quantiles, count, min, max, and sum.
  *
  * **Example** (Reading metric state)
  *
@@ -3007,7 +3000,7 @@ export const timer = (name: string, options?: {
  * })
  * ```
  *
- * @category utils
+ * @category getters
  * @since 2.0.0
  */
 export const value = <Input, State>(
@@ -3023,13 +3016,11 @@ export const value = <Input, State>(
  *
  * **Details**
  *
- * The behavior of `modify` depends on the metric type:
- *
- * - **Counter**: Adds the input value to the current count
- * - **Gauge**: Adds the input value to the current gauge value
- * - **Frequency**: Same as `update` - increments the occurrence count for the input string
- * - **Histogram**: Same as `update` - records the input value in the appropriate bucket
- * - **Summary**: Same as `update` - records the input observation
+ * The behavior of `modify` depends on the metric type. Counters add the input
+ * value to the current count, gauges add the input value to the current gauge
+ * value, frequencies increment the occurrence count for the input string,
+ * histograms record the input value in the appropriate bucket, and summaries
+ * record the input observation.
  *
  * **Example** (Modifying metric values)
  *
@@ -3059,7 +3050,7 @@ export const value = <Input, State>(
  * })
  * ```
  *
- * @category utils
+ * @category mutations
  * @since 3.6.5
  */
 export const modify: {
@@ -3068,13 +3059,11 @@ export const modify: {
    *
    * **Details**
    *
-   * The behavior of `modify` depends on the metric type:
-   *
-   * - **Counter**: Adds the input value to the current count
-   * - **Gauge**: Adds the input value to the current gauge value
-   * - **Frequency**: Same as `update` - increments the occurrence count for the input string
-   * - **Histogram**: Same as `update` - records the input value in the appropriate bucket
-   * - **Summary**: Same as `update` - records the input observation
+   * The behavior of `modify` depends on the metric type. Counters add the input
+   * value to the current count, gauges add the input value to the current gauge
+   * value, frequencies increment the occurrence count for the input string,
+   * histograms record the input value in the appropriate bucket, and summaries
+   * record the input observation.
    *
    * **Example** (Modifying metric values)
    *
@@ -3104,7 +3093,7 @@ export const modify: {
    * })
    * ```
    *
-   * @category utils
+   * @category mutations
    * @since 3.6.5
    */
   <Input>(input: Input): <State>(self: Metric<Input, State>) => Effect<void>
@@ -3113,13 +3102,11 @@ export const modify: {
    *
    * **Details**
    *
-   * The behavior of `modify` depends on the metric type:
-   *
-   * - **Counter**: Adds the input value to the current count
-   * - **Gauge**: Adds the input value to the current gauge value
-   * - **Frequency**: Same as `update` - increments the occurrence count for the input string
-   * - **Histogram**: Same as `update` - records the input value in the appropriate bucket
-   * - **Summary**: Same as `update` - records the input observation
+   * The behavior of `modify` depends on the metric type. Counters add the input
+   * value to the current count, gauges add the input value to the current gauge
+   * value, frequencies increment the occurrence count for the input string,
+   * histograms record the input value in the appropriate bucket, and summaries
+   * record the input observation.
    *
    * **Example** (Modifying metric values)
    *
@@ -3149,7 +3136,7 @@ export const modify: {
    * })
    * ```
    *
-   * @category utils
+   * @category mutations
    * @since 3.6.5
    */
   <Input, State>(self: Metric<Input, State>, input: Input): Effect<void>
@@ -3159,13 +3146,11 @@ export const modify: {
    *
    * **Details**
    *
-   * The behavior of `modify` depends on the metric type:
-   *
-   * - **Counter**: Adds the input value to the current count
-   * - **Gauge**: Adds the input value to the current gauge value
-   * - **Frequency**: Same as `update` - increments the occurrence count for the input string
-   * - **Histogram**: Same as `update` - records the input value in the appropriate bucket
-   * - **Summary**: Same as `update` - records the input observation
+   * The behavior of `modify` depends on the metric type. Counters add the input
+   * value to the current count, gauges add the input value to the current gauge
+   * value, frequencies increment the occurrence count for the input string,
+   * histograms record the input value in the appropriate bucket, and summaries
+   * record the input observation.
    *
    * **Example** (Modifying metric values)
    *
@@ -3195,7 +3180,7 @@ export const modify: {
    * })
    * ```
    *
-   * @category utils
+   * @category mutations
    * @since 3.6.5
    */
   <Input>(input: Input) => <State>(self: Metric<Input, State>) => Effect<void>,
@@ -3204,13 +3189,11 @@ export const modify: {
    *
    * **Details**
    *
-   * The behavior of `modify` depends on the metric type:
-   *
-   * - **Counter**: Adds the input value to the current count
-   * - **Gauge**: Adds the input value to the current gauge value
-   * - **Frequency**: Same as `update` - increments the occurrence count for the input string
-   * - **Histogram**: Same as `update` - records the input value in the appropriate bucket
-   * - **Summary**: Same as `update` - records the input observation
+   * The behavior of `modify` depends on the metric type. Counters add the input
+   * value to the current count, gauges add the input value to the current gauge
+   * value, frequencies increment the occurrence count for the input string,
+   * histograms record the input value in the appropriate bucket, and summaries
+   * record the input observation.
    *
    * **Example** (Modifying metric values)
    *
@@ -3240,7 +3223,7 @@ export const modify: {
    * })
    * ```
    *
-   * @category utils
+   * @category mutations
    * @since 3.6.5
    */
   <Input, State>(self: Metric<Input, State>, input: Input) => Effect<void>
@@ -3255,13 +3238,11 @@ export const modify: {
  *
  * **Details**
  *
- * The behavior of `update` depends on the metric type:
- *
- * - **Counter**: Adds the input value to the current count (same as `modify`)
- * - **Gauge**: Sets the gauge to the specified value (replaces current value)
- * - **Frequency**: Increments the occurrence count for the input string by 1
- * - **Histogram**: Records the input value in the appropriate bucket
- * - **Summary**: Records the input value as a new observation
+ * The behavior of `update` depends on the metric type. Counters add the input
+ * value to the current count, gauges replace the current value with the input
+ * value, frequencies increment the occurrence count for the input string,
+ * histograms record the input value in the appropriate bucket, and summaries
+ * record the input value as a new observation.
  *
  * **Example** (Updating metric values)
  *
@@ -3300,7 +3281,7 @@ export const modify: {
  * })
  * ```
  *
- * @category utils
+ * @category mutations
  * @since 2.0.0
  */
 export const update: {
@@ -3309,13 +3290,11 @@ export const update: {
    *
    * **Details**
    *
-   * The behavior of `update` depends on the metric type:
-   *
-   * - **Counter**: Adds the input value to the current count (same as `modify`)
-   * - **Gauge**: Sets the gauge to the specified value (replaces current value)
-   * - **Frequency**: Increments the occurrence count for the input string by 1
-   * - **Histogram**: Records the input value in the appropriate bucket
-   * - **Summary**: Records the input value as a new observation
+   * The behavior of `update` depends on the metric type. Counters add the input
+   * value to the current count, gauges replace the current value with the input
+   * value, frequencies increment the occurrence count for the input string,
+   * histograms record the input value in the appropriate bucket, and summaries
+   * record the input value as a new observation.
    *
    * **Example** (Updating metric values)
    *
@@ -3354,7 +3333,7 @@ export const update: {
    * })
    * ```
    *
-   * @category utils
+   * @category mutations
    * @since 2.0.0
    */
   <Input>(input: Input): <State>(self: Metric<Input, State>) => Effect<void>
@@ -3363,13 +3342,11 @@ export const update: {
    *
    * **Details**
    *
-   * The behavior of `update` depends on the metric type:
-   *
-   * - **Counter**: Adds the input value to the current count (same as `modify`)
-   * - **Gauge**: Sets the gauge to the specified value (replaces current value)
-   * - **Frequency**: Increments the occurrence count for the input string by 1
-   * - **Histogram**: Records the input value in the appropriate bucket
-   * - **Summary**: Records the input value as a new observation
+   * The behavior of `update` depends on the metric type. Counters add the input
+   * value to the current count, gauges replace the current value with the input
+   * value, frequencies increment the occurrence count for the input string,
+   * histograms record the input value in the appropriate bucket, and summaries
+   * record the input value as a new observation.
    *
    * **Example** (Updating metric values)
    *
@@ -3408,7 +3385,7 @@ export const update: {
    * })
    * ```
    *
-   * @category utils
+   * @category mutations
    * @since 2.0.0
    */
   <Input, State>(self: Metric<Input, State>, input: Input): Effect<void>
@@ -3418,13 +3395,11 @@ export const update: {
    *
    * **Details**
    *
-   * The behavior of `update` depends on the metric type:
-   *
-   * - **Counter**: Adds the input value to the current count (same as `modify`)
-   * - **Gauge**: Sets the gauge to the specified value (replaces current value)
-   * - **Frequency**: Increments the occurrence count for the input string by 1
-   * - **Histogram**: Records the input value in the appropriate bucket
-   * - **Summary**: Records the input value as a new observation
+   * The behavior of `update` depends on the metric type. Counters add the input
+   * value to the current count, gauges replace the current value with the input
+   * value, frequencies increment the occurrence count for the input string,
+   * histograms record the input value in the appropriate bucket, and summaries
+   * record the input value as a new observation.
    *
    * **Example** (Updating metric values)
    *
@@ -3463,7 +3438,7 @@ export const update: {
    * })
    * ```
    *
-   * @category utils
+   * @category mutations
    * @since 2.0.0
    */
   <Input>(input: Input) => <State>(self: Metric<Input, State>) => Effect<void>,
@@ -3472,13 +3447,11 @@ export const update: {
    *
    * **Details**
    *
-   * The behavior of `update` depends on the metric type:
-   *
-   * - **Counter**: Adds the input value to the current count (same as `modify`)
-   * - **Gauge**: Sets the gauge to the specified value (replaces current value)
-   * - **Frequency**: Increments the occurrence count for the input string by 1
-   * - **Histogram**: Records the input value in the appropriate bucket
-   * - **Summary**: Records the input value as a new observation
+   * The behavior of `update` depends on the metric type. Counters add the input
+   * value to the current count, gauges replace the current value with the input
+   * value, frequencies increment the occurrence count for the input string,
+   * histograms record the input value in the appropriate bucket, and summaries
+   * record the input value as a new observation.
    *
    * **Example** (Updating metric values)
    *
@@ -3517,7 +3490,7 @@ export const update: {
    * })
    * ```
    *
-   * @category utils
+   * @category mutations
    * @since 2.0.0
    */
   <Input, State>(self: Metric<Input, State>, input: Input) => Effect<void>
@@ -5171,9 +5144,8 @@ export const enableRuntimeMetrics: <A, E, R>(self: Effect<A, E, R>) => Effect<A,
  *
  * **When to use**
  *
- * Use when this is useful when you want to selectively disable runtime metrics for specific
- * parts of your application while keeping them enabled elsewhere, or when you need
- * to avoid the overhead of metrics collection in performance-critical sections.
+ * Use when you need to disable runtime metrics for a specific effect while
+ * keeping them enabled elsewhere.
  *
  * **Example** (Disabling runtime metrics for an effect)
  *