[core] Group observability APIs in ray CLI help output

[nhquana2]

Description

Currently, when running ray --help, the core State API CLI commands (get, list, summary, and logs) are mixed alphabetically in the general "Commands" section alongside other commands. This makes it difficult for users to quickly identify which tools are available without referring to Ray's documentation.

I solved the issue by constructing a custom click Group subclass (RayCLI) that intercepts formatting. It groups the State API commands correctly under the Observability section when calling ray --help.

Implementation details

1. Created RayCLI Class: Overrides standard click.Group's format_commands() method to intercept and separate incoming subcommands.
2. Filtering State APIs: The method scans the loaded commands for "list", "get", "summary", and "logs".
3. Partitioned sections: Any matched commands are pushed into an Observability dict buffer while all remaining commands are pushed into the standard Commands.
4. Integration: Simply replaced the default @click.group() app entry decorator at scripts.py:cli with @click.group(cls=RayCLI).

Output of ray --help after changes:

Usage: ray [OPTIONS] COMMAND [ARGS]...

Options:
  --logging-level TEXT   The logging level threshold, choices=['debug',
                         'info', 'warning', 'error', 'critical'],
                         default='info'
  --logging-format TEXT  The logging format.
                         default="%%(asctime)s\t%%(levelname)s
                         %%(filename)s:%%(lineno)s -- %%(message)s"
  --version              Show the version and exit.
  --help                 Show this message and exit.

Commands:
  attach               Create or attach to a SSH session to a Ray cluster.
  check-open-ports     Check open ports in the local Ray cluster.
  cluster-dump         Get log data from one or more nodes.
  cpp                  Show the cpp library path and generate the bazel...
  dashboard            Port-forward a Ray cluster's dashboard to the...
  debug                Show all active breakpoints and exceptions in the...
  disable-usage-stats  Disable usage stats collection.
  down                 Tear down a Ray cluster.
  enable-usage-stats   Enable usage stats collection.
  exec                 Execute a command via SSH on a Ray cluster.
  get-auth-token       Prints the Ray authentication token to stdout.
  get-head-ip          Return the head node IP of a Ray cluster.
  get-worker-ips       Return the list of worker IPs of a Ray cluster.
  job                  Submit, stop, delete, or list Ray jobs.
  kill-actor           Kill an actor by name.
  memory               Print object references held in a Ray cluster.
  metrics
  microbenchmark       Run a local Ray microbenchmark on the current...
  monitor              Tails the autoscaler logs of a Ray cluster.
  rsync-down           Download specific files from a Ray cluster.
  rsync-up             Upload specific files to a Ray cluster.
  stack                Take a stack dump of all Python workers on the...
  start                Start Ray processes manually on the local machine.
  status               Print cluster status, including autoscaling info.
  stop                 Stop Ray processes manually on the local machine.
  submit               Uploads and runs a script on the specified cluster.
  symmetric-run        Command to start Ray across all nodes and execute...
  timeline             Take a Chrome tracing timeline for a Ray cluster.
  up                   Create or update a Ray cluster.

Observability:
  get      Get a state of a given resource by ID.
  list     List all states of a given resource.
  logs     Get logs based on filename (cluster) or resource...
  summary  Return the summarized information of a given...

Related Issue

• Fixes [Core][State Observability] Grouping state APIs when ray --help is called.  #26376

Testing / Verification

• Verified ray --help output manually on my local.
• All formatting and linting scripts passed pre-push hooks (using setup_hooks.sh).

[gemini-code-assist]

Code Review

This pull request introduces a custom RayCLI class that overrides the default command formatting to group CLI commands into 'Commands' and 'Observability' sections. The review feedback suggests expanding the list of observability-related commands to include additional diagnostic tools and refactoring the command set into a class-level constant for better code organization and idiomaticity.

[edoakes]

Looks good, thanks for the contribution. Could you leave a docstring comment on the RayCLI class indicating why it exists?

I've triggered premerge CI tests

[nhquana2]

Looks good, thanks for the contribution. Could you leave a docstring comment on the RayCLI class indicating why it exists?

I've triggered premerge CI tests

Hi @edoakes,

I’ve added the requested docstring. This is my first contribution to Ray as part of my university lab project, so I’d appreciate it if you could review and merge the changes.

I also have a couple of questions:

• The buildkite/microcheck is failing on some tests, I think those are flakey tests, would that be a problem? (Update: The failing tests are flakey, so it's no problem with my code and should be ignored)
• Could you please add me as the assignee of this issue [Core][State Observability] Grouping state APIs when ray --help is called.  #26376, since it's part of the requirements for my lab project.

Thanks for your support!

[edoakes]

Thanks for the contribution @nhquana2

[nhquana2]

Thanks, it was a pleasure contributing to Ray!