PrometheusMetrics unstable

Formats Effect metrics for Prometheus.

This module reads metrics from the current Effect context and renders them in the Prometheus text format. It can also register a pull-based HTTP endpoint, such as /metrics, for Prometheus to scrape.

6 exports Since v4.0.0 Source

Formatting

format

unstable

Since v4.0.0

Formats all metrics in the registry to Prometheus exposition format.

Signature

declare const format: (options?: FormatOptions) => Effect.Effect<string>

Example Formatting metrics

import { Effect, Metric } from "effect"
import { PrometheusMetrics } from "effect/observability"

const program = Effect.gen(function*() {
  const counter = Metric.counter("api_requests_total", {
    description: "Total API requests"
  })
  const gauge = Metric.gauge("active_connections", {
    description: "Number of active connections"
  })

  yield* Metric.update(counter, 100)
  yield* Metric.update(gauge, 25)

  // Format without prefix
  const output1 = yield* PrometheusMetrics.format()

  // Format with prefix
  const output2 = yield* PrometheusMetrics.format({ prefix: "myapp" })

  return [output1.includes("api_requests_total"), output2.includes("myapp_active_connections")]
})

Effect.runSync(program) // => [true, true]

formatUnsafe

unstable

Since v4.0.0

Formats all metrics in the registry to Prometheus exposition format synchronously.

When to use

Use when you already have access to the context and need low-level synchronous formatting.

See

format for effectful formatting from the current context

Signature

declare function formatUnsafe(context: Context<never>, options?: FormatOptions): string

Layers

layerHttp

unstable

Since v4.0.0

Creates a Layer that registers a /metrics HTTP endpoint for Prometheus scraping.

Details

This layer automatically adds a GET route to your HTTP router that serves metrics in Prometheus exposition format. By default, the endpoint is registered at /metrics, but this can be customized via the path option.

Signature

declare function layerHttp(options?: HttpOptions): Layer<never, never, HttpRouter>

Example Serving metrics over HTTP

import { Layer } from "effect"
import { PrometheusMetrics } from "effect/observability"

// Create a layer that adds /metrics endpoint to the router
const PrometheusLayer = PrometheusMetrics.layerHttp()

// Or customize the path and add a prefix to all metric names
const CustomPrometheusLayer = PrometheusMetrics.layerHttp({
  path: "/prometheus/metrics",
  prefix: "myapp"
})

const result = [Layer.isLayer(PrometheusLayer), Layer.isLayer(CustomPrometheusLayer)] // => [true, true]

Models

MetricNameMapper

type unstable

Since v4.0.0

A function that transforms metric names before formatting.

Signature

type MetricNameMapper = (name: string) => string

Example Mapping metric names

import type { PrometheusMetrics } from "effect/observability"

// Convert camelCase to snake_case
const mapper: PrometheusMetrics.MetricNameMapper = (name) =>
  name.replace(/([a-z])([A-Z])/g, "$1_$2").toLowerCase()

mapper("httpRequests") // => "http_requests"

Options

FormatOptions

interface unstable

Since v4.0.0

Options for formatting metrics.

Signature

interface FormatOptions {
  readonly metricNameMapper?: MetricNameMapper;
  readonly prefix?: string;
}

HttpOptions

interface unstable

Since v4.0.0

Options for exporting Prometheus metrics over HTTP.

Signature

interface HttpOptions extends FormatOptions {
  readonly path?: PathInput;
}