Skip to main content Link Search Menu Expand Document (external link)
effect

Metric.ts overview

Since v2.0.0

Exports Grouped by Category

aspects

set

Signature

declare const set: {
  (value: number): (self: Metric.Gauge<number>) => Effect.Effect<void>
  (value: bigint): (self: Metric.Gauge<bigint>) => Effect.Effect<void>
  (self: Metric.Gauge<number>, value: number): Effect.Effect<void>
  (self: Metric.Gauge<bigint>, value: bigint): Effect.Effect<void>
}

Source

Since v2.0.0

trackAll

Returns an aspect that will update this metric with the specified constant value every time the aspect is applied to an effect, regardless of whether that effect fails or succeeds.

Signature

declare const trackAll: {
  <In>(
    input: In
  ): <Type, Out>(self: Metric<Type, In, Out>) => <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>
  <Type, In, Out>(
    self: Metric<Type, In, Out>,
    input: In
  ): <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>
}

Source

Since v2.0.0

trackDefect

Returns an aspect that will update this metric with the defects of the effects that it is applied to.

Signature

declare const trackDefect: {
  <Type, Out>(metric: Metric<Type, unknown, Out>): <A, E, R>(self: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>
  <A, E, R, Type, Out>(self: Effect.Effect<A, E, R>, metric: Metric<Type, unknown, Out>): Effect.Effect<A, E, R>
}

Source

Since v2.0.0

trackDefectWith

Returns an aspect that will update this metric with the result of applying the specified function to the defect throwables of the effects that the aspect is applied to.

Signature

declare const trackDefectWith: {
  <Type, In, Out>(
    metric: Metric<Type, In, Out>,
    f: (defect: unknown) => In
  ): <A, E, R>(self: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>
  <A, E, R, Type, In, Out>(
    self: Effect.Effect<A, E, R>,
    metric: Metric<Type, In, Out>,
    f: (defect: unknown) => In
  ): Effect.Effect<A, E, R>
}

Source

Since v2.0.0

trackDuration

Returns an aspect that will update this metric with the duration that the effect takes to execute. To call this method, the input type of the metric must be Duration.

Signature

declare const trackDuration: {
  <Type, Out>(
    metric: Metric<Type, Duration.Duration, Out>
  ): <A, E, R>(self: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>
  <A, E, R, Type, Out>(
    self: Effect.Effect<A, E, R>,
    metric: Metric<Type, Duration.Duration, Out>
  ): Effect.Effect<A, E, R>
}

Source

Since v2.0.0

trackDurationWith

Returns an aspect that will update this metric with the duration that the effect takes to execute. To call this method, you must supply a function that can convert the Duration to the input type of this metric.

Signature

declare const trackDurationWith: {
  <Type, In, Out>(
    metric: Metric<Type, In, Out>,
    f: (duration: Duration.Duration) => In
  ): <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>
  <A, E, R, Type, In, Out>(
    self: Effect.Effect<A, E, R>,
    metric: Metric<Type, In, Out>,
    f: (duration: Duration.Duration) => In
  ): Effect.Effect<A, E, R>
}

Source

Since v2.0.0

trackError

Returns an aspect that will update this metric with the failure value of the effects that it is applied to.

Signature

declare const trackError: {
  <Type, In, Out>(
    metric: Metric<Type, In, Out>
  ): <A, E extends In, R>(self: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>
  <A, E extends In, R, Type, In, Out>(
    self: Effect.Effect<A, E, R>,
    metric: Metric<Type, In, Out>
  ): Effect.Effect<A, E, R>
}

Source

Since v2.0.0

trackErrorWith

Returns an aspect that will update this metric with the result of applying the specified function to the error value of the effects that the aspect is applied to.

Signature

declare const trackErrorWith: {
  <Type, In, Out, In2>(
    metric: Metric<Type, In, Out>,
    f: (error: In2) => In
  ): <A, E extends In2, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>
  <A, E extends In2, R, Type, In, Out, In2>(
    self: Effect.Effect<A, E, R>,
    metric: Metric<Type, In, Out>,
    f: (error: In2) => In
  ): Effect.Effect<A, E, R>
}

Source

Since v2.0.0

trackSuccess

Returns an aspect that will update this metric with the success value of the effects that it is applied to.

Signature

declare const trackSuccess: {
  <Type, In, Out>(
    metric: Metric<Type, In, Out>
  ): <A extends In, E, R>(self: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>
  <A extends In, E, R, Type, In, Out>(
    self: Effect.Effect<A, E, R>,
    metric: Metric<Type, In, Out>
  ): Effect.Effect<A, E, R>
}

Source

Since v2.0.0

trackSuccessWith

Returns an aspect that will update this metric with the result of applying the specified function to the success value of the effects that the aspect is applied to.

Signature

declare const trackSuccessWith: {
  <Type, In, Out, In2>(
    metric: Metric<Type, In, Out>,
    f: (value: In2) => In
  ): <A extends In2, E, R>(self: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>
  <A extends In2, E, R, Type, In, Out, In2>(
    self: Effect.Effect<A, E, R>,
    metric: Metric<Type, In, Out>,
    f: (value: In2) => In
  ): Effect.Effect<A, E, R>
}

Source

Since v2.0.0

combinators

increment

Signature

declare const increment: (
  self: Metric.Counter<number> | Metric.Counter<bigint> | Metric.Gauge<number> | Metric.Gauge<bigint>
) => Effect.Effect<void>

Source

Since v2.0.0

incrementBy

Signature

declare const incrementBy: {
  (amount: number): (self: Metric.Counter<number> | Metric.Counter<number>) => Effect.Effect<void>
  (amount: bigint): (self: Metric.Counter<bigint> | Metric.Gauge<bigint>) => Effect.Effect<void>
  (self: Metric.Counter<number> | Metric.Gauge<number>, amount: number): Effect.Effect<void>
  (self: Metric.Counter<bigint> | Metric.Gauge<bigint>, amount: bigint): Effect.Effect<void>
}

Source

Since v2.0.0

constructors

counter

Represents a Counter metric that tracks cumulative numerical values over time. Counters can be incremented and decremented and provide a running total of changes.

Options

  • description - A description of the counter.
  • bigint - Indicates if the counter uses ‘bigint’ data type.
  • incremental - Set to ‘true’ for a counter that only increases. With this configuration, Effect ensures that non-incremental updates have no impact on the counter, making it exclusively suitable for counting upwards.

Example

import { Metric } from "effect"

const numberCounter = Metric.counter("count", {
  description: "A number counter"
})

const bigintCounter = Metric.counter("count", {
  description: "A bigint counter",
  bigint: true
})

Signature

declare const counter: {
  (
    name: string,
    options?: {
      readonly description?: string | undefined
      readonly bigint?: false | undefined
      readonly incremental?: boolean | undefined
    }
  ): Metric.Counter<number>
  (
    name: string,
    options: {
      readonly description?: string | undefined
      readonly bigint: true
      readonly incremental?: boolean | undefined
    }
  ): Metric.Counter<bigint>
}

Source

Since v2.0.0

frequency

Creates a Frequency metric to count occurrences of events. Frequency metrics are used to count the number of times specific events or incidents occur.

Example

import { Metric } from "effect"

const errorFrequency = Metric.frequency("error_frequency", {
  description: "Counts the occurrences of errors."
})

Signature

declare const frequency: (
  name: string,
  options?:
    | { readonly description?: string | undefined; readonly preregisteredWords?: ReadonlyArray<string> | undefined }
    | undefined
) => Metric.Frequency<string>

Source

Since v2.0.0

fromMetricKey

Signature

declare const fromMetricKey: <Type extends MetricKeyType.MetricKeyType<any, any>>(
  key: MetricKey.MetricKey<Type>
) => Metric<Type, MetricKeyType.MetricKeyType.InType<Type>, MetricKeyType.MetricKeyType.OutType<Type>>

Source

Since v2.0.0

gauge

Represents a Gauge metric that tracks and reports a single numerical value at a specific moment. Gauges are suitable for metrics that represent instantaneous values, such as memory usage or CPU load.

Options

  • description - A description of the gauge metric.
  • bigint - Indicates if the counter uses ‘bigint’ data type.

Example

import { Metric } from "effect"

const numberGauge = Metric.gauge("memory_usage", {
  description: "A gauge for memory usage"
})

const bigintGauge = Metric.gauge("cpu_load", {
  description: "A gauge for CPU load",
  bigint: true
})

Signature

declare const gauge: {
  (
    name: string,
    options?: { readonly description?: string | undefined; readonly bigint?: false | undefined }
  ): Metric.Gauge<number>
  (name: string, options: { readonly description?: string | undefined; readonly bigint: true }): Metric.Gauge<bigint>
}

Source

Since v2.0.0

histogram

Represents a Histogram metric that records observations in specified value boundaries. Histogram metrics are useful for measuring the distribution of values within a range.

Example

import { Metric, MetricBoundaries } from "effect"

const latencyHistogram = Metric.histogram(
  "latency_histogram",
  MetricBoundaries.linear({ start: 0, width: 10, count: 11 }),
  "Measures the distribution of request latency."
)

Signature

declare const histogram: (
  name: string,
  boundaries: MetricBoundaries.MetricBoundaries,
  description?: string
) => Metric<MetricKeyType.MetricKeyType.Histogram, number, MetricState.MetricState.Histogram>

Source

Since v2.0.0

make

Signature

declare const make: MetricApply

Source

Since v2.0.0

succeed

Creates a metric that ignores input and produces constant output.

Signature

declare const succeed: <Out>(out: Out) => Metric<void, unknown, Out>

Source

Since v2.0.0

summary

Creates a Summary metric that records observations and calculates quantiles. Summary metrics provide statistical information about a set of values, including quantiles.

Options

  • name - The name of the Summary metric.
  • maxAge - The maximum age of observations to retain.
  • maxSize - The maximum number of observations to keep.
  • error - The error percentage when calculating quantiles.
  • quantiles - An Chunk of quantiles to calculate (e.g., [0.5, 0.9]).
  • description - An optional description of the Summary metric.

Example

import { Metric, Chunk } from "effect"

const responseTimesSummary = Metric.summary({
  name: "response_times_summary",
  maxAge: "60 seconds", // Retain observations for 60 seconds.
  maxSize: 1000, // Keep a maximum of 1000 observations.
  error: 0.01, // Allow a 1% error when calculating quantiles.
  quantiles: [0.5, 0.9, 0.99], // Calculate 50th, 90th, and 99th percentiles.
  description: "Measures the distribution of response times."
})

Signature

declare const summary: (options: {
  readonly name: string
  readonly maxAge: Duration.DurationInput
  readonly maxSize: number
  readonly error: number
  readonly quantiles: ReadonlyArray<number>
  readonly description?: string | undefined
}) => Metric.Summary<number>

Source

Since v2.0.0

summaryTimestamp

Signature

declare const summaryTimestamp: (options: {
  readonly name: string
  readonly maxAge: Duration.DurationInput
  readonly maxSize: number
  readonly error: number
  readonly quantiles: ReadonlyArray<number>
  readonly description?: string | undefined
}) => Metric.Summary<readonly [value: number, timestamp: number]>

Source

Since v2.0.0

sync

Creates a metric that ignores input and produces constant output.

Signature

declare const sync: <Out>(evaluate: LazyArg<Out>) => Metric<void, unknown, Out>

Source

Since v2.0.0

timer

Creates a timer metric, based on a histogram, which keeps track of durations in milliseconds. The unit of time will automatically be added to the metric as a tag (i.e. "time_unit: milliseconds").

Signature

declare const timer: (
  name: string,
  description?: string
) => Metric<MetricKeyType.MetricKeyType.Histogram, Duration.Duration, MetricState.MetricState.Histogram>

Source

Since v2.0.0

timerWithBoundaries

Creates a timer metric, based on a histogram created from the provided boundaries, which keeps track of durations in milliseconds. The unit of time will automatically be added to the metric as a tag (i.e. "time_unit: milliseconds").

Signature

declare const timerWithBoundaries: (
  name: string,
  boundaries: ReadonlyArray<number>,
  description?: string
) => Metric<MetricKeyType.MetricKeyType.Histogram, Duration.Duration, MetricState.MetricState.Histogram>

Source

Since v2.0.0

withConstantInput

Returns a new metric that is powered by this one, but which accepts updates of any type, and translates them to updates with the specified constant update value.

Signature

declare const withConstantInput: {
  <In>(input: In): <Type, Out>(self: Metric<Type, In, Out>) => Metric<Type, unknown, Out>
  <Type, In, Out>(self: Metric<Type, In, Out>, input: In): Metric<Type, unknown, Out>
}

Source

Since v2.0.0

getters

snapshot

Captures a snapshot of all metrics recorded by the application.

Signature

declare const snapshot: Effect.Effect<Array<MetricPair.MetricPair.Untyped>, never, never>

Source

Since v2.0.0

value

Retrieves a snapshot of the value of the metric at this moment in time.

Signature

declare const value: <Type, In, Out>(self: Metric<Type, In, Out>) => Effect.Effect<Out>

Source

Since v2.0.0

globals

globalMetricRegistry

Signature

declare const globalMetricRegistry: MetricRegistry.MetricRegistry

Source

Since v2.0.0

mapping

map

Returns a new metric that is powered by this one, but which outputs a new state type, determined by transforming the state type of this metric by the specified function.

Signature

declare const map: {
  <Out, Out2>(f: (out: Out) => Out2): <Type, In>(self: Metric<Type, In, Out>) => Metric<Type, In, Out2>
  <Type, In, Out, Out2>(self: Metric<Type, In, Out>, f: (out: Out) => Out2): Metric<Type, In, Out2>
}

Source

Since v2.0.0

mapInput

Returns a new metric that is powered by this one, but which accepts updates of the specified new type, which must be transformable to the input type of this metric.

Signature

declare const mapInput: {
  <In, In2>(f: (input: In2) => In): <Type, Out>(self: Metric<Type, In, Out>) => Metric<Type, In2, Out>
  <Type, In, Out, In2>(self: Metric<Type, In, Out>, f: (input: In2) => In): Metric<Type, In2, Out>
}

Source

Since v2.0.0

mapType

Signature

declare const mapType: {
  <Type, Type2>(f: (type: Type) => Type2): <In, Out>(self: Metric<Type, In, Out>) => Metric<Type2, In, Out>
  <Type, In, Out, Type2>(self: Metric<Type, In, Out>, f: (type: Type) => Type2): Metric<Type2, In, Out>
}

Source

Since v2.0.0

metrics

fiberActive

Signature

declare const fiberActive: Metric.Counter<number>

Source

Since v2.0.0

fiberFailures

Signature

declare const fiberFailures: Metric.Counter<number>

Source

Since v2.0.0

fiberLifetimes

Signature

declare const fiberLifetimes: Metric<MetricKeyType.MetricKeyType.Histogram, number, MetricState.MetricState.Histogram>

Source

Since v2.0.0

fiberStarted

Signature

declare const fiberStarted: Metric.Counter<number>

Source

Since v2.0.0

fiberSuccesses

Signature

declare const fiberSuccesses: Metric.Counter<number>

Source

Since v2.0.0

models

Metric (interface)

A Metric<Type, In, Out> represents a concurrent metric which accepts updates of type In and are aggregated to a stateful value of type Out.

For example, a counter metric would have type Metric<number, number>, representing the fact that the metric can be updated with numbers (the amount to increment or decrement the counter by), and the state of the counter is a number.

There are five primitive metric types supported by Effect:

  • Counters
  • Frequencies
  • Gauges
  • Histograms
  • Summaries

Signature

export interface Metric<in out Type, in In, out Out> extends Metric.Variance<Type, In, Out>, Pipeable {
  /**
   * The type of the underlying primitive metric. For example, this could be
   * `MetricKeyType.Counter` or `MetricKeyType.Gauge`.
   */
  readonly keyType: Type
  unsafeUpdate(input: In, extraTags: ReadonlyArray<MetricLabel.MetricLabel>): void
  unsafeValue(extraTags: ReadonlyArray<MetricLabel.MetricLabel>): Out
  unsafeModify(input: In, extraTags: ReadonlyArray<MetricLabel.MetricLabel>): void
  register(): this
  <A extends In, E, R>(effect: Effect.Effect<A, E, R>): Effect.Effect<A, E, R>
}

Source

Since v2.0.0

MetricApply (interface)

Signature

export interface MetricApply {
  <Type, In, Out>(
    keyType: Type,
    unsafeUpdate: (input: In, extraTags: ReadonlyArray<MetricLabel.MetricLabel>) => void,
    unsafeValue: (extraTags: ReadonlyArray<MetricLabel.MetricLabel>) => Out,
    unsafeModify: (input: In, extraTags: ReadonlyArray<MetricLabel.MetricLabel>) => void
  ): Metric<Type, In, Out>
}

Source

Since v2.0.0

symbols

MetricTypeId

Signature

declare const MetricTypeId: unique symbol

Source

Since v2.0.0

MetricTypeId (type alias)

Signature

type MetricTypeId = typeof MetricTypeId

Source

Since v2.0.0

unsafe

unsafeSnapshot

Unsafely captures a snapshot of all metrics recorded by the application.

Signature

declare const unsafeSnapshot: (_: void) => ReadonlyArray<MetricPair.MetricPair.Untyped>

Source

Since v2.0.0

utils

Metric (namespace)

Source

Since v2.0.0

Counter (interface)

Signature

export interface Counter<In extends number | bigint>
  extends Metric<MetricKeyType.MetricKeyType.Counter<In>, In, MetricState.MetricState.Counter<In>> {}

Source

Since v2.0.0

Gauge (interface)

Signature

export interface Gauge<In extends number | bigint>
  extends Metric<MetricKeyType.MetricKeyType.Gauge<In>, In, MetricState.MetricState.Gauge<In>> {}

Source

Since v2.0.0

Frequency (interface)

Signature

export interface Frequency<In>
  extends Metric<MetricKeyType.MetricKeyType.Frequency, In, MetricState.MetricState.Frequency> {}

Source

Since v2.0.0

Histogram (interface)

Signature

export interface Histogram<In>
  extends Metric<MetricKeyType.MetricKeyType.Histogram, In, MetricState.MetricState.Histogram> {}

Source

Since v2.0.0

Summary (interface)

Signature

export interface Summary<In> extends Metric<MetricKeyType.MetricKeyType.Summary, In, MetricState.MetricState.Summary> {}

Source

Since v2.0.0

Variance (interface)

Signature

export interface Variance<in out Type, in In, out Out> {
  readonly [MetricTypeId]: {
    readonly _Type: Types.Invariant<Type>
    readonly _In: Types.Contravariant<In>
    readonly _Out: Types.Covariant<Out>
  }
}

Source

Since v2.0.0

modify

Modifies the metric with the specified update message. For example, if the metric were a gauge, the update would increment the method by the provided amount.

Signature

declare const modify: {
  <In>(input: In): <Type, Out>(self: Metric<Type, In, Out>) => Effect.Effect<void>
  <Type, In, Out>(self: Metric<Type, In, Out>, input: In): Effect.Effect<void>
}

Source

Since v3.6.5

tagged

Returns a new metric, which is identical in every way to this one, except the specified tags have been added to the tags of this metric.

Signature

declare const tagged: {
  <Type, In, Out>(key: string, value: string): (self: Metric<Type, In, Out>) => Metric<Type, In, Out>
  <Type, In, Out>(self: Metric<Type, In, Out>, key: string, value: string): Metric<Type, In, Out>
}

Source

Since v2.0.0

taggedWithLabels

Returns a new metric, which is identical in every way to this one, except the specified tags have been added to the tags of this metric.

Signature

declare const taggedWithLabels: {
  <Type, In, Out>(extraTags: Iterable<MetricLabel.MetricLabel>): (self: Metric<Type, In, Out>) => Metric<Type, In, Out>
  <Type, In, Out>(self: Metric<Type, In, Out>, extraTags: Iterable<MetricLabel.MetricLabel>): Metric<Type, In, Out>
}

Source

Since v2.0.0

taggedWithLabelsInput

Returns a new metric, which is identical in every way to this one, except dynamic tags are added based on the update values. Note that the metric returned by this method does not return any useful information, due to the dynamic nature of the added tags.

Signature

declare const taggedWithLabelsInput: {
  <In>(
    f: (input: In) => Iterable<MetricLabel.MetricLabel>
  ): <Type, Out>(self: Metric<Type, In, Out>) => Metric<Type, In, void>
  <Type, In, Out>(
    self: Metric<Type, In, Out>,
    f: (input: In) => Iterable<MetricLabel.MetricLabel>
  ): Metric<Type, In, void>
}

Source

Since v2.0.0

update

Updates the metric with the specified update message. For example, if the metric were a counter, the update would increment the method by the provided amount.

Signature

declare const update: {
  <In>(input: In): <Type, Out>(self: Metric<Type, In, Out>) => Effect.Effect<void>
  <Type, In, Out>(self: Metric<Type, In, Out>, input: In): Effect.Effect<void>
}

Source

Since v2.0.0

withNow

Signature

declare const withNow: <Type, In, Out>(self: Metric<Type, readonly [In, number], Out>) => Metric<Type, In, Out>

Source

Since v2.0.0

zipping

zip

Signature

declare const zip: {
  <Type2, In2, Out2>(
    that: Metric<Type2, In2, Out2>
  ): <Type, In, Out>(self: Metric<Type, In, Out>) => Metric<readonly [Type, Type2], readonly [In, In2], [Out, Out2]>
  <Type, In, Out, Type2, In2, Out2>(
    self: Metric<Type, In, Out>,
    that: Metric<Type2, In2, Out2>
  ): Metric<readonly [Type, Type2], readonly [In, In2], [Out, Out2]>
}

Source

Since v2.0.0