(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
})Snapshotting
Source effect/Metric.ts:32087 lines
export const 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;
}
import ContextContext.type Context.Context = /*unresolved*/ anyContext<never>): 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> => {
const const registry: anyregistry = import ContextContext.get(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 MetricRegistry: Context.Reference<
Map<string, Metric.Metadata<any, any>>
>
const MetricRegistry: {
key: string;
Service: {
clear: () => void;
delete: (key: string) => boolean;
forEach: (callbackfn: (value: Metric.Metadata<any, any>, key: string, map: Map<string, Metric.Metadata<any, any>>) => void, thisArg?: any) => void;
get: (key: string) => Metric.Metadata<any, any> | undefined;
has: (key: string) => boolean;
set: (key: string, value: Metric.Metadata<any, any>) => Map<string, Metric.Metadata<any, any>>;
size: number;
entries: () => MapIterator<[string, Metric.Metadata<any, any>]>;
keys: () => MapIterator<string>;
values: () => MapIterator<Metric.Metadata<any, any>>;
};
defaultValue: () => Shape;
of: (this: void, self: Map<string, Metric.Metadata<any, any>>) => Map<string, Metric.Metadata<any, any>>;
context: (self: Map<string, Metric.Metadata<any, any>>) => Context.Context<never>;
use: (f: (service: Map<string, Metric.Metadata<any, any>>) => Effect<A, E, R>) => Effect<A, E, R>;
useSync: (f: (service: Map<string, Metric.Metadata<any, any>>) => A) => Effect<A, never, never>;
Identifier: Identifier;
stack: string | undefined;
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;
}
Context reference for the metric registry in the current context.
When to use
Use when you need a custom metric registry for an isolated program or test
instead of the default registry.
Details
By default, the reference creates an empty Map the first time it is
resolved. Metrics register their metadata and hooks lazily in this map when
they are read or updated.
Gotchas
Because Context.Reference caches default values, the default Map is
shared by contexts that do not provide an override. Provide MetricRegistry
with a fresh Map when isolation matters.
MetricRegistry)
return var Array: ArrayConstructorArray.ArrayConstructor.from<unknown>(iterable: ArrayLike<unknown> | Iterable<unknown>): unknown[] (+3 overloads)Creates an array from an iterable object.
from(const registry: anyregistry.values()).Array<unknown>.map<Metric<in Input, out State>.Snapshot>(callbackfn: (value: unknown, index: number, array: unknown[]) => Metric.Snapshot, thisArg?: any): Metric.Snapshot[]Calls a defined callback function on each element of an array, and returns an array that contains the results.
map(({ hooks: any(parameter) hooks: {
get: (context: Context.Context<never>) => State;
update: (input: Input, context: Context.Context<never>) => void;
modify: (input: Input, context: Context.Context<never>) => void;
}
meta: {
[x: string]: any
}
meta: {
[x: string]: any
}
state: anystate: hooks: any(parameter) hooks: {
get: (context: Context.Context<never>) => State;
update: (input: Input, context: Context.Context<never>) => void;
modify: (input: Input, context: Context.Context<never>) => void;
}
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 2 symbols