Implementation:Ray project Ray Metric Histogram

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

Overview

The Histogram class is a concrete metric implementation that tracks the distribution of values across configurable boundaries within the Ray Java runtime.

Description

⚠️ Partial Deprecation: The direct constructor Histogram(String, String, String, List<Double>, Map<TagKey, String>) is annotated @Deprecated. Use the Metrics.histogram() builder API instead.

Histogram extends the abstract Metric base class and registers itself with the native stats system via NativeMetric.registerHistogramNative, accepting a list of boundary values that define the histogram buckets. To reduce JNI call overhead, it maintains a synchronized in-memory histogramWindow list that buffers up to 100 recent values. When getAndReset() is called during a flush cycle, the window is cleared and the last recorded value is returned.

Usage

Use Histogram when you need to track the distribution of values in a Ray Java application, such as request latencies, response sizes, or task execution times. The boundary configuration allows percentile analysis. Create instances through the Metrics.histogram() builder API rather than instantiating directly.

Code Reference

Source Location

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

Signature

public class Histogram extends Metric {
    public static final int HISTOGRAM_WINDOW_SIZE = 100;

    public Histogram(String name, String description, String unit,
                     List<Double> boundaries, Map<TagKey, String> tags)
    public Histogram(String name, String description,
                     List<Double> boundaries, Map<String, String> tags)
    public void update(double value)
    protected double getAndReset()
    public List<Double> getHistogramWindow()
    public double getValue()
}

Import

import io.ray.runtime.metric.Histogram;

I/O Contract

Constructor Parameters
Name	Type	Required	Description
name	String	Yes	The metric name used for identification in the stats system
description	String	Yes	Human-readable description of what the metric tracks
unit	String	No (deprecated constructor)	Unit of measurement (empty string in simplified constructor)
boundaries	List<Double>	Yes	Bucket boundary values defining the histogram distribution ranges
tags	Map<String, String>	Yes	Key-value pairs for metric labeling and filtering

Methods
Method	Parameter	Return Type	Description
update(double)	value - the observed value	void	Records a value into the histogram window and sets the current value
getValue()	none	double	Returns the most recently recorded value
getHistogramWindow()	none	List<Double>	Returns the buffered list of recent values (up to 100)
getAndReset()	none	double	Clears the histogram window and returns the last value

Constants
Name	Description
HISTOGRAM_WINDOW_SIZE	Maximum number of values retained in the in-memory window (100)

Usage Examples

// Create and register a Histogram metric via the Metrics builder API
Map<String, String> tags = new HashMap<>();
tags.put("operation", "task_execute");

List<Double> boundaries = Arrays.asList(10.0, 25.0, 50.0, 100.0, 250.0, 500.0, 1000.0);

Histogram latency = Metrics.histogram()
    .name("ray.task.latency_ms")
    .description("Task execution latency in milliseconds")
    .unit("ms")
    .boundaries(boundaries)
    .tags(tags)
    .register();

// Record observed latency values
latency.update(45.0);
latency.update(120.0);
latency.update(8.5);

// Read the most recent value
double lastValue = latency.getValue();

// Access the buffered window of recent values
List<Double> recentValues = latency.getHistogramWindow();

// Flush to native stats
latency.record();

Related Pages

• Environment:Ray_project_Ray_Java_Build_Environment
• Ray_project_Ray_Metric_Base - Abstract base class for all metric types
• Ray_project_Ray_Metrics_API - Entry point builder API for creating metrics