OtlpMetrics unstable

Exports Effect metrics over OTLP/HTTP.

This module periodically snapshots metrics from the current Effect context, serializes them as OTLP resource metrics, and posts them to a metrics endpoint such as an OpenTelemetry Collector or vendor intake. It is meant for long-running services that already update Metric counters, gauges, histograms, frequencies, or summaries. The exporter supports cumulative reporting from a fixed start time and delta reporting from the previous export.

5 exports Since v4.0.0 Source

Constructors

make

unstable

Since v4.0.0

Starts a scoped OTLP metrics exporter.

Details

The exporter snapshots registered Effect metrics on the configured interval, serializes them with the selected aggregation temporality, and flushes during scope finalization up to shutdownTimeout. Manual flushing also triggers a snapshot. With delta temporality, each successful export advances the previous-export state, so frequent successful flushes narrow the delta aggregation windows.

Signature

declare const make: (options: {
  readonly compression?: "gzip" | "none";
  readonly exportInterval?: Duration.Input;
  readonly headers?: Headers.Input;
  readonly resource?: {
    readonly attributes?: Record<string, unknown>;
    readonly serviceName?: string;
    readonly serviceVersion?: string;
  };
  readonly shutdownTimeout?: Duration.Input;
  readonly temporality?: AggregationTemporality;
  readonly url: string;
}) => Effect.Effect<void, never, Exporter.Flusher | HttpClient.HttpClient | OtlpSerialization | Scope.Scope>

Layers

layer

unstable

Since v4.0.0

Layer that starts the OTLP metrics exporter created by make.

Signature

declare function layer(options: {
  readonly compression?: "none" | "gzip";
  readonly exportInterval?: Input;
  readonly headers?: Input;
  readonly resource?: {
    readonly attributes?: Record<string, unknown>;
    readonly serviceName?: string;
    readonly serviceVersion?: string;
  };
  readonly shutdownTimeout?: Input;
  readonly temporality?: AggregationTemporality;
  readonly url: string;
}): Layer<Flusher, never, HttpClient | OtlpSerialization>

layerFromConfig

unstable

Since v4.0.0

Creates an OTLP metrics layer from OpenTelemetry configuration.

Details

Compression accepts "gzip" or "none". OTEL_EXPORTER_OTLP_METRICS_COMPRESSION takes precedence over OTEL_EXPORTER_OTLP_COMPRESSION, defaulting to "none". Gzip uses HttpClientRequest's default minimum body size of 1KB.

Signature

declare function layerFromConfig(options?: {
  readonly headers?: Input;
  readonly resource?: {
    readonly attributes?: Record<string, unknown>;
    readonly serviceName?: string;
    readonly serviceVersion?: string;
  };
}): Layer<Flusher, never, HttpClient | OtlpSerialization>

Models

AggregationTemporality

type unstable

Since v4.0.0

Determines how metric values relate to the time interval over which they are aggregated.

Details

"cumulative" reports total since a fixed start time. Each data point depends on all previous measurements. This is the default behavior.

"delta" reports changes since the last export. Each interval is independent with no dependency on previous measurements.

Summaries are always cumulative, regardless of this setting.

Signature

type AggregationTemporality = "cumulative" | "delta"

Example Configuring aggregation temporality

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

// Use delta temporality for backends that prefer it (e.g., Datadog, Dynatrace)
const metricsLayer = OtlpMetrics.layer({
  url: "http://localhost:4318/v1/metrics",
  temporality: "delta"
})

// Use cumulative temporality for backends like Prometheus
const cumulativeLayer = OtlpMetrics.layer({
  url: "http://localhost:4318/v1/metrics",
  temporality: "cumulative" // This is the default
})

const result = [Layer.isLayer(metricsLayer), Layer.isLayer(cumulativeLayer)] // => [true, true]

MetricsData

interface unstable

Since v4.0.0

OTLP metrics payload serialized by OtlpMetrics.

Signature

interface MetricsData {
  readonly resourceMetrics: readonly Array<IResourceMetrics>;
}