Cats Effect IO runtime metrics reference

IORuntimeMetrics registers observable metrics from Cats Effect's runtime metrics interface. It uses the cats.effect.runtime meter scope and returns a Resource that owns the collector registrations.

For dependency setup, registration, and a focused configuration example, see Register Cats Effect runtime metrics.

IORuntimeMetrics.register

register[F] requires Sync[F] and an implicit MeterProvider[F].

The result is a Resource[F, Unit]. Acquiring the resource registers the selected observable instruments; releasing it removes their callbacks.

import cats.effect.{IO, Resource}
import cats.effect.unsafe.metrics.{IORuntimeMetrics => CatsIORuntimeMetrics}
import org.typelevel.otel4s.instrumentation.ce.IORuntimeMetrics
import org.typelevel.otel4s.metrics.MeterProvider

def registerRuntimeMetrics(
    metrics: CatsIORuntimeMetrics
)(implicit meterProvider: MeterProvider[IO]): Resource[IO, Unit] =
  IORuntimeMetrics.register[IO](
    metrics = metrics,
    config = IORuntimeMetrics.Config.default,
  )

Platform support

Metric catalog

CPU starvation

Platforms: JVM, Scala.js, Scala Native.

These metrics report CPU starvation events and the current and maximum clock drift observed by the Cats Effect runtime.

Work-stealing thread pool: compute

Platforms: JVM, Scala Native.

These metrics report fiber and worker-thread activity for the compute pool.

Work-stealing thread pool: threads

Platforms: JVM, Scala Native.

Every thread metric includes pool.id and worker.index. The cats.effect.runtime.wstp.worker.thread.event.count metric also includes thread.event, with these values:

Work-stealing thread pool: local queue

Platforms: JVM, Scala Native.

These metrics report the distribution of fibers across worker-local queues.

Work-stealing thread pool: timer heap

Platforms: JVM, Scala Native.

Every timer-heap metric includes pool.id and worker.index. The cats.effect.runtime.wstp.worker.timerheap.timer.count metric also includes timer.state, with these values:

Work-stealing thread pool: poller

Platforms: JVM, Scala Native.

Every poller metric includes pool.id, worker.index, and poller.operation. poller.operation has the values accept, connect, read, and write.

The cats.effect.runtime.wstp.worker.poller.operation.count metric also includes poller.operation.status, with these values:

Configuration

The configuration surface differs by platform because Scala.js does not expose work-stealing thread-pool metrics.

Configuration hierarchy

Create an IORuntimeMetrics.Config

The IORuntimeMetrics.Config companion object provides these methods:

Scala allows an apply method to be called with the companion object's name. For example, IORuntimeMetrics.Config(cpuStarvation, workStealingThreadPool) calls the two-argument apply method.

import org.typelevel.otel4s.instrumentation.ce.IORuntimeMetrics
import IORuntimeMetrics.Config._

val config: IORuntimeMetrics.Config =
  IORuntimeMetrics.Config(
    cpuStarvation = CpuStarvationConfig.disabled,
    workStealingThreadPool = WorkStealingThreadPoolConfig.enabled,
  )

Configure an individual collector

Each config value exposes these fields:

The companion object for each type provides the same creation methods. For example, CpuStarvationConfig provides:

import org.typelevel.otel4s.{Attribute, Attributes}

val cpuStarvation: CpuStarvationConfig =
  CpuStarvationConfig.enabled(
    attributes = Attributes(Attribute("example.attribute", "value"))
  )

Create composite work-stealing configs

These types are available on the JVM and Scala Native.

import WorkStealingThreadPoolConfig.{ComputeConfig, WorkerThreadsConfig}
import WorkerThreadsConfig._

val workStealingThreadPool: WorkStealingThreadPoolConfig =
  WorkStealingThreadPoolConfig(
    compute = ComputeConfig.enabled,
    workerThreads = WorkerThreadsConfig(
      thread = ThreadConfig.enabled,
      localQueue = LocalQueueConfig.disabled,
      timerHeap = TimerHeapConfig.enabled,
      poller = PollerConfig.disabled,
    ),
  )

All configuration types provide a Show instance and use it for toString.

Related material

• Register Cats Effect runtime metrics
• Metrics API reference