Effect<ReadonlyArray<Metric.Snapshot>, never, never>Captures a snapshot of all registered metrics in the current context.
Details
Returns an array of metric snapshots, each containing the metric's metadata (name, description, type) and current state (values, counts, etc.).
Example (Capturing metric snapshots)
import { Console, Data, Effect, Metric } from "effect"
class SnapshotError extends Data.TaggedError("SnapshotError")<{
readonly operation: string
}> {}
const program = Effect.gen(function*() {
// Create and update some metrics
const requestCounter = Metric.counter("http_requests", {
description: "Total HTTP requests"
})
const responseTime = Metric.histogram("response_time_ms", {
description: "Response time in milliseconds",
boundaries: Metric.linearBoundaries({ start: 0, width: 100, count: 5 })
})
// Update the metrics with some values
yield* Metric.update(requestCounter, 1)
yield* Metric.update(requestCounter, 1)
yield* Metric.update(responseTime, 150)
yield* Metric.update(responseTime, 75)
// Take a snapshot of all metrics
const snapshots = yield* Metric.snapshot
// Examine the snapshots
for (const snapshot of snapshots) {
yield* Console.log(`Metric: ${snapshot.id}`)
yield* Console.log(`Description: ${snapshot.description}`)
yield* Console.log(`Type: ${snapshot.type}`)
yield* Console.log(`State:`, snapshot.state)
}
return snapshots
})Snapshotting
Source effect/Metric.ts:30424 lines
export const const snapshot: Effect<
ReadonlyArray<Metric.Snapshot>
>
const snapshot: {
pipe: { <A>(this: A): A; <A, B = never>(this: A, ab: (_: A) => B): B; <A, B = never, C = never>(this: A, ab: (_: A) => B, bc: (_: B) => C): C; <A, B = never, C = never, D = never>(this: A, ab: (_: A) => B, bc: (_: B) => C, cd: (_: C) => D): D; <…;
toString: () => string;
toJSON: () => unknown;
}
Captures a snapshot of all registered metrics in the current context.
Details
Returns an array of metric snapshots, each containing the metric's metadata
(name, description, type) and current state (values, counts, etc.).
Example (Capturing metric snapshots)
import { Console, Data, Effect, Metric } from "effect"
class SnapshotError extends Data.TaggedError("SnapshotError")<{
readonly operation: string
}> {}
const program = Effect.gen(function*() {
// Create and update some metrics
const requestCounter = Metric.counter("http_requests", {
description: "Total HTTP requests"
})
const responseTime = Metric.histogram("response_time_ms", {
description: "Response time in milliseconds",
boundaries: Metric.linearBoundaries({ start: 0, width: 100, count: 5 })
})
// Update the metrics with some values
yield* Metric.update(requestCounter, 1)
yield* Metric.update(requestCounter, 1)
yield* Metric.update(responseTime, 150)
yield* Metric.update(responseTime, 75)
// Take a snapshot of all metrics
const snapshots = yield* Metric.snapshot
// Examine the snapshots
for (const snapshot of snapshots) {
yield* Console.log(`Metric: ${snapshot.id}`)
yield* Console.log(`Description: ${snapshot.description}`)
yield* Console.log(`Type: ${snapshot.type}`)
yield* Console.log(`State:`, snapshot.state)
}
return snapshots
})
snapshot: interface Effect<out A, out E = never, out R = never>The Effect interface defines a value that lazily describes a workflow or
job. The workflow requires some context R, and may fail with an error of
type E, or succeed with a value of type A.
When to use
Use when you need to represent a lazy, composable workflow that can require
services, fail with a typed error, or succeed with a typed value.
Details
Effect values model resourceful interaction with the outside world,
including synchronous, asynchronous, concurrent, and parallel interaction.
They use a fiber-based concurrency model, with built-in support for
scheduling, fine-grained interruption, structured concurrency, and high
scalability.
To run an Effect value, you need a Runtime, which is a type that is
capable of executing Effect values.
Effect<interface ReadonlyArray<T>ReadonlyArray<Metric.type Metric<in Input, out State>.Snapshot = Metric.SnapshotProto<"Counter", CounterState<number | bigint>> | Metric.SnapshotProto<"Gauge", GaugeState<number | bigint>> | Metric.SnapshotProto<"Frequency", FrequencyState> | Metric.SnapshotProto<"Histogram", HistogramState> | Metric.SnapshotProto<"Summary", SummaryState>Union type representing all possible metric snapshot types with their corresponding states.
Example (Analyzing metric snapshots)
import { Data, Effect, Metric } from "effect"
class SnapshotError extends Data.TaggedError("SnapshotError")<{
readonly operation: string
}> {}
const program = Effect.gen(function*() {
// Create different types of metrics
const requestCounter = Metric.counter("requests_total")
const cpuGauge = Metric.gauge("cpu_usage_percent")
const statusFrequency = Metric.frequency("http_status")
const responseHistogram = Metric.histogram("response_time_ms", {
boundaries: Metric.linearBoundaries({ start: 0, width: 100, count: 10 })
})
const latencySummary = Metric.summary("request_latency", {
maxAge: "1 minute",
maxSize: 100,
quantiles: [0.5, 0.95, 0.99]
})
// Update all metrics
yield* Metric.update(requestCounter, 150)
yield* Metric.update(cpuGauge, 45.7)
yield* Metric.update(statusFrequency, "200")
yield* Metric.update(statusFrequency, "404")
yield* Metric.update(responseHistogram, 250)
yield* Metric.update(latencySummary, 120)
// Take snapshot of all metrics
const allSnapshots = yield* Metric.snapshot
// Type-safe snapshot analysis using discriminated union
const analyzeSnapshot = (snapshot: any) => {
switch (snapshot.type) {
case "Counter":
return { type: "Counter", count: snapshot.state.count }
case "Gauge":
return { type: "Gauge", value: snapshot.state.value }
case "Frequency":
return {
type: "Frequency",
uniqueValues: snapshot.state.occurrences.size
}
case "Histogram":
return { type: "Histogram", observations: snapshot.state.count }
case "Summary":
return { type: "Summary", observations: snapshot.state.count }
}
}
const analysis = allSnapshots.map(analyzeSnapshot)
return {
totalMetrics: allSnapshots.length, // 5
metricTypes: allSnapshots.map((s) => s.type), // ["Counter", "Gauge", "Frequency", "Histogram", "Summary"]
analysis
}
})
Snapshot>> = import InternalEffectInternalEffect.const map: {
<A, B>(f: (a: A) => B): <E, R>(
self: Effect.Effect<A, E, R>
) => Effect.Effect<B, E, R>
<A, E, R, B>(
self: Effect.Effect<A, E, R>,
f: (a: A) => B
): Effect.Effect<B, E, R>
}
import InternalEffectInternalEffect.const context: <
R = never
>() => Effect.Effect<Context.Context<R>>
context: Context.Context<never>(parameter) context: {
mapUnsafe: ReadonlyMap<string, any>;
mutable: boolean;
pipe: { <A>(this: A): A; <A, B = never>(this: A, ab: (_: A) => B): B; <A, B = never, C = never>(this: A, ab: (_: A) => B, bc: (_: B) => C): C; <A, B = never, C = never, D = never>(this: A, ab: (_: A) => B, bc: (_: B) => C, cd: (_: C) => D): D; <…;
toString: () => string;
toJSON: () => unknown;
}
const snapshotUnsafe: (
context: Context.Context<never>
) => ReadonlyArray<Metric.Snapshot>
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
manual handling of the services context. Use the safe snapshot function for normal
application code.
Example (Capturing snapshots from a context)
import { Data, Effect, Metric } from "effect"
class UnsafeSnapshotError extends Data.TaggedError("UnsafeSnapshotError")<{
readonly operation: string
}> {}
// Use unsafeSnapshot in performance-critical scenarios or internal implementations
const performanceMetricsExporter = Effect.gen(function*() {
// Create some metrics first
const requestCounter = Metric.counter("http_requests", {
description: "Total HTTP requests"
})
const responseTime = Metric.gauge("response_time_ms", {
description: "Current response time"
})
// Update metrics
yield* Metric.update(requestCounter, 1)
yield* Metric.update(responseTime, 150)
// Get services context for unsafe operations
const services = yield* Effect.context()
// Use snapshotUnsafe for direct, synchronous access
const snapshots = Metric.snapshotUnsafe(services)
const exportBatchCreatedAt = 1_700_000_000_000
// Process snapshots immediately (useful for exporters, debugging tools)
const exportData = snapshots.map((snapshot) => ({
name: snapshot.id,
type: snapshot.type,
value: snapshot.state,
timestamp: exportBatchCreatedAt
}))
// This is synchronous and doesn't involve Effect overhead
// Useful for performance-critical metric export operations
return exportData
})
// For normal application use, prefer the safe snapshot function:
const safeSnapshotExample = Effect.gen(function*() {
// This automatically handles the services context
const snapshots = yield* Metric.snapshot
return snapshots
})
snapshotUnsafe(context: Context.Context<never>(parameter) context: {
mapUnsafe: ReadonlyMap<string, any>;
mutable: boolean;
pipe: { <A>(this: A): A; <A, B = never>(this: A, ab: (_: A) => B): B; <A, B = never, C = never>(this: A, ab: (_: A) => B, bc: (_: B) => C): C; <A, B = never, C = never, D = never>(this: A, ab: (_: A) => B, bc: (_: B) => C, cd: (_: C) => D): D; <…;
toString: () => string;
toJSON: () => unknown;
}
Referenced by 1 symbols