Implementation:Ray project Ray Metric Sum

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

Overview

The Sum class is a concrete metric implementation that tracks a cumulative running sum of values within the Ray Java runtime.

Description

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

Sum extends the abstract Metric base class and uses a thread-safe DoubleAdder for accumulation. It registers itself with the native stats system via NativeMetric.registerSumNative and maintains both a transient sum (reset on each flush) and a total cumulative value in the inherited value field. Semantically similar to Count, but Sum represents a cumulative total of arbitrary values rather than discrete event counts.

Usage

Use Sum when you need to track cumulative totals of measured values in a Ray Java application, such as total bytes transferred, total processing time, or total resource consumption. Create instances through the Metrics.sum() builder API rather than instantiating directly.

Code Reference

Source Location

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

Signature

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

Import

import io.ray.runtime.metric.Sum;

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 amount to add	void	Adds the given value to both the transient and cumulative sums
getSum()	none	double	Returns the cumulative sum since creation
getAndReset()	none	double	Returns the transient sum since last flush and resets it

Usage Examples

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

Sum bytesTransferred = Metrics.sum()
    .name("ray.bytes.transferred")
    .description("Total bytes transferred by the worker")
    .unit("bytes")
    .tags(tags)
    .register();

// Add values to the running sum
bytesTransferred.update(1024.0);
bytesTransferred.update(2048.0);
bytesTransferred.update(512.0);

// Read the cumulative sum
double total = bytesTransferred.getSum();  // 3584.0

// Flush to native stats
bytesTransferred.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
• Ray_project_Ray_Metric_Count - Similar accumulating metric for event counts