Metric
Aspects
Signature
declare const set: {
(value: number): (self: Gauge<number>) => Effect<void>;
(value: bigint): (self: Gauge<bigint>) => Effect<void>;
(self: Gauge<number>, value: number): Effect<void>;
(self: Gauge<bigint>, value: bigint): Effect<void>;
};Signature
declare const trackAll: {
<In>(
input: In,
): <Type, Out>(
self: Metric<Type, In, Out>,
) => <A, E, R>(effect: Effect<A, E, R>) => Effect<A, E, R>;
<Type, In, Out>(
self: Metric<Type, In, Out>,
input: In,
): <A, E, R>(effect: Effect<A, E, R>) => Effect<A, E, R>;
};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<A, E, R>) => Effect<A, E, R>;
<A, E, R, Type, Out>(self: Effect<A, E, R>, metric: Metric<Type, unknown, Out>): Effect<A, E, R>;
};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<A, E, R>) => Effect<A, E, R>;
<A, E, R, Type, In, Out>(
self: Effect<A, E, R>,
metric: Metric<Type, In, Out>,
f: (defect: unknown) => In,
): Effect<A, E, R>;
};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, Out>,
): <A, E, R>(self: Effect<A, E, R>) => Effect<A, E, R>;
<A, E, R, Type, Out>(self: Effect<A, E, R>, metric: Metric<Type, Duration, Out>): Effect<A, E, R>;
};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) => In,
): <A, E, R>(effect: Effect<A, E, R>) => Effect<A, E, R>;
<A, E, R, Type, In, Out>(
self: Effect<A, E, R>,
metric: Metric<Type, In, Out>,
f: (duration: Duration) => In,
): Effect<A, E, R>;
};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, R>(self: Effect<A, E, R>) => Effect<A, E, R>;
<A, E, R, Type, In, Out>(self: Effect<A, E, R>, metric: Metric<Type, In, Out>): Effect<A, E, R>;
};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, R>(effect: Effect<A, E, R>) => Effect<A, E, R>;
<A, E, R, Type, In, Out, In2>(
self: Effect<A, E, R>,
metric: Metric<Type, In, Out>,
f: (error: In2) => In,
): Effect<A, E, R>;
};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, E, R>(self: Effect<A, E, R>) => Effect<A, E, R>;
<A, E, R, Type, In, Out>(self: Effect<A, E, R>, metric: Metric<Type, In, Out>): Effect<A, E, R>;
};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, A>(
metric: Metric<Type, In, Out>,
f: (value: NoInfer<A>) => In,
): <E, R>(self: Effect<A, E, R>) => Effect<A, E, R>;
<A, E, R, Type, In, Out>(
self: Effect<A, E, R>,
metric: Metric<Type, In, Out>,
f: (value: NoInfer<A>) => In,
): Effect<A, E, R>;
};Combinators
Signature
declare const increment: (
self:
| Metric.Counter<number>
| Metric.Counter<bigint>
| Metric.Gauge<number>
| Metric.Gauge<bigint>,
) => Effect.Effect<void>;incrementBy
Signature
declare const incrementBy: {
(amount: number): (self: Counter<number>) => Effect<void>;
(amount: bigint): (self: Counter<bigint> | Gauge<bigint>) => Effect<void>;
(self: Counter<number> | Gauge<number>, amount: number): Effect<void>;
(self: Counter<bigint> | Gauge<bigint>, amount: bigint): Effect<void>;
};Constructors
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.
Signature
declare const counter: {
(
name: string,
options?: {
readonly bigint?: false;
readonly description?: string;
readonly incremental?: boolean;
},
): Counter<number>;
(
name: string,
options: {
readonly bigint: true;
readonly description?: string;
readonly incremental?: boolean;
},
): Counter<bigint>;
};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,
})Creates a Frequency metric to count occurrences of events. Frequency metrics are used to count the number of times specific events or incidents occur.
Signature
declare const frequency: (
name: string,
options?: {
readonly description?: string;
readonly preregisteredWords?: ReadonlyArray<string>;
},
) => Metric.Frequency<string>;Example
import { Metric } from "effect"
const errorFrequency = Metric.frequency("error_frequency", {
description: "Counts the occurrences of errors.",
})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>
>;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.
Signature
declare const gauge: {
(
name: string,
options?: {
readonly bigint?: false;
readonly description?: string;
},
): Gauge<number>;
(
name: string,
options: {
readonly bigint: true;
readonly description?: string;
},
): Gauge<bigint>;
};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,
})Represents a Histogram metric that records observations in specified value boundaries. Histogram metrics are useful for measuring the distribution of values within a range.
Signature
declare const histogram: (
name: string,
boundaries: MetricBoundaries.MetricBoundaries,
description?: string,
) => Metric<MetricKeyType.MetricKeyType.Histogram, number, MetricState.MetricState.Histogram>;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 make: MetricApply;Creates a metric that ignores input and produces constant output.
Signature
declare const succeed: <Out>(out: Out) => Metric<void, unknown, Out>;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.
Signature
declare const summary: (options: {
readonly description?: string;
readonly error: number;
readonly maxAge: Duration.DurationInput;
readonly maxSize: number;
readonly name: string;
readonly quantiles: ReadonlyArray<number>;
}) => Metric.Summary<number>;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.",
})summaryTimestamp
Signature
declare const summaryTimestamp: (options: {
readonly description?: string;
readonly error: number;
readonly maxAge: Duration.DurationInput;
readonly maxSize: number;
readonly name: string;
readonly quantiles: ReadonlyArray<number>;
}) => Metric.Summary<readonly [value: number, timestamp: number]>;Creates a metric that ignores input and produces constant output.
Signature
declare const sync: <Out>(evaluate: LazyArg<Out>) => Metric<void, unknown, Out>;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
>;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
>;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>;
};Getters
Captures a snapshot of all metrics recorded by the application.
Signature
declare const snapshot: Effect.Effect<Array<MetricPair.MetricPair.Untyped>>;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>;Globals
globalMetricRegistry
Signature
declare const globalMetricRegistry: MetricRegistry.MetricRegistry;Mapping
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>;
};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>;
};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>;
};Metrics
fiberActive
Signature
declare const fiberActive: Metric.Counter<number>;fiberFailures
Signature
declare const fiberFailures: Metric.Counter<number>;fiberLifetimes
Signature
declare const fiberLifetimes: Metric<
MetricKeyType.MetricKeyType.Histogram,
number,
MetricState.MetricState.Histogram
>;fiberStarted
Signature
declare const fiberStarted: Metric.Counter<number>;fiberSuccesses
Signature
declare const fiberSuccesses: Metric.Counter<number>;Models
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
interface Metric<in out Type, in In, out Out> extends Variance<Type, In, Out>, Pipeable {
<A, E, R>(effect: Effect<A, E, R>): Effect<A, E, R>;
readonly keyType: Type;
register(): this;
unsafeModify(input: In, extraTags: readonly Array<MetricLabel>): void;
unsafeUpdate(input: In, extraTags: readonly Array<MetricLabel>): void;
unsafeValue(extraTags: readonly Array<MetricLabel>): Out;
}MetricApply interface
Signature
interface MetricApply {
<Type, In, Out>(keyType: Type, unsafeUpdate: (input: In, extraTags: readonly Array<MetricLabel>) => void, unsafeValue: (extraTags: readonly Array<MetricLabel>) => Out, unsafeModify: (input: In, extraTags: readonly Array<MetricLabel>) => void): Metric<Type, In, Out>;
}Other
Symbols
MetricTypeId
Signature
declare const MetricTypeId: unique symbol;MetricTypeId type
Signature
type MetricTypeId = typeof MetricTypeId;Unsafe
unsafeSnapshot
Unsafely captures a snapshot of all metrics recorded by the application.
Signature
declare const unsafeSnapshot: (_: void) => ReadonlyArray<MetricPair.MetricPair.Untyped>;Utils
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<void>;
<Type, In, Out>(self: Metric<Type, In, Out>, input: In): Effect<void>;
};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>;
};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>,
): (self: Metric<Type, In, Out>) => Metric<Type, In, Out>;
<Type, In, Out>(
self: Metric<Type, In, Out>,
extraTags: Iterable<MetricLabel>,
): Metric<Type, In, Out>;
};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>,
): <Type, Out>(self: Metric<Type, In, Out>) => Metric<Type, In, void>;
<Type, In, Out>(
self: Metric<Type, In, Out>,
f: (input: In) => Iterable<MetricLabel>,
): Metric<Type, In, void>;
};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<void>;
<Type, In, Out>(self: Metric<Type, In, Out>, input: In): Effect<void>;
};Signature
declare const withNow: <Type, In, Out>(
self: Metric<Type, readonly [In, number], Out>,
) => Metric<Type, In, Out>;Zipping
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]>;
};
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.