effect 4.0.0-beta.70 → 4.0.0-beta.72

package/src/Metric.ts

@@ -195,7 +195,7 @@ export interface Metric<in Input, out State> extends Pipeable {
  *
  * **When to use**
  *
- * Counters are useful for tracking monotonically increasing values like request counts,
+ * Use when counters are useful for tracking monotonically increasing values like request counts,
  * bytes processed, errors encountered, or any value that accumulates over time.
  *
  * **Example** (Using counter metrics)
@@ -328,7 +328,7 @@ export interface CounterState<in Input extends number | bigint> {
  *
  * **When to use**
  *
- * Frequency metrics are ideal for tracking categorical data where you want to count
+ * Use when frequency metrics are ideal for tracking categorical data where you want to count
  * how many times specific string values occur, such as HTTP status codes, user actions,
  * error types, or any discrete string-based events.
  *
@@ -500,7 +500,7 @@ export interface FrequencyState {
  *
  * **When to use**
  *
- * Gauges are useful for tracking current state values like memory usage, CPU load,
+ * Use when 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** (Using gauge metrics)
@@ -632,7 +632,7 @@ export interface GaugeState<in Input extends number | bigint> {
  *
  * **When to use**
  *
- * Histograms are ideal for measuring request durations, response sizes, and other continuous values
+ * Use when 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** (Using histogram metrics)
@@ -814,7 +814,7 @@ export interface HistogramState {
  *
  * **When to use**
  *
- * Summaries provide statistical insights into value distributions by tracking specific quantiles
+ * Use when summaries provide statistical insights into value distributions by tracking specific quantiles
  * (percentiles) such as median (50th), 95th percentile, 99th percentile, etc. They're ideal for
  * understanding performance characteristics like response time distributions.
  *
@@ -1708,9 +1708,14 @@ export declare namespace Metric {
 export const CurrentMetricAttributesKey = "effect/Metric/CurrentMetricAttributes" as const
 
 /**
- * `Context.Reference` for metric attributes applied from the current Effect
+ * Context reference for metric attributes applied from the current Effect
  * context.
  *
+ * **When to use**
+ *
+ * Use to provide default attributes that should be merged into metric updates
+ * and reads in a scoped part of a program.
+ *
  * **Details**
  *
  * The default value is an empty attribute set. Metric reads and updates merge
@@ -1756,12 +1761,27 @@ export const CurrentMetricAttributes = Context.Reference<Metric.AttributeSet>(Cu
 const MetricRegistryKey = "~effect/observability/Metric/MetricRegistryKey"
 
 /**
- * `Context.Reference` for the metric registry in the current context.
+ * Context reference for the metric registry in the current context.
+ *
+ * **When to use**
+ *
+ * Use to provide a custom metric registry when a program or test needs metrics
+ * isolated from the default registry.
  *
  * **Details**
  *
- * The default registry is an empty `Map`. Metrics register their metadata and
- * hooks lazily in this map when they are read or updated.
+ * By default, the reference creates an empty `Map` the first time it is
+ * resolved. Metrics register their metadata and hooks lazily in this map when
+ * they are read or updated.
+ *
+ * **Gotchas**
+ *
+ * Because `Context.Reference` caches default values, the default `Map` is
+ * shared by contexts that do not provide an override. Provide `MetricRegistry`
+ * with a fresh `Map` when isolation matters.
+ *
+ * @see {@link snapshot} for reading all registered metrics from the current `Effect` context
+ * @see {@link snapshotUnsafe} for reading all registered metrics from an explicit `Context`
  *
  * @category references
  * @since 4.0.0
@@ -2142,7 +2162,7 @@ class MetricTransform<in Input, out State, in Input2> extends Metric$<Input2, St
  *
  * **When to use**
  *
- * This function is useful for runtime type checking and ensuring that a value
+ * Use when you need runtime type checking and ensuring that a value
  * conforms to the Metric interface before performing metric operations.
  *
  * **Example** (Checking metric values)
@@ -2370,7 +2390,7 @@ export const counter: {
  *
  * **When to use**
  *
- * Gauges are most suitable for metrics that represent instantaneous values,
+ * Use when gauges are most suitable for metrics that represent instantaneous values,
  * such as memory usage or CPU load.
  *
  * **Details**
@@ -2437,7 +2457,7 @@ export const gauge: {
    *
    * **When to use**
    *
-   * Gauges are most suitable for metrics that represent instantaneous values,
+   * Use when gauges are most suitable for metrics that represent instantaneous values,
    * such as memory usage or CPU load.
    *
    * **Details**
@@ -2511,7 +2531,7 @@ export const gauge: {
    *
    * **When to use**
    *
-   * Gauges are most suitable for metrics that represent instantaneous values,
+   * Use when gauges are most suitable for metrics that represent instantaneous values,
    * such as memory usage or CPU load.
    *
    * **Details**
@@ -2587,7 +2607,7 @@ export const gauge: {
  *
  * **When to use**
  *
- * Frequency metrics are most suitable for counting the number of times a
+ * Use when frequency metrics are most suitable for counting the number of times a
  * specific event or incident occurs.
  *
  * **Details**
@@ -2670,7 +2690,7 @@ export const frequency = (name: string, options?: {
  *
  * **When to use**
  *
- * Histogram metrics are most suitable for measuring the distribution of values
+ * Use when histogram metrics are most suitable for measuring the distribution of values
  * within a range.
  *
  * **Details**
@@ -2750,7 +2770,7 @@ export const histogram = (name: string, options: {
  *
  * **When to use**
  *
- * Summary metrics are most suitable for providing statistical information about
+ * Use when summary metrics are most suitable for providing statistical information about
  * a set of values, including quantiles.
  *
  * **Details**
@@ -2846,7 +2866,7 @@ export const summary = (name: string, options: {
  *
  * **When to use**
  *
- * Summary metrics are most suitable for statistical information about a set of
+ * Use when summary metrics are most suitable for statistical information about a set of
  * values.
  *
  * **Details**
@@ -4371,9 +4391,14 @@ export const dump: Effect<string> = InternalEffect.flatMap(InternalEffect.contex
 })
 
 /**
- * Synchronously captures a snapshot of all registered metrics using the provided
+ * Captures a snapshot of all registered metrics synchronously using the provided
  * service context.
  *
+ * **When to use**
+ *
+ * Use to read metric snapshots from an explicit `Context` in low-level
+ * integrations, exporters, or debugging tools that already have the context.
+ *
  * **Details**
  *
  * This is the "unsafe" version that bypasses Effect's safety guarantees and requires
@@ -4504,8 +4529,7 @@ const attributesToString = (attributes: Metric.AttributeSet): string => {
 // Metric Boundaries
 
 /**
- * A helper method to create histogram bucket boundaries from an iterable set
- * of values.
+ * Creates histogram bucket boundaries from an iterable set of values.
  *
  * **Details**
  *
@@ -4568,7 +4592,7 @@ const attributesToString = (attributes: Metric.AttributeSet): string => {
  * })
  * ```
  *
- * @category Boundaries
+ * @category boundaries
  * @since 4.0.0
  */
 export const boundariesFromIterable = (iterable: Iterable<number>): ReadonlyArray<number> =>
@@ -4619,7 +4643,7 @@ export const boundariesFromIterable = (iterable: Iterable<number>): ReadonlyArra
  * })
  * ```
  *
- * @category Boundaries
+ * @category boundaries
  * @since 4.0.0
  */
 export const linearBoundaries = (options: {
@@ -4630,8 +4654,7 @@ export const linearBoundaries = (options: {
   boundariesFromIterable(Arr.makeBy(options.count - 1, (n) => options.start + n + options.width))
 
 /**
- * A helper method to create histogram bucket boundaries with exponentially
- * increasing values.
+ * Creates histogram bucket boundaries with exponentially increasing values.
  *
  * **Details**
  *
@@ -4680,7 +4703,7 @@ export const linearBoundaries = (options: {
  * })
  * ```
  *
- * @category Boundaries
+ * @category boundaries
  * @since 4.0.0
  */
 export const exponentialBoundaries = (options: {
@@ -4742,7 +4765,7 @@ const fiberFailures = counter("child_fiber_failures", {
  * })
  * ```
  *
- * @category Runtime Metrics
+ * @category metrics
  * @since 4.0.0
  */
 export const FiberRuntimeMetricsKey: "effect/observability/Metric/FiberRuntimeMetricsKey" =
@@ -4784,7 +4807,7 @@ export const FiberRuntimeMetricsKey: "effect/observability/Metric/FiberRuntimeMe
  * })
  * ```
  *
- * @category Runtime Metrics
+ * @category metrics
  * @since 4.0.0
  */
 export interface FiberRuntimeMetricsService {
@@ -4793,7 +4816,13 @@ export interface FiberRuntimeMetricsService {
 }
 
 /**
- * `Context.Reference` for the optional fiber runtime metrics service.
+ * Context reference for the optional service that records fiber runtime
+ * metrics.
+ *
+ * **When to use**
+ *
+ * Use to provide or inspect the service that receives fiber start and end
+ * notifications for automatic runtime metrics.
  *
  * **Details**
  *
@@ -4841,7 +4870,7 @@ export interface FiberRuntimeMetricsService {
  * })
  * ```
  *
- * @category Runtime Metrics
+ * @category runtime metrics
  * @since 4.0.0
  */
 export const FiberRuntimeMetrics = Context.Reference<FiberRuntimeMetricsService | undefined>(
@@ -4891,7 +4920,7 @@ export const FiberRuntimeMetrics = Context.Reference<FiberRuntimeMetricsService
  * })
  * ```
  *
- * @category Runtime Metrics
+ * @category metrics
  * @since 4.0.0
  */
 export const FiberRuntimeMetricsImpl: FiberRuntimeMetricsService = {
@@ -4910,15 +4939,13 @@ export const FiberRuntimeMetricsImpl: FiberRuntimeMetricsService = {
 }
 
 /**
- * A Layer that enables automatic collection of fiber runtime metrics across
+ * Layer that enables automatic collection of fiber runtime metrics across
  * an entire Effect application.
  *
  * **When to use**
  *
- * Unlike the function version which wraps individual Effects, this layer provides
- * runtime metrics collection to all Effects in the application context. This is
- * the recommended approach for production applications that need comprehensive
- * fiber monitoring.
+ * Use when you need runtime metrics collection for all Effects in the
+ * application context rather than wrapping individual Effects.
  *
  * **Example** (Enabling runtime metrics with a layer)
  *
@@ -5006,13 +5033,13 @@ export const FiberRuntimeMetricsImpl: FiberRuntimeMetricsService = {
  * )
  * ```
  *
- * @category Runtime Metrics
+ * @category metrics
  * @since 4.0.0
  */
 export const enableRuntimeMetricsLayer = Layer.succeed(FiberRuntimeMetrics)(FiberRuntimeMetricsImpl)
 
 /**
- * A Layer that disables automatic collection of fiber runtime metrics.
+ * Layer that disables automatic collection of fiber runtime metrics.
  *
  * **Example** (Disabling runtime metrics with a layer)
  *
@@ -5047,7 +5074,7 @@ export const enableRuntimeMetricsLayer = Layer.succeed(FiberRuntimeMetrics)(Fibe
  * })
  * ```
  *
- * @category Runtime Metrics
+ * @category metrics
  * @since 4.0.0
  */
 export const disableRuntimeMetricsLayer = Layer.succeed(FiberRuntimeMetrics)(undefined)
@@ -5131,7 +5158,7 @@ export const disableRuntimeMetricsLayer = Layer.succeed(FiberRuntimeMetrics)(und
  * )
  * ```
  *
- * @category Runtime Metrics
+ * @category metrics
  * @since 4.0.0
  */
 export const enableRuntimeMetrics: <A, E, R>(self: Effect<A, E, R>) => Effect<A, E, R> = InternalEffect.provideService(
@@ -5144,7 +5171,7 @@ export const enableRuntimeMetrics: <A, E, R>(self: Effect<A, E, R>) => Effect<A,
  *
  * **When to use**
  *
- * This is useful when you want to selectively disable runtime metrics for specific
+ * 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.
  *
@@ -5219,7 +5246,7 @@ export const enableRuntimeMetrics: <A, E, R>(self: Effect<A, E, R>) => Effect<A,
  * )
  * ```
  *
- * @category Runtime Metrics
+ * @category metrics
  * @since 4.0.0
  */
 export const disableRuntimeMetrics: <A, E, R>(self: Effect<A, E, R>) => Effect<A, E, R> = InternalEffect.provideService(