URI path filtering support in cluster stats API

[SwethaGuptha]

Description

Introduced new URI paths to fetch specific information from _cluster/stats without having to fetch the entire stats that will benefit the API's performance. Motivation from #14447. The _cluster/stats API primarily comprises of nodes stats and indices stats, with the new URI paths, properties of these stats objects are flattened and clients can request for specific information.

URI paths introduced:

/_cluster/stats/{metric}/nodes/{nodeId}
/_cluster/stats/{metric}/{index_metric}/nodes/{nodeId}

Metrics supported:
os, process, jvm, fs, plugins, ingest, network_types, discovery_types, packaging_types, indices, _all

Index Metrics supported:
shards, docs, store , fielddata, query_cache, completion, segments, analysis, mappings, _all

Example REST request formats to exclude the information for

Request for fetching specific index stats properties only:

$ curl localhost:9200/_cluster/stats/indices/docs,segments/nodes/_all                                 
{"_nodes":{"total":1,"successful":1,"failed":0},"cluster_name":"runTask","cluster_uuid":"mtnrtcVURy2hOJn5scMSmQ","timestamp":1728897501917,"status":"green","indices":{"count":0,"docs":{"count":0,"deleted":0},"segments":{"count":0,"memory_in_bytes":0,"terms_memory_in_bytes":0,"stored_fields_memory_in_bytes":0,"term_vectors_memory_in_bytes":0,"norms_memory_in_bytes":0,"points_memory_in_bytes":0,"doc_values_memory_in_bytes":0,"index_writer_memory_in_bytes":0,"version_map_memory_in_bytes":0,"fixed_bit_set_memory_in_bytes":0,"max_unsafe_auto_id_timestamp":-9223372036854775808,"remote_store":{"upload":{"total_upload_size":{"started_bytes":0,"succeeded_bytes":0,"failed_bytes":0},"refresh_size_lag":{"total_bytes":0,"max_bytes":0},"max_refresh_time_lag_in_millis":0,"total_time_spent_in_millis":0,"pressure":{"total_rejections":0}},"download":{"total_download_size":{"started_bytes":0,"succeeded_bytes":0,"failed_bytes":0},"total_time_spent_in_millis":0}},"segment_replication":{"max_bytes_behind":0,"total_bytes_behind":0,"max_replication_lag":0},"file_sizes":{}}}}%  

$ curl localhost:9200/_cluster/stats/indices/mappings,analysis/nodes/_all
{"_nodes":{"total":1,"successful":1,"failed":0},"cluster_name":"runTask","cluster_uuid":"mtnrtcVURy2hOJn5scMSmQ","timestamp":1728897531305,"status":"green","indices":{"count":0,"mappings":{"field_types":[]},"analysis":{"char_filter_types":[],"tokenizer_types":[],"filter_types":[],"analyzer_types":[],"built_in_char_filters":[],"built_in_tokenizers":[],"built_in_filters":[],"built_in_analyzers":[]}}}% 

Request for fetching specific node stats properties only:

$ curl localhost:9200/_cluster/stats/os,jvm/nodes/_all
{"_nodes":{"total":1,"successful":1,"failed":0},"cluster_name":"runTask","cluster_uuid":"mtnrtcVURy2hOJn5scMSmQ","timestamp":1728897551016,"status":"green","nodes":{"count":{"total":1,"cluster_manager":1,"coordinating_only":0,"data":1,"ingest":1,"master":1,"remote_cluster_client":1,"search":0},"versions":["3.0.0"],"os":{"available_processors":12,"allocated_processors":12,"names":[{"name":"Mac OS X","count":1}],"pretty_names":[{"pretty_name":"Mac OS X","count":1}],"mem":{"total_in_bytes":17179869184,"free_in_bytes":22298624,"used_in_bytes":17157570560,"free_percent":0,"used_percent":100}},"jvm":{"max_uptime_in_millis":495233,"versions":[{"version":"19.0.1","vm_name":"OpenJDK 64-Bit Server VM","vm_version":"19.0.1+10-21","vm_vendor":"Oracle Corporation","bundled_jdk":true,"using_bundled_jdk":false,"count":1}],"mem":{"heap_used_in_bytes":106676736,"heap_max_in_bytes":536870912},"threads":25}}}% 

Request for fetching specific node stats and indices state properties:

$ curl localhost:9200/_cluster/stats/indices,os,jvm/shards/nodes/_all          
{"_nodes":{"total":1,"successful":1,"failed":0},"cluster_name":"runTask","cluster_uuid":"mtnrtcVURy2hOJn5scMSmQ","timestamp":1728897709009,"status":"yellow","indices":{"count":1,"shards":{"total":3,"primaries":3,"replication":0.0,"index":{"shards":{"min":3,"max":3,"avg":3.0},"primaries":{"min":3,"max":3,"avg":3.0},"replication":{"min":0.0,"max":0.0,"avg":0.0}}}},"nodes":{"count":{"total":1,"cluster_manager":1,"coordinating_only":0,"data":1,"ingest":1,"master":1,"remote_cluster_client":1,"search":0},"versions":["3.0.0"],"os":{"available_processors":12,"allocated_processors":12,"names":[{"name":"Mac OS X","count":1}],"pretty_names":[{"pretty_name":"Mac OS X","count":1}],"mem":{"total_in_bytes":17179869184,"free_in_bytes":27590656,"used_in_bytes":17152278528,"free_percent":0,"used_percent":100}},"jvm":{"max_uptime_in_millis":653256,"versions":[{"version":"19.0.1","vm_name":"OpenJDK 64-Bit Server VM","vm_version":"19.0.1+10-21","vm_vendor":"Oracle Corporation","bundled_jdk":true,"using_bundled_jdk":false,"count":1}],"mem":{"heap_used_in_bytes":141279744,"heap_max_in_bytes":536870912},"threads":31}}}%


$ curl localhost:9200/_cluster/stats/_all/shards/nodes/_all
{"_nodes":{"total":1,"successful":1,"failed":0},"cluster_name":"runTask","cluster_uuid":"mtnrtcVURy2hOJn5scMSmQ","timestamp":1728897740389,"status":"yellow","indices":{"count":1,"shards":{"total":3,"primaries":3,"replication":0.0,"index":{"shards":{"min":3,"max":3,"avg":3.0},"primaries":{"min":3,"max":3,"avg":3.0},"replication":{"min":0.0,"max":0.0,"avg":0.0}}}},"nodes":{"count":{"total":1,"cluster_manager":1,"coordinating_only":0,"data":1,"ingest":1,"master":1,"remote_cluster_client":1,"search":0},"versions":["3.0.0"],"os":{"available_processors":12,"allocated_processors":12,"names":[{"name":"Mac OS X","count":1}],"pretty_names":[{"pretty_name":"Mac OS X","count":1}],"mem":{"total_in_bytes":17179869184,"free_in_bytes":260648960,"used_in_bytes":16919220224,"free_percent":2,"used_percent":98}},"process":{"cpu":{"percent":0},"open_file_descriptors":{"min":191,"max":191,"avg":191}},"jvm":{"max_uptime_in_millis":684642,"versions":[{"version":"19.0.1","vm_name":"OpenJDK 64-Bit Server VM","vm_version":"19.0.1+10-21","vm_vendor":"Oracle Corporation","bundled_jdk":true,"using_bundled_jdk":false,"count":1}],"mem":{"heap_used_in_bytes":147571200,"heap_max_in_bytes":536870912},"threads":35},"fs":{"total_in_bytes":499963174912,"free_in_bytes":94558470144,"available_in_bytes":94558470144,"cache_reserved_in_bytes":0},"plugins":[],"network_types":{"transport_types":{"netty4":1},"http_types":{"netty4":1}},"discovery_types":{"zen":1},"packaging_types":[{"type":"tar","count":1}],"ingest":{"number_of_pipelines":0,"processor_stats":{}}}}

If a random metric is requested, exception is thrown:

$ curl localhost:9200/_cluster/stats/os,mappings,jvm,analysis,addssf/nodes/_all
{"error":{"root_cause":[{"type":"illegal_argument_exception","reason":"request [/_cluster/stats/os,mappings,jvm,analysis,addssf/nodes/_all] contains unrecognized metrics: [addssf], [analysis], [mappings]"}],"type":"illegal_argument_exception","reason":"request [/_cluster/stats/os,mappings,jvm,analysis,addssf/nodes/_all] contains unrecognized metrics: [addssf], [analysis], [mappings]"},"status":400}%

Related Issues

Resolves #[Issue number to be closed when this PR is merged]

Check List

• Functionality includes testing.
• API changes companion pull request created, if applicable.
• Public documentation issue/PR created, if applicable.

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.
For more information on following Developer Certificate of Origin and signing off your commits, please check here.

[github-actions]

❌ Gradle check result for 1a7b37b: FAILURE

Please examine the workflow log, locate, and copy-paste the failure(s) below, then iterate to green. Is the failure a flaky test unrelated to your change?

[github-actions]

❌ Gradle check result for f95c505: FAILURE

Please examine the workflow log, locate, and copy-paste the failure(s) below, then iterate to green. Is the failure a flaky test unrelated to your change?

[github-actions]

❌ Gradle check result for 2263cf0: FAILURE

Please examine the workflow log, locate, and copy-paste the failure(s) below, then iterate to green. Is the failure a flaky test unrelated to your change?

[github-actions]

❌ Gradle check result for 0038530: FAILURE

Please examine the workflow log, locate, and copy-paste the failure(s) below, then iterate to green. Is the failure a flaky test unrelated to your change?

[github-actions]

❌ Gradle check result for be9e6cd: FAILURE

Please examine the workflow log, locate, and copy-paste the failure(s) below, then iterate to green. Is the failure a flaky test unrelated to your change?

[github-actions]

✅ Gradle check result for 302e7ec: SUCCESS

[shwetathareja]

@SwethaGuptha please add changelog for it

[shwetathareja]

we will need documentation PR and Rest API spec PR as well for this change.

[SwethaGuptha]

we will need documentation PR and Rest API spec PR as well for this change.

Raised PR for both of them.

[github-actions]

✅ Gradle check result for 6b87984: SUCCESS

[github-actions]

✅ Gradle check result for f596268: SUCCESS

[opensearch-trigger-bot]

The backport to 2.x failed:

The process '/usr/bin/git' failed with exit code 128

To backport manually, run these commands in your terminal:

# Navigate to the root of your repository
cd $(git rev-parse --show-toplevel)
# Fetch latest updates from GitHub
git fetch
# Create a new working tree
git worktree add ../.worktrees/OpenSearch/backport-2.x 2.x
# Navigate to the new working tree
pushd ../.worktrees/OpenSearch/backport-2.x
# Create a new branch
git switch --create backport/backport-15938-to-2.x
# Cherry-pick the merged commit of this pull request and resolve the conflicts
git cherry-pick -x --mainline 1 19824275fe78014249143724c5b84a6211e6e642
# Push it to GitHub
git push --set-upstream origin backport/backport-15938-to-2.x
# Go back to the original working tree
popd
# Delete the working tree
git worktree remove ../.worktrees/OpenSearch/backport-2.x

Then, create a pull request where the base branch is 2.x and the compare/head branch is backport/backport-15938-to-2.x.