[data] documentation for ray data metrics (#58610)

## Description
Adds ray data metrics documentation for visibility. This should be
periodically updated with the latest metrics.

## Related issues
None

## Additional information
None

---------

Signed-off-by: iamjustinhsu <jhsu@anyscale.com>

Author: iamjustinhsu

doc/source/data/monitoring-your-workload.rst

@@ -118,6 +118,239 @@ The metrics recorded include:
 
 To learn more about the Ray dashboard, including detailed setup instructions, see :ref:`Ray Dashboard <observability-getting-started>`.
 
+Prometheus metrics
+~~~~~~~~~~~~~~~~~~
+
+Ray Data emits Prometheus metrics that you can use to monitor dataset execution. The metrics are tagged with `dataset` and `operator` labels to help you identify which dataset and operator the metrics are coming from.
+
+To access these metrics, you can query the Prometheus server running on the Ray head node. The default Prometheus server URL is `http://<head-node-ip>:8080`.
+
+The following tables list all available Ray Data metrics grouped by category.
+
+Overview metrics
+^^^^^^^^^^^^^^^^
+
+These metrics provide high-level information about dataset execution and resource usage.
+
+.. list-table::
+   :header-rows: 1
+   :widths: 30 70
+
+   * - Metric name
+     - Description
+   * - `data_spilled_bytes`
+     - Bytes spilled by dataset operators. Set `DataContext.enable_get_object_locations_for_metrics` to `True` to report this metric.
+   * - `data_freed_bytes`
+     - Bytes freed by dataset operators
+   * - `data_current_bytes`
+     - Bytes of object store memory used by dataset operators
+   * - `data_cpu_usage_cores`
+     - CPUs allocated to dataset operators
+   * - `data_gpu_usage_cores`
+     - GPUs allocated to dataset operators
+   * - `data_output_bytes`
+     - Bytes outputted by dataset operators
+   * - `data_output_rows`
+     - Rows outputted by dataset operators
+
+Input metrics
+^^^^^^^^^^^^^
+
+These metrics track input data flowing into operators.
+
+.. list-table::
+   :header-rows: 1
+   :widths: 30 70
+
+   * - Metric name
+     - Description
+   * - `num_inputs_received`
+     - Number of input blocks received by operator
+   * - `num_row_inputs_received`
+     - Number of input rows received by operator
+   * - `bytes_inputs_received`
+     - Byte size of input blocks received by operator
+   * - `num_task_inputs_processed`
+     - Number of input blocks that the operator's tasks finished processing
+   * - `bytes_task_inputs_processed`
+     - Byte size of input blocks that the operator's tasks finished processing
+   * - `bytes_inputs_of_submitted_tasks`
+     - Byte size of input blocks passed to submitted tasks
+   * - `rows_inputs_of_submitted_tasks`
+     - Number of rows in the input blocks passed to submitted tasks
+   * - `average_num_inputs_per_task`
+     - Average number of input blocks per task, or `None` if no task finished
+   * - `average_bytes_inputs_per_task`
+     - Average size in bytes of ref bundles passed to tasks, or `None` if no tasks submitted
+   * - `average_rows_inputs_per_task`
+     - Average number of rows in input blocks per task, or `None` if no task submitted
+
+Output metrics
+^^^^^^^^^^^^^^
+
+These metrics track output data generated by operators.
+
+.. list-table::
+   :header-rows: 1
+   :widths: 30 70
+
+   * - Metric name
+     - Description
+   * - `num_task_outputs_generated`
+     - Number of output blocks generated by tasks
+   * - `bytes_task_outputs_generated`
+     - Byte size of output blocks generated by tasks
+   * - `rows_task_outputs_generated`
+     - Number of output rows generated by tasks
+   * - `row_outputs_taken`
+     - Number of rows that are already taken by downstream operators
+   * - `block_outputs_taken`
+     - Number of blocks that are already taken by downstream operators
+   * - `num_outputs_taken`
+     - Number of output blocks that are already taken by downstream operators
+   * - `bytes_outputs_taken`
+     - Byte size of output blocks that are already taken by downstream operators
+   * - `num_outputs_of_finished_tasks`
+     - Number of generated output blocks that are from finished tasks
+   * - `bytes_outputs_of_finished_tasks`
+     - Total byte size of generated output blocks produced by finished tasks
+   * - `rows_outputs_of_finished_tasks`
+     - Number of rows generated by finished tasks
+   * - `num_external_inqueue_blocks`
+     - Number of blocks in the external inqueue
+   * - `num_external_inqueue_bytes`
+     - Byte size of blocks in the external inqueue
+   * - `num_external_outqueue_blocks`
+     - Number of blocks in the external outqueue
+   * - `num_external_outqueue_bytes`
+     - Byte size of blocks in the external outqueue
+   * - `average_num_outputs_per_task`
+     - Average number of output blocks per task, or `None` if no task finished
+   * - `average_bytes_per_output`
+     - Average size in bytes of output blocks
+   * - `average_bytes_outputs_per_task`
+     - Average total output size of task in bytes, or `None` if no task finished
+   * - `average_rows_outputs_per_task`
+     - Average number of rows produced per task, or `None` if no task finished
+   * - `num_output_blocks_per_task_s`
+     - Average number of output blocks per task per second
+
+Task metrics
+^^^^^^^^^^^^
+
+These metrics track task execution and scheduling.
+
+.. list-table::
+   :header-rows: 1
+   :widths: 30 70
+
+   * - Metric name
+     - Description
+   * - `num_tasks_submitted`
+     - Number of submitted tasks
+   * - `num_tasks_running`
+     - Number of running tasks
+   * - `num_tasks_have_outputs`
+     - Number of tasks with at least one output
+   * - `num_tasks_finished`
+     - Number of finished tasks
+   * - `num_tasks_failed`
+     - Number of failed tasks
+   * - `block_generation_time`
+     - Time spent generating blocks in tasks
+   * - `task_submission_backpressure_time`
+     - Time spent in task submission backpressure
+   * - `task_output_backpressure_time`
+     - Time spent in task output backpressure
+   * - `task_completion_time`
+     - Histogram of time spent running tasks to completion
+   * - `block_completion_time`
+     - Histogram of time spent running a single block to completion. If multiple blocks are generated per task, Ray Data approximates this by assuming each block took an equal amount of time to process.
+   * - `task_completion_time_s`
+     - Time spent running tasks to completion
+   * - `task_completion_time_excl_backpressure_s`
+     - Time spent running tasks to completion without backpressure
+   * - `block_size_bytes`
+     - Histogram of block sizes in bytes generated by tasks
+   * - `block_size_rows`
+     - Histogram of number of rows in blocks generated by tasks
+   * - `average_total_task_completion_time_s`
+     - Average task completion time in seconds including throttling. This includes Ray Core and Ray Data backpressure.
+   * - `average_task_completion_excl_backpressure_time_s`
+     - Average task completion time in seconds excluding throttling
+   * - `average_max_uss_per_task`
+     - Average Unique Set Size (USS) memory usage of tasks. USS is the amount of memory unique to a process that would be freed if the process was terminated.
+
+Actor metrics
+^^^^^^^^^^^^^
+
+These metrics track actor lifecycle for operations that use actors.
+
+.. list-table::
+   :header-rows: 1
+   :widths: 30 70
+
+   * - Metric name
+     - Description
+   * - `num_alive_actors`
+     - Number of alive actors
+   * - `num_restarting_actors`
+     - Number of restarting actors
+   * - `num_pending_actors`
+     - Number of pending actors
+
+Object store memory metrics
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+These metrics track memory usage in the Ray object store.
+
+.. list-table::
+   :header-rows: 1
+   :widths: 30 70
+
+   * - Metric name
+     - Description
+   * - `obj_store_mem_internal_inqueue_blocks`
+     - Number of blocks in the operator's internal input queue
+   * - `obj_store_mem_internal_outqueue_blocks`
+     - Number of blocks in the operator's internal output queue
+   * - `obj_store_mem_freed`
+     - Byte size of freed memory in object store
+   * - `obj_store_mem_spilled`
+     - Byte size of spilled memory in object store
+   * - `obj_store_mem_used`
+     - Byte size of used memory in object store
+   * - `obj_store_mem_internal_inqueue`
+     - Byte size of input blocks in the operator's internal input queue
+   * - `obj_store_mem_internal_outqueue`
+     - Byte size of output blocks in the operator's internal output queue
+   * - `obj_store_mem_pending_task_inputs`
+     - Byte size of input blocks used by pending tasks
+
+Scheduling and resource metrics
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+These metrics track resource allocation and scheduling behavior in the streaming executor.
+
+.. list-table::
+   :header-rows: 1
+   :widths: 30 70
+
+   * - Metric name
+     - Description
+   * - `data_sched_loop_duration_s`
+     - Duration of the scheduling loop in seconds
+   * - `data_cpu_budget`
+     - CPU budget allocated per operator
+   * - `data_gpu_budget`
+     - GPU budget allocated per operator
+   * - `data_memory_budget`
+     - Memory budget allocated per operator
+   * - `data_object_store_memory_budget`
+     - Object store memory budget allocated per operator
+   * - `data_max_bytes_to_read`
+     - Maximum bytes to read from streaming generator buffer per operator
+
 .. _ray-data-logs:
 
 Ray Data logs