Implementation:Ray project Ray Metric Gauge

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

Overview

The Gauge class is a concrete metric implementation that records the most recent (last) value, representing an instantaneous measurement within the Ray Java runtime.

Description

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

Gauge extends the abstract Metric base class and registers itself with the native stats system via NativeMetric.registerGaugeNative. Unlike accumulating metrics such as Count or Sum, the update() method atomically sets the value rather than adding to it. The getAndReset() method returns the current value without resetting it, reflecting gauge semantics where the last observed value persists until explicitly changed.

Usage

Use Gauge when you need to track instantaneous point-in-time measurements in a Ray Java application, such as queue depth, active connection count, memory usage, or CPU utilization. Create instances through the Metrics.gauge() builder API rather than instantiating directly.

Code Reference

Source Location

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

Signature

public class Gauge extends Metric {
    public Gauge(String name, String description, String unit, Map<TagKey, String> tags)
    public Gauge(String name, String description, Map<String, String> tags)
    public double getValue()
    protected double getAndReset()
    public void update(double value)
}

Import

import io.ray.runtime.metric.Gauge;

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)
tags	Map<String, String>	Yes	Key-value pairs for metric labeling and filtering

Methods
Method	Parameter	Return Type	Description
update(double)	value - the new gauge value	void	Atomically sets the gauge to the given value (replaces, does not accumulate)
getValue()	none	double	Returns the current gauge value
getAndReset()	none	double	Returns the current value without resetting (gauge semantics)

Usage Examples

// Create and register a Gauge metric via the Metrics builder API
Map<String, String> tags = new HashMap<>();
tags.put("node", "worker-1");

Gauge queueDepth = Metrics.gauge()
    .name("ray.queue.depth")
    .description("Current depth of the task queue")
    .unit("")
    .tags(tags)
    .register();

// Set the gauge to the current value
queueDepth.update(42.0);

// Read the current gauge value
double current = queueDepth.getValue();

// Update with new value (replaces the previous)
queueDepth.update(35.0);

// Flush to native stats
queueDepth.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