Implementation:Ray project Ray Metrics API

Knowledge Sources	Ray
Domains	Observability, Metrics
Last Updated	2026-02-13 16:00 GMT

Overview

The Metrics class is the primary user-facing entry point for creating and registering Ray Java metrics, providing a fluent builder API for all metric types.

Description

Metrics is a final utility class that offers static builder methods (count(), gauge(), sum(), histogram()) returning type-specific builders that extend a common AbstractBuilder. Each builder collects name, description, unit, and tags via a fluent API, then creates and registers the metric with the internal MetricRegistry. The registry is lazily initialized on first metric registration if not already started via Metrics.init().

Usage

Use Metrics as the standard way to create and register all metric types in Ray Java applications. Call Metrics.init(MetricConfig) to explicitly start the registry with custom configuration, or let it auto-initialize with defaults on first metric registration. Call Metrics.shutdown() to cleanly stop the metric reporting scheduler.

Code Reference

Source Location

• Repository: Ray
• File: java/runtime/src/main/java/io/ray/runtime/metric/Metrics.java

Signature

public final class Metrics {
    public static MetricRegistry init(MetricConfig metricConfig)
    public static void shutdown()
    public static CountBuilder count()
    public static GaugeBuilder gauge()
    public static SumBuilder sum()
    public static HistogramBuilder histogram()

    public static class CountBuilder extends AbstractBuilder<CountBuilder, Count> { ... }
    public static class GaugeBuilder extends AbstractBuilder<GaugeBuilder, Gauge> { ... }
    public static class SumBuilder extends AbstractBuilder<SumBuilder, Sum> { ... }
    public static class HistogramBuilder extends AbstractBuilder<HistogramBuilder, Histogram> {
        public HistogramBuilder boundaries(List<Double> boundaries)
    }

    public abstract static class AbstractBuilder<B extends AbstractBuilder, M extends Metric> {
        public B name(String name)
        public B description(String description)
        public B unit(String unit)
        public B tags(Map<String, String> tags)
        protected abstract M create()
        public M register()
    }
}

Import

import io.ray.runtime.metric.Metrics;

I/O Contract

Static Lifecycle Methods
Method	Parameters	Return Type	Description
init(MetricConfig)	metricConfig - registry configuration	MetricRegistry	Initializes and starts the metric registry with the given configuration (synchronized)
shutdown()	none	void	Stops the metric registry and releases resources (synchronized)

Static Builder Factory Methods
Method	Return Type	Description
count()	CountBuilder	Returns a builder for creating a Count metric
gauge()	GaugeBuilder	Returns a builder for creating a Gauge metric
sum()	SumBuilder	Returns a builder for creating a Sum metric
histogram()	HistogramBuilder	Returns a builder for creating a Histogram metric

AbstractBuilder Methods (Common to All Builders)
Method	Parameter	Return Type	Description
name(String)	name - metric name (not null)	B (builder)	Sets the metric name
description(String)	description - metric description (not null)	B (builder)	Sets the metric description
unit(String)	unit - measurement unit (not null)	B (builder)	Sets the measurement unit
tags(Map<String, String>)	tags - tag key-value map (not null)	B (builder)	Sets the metric tags
register()	none	M (metric)	Creates the metric and registers it with the MetricRegistry

HistogramBuilder Additional Methods
Method	Parameter	Return Type	Description
boundaries(List<Double>)	boundaries - bucket boundary values	HistogramBuilder	Sets the histogram bucket boundaries

Usage Examples

// Initialize the metrics system with custom configuration
MetricConfig config = MetricConfig.builder()
    .timeIntervalMs(10000)
    .create();
Metrics.init(config);

// Create a Count metric
Map<String, String> tags = new HashMap<>();
tags.put("service", "raylet");

Count errorCount = Metrics.count()
    .name("ray.errors.total")
    .description("Total number of errors")
    .unit("")
    .tags(tags)
    .register();

// Create a Gauge metric
Gauge memoryUsage = Metrics.gauge()
    .name("ray.memory.used_bytes")
    .description("Current memory usage in bytes")
    .unit("bytes")
    .tags(tags)
    .register();

// Create a Sum metric
Sum bytesProcessed = Metrics.sum()
    .name("ray.bytes.processed")
    .description("Total bytes processed")
    .unit("bytes")
    .tags(tags)
    .register();

// Create a Histogram metric with boundaries
List<Double> latencyBounds = Arrays.asList(1.0, 5.0, 10.0, 50.0, 100.0, 500.0);
Histogram latency = Metrics.histogram()
    .name("ray.task.duration_ms")
    .description("Task execution duration")
    .unit("ms")
    .boundaries(latencyBounds)
    .tags(tags)
    .register();

// Use the metrics
errorCount.inc(1.0);
memoryUsage.update(1048576.0);
bytesProcessed.update(4096.0);
latency.update(25.3);

// Shutdown when done
Metrics.shutdown();

Related Pages

• Environment:Ray_project_Ray_Java_Build_Environment
• Ray_project_Ray_Metric_Base - Abstract base class for all metric types
• Ray_project_Ray_Metric_Count - Count metric implementation
• Ray_project_Ray_Metric_Gauge - Gauge metric implementation
• Ray_project_Ray_Metric_Sum - Sum metric implementation
• Ray_project_Ray_Metric_Histogram - Histogram metric implementation
• Ray_project_Ray_MetricConfig - Configuration for the metric registry