To help monitor Ray applications, Ray

  • Collects system-level metrics.

  • Provides a default configuration for prometheus.

  • Provides a default Grafana dashboard.

  • Exposes metrics in a Prometheus format. We’ll call the endpoint to access these metrics a Prometheus endpoint.

  • Supports custom metrics APIs that resemble Prometheus metric types.

Getting Started#

Ray exposes its metrics in Prometheus format. This allows us to easily scrape them using Prometheus.

First, download Prometheus. Make sure to download the correct binary for your operating system. (Ex: darwin for mac osx)

Then, unzip the the archive into a local directory using the following command.

tar xvfz prometheus-*.tar.gz
cd prometheus-*

Ray exports metrics only when ray[default] is installed.

pip install "ray[default]"

Ray provides a prometheus config that works out of the box. After running ray, it can be found at /tmp/ray/session_latest/metrics/prometheus/prometheus.yml.

  scrape_interval: 15s
  evaluation_interval: 15s

# Scrape from each ray node as defined in the service_discovery.json provided by ray.
- job_name: 'ray'
  - files:
    - '/tmp/ray/prom_metrics_service_discovery.json'

Next, let’s start Prometheus.

./prometheus --config.file=/tmp/ray/session_latest/metrics/prometheus/prometheus.yml


If you are using mac, you may receive an error at this point about trying to launch an application where the developer has not been verified. See this link to fix the issue.

Now, you can access Ray metrics from the default Prometheus url, http://localhost:9090.

See here for more information on how to set up Prometheus on a Ray Cluster.


Grafana is a tool that supports more advanced visualizations of prometheus metrics and allows you to create custom dashboards with your favorite metrics. Ray exports some default configurations which includes a default dashboard showing some of the most valuable metrics for debugging ray applications.

First, download Grafana. Follow the instructions on the download page to download the right binary for your operating system.

Then go to to the location of the binary and run grafana using the built in configuration found in /tmp/ray/session_latest/metrics/grafana folder.

./bin/grafana-server --config /tmp/ray/session_latest/metrics/grafana/grafana.ini web

Now, you can access grafana using the default grafana url, http://localhost:3000. You can then see the default dashboard by going to dashboards -> manage -> Ray -> Default Dashboard. The same metric graphs are also accessible via Ray Dashboard.


If this is your first time using Grafana, you can login with the username: admin and password admin.


System Metrics#

Ray exports a number of system metrics, which provide introspection into the state of Ray workloads, as well as hardware utilization statistics. The following table describes the officially supported metrics:


Certain labels are common across all metrics, such as SessionName (uniquely identifies a Ray cluster instance), instance (per-node label applied by Prometheus, and JobId (Ray job id, as applicable).

Ray System Metrics#

Prometheus Metric




Name, State

Current number of tasks (both remote functions and actor calls) by state. The State label (e.g., RUNNING, FINISHED, FAILED) describes the state of the task. See rpc::TaskState for more information. The function/method name is available as the Name label.


Name, State

Current number of actors in a particular state. The State label is described by rpc::ActorTableData proto in gcs.proto. The actor class name is available in the Name label.


Name, State

Logical resource usage for each node of the cluster. Each resource has some quantity that is in either USED state vs AVAILABLE state. The Name label defines the resource name (e.g., CPU, GPU).


Location, ObjectState

Object store memory usage in bytes, broken down by logical Location (SPILLED, IN_MEMORY, etc.), and ObjectState (UNSEALED, SEALED).



Current number of placement groups by state. The State label (e.g., PENDING, CREATED, REMOVED) describes the state of the placement group. See rpc::PlacementGroupTable for more information.



The CPU utilization per node as a percentage quantity (0..100). This should be scaled by the number of cores per node to convert the units into cores.



The number of CPU cores per node.



The GPU utilization per node as a percentage quantity (0..NGPU*100). Note that unlike ray_node_cpu_utilization, this quantity is pre-multiplied by the number of GPUs per node.



The amount of disk space used per node, in bytes.



The amount of disk space available per node, in bytes.



The disk write throughput per node, in bytes per second.



The disk read throughput per node, in bytes per second.



The amount of physical memory used per node, in bytes.



The amount of physical memory available per node, in bytes.



The measured unique set size in megabytes, broken down by logical Ray component (e.g., raylet, gcs, workers).



The amount of GPU memory used per node, in bytes.



The network receive throughput per node, in bytes per second.



The network send throughput per node, in bytes per second.



The number of healthy nodes in the cluster, broken down by autoscaler node type.



The number of failed nodes reported by the autoscaler, broken down by node type.



The number of pending nodes reported by the autoscaler, broken down by node type.

Metrics Semantics and Consistency#

Ray guarantees all its internal state metrics are eventually consistent even in the presence of failures— should any worker fail, eventually the right state will be reflected in the Prometheus time-series output. However, any particular metrics query is not guaranteed to reflect an exact snapshot of the cluster state.

For the ray_tasks and ray_actors metrics, you should use sum queries to plot their outputs (e.g., sum(ray_tasks) by (Name, State)). The reason for this is that Ray’s task metrics are emitted from multiple distributed components. Hence, there are multiple metric points, including negative metric points, emitted from different processes that must be summed to produce the correct logical view of the distributed system. For example, for a single task submitted and executed, Ray may emit (submitter) SUBMITTED_TO_WORKER: 1, (executor) SUBMITTED_TO_WORKER: -1, (executor) RUNNING: 1, which reduces to SUBMITTED_TO_WORKER: 0, RUNNING: 1 after summation.

Application-level Metrics#

Ray provides a convenient API in ray.util.metrics for defining and exporting custom metrics for visibility into your applications. There are currently three metrics supported: Counter, Gauge, and Histogram. These metrics correspond to the same Prometheus metric types. Below is a simple example of an actor that exports metrics using these APIs:

import time

import ray
from ray.util.metrics import Counter, Gauge, Histogram


class MyActor:
    def __init__(self, name):
        self._curr_count = 0

        self.counter = Counter(
            description="Number of requests processed by the actor.",
        self.counter.set_default_tags({"actor_name": name})

        self.gauge = Gauge(
            description="Current count held by the actor. Goes up and down.",
        self.gauge.set_default_tags({"actor_name": name})

        self.histogram = Histogram(
            description="Latencies of requests in ms.",
            boundaries=[0.1, 1],
        self.histogram.set_default_tags({"actor_name": name})

    def process_request(self, num):
        start = time.time()
        self._curr_count += num

        # Increment the total request count.
        # Update the gauge to the new value.
        # Record the latency for this request in ms.
        self.histogram.observe(1000 * (time.time() - start))

        return self._curr_count

print("Starting actor.")
my_actor = MyActor.remote("my_actor")
print("Calling actor.")
print("Calling actor.")
print("Metrics should be exported.")
print("See http://localhost:8080 (this may take a few seconds to load).")

# Sleep so we can look at the metrics before exiting.

While the script is running, the metrics will be exported to localhost:8080 (this is the endpoint that Prometheus would be configured to scrape). If you open this in the browser, you should see the following output:

# HELP ray_request_latency Latencies of requests in ms.
# TYPE ray_request_latency histogram
ray_request_latency_bucket{Component="core_worker",Version="3.0.0.dev0",actor_name="my_actor",le="0.1"} 2.0
ray_request_latency_bucket{Component="core_worker",Version="3.0.0.dev0",actor_name="my_actor",le="1.0"} 2.0
ray_request_latency_bucket{Component="core_worker",Version="3.0.0.dev0",actor_name="my_actor",le="+Inf"} 2.0
ray_request_latency_count{Component="core_worker",Version="3.0.0.dev0",actor_name="my_actor"} 2.0
ray_request_latency_sum{Component="core_worker",Version="3.0.0.dev0",actor_name="my_actor"} 0.11992454528808594
# HELP ray_curr_count Current count held by the actor. Goes up and down.
# TYPE ray_curr_count gauge
ray_curr_count{Component="core_worker",Version="3.0.0.dev0",actor_name="my_actor"} -15.0
# HELP ray_num_requests_total Number of requests processed by the actor.
# TYPE ray_num_requests_total counter
ray_num_requests_total{Component="core_worker",Version="3.0.0.dev0",actor_name="my_actor"} 2.0

Please see ray.util.metrics for more details.

Customize prometheus export port#

Ray by default provides the service discovery file, but you can directly scrape metrics from prometheus ports. To do that, you may want to customize the port that metrics gets exposed to a pre-defined port.

ray start --head --metrics-export-port=8080 # Assign metrics export port on a head node.

Now, you can scrape Ray’s metrics using Prometheus via <ip>:8080.


Mac does not trust the developer when installing prometheus or grafana#

You may have received an error that looks like this:

When downloading binaries from the internet, Mac requires that the binary be signed by a trusted developer ID. Unfortunately, many developers today are not trusted by Mac and so this requirement must be overridden by the user manaully.

See these instructions on how to override the restriction and install or run the application.