Gauge<Input>A Gauge metric that tracks instantaneous values that can go up or down.
When to use
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)
import { Data, Effect, Metric } from "effect"
class GaugeInterfaceError extends Data.TaggedError("GaugeInterfaceError")<{
readonly operation: string
}> {}
const program = Effect.gen(function*() {
// Create different types of gauges
const memoryGauge: Metric.Gauge<number> = Metric.gauge("memory_usage_mb", {
description: "Current memory usage in megabytes"
})
const diskSpaceGauge: Metric.Gauge<bigint> = Metric.gauge("disk_free_bytes", {
description: "Available disk space in bytes",
bigint: true,
attributes: { mount: "/var" }
})
// Set gauge values (absolute values)
yield* Metric.update(memoryGauge, 512) // Set to 512 MB
yield* Metric.update(memoryGauge, 640) // Set to 640 MB (replaces 512)
yield* Metric.update(diskSpaceGauge, 5000000000n) // Set to ~5GB free
// Modify gauge values (relative changes)
yield* Metric.modify(memoryGauge, 128) // Add 128 MB (total: 768)
yield* Metric.modify(memoryGauge, -64) // Subtract 64 MB (total: 704)
// Read gauge state
const memoryState: Metric.GaugeState<number> = yield* Metric.value(
memoryGauge
)
const diskState: Metric.GaugeState<bigint> = yield* Metric.value(
diskSpaceGauge
)
// Gauge state contains:
// - value: current instantaneous value
return {
memory: { currentValue: memoryState.value }, // 704
disk: { currentValue: diskState.value } // 5000000000n
}
})metrics
Source effect/Metric.ts:4841 lines
export interface interface Gauge<in Input extends number | bigint>A Gauge metric that tracks instantaneous values that can go up or down.
When to use
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)
import { Data, Effect, Metric } from "effect"
class GaugeInterfaceError extends Data.TaggedError("GaugeInterfaceError")<{
readonly operation: string
}> {}
const program = Effect.gen(function*() {
// Create different types of gauges
const memoryGauge: Metric.Gauge<number> = Metric.gauge("memory_usage_mb", {
description: "Current memory usage in megabytes"
})
const diskSpaceGauge: Metric.Gauge<bigint> = Metric.gauge("disk_free_bytes", {
description: "Available disk space in bytes",
bigint: true,
attributes: { mount: "/var" }
})
// Set gauge values (absolute values)
yield* Metric.update(memoryGauge, 512) // Set to 512 MB
yield* Metric.update(memoryGauge, 640) // Set to 640 MB (replaces 512)
yield* Metric.update(diskSpaceGauge, 5000000000n) // Set to ~5GB free
// Modify gauge values (relative changes)
yield* Metric.modify(memoryGauge, 128) // Add 128 MB (total: 768)
yield* Metric.modify(memoryGauge, -64) // Subtract 64 MB (total: 704)
// Read gauge state
const memoryState: Metric.GaugeState<number> = yield* Metric.value(
memoryGauge
)
const diskState: Metric.GaugeState<bigint> = yield* Metric.value(
diskSpaceGauge
)
// Gauge state contains:
// - value: current instantaneous value
return {
memory: { currentValue: memoryState.value }, // 704
disk: { currentValue: diskState.value } // 5000000000n
}
})
Gauge<in function (type parameter) Input in Gauge<in Input extends number | bigint>Input extends number | bigint> extends interface Metric<in Input, out State>A Metric<Input, State> represents a concurrent metric which accepts update
values of type Input and are aggregated to a value of type State.
Details
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
Example (Using multiple metric types)
import { Data, Effect, Metric } from "effect"
class MetricExample extends Data.TaggedError("MetricExample")<{
readonly operation: string
}> {}
const program = Effect.gen(function*() {
// Create different types of metrics
const requestCounter: Metric.Counter<number> = Metric.counter("requests", {
description: "Total requests processed"
})
const memoryGauge: Metric.Gauge<number> = Metric.gauge("memory_usage", {
description: "Current memory usage in MB"
})
const statusFrequency: Metric.Frequency = Metric.frequency("status_codes", {
description: "HTTP status code frequency"
})
// All metrics share the same interface for updates and reads
yield* Metric.update(requestCounter, 1)
yield* Metric.update(memoryGauge, 128)
yield* Metric.update(statusFrequency, "200")
// All metrics can be read with Metric.value
const counterState = yield* Metric.value(requestCounter)
const gaugeState = yield* Metric.value(memoryGauge)
const frequencyState = yield* Metric.value(statusFrequency)
// Metrics have common properties accessible through the interface:
// - id: unique identifier
// - type: metric type ("Counter", "Gauge", "Frequency", etc.)
// - description: optional human-readable description
// - attributes: optional key-value attributes for tagging
return {
counter: {
id: requestCounter.id,
type: requestCounter.type,
state: counterState
},
gauge: { id: memoryGauge.id, type: memoryGauge.type, state: gaugeState },
frequency: {
id: statusFrequency.id,
type: statusFrequency.type,
state: frequencyState
}
}
})
The Metric namespace provides a comprehensive system for collecting, aggregating, and observing
application metrics in Effect applications.
Example (Collecting application metrics)
import { Data, Effect, Metric } from "effect"
class MetricsError extends Data.TaggedError("MetricsError")<{
readonly operation: string
}> {}
const program = Effect.gen(function*() {
// Create different types of metrics
const requestCounter = Metric.counter("http_requests_total")
const responseTimeHistogram = Metric.histogram("http_response_time", {
boundaries: Metric.linearBoundaries({ start: 0, width: 10, count: 10 })
})
const activeConnectionsGauge = Metric.gauge("active_connections")
const statusFrequency = Metric.frequency("http_status_codes")
// Update metrics
yield* Metric.update(requestCounter, 1)
yield* Metric.update(responseTimeHistogram, 45.2)
yield* Metric.update(activeConnectionsGauge, 12)
yield* Metric.update(statusFrequency, "200")
// Get metric values
const counterValue = yield* Metric.value(requestCounter)
const histogramValue = yield* Metric.value(responseTimeHistogram)
const gaugeValue = yield* Metric.value(activeConnectionsGauge)
const frequencyValue = yield* Metric.value(statusFrequency)
return {
counter: counterValue,
histogram: histogramValue,
gauge: gaugeValue,
frequency: frequencyValue
}
})
Metric<function (type parameter) Input in Gauge<in Input extends number | bigint>Input, interface GaugeState<in Input extends number | bigint>State interface for Gauge metrics containing the current instantaneous value.
Example (Reading gauge state)
import { Data, Effect, Metric } from "effect"
class GaugeStateError extends Data.TaggedError("GaugeStateError")<{
readonly operation: string
}> {}
const program = Effect.gen(function*() {
// Create different types of gauges
const temperatureGauge = Metric.gauge("room_temperature_celsius", {
description: "Current room temperature"
})
const diskSpaceGauge = Metric.gauge("disk_usage_bytes", {
description: "Current disk usage",
bigint: true
})
const queueSizeGauge = Metric.gauge("queue_size", {
description: "Current queue size"
})
// Set gauge values (absolute values)
yield* Metric.update(temperatureGauge, 22.5) // Set to 22.5°C
yield* Metric.update(diskSpaceGauge, 5000000000n) // Set to 5GB usage
yield* Metric.update(queueSizeGauge, 10) // Set to 10 items
// Update gauge values (new absolute values)
yield* Metric.update(temperatureGauge, 23.1) // Temperature changed
yield* Metric.update(queueSizeGauge, 15) // Queue grew
// Read gauge states
const tempState: Metric.GaugeState<number> = yield* Metric.value(
temperatureGauge
)
const diskState: Metric.GaugeState<bigint> = yield* Metric.value(
diskSpaceGauge
)
const queueState: Metric.GaugeState<number> = yield* Metric.value(
queueSizeGauge
)
// GaugeState contains:
// - value: current instantaneous value (number or bigint based on gauge type)
return {
environment: {
temperature: tempState.value, // 23.1
temperatureUnit: "°C"
},
system: {
diskUsage: diskState.value, // 5000000000n
diskUsageGB: Number(diskState.value) / 1_000_000_000, // 5
queueSize: queueState.value // 15
}
}
})
GaugeState<function (type parameter) Input in Gauge<in Input extends number | bigint>Input>> {}Referenced by 2 symbols