PrometheusMetrics

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 Added in v4.0.0 Source

Formatting

format

Added in v4.0.0 Source

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/unstable/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

Added in v4.0.0 Source

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

Added in v4.0.0 Source

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/unstable/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

Added in v4.0.0 Source

A function that transforms metric names before formatting.

Signature

type MetricNameMapper = (name: string) => string

Example

(Mapping metric names)

import type { PrometheusMetrics } from "effect/unstable/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

Added in v4.0.0 Source

Options for formatting metrics.

Signature

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

HttpOptions interface

Added in v4.0.0 Source

Options for exporting Prometheus metrics over HTTP.

Signature

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