cat API: added endpoint for Circuit Breakers #136890

mamazzol · 2025-10-21T16:15:38Z

Added CAT Action to display Circuit Breakers stats for all nodes. The API supports pattern matching as a path parameter and the standard query parameters of CAT actions (help, format, h...).

The default call only prints node_id, breaker, limit, estimated and tripped as a minimal set of sufficient information.
The test uses action.handleRequest(restRequest, channel, nodeClient); to retrieve the response from the channel from the main thread. The flow executed from controller.dispatchRequest in RestActionTestCase chunks the response and the encoding is required to happen on a Transport thread.

Addresses: #132688

Added CAT Action to display Circuit Breakers stats for all nodes. The API supports pattern matching as a path parameter and the standard query parameters of CAT actions. Addresses elastic#132688

elasticsearchmachine · 2025-10-21T16:16:16Z

Pinging @elastic/es-core-infra (Team:Core/Infra)

elasticsearchmachine · 2025-10-21T16:16:58Z

Hi @mamazzol, I've created a changelog YAML for you.

ldematte

Looks good!
I left a couple of comments, more for discussion and learning really.

ldematte · 2025-10-22T07:27:51Z

server/src/main/java/org/elasticsearch/rest/action/cat/RestCatCircuitBreakerAction.java

+            @Override
+            public void processResponse(final ClusterStateResponse clusterStateResponse) {
+                NodesStatsRequest nodesStatsRequest = new NodesStatsRequest(
+                    clusterStateResponse.getState().nodes().stream().map(DiscoveryNode::getId).toArray(String[]::new)


It's kind of a pity to have DiscoveryNode here, get the ID, and then have BaseNodeRequest#resolveNodes find the DiscoveryNode again

It's a little subtle, but this should be unnecessary: AFAICT we're always getting these stats from all nodes, but that's the default behaviour, we can just pass the empty array. See org.elasticsearch.action.support.nodes.BaseNodesRequest#resolveNodes which calls org.elasticsearch.cluster.node.DiscoveryNodes#resolveNodes which does this:

elasticsearch/server/src/main/java/org/elasticsearch/cluster/node/DiscoveryNodes.java

Lines 438 to 439 in f3a1664

if (nodes == null || nodes.length == 0) {

return stream().map(DiscoveryNode::getId).toArray(String[]::new);

Thanks! After looking through the code I saw what you were pointing at, it is indeed redundant to get the nodes from the ClusterState with a separate request. I have removed it

ldematte · 2025-10-22T07:30:39Z

server/src/main/java/org/elasticsearch/rest/action/cat/RestCatCircuitBreakerAction.java

+                    clusterStateResponse.getState().nodes().stream().map(DiscoveryNode::getId).toArray(String[]::new)
+                );
+                nodesStatsRequest.clear().addMetric(NodesStatsRequestParameters.Metric.BREAKER);
+                client.admin().cluster().nodesStats(nodesStatsRequest, new RestResponseListener<>(channel) {


If you want to avoid this kind of nesting, and possibly generate better response in case of failure, you might consider ListenableFuture. It makes reasoning more complicated though (IMO). See RestShardsAction for an example.

Please prefer SubscribableListener over ListenableFuture. They're basically the same, except ListenableFuture adds multiple layers of wrapping around the exceptions it encounters for largely-historical reasons.

Thanks for the tip @DaveCTurner!

Thanks! I'll keep that in mind for the future. For now, after removing the first request there's only 1 action executed so it shouldn't be needed.

…mplified logic

mosche · 2025-10-24T10:48:27Z

Looking good, @mamazzol !
I think the only thing missing for a new cat endpoint is a corresponding spec in rest-api-spec/src/main/resources/rest-api-spec.api and a corresponding very basic yamlRestTest similar to the other test for the cat api, see rest-api-spec/src/yamlRestTest/resources/rest-api-spec.test.

To skip the test when running backwards compatibility tests against older versions, you can use a capability (which is just the endpoint itself in this case, see https://github.com/elastic/elasticsearch/blob/main/rest-api-spec/src/yamlRestTest/resources/rest-api-spec/test/README.asciidoc#require-or-skip-api-capabilities)

For examples you can have a look at cat.health/10_basic.yml or capabilities/10_basic.yml.

mosche

LGTM, @mamazzol, great work.
Just a tiny nit before merging.

mosche · 2025-10-28T16:38:09Z

server/src/main/java/org/elasticsearch/rest/action/cat/RestCatCircuitBreakerAction.java

+
+    @Override
+    public Set<String> supportedCapabilities() {
+        return Sets.union(Set.of("cat_circuit_breaker"), super.supportedCapabilities());


This shouldn't be necessary, the pure existence of the REST endpoint should be enough

Do you know how I can verify it?
I saw other tests added this capability filter, like cat_circuit_breaker in my case, but where does that get defined as a capability, if not in that method? ( I trust you, I am just curious :D )

mosche · 2025-10-28T16:40:02Z

rest-api-spec/src/yamlRestTest/resources/rest-api-spec/test/cat.circuit_breaker/10_basic.yml

+      capabilities:
+        - method: GET
+          path: /_cat/circuit_breaker
+          capabilities: [ cat_circuit_breaker ]


Suggested change

capabilities: [ cat_circuit_breaker ]

As mentioned above, defining and checking for a capability shouldn't be needed here. Existence should do

ldematte · 2025-10-29T15:01:27Z

🥳

Added CAT Action to display Circuit Breakers stats for all nodes. The API supports pattern matching as a path parameter and the standard query parameters of CAT actions. This change includes spec and yamlRestTest. Addresses elastic#132688

cat API: added endpoint for Circuit Breakers

7bfe80a

Added CAT Action to display Circuit Breakers stats for all nodes. The API supports pattern matching as a path parameter and the standard query parameters of CAT actions. Addresses elastic#132688

mamazzol added >enhancement :Core/Infra/REST API REST infrastructure and utilities Team:Core/Infra Meta label for core/infra team Supportability Improve our (devs, SREs, support eng, users) ability to troubleshoot/self-service product better. labels Oct 21, 2025

Merge branch 'main' into cat-circuit-breaker

57b8e42

elasticsearchmachine added external-contributor Pull request authored by a developer outside the Elasticsearch team v9.3.0 labels Oct 21, 2025

Update docs/changelog/136890.yaml

1d6853a

ldematte reviewed Oct 22, 2025

View reviewed changes

ldematte requested a review from a team October 22, 2025 07:36

arpadkiraly removed the external-contributor Pull request authored by a developer outside the Elasticsearch team label Oct 22, 2025

mamazzol added 2 commits October 23, 2025 17:23

Improve cat circuit breaker implementation with error handling and si…

b49d08d

…mplified logic

Merge branch 'main' into cat-circuit-breaker

662e3cb

mamazzol added 2 commits October 28, 2025 14:05

Add cat circuit_breaker specs and yamlRestTest

7d0db66

Merge branch 'main' into cat-circuit-breaker

1468d4d

mosche approved these changes Oct 28, 2025

View reviewed changes

mosche added auto-backport Automatically create backport pull requests when merged and removed auto-backport Automatically create backport pull requests when merged labels Oct 29, 2025

mamazzol added 2 commits October 29, 2025 11:25

Remove unnecessary capability code

5cd3b8e

Merge branch 'main' into cat-circuit-breaker

b658493

mamazzol enabled auto-merge (squash) October 29, 2025 11:27

[CI] Auto commit changes from spotless

ff13743

mamazzol merged commit 52feb00 into elastic:main Oct 29, 2025
34 checks passed

mamazzol deleted the cat-circuit-breaker branch October 29, 2025 12:42

stefnestor mentioned this pull request Oct 31, 2025

CAT Circuit Breakers | Report Node Roles #137461

Open

pquentin mentioned this pull request Nov 25, 2025

Add cat.circuit_breaker API elastic/elasticsearch-specification#5738

Merged

	if (nodes == null \|\| nodes.length == 0) {
	return stream().map(DiscoveryNode::getId).toArray(String[]::new);

cat API: added endpoint for Circuit Breakers #136890

cat API: added endpoint for Circuit Breakers #136890

Uh oh!

Conversation

mamazzol commented Oct 21, 2025

Uh oh!

elasticsearchmachine commented Oct 21, 2025

Uh oh!

elasticsearchmachine commented Oct 21, 2025

Uh oh!

ldematte left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mosche commented Oct 24, 2025

Uh oh!

mosche left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

ldematte commented Oct 29, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants