Implementation:Ray project Ray Metric Base

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

Overview

The Metric class is the abstract base class for all Ray Java metric types, providing common fields and the mechanism to flush metric data to the native stats system.

Description

Metric stores the metric name, an AtomicDouble value, a native pointer to the C++ stats object, and a tag map of TagKey to String entries. The record() method collects tag keys and values from the map and calls NativeMetric.recordNative to push the current value to the native layer. Subclasses (Count, Gauge, Sum, Histogram) implement the abstract update() and getAndReset() methods to define type-specific aggregation behavior.

Usage

Metric is not instantiated directly. It serves as the foundation for all concrete metric types in the Ray Java metrics framework. Developers interact with its public methods (record(), update(), unregister(), getTagMap()) through concrete subclass instances created via the Metrics builder API.

Code Reference

Source Location

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

Signature

public abstract class Metric {
    protected String name;
    protected AtomicDouble value;
    protected long metricNativePointer = 0L;
    protected Map<TagKey, String> tags;

    public Metric(String name, Map<TagKey, String> tags)
    public void record()
    protected abstract double getAndReset()
    public abstract void update(double value)
    public void update(double value, Map<TagKey, String> tags)
    public void update(Map<String, String> tags, double value)
    public Map<String, String> getTagMap()
    public void unregister()
}

Import

import io.ray.runtime.metric.Metric;

I/O Contract

Constructor Parameters
Name	Type	Required	Description
name	String	Yes	The metric name (must not be null)
tags	Map<TagKey, String>	Yes	Tag key-value map for metric labeling (must not be null)

Public Methods
Method	Parameters	Return Type	Description
record()	none	void	Flushes the current metric value and tags to the native stats system via JNI
update(double)	value - new metric value	void	Abstract: updates the metric value (subclass-specific behavior)
update(double, Map<TagKey, String>)	value, tags	void	Updates both the metric value and the tag map
update(Map<String, String>, double)	tags, value	void	Updates value and converts string tags to TagKey map
getTagMap()	none	Map<String, String>	Returns tags as a plain string key-value map
unregister()	none	void	Deallocates the native stats object and resets the native pointer to 0

Protected Abstract Methods
Method	Parameters	Return Type	Description
getAndReset()	none	double	Returns the value to record and resets the transient state (subclass-specific)
update(double)	value	void	Defines how the metric value is updated (set vs. accumulate)

Protected Fields
Field	Type	Description
name	String	The metric identifier name
value	AtomicDouble	Thread-safe atomic double storing the current metric value
metricNativePointer	long	Native pointer to the C++ stats object (0 when unregistered)
tags	Map<TagKey, String>	Tag key-value pairs for dimensional labeling

Usage Examples

// Metric is abstract - use through concrete subclasses
// Example using a Count (which extends Metric)
Map<String, String> tags = new HashMap<>();
tags.put("component", "scheduler");

Count taskCount = Metrics.count()
    .name("ray.tasks.completed")
    .description("Number of completed tasks")
    .unit("")
    .tags(tags)
    .register();

// update() - defined by subclass
taskCount.update(1.0);

// record() - inherited from Metric, flushes to native stats
taskCount.record();

// Update with dynamic tags
Map<String, String> newTags = new HashMap<>();
newTags.put("component", "worker");
taskCount.update(newTags, 5.0);

// Get the current tag map
Map<String, String> currentTags = taskCount.getTagMap();

// Unregister when done
taskCount.unregister();

Related Pages

• Environment:Ray_project_Ray_Java_Build_Environment
• Ray_project_Ray_Metric_Count - Count metric subclass
• Ray_project_Ray_Metric_Gauge - Gauge metric subclass
• Ray_project_Ray_Metric_Sum - Sum metric subclass
• Ray_project_Ray_Metric_Histogram - Histogram metric subclass
• Ray_project_Ray_Metrics_API - Entry point builder API for creating metrics