(
name: string,
options?: {
readonly description?: string | undefined
readonly attributes?: Metric.Attributes | undefined
readonly bigint?: false | undefined
}
): Gauge<number>
(
name: string,
options: {
readonly description?: string | undefined
readonly attributes?: Metric.Attributes | undefined
readonly bigint: true
}
): Gauge<bigint>Represents a Gauge metric that tracks and reports a single numerical value
at a specific moment.
When to use
Use when you need a metric for instantaneous values, such as memory usage or CPU load.
Details
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)
import { Data, Effect, Metric } from "effect"
class GaugeError extends Data.TaggedError("GaugeError")<{
readonly operation: string
}> {}
const program = Effect.gen(function*() {
// Create a gauge for tracking memory usage
const memoryGauge = Metric.gauge("memory_usage_mb", {
description: "Current memory usage in megabytes"
})
// Create a gauge for CPU utilization
const cpuGauge = Metric.gauge("cpu_utilization", {
description: "Current CPU utilization percentage",
attributes: { host: "server-01" }
})
// Create a bigint gauge for large values
const diskSpaceGauge = Metric.gauge("disk_free_bytes", {
description: "Free disk space in bytes",
bigint: true
})
// Set gauge values (replaces current value)
yield* Metric.update(memoryGauge, 512) // Set to 512 MB
yield* Metric.update(cpuGauge, 85.5) // Set to 85.5%
yield* Metric.update(diskSpaceGauge, 1024000000n) // Set to ~1GB
// Modify gauge values (adds to current value)
yield* Metric.modify(memoryGauge, 128) // Increase by 128 MB (total: 640)
yield* Metric.modify(cpuGauge, -10.5) // Decrease by 10.5% (total: 75%)
// Update with new absolute values
yield* Metric.update(memoryGauge, 800) // Set to 800 MB (replaces 640)
// Get current gauge values
const memoryValue = yield* Metric.value(memoryGauge)
const cpuValue = yield* Metric.value(cpuGauge)
const diskValue = yield* Metric.value(diskSpaceGauge)
return { memoryValue, cpuValue, diskValue }
})constructors
Source effect/Metric.ts:226112 lines
export const const gauge: {
(
name: string,
options?: {
readonly description?: string | undefined
readonly attributes?:
| Metric.Attributes
| undefined
readonly bigint?: false | undefined
}
): Gauge<number>
(
name: string,
options: {
readonly description?: string | undefined
readonly attributes?:
| Metric.Attributes
| undefined
readonly bigint: true
}
): Gauge<bigint>
}
Represents a Gauge metric that tracks and reports a single numerical value
at a specific moment.
When to use
Use when you need a metric for instantaneous values, such as memory usage or
CPU load.
Details
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)
import { Data, Effect, Metric } from "effect"
class GaugeError extends Data.TaggedError("GaugeError")<{
readonly operation: string
}> {}
const program = Effect.gen(function*() {
// Create a gauge for tracking memory usage
const memoryGauge = Metric.gauge("memory_usage_mb", {
description: "Current memory usage in megabytes"
})
// Create a gauge for CPU utilization
const cpuGauge = Metric.gauge("cpu_utilization", {
description: "Current CPU utilization percentage",
attributes: { host: "server-01" }
})
// Create a bigint gauge for large values
const diskSpaceGauge = Metric.gauge("disk_free_bytes", {
description: "Free disk space in bytes",
bigint: true
})
// Set gauge values (replaces current value)
yield* Metric.update(memoryGauge, 512) // Set to 512 MB
yield* Metric.update(cpuGauge, 85.5) // Set to 85.5%
yield* Metric.update(diskSpaceGauge, 1024000000n) // Set to ~1GB
// Modify gauge values (adds to current value)
yield* Metric.modify(memoryGauge, 128) // Increase by 128 MB (total: 640)
yield* Metric.modify(cpuGauge, -10.5) // Decrease by 10.5% (total: 75%)
// Update with new absolute values
yield* Metric.update(memoryGauge, 800) // Set to 800 MB (replaces 640)
// Get current gauge values
const memoryValue = yield* Metric.value(memoryGauge)
const cpuValue = yield* Metric.value(cpuGauge)
const diskValue = yield* Metric.value(diskSpaceGauge)
return { memoryValue, cpuValue, diskValue }
})
gauge: {
(name: stringname: string, options: | {
readonly description?: string | undefined
readonly attributes?:
| Metric.Attributes
| undefined
readonly bigint?: false | undefined
}
| undefined
description?: string | undefineddescription?: string | undefined
readonly attributes?: Metric.Attributes | undefinedattributes?: Metric.type Metric<in Input, out State>.Attributes = Readonly<Record<string, string>> | readonly [string, string][]Union type for metric attributes that can be provided as either an object or array of tuples.
Example (Providing attributes in different formats)
import { Data, Effect, Metric } from "effect"
class AttributesError extends Data.TaggedError("AttributesError")<{
readonly operation: string
}> {}
const program = Effect.gen(function*() {
// Different ways to specify attributes
const attributesAsObject = {
service: "api",
environment: "production",
version: "1.2.3"
}
const attributesAsArray: ReadonlyArray<[string, string]> = [
["service", "api"],
["environment", "production"],
["version", "1.2.3"]
]
// Create metrics with different attribute formats
const requestCounter1 = Metric.counter("requests", {
description: "Total requests",
attributes: attributesAsObject // Using object format
})
const requestCounter2 = Metric.counter("requests", {
description: "Total requests",
attributes: attributesAsArray // Using array format
})
// Function to normalize attributes to object format
const normalizeAttributes = (
attrs: typeof attributesAsObject | ReadonlyArray<[string, string]>
) => {
if (Array.isArray(attrs)) {
return Object.fromEntries(attrs)
}
return attrs
}
// Add runtime attributes using withAttributes
const contextualCounter = Metric.withAttributes(requestCounter1, {
method: "GET",
endpoint: "/api/users"
})
// Update metrics with different attribute combinations
yield* Metric.update(contextualCounter, 1)
// Both formats result in the same internal representation
const normalizedObject = normalizeAttributes(attributesAsObject)
const normalizedArray = normalizeAttributes(attributesAsArray)
return {
attributeFormats: {
object: normalizedObject, // { service: "api", environment: "production", version: "1.2.3" }
array: normalizedArray, // { service: "api", environment: "production", version: "1.2.3" }
areEqual:
JSON.stringify(normalizedObject) === JSON.stringify(normalizedArray) // true
}
}
})
Attributes | undefined
readonly bigint?: false | undefinedbigint?: false | undefined
}): 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<number>
(name: stringname: string, options: {
readonly description?: string | undefined
readonly attributes?:
| Metric.Attributes
| undefined
readonly bigint: true
}
description?: string | undefineddescription?: string | undefined
readonly attributes?: Metric.Attributes | undefinedattributes?: Metric.type Metric<in Input, out State>.Attributes = Readonly<Record<string, string>> | readonly [string, string][]Union type for metric attributes that can be provided as either an object or array of tuples.
Example (Providing attributes in different formats)
import { Data, Effect, Metric } from "effect"
class AttributesError extends Data.TaggedError("AttributesError")<{
readonly operation: string
}> {}
const program = Effect.gen(function*() {
// Different ways to specify attributes
const attributesAsObject = {
service: "api",
environment: "production",
version: "1.2.3"
}
const attributesAsArray: ReadonlyArray<[string, string]> = [
["service", "api"],
["environment", "production"],
["version", "1.2.3"]
]
// Create metrics with different attribute formats
const requestCounter1 = Metric.counter("requests", {
description: "Total requests",
attributes: attributesAsObject // Using object format
})
const requestCounter2 = Metric.counter("requests", {
description: "Total requests",
attributes: attributesAsArray // Using array format
})
// Function to normalize attributes to object format
const normalizeAttributes = (
attrs: typeof attributesAsObject | ReadonlyArray<[string, string]>
) => {
if (Array.isArray(attrs)) {
return Object.fromEntries(attrs)
}
return attrs
}
// Add runtime attributes using withAttributes
const contextualCounter = Metric.withAttributes(requestCounter1, {
method: "GET",
endpoint: "/api/users"
})
// Update metrics with different attribute combinations
yield* Metric.update(contextualCounter, 1)
// Both formats result in the same internal representation
const normalizedObject = normalizeAttributes(attributesAsObject)
const normalizedArray = normalizeAttributes(attributesAsArray)
return {
attributeFormats: {
object: normalizedObject, // { service: "api", environment: "production", version: "1.2.3" }
array: normalizedArray, // { service: "api", environment: "production", version: "1.2.3" }
areEqual:
JSON.stringify(normalizedObject) === JSON.stringify(normalizedArray) // true
}
}
})
Attributes | undefined
readonly bigint: truebigint: true
}): 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<bigint>
} = (name: stringname, options: | {
readonly description?: string | undefined
readonly attributes?:
| Metric.Attributes
| undefined
readonly bigint?: false | undefined
}
| {
readonly description?: string | undefined
readonly attributes?:
| Metric.Attributes
| undefined
readonly bigint: true
}
| undefined
constructor GaugeMetric<number | bigint>(id: string, options?: {
readonly description?: string | undefined;
readonly attributes?: Metric.Attributes | undefined;
readonly bigint?: boolean | undefined;
}): GaugeMetric<number | bigint>
name: stringname, options: | {
readonly description?: string | undefined
readonly attributes?:
| Metric.Attributes
| undefined
readonly bigint?: false | undefined
}
| {
readonly description?: string | undefined
readonly attributes?:
| Metric.Attributes
| undefined
readonly bigint: true
}
| undefined