From 335ba409f9a8404e036430ebe911dff7c7965036 Mon Sep 17 00:00:00 2001 From: Quentin Pradet Date: Tue, 25 Nov 2025 17:21:35 +0400 Subject: [PATCH] Add cat.circuit_breaker API --- specification/_doc_ids/table.csv | 1 + specification/cat/_types/CatBase.ts | 52 +++++++++++++ .../CatCircuitBreakerRequest.ts | 75 +++++++++++++++++++ .../CatCircuitBreakerResponse.ts | 25 +++++++ .../CatCircuitBreakerResponseExample1.yaml | 23 ++++++ .../CatCircuitBreakerRequestExample1.yaml | 1 + specification/cat/circuit_breaker/types.ts | 68 +++++++++++++++++ 7 files changed, 245 insertions(+) create mode 100644 specification/cat/circuit_breaker/CatCircuitBreakerRequest.ts create mode 100644 specification/cat/circuit_breaker/CatCircuitBreakerResponse.ts create mode 100644 specification/cat/circuit_breaker/examples/200_response/CatCircuitBreakerResponseExample1.yaml create mode 100644 specification/cat/circuit_breaker/examples/request/CatCircuitBreakerRequestExample1.yaml create mode 100644 specification/cat/circuit_breaker/types.ts diff --git a/specification/_doc_ids/table.csv b/specification/_doc_ids/table.csv index 9a8c5d3fd9..e94e2e25c2 100644 --- a/specification/_doc_ids/table.csv +++ b/specification/_doc_ids/table.csv @@ -51,6 +51,7 @@ calendar-and-fixed-intervals,https://www.elastic.co/docs/reference/aggregations/ cat-alias,https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-cat-aliases,https://www.elastic.co/guide/en/elasticsearch/reference/8.18/cat-alias.html, cat-allocation,https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-cat-allocation,https://www.elastic.co/guide/en/elasticsearch/reference/8.18/cat-allocation.html, cat-anomaly-detectors,https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-cat-ml-jobs,https://www.elastic.co/guide/en/elasticsearch/reference/8.18/cat-anomaly-detectors.html, +cat-circuit-breaker,https://www.elastic.co/docs/api/doc/elasticsearch#TODO,, cat-component-templates,https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-cat-component-templates,https://www.elastic.co/guide/en/elasticsearch/reference/8.18/cat-component-templates.html, cat-count,https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-cat-count,https://www.elastic.co/guide/en/elasticsearch/reference/8.18/cat-count.html, cat-datafeeds,https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-cat-ml-datafeeds,https://www.elastic.co/guide/en/elasticsearch/reference/8.18/cat-datafeeds.html, diff --git a/specification/cat/_types/CatBase.ts b/specification/cat/_types/CatBase.ts index 7812de95e7..6347c7cdb6 100644 --- a/specification/cat/_types/CatBase.ts +++ b/specification/cat/_types/CatBase.ts @@ -1260,6 +1260,55 @@ export enum CatAllocationColumn { 'node.role' } +/** @non_exhaustive */ +export enum CatCircuitBreakerColumn { + /** + * Persistent node ID + * @aliases id + */ + node_id, + /** + * Node name + * @aliases nn + */ + node_name, + /** + * Breaker name + * @aliases br + */ + breaker, + /** + * Limit size + * @aliases l + */ + limit, + /** + * Limit size in bytes + * @aliases lb + */ + limit_bytes, + /** + * Estimated size + * @aliases e + */ + estimated, + /** + * Estimated size in bytes + * @aliases eb + */ + estimated_bytes, + /** + * Tripped count + * @aliases t + */ + tripped, + /** + * Overhead + * @aliases o + */ + overhead +} + /** @non_exhaustive */ export enum CatComponentColumn { /** @@ -2479,6 +2528,9 @@ export type CatSegmentsColumns = CatSegmentsColumn | CatSegmentsColumn[] export type CatSnapshotsColumns = CatSnapshotsColumn | CatSnapshotsColumn[] export type CatAliasesColumns = CatAliasesColumn | CatAliasesColumn[] export type CatAllocationColumns = CatAllocationColumn | CatAllocationColumn[] +export type CatCircuitBreakerColumns = + | CatCircuitBreakerColumn + | CatCircuitBreakerColumn[] export type CatComponentColumns = CatComponentColumn | CatComponentColumn[] export type CatCountColumns = CatCountColumn | CatCountColumn[] export type CatFieldDataColumns = CatFieldDataColumn | CatFieldDataColumn[] diff --git a/specification/cat/circuit_breaker/CatCircuitBreakerRequest.ts b/specification/cat/circuit_breaker/CatCircuitBreakerRequest.ts new file mode 100644 index 0000000000..ff312417bc --- /dev/null +++ b/specification/cat/circuit_breaker/CatCircuitBreakerRequest.ts @@ -0,0 +1,75 @@ +/* + * Licensed to Elasticsearch B.V. under one or more contributor + * license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright + * ownership. Elasticsearch B.V. licenses this file to you under + * the Apache License, Version 2.0 (the "License"); you may + * not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ + +import { Names } from '@_types/common' +import { Duration } from '@_types/Time' +import { CatCircuitBreakerColumns, CatRequestBase } from '@cat/_types/CatBase' + +/** + * Get circuit breakers statistics. + * + * + * IMPORTANT: CAT APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications. + * @rest_spec_name cat.circuit_breaker + * @availability stack stability=stable + * @availability serverless stability=stable visibility=private + * @doc_id cat-circuit-breaker + * @cluster_privileges monitor + */ +export interface Request extends CatRequestBase { + urls: [ + { + path: '/_cat/circuit_breaker' + methods: ['GET'] + }, + { + path: '/_cat/circuit_breaker/{circuit_breaker_patterns}' + methods: ['GET'] + } + ] + path_parts: { + /** A comma-separated list of regular-expressions to filter the circuit breakers in the output */ + circuit_breaker_patterns?: string | string[] + } + query_parameters: { + /** + * A comma-separated list of columns names to display. It supports simple wildcards. + */ + h?: CatCircuitBreakerColumns + /** + * List of columns that determine how the table should be sorted. + * Sorting defaults to ascending and can be changed by setting `:asc` + * or `:desc` as a suffix to the column name. + */ + s?: Names + /** + * If `true`, the request computes the list of selected nodes from the + * local cluster state. If `false` the list of selected nodes are computed + * from the cluster state of the master node. In both cases the coordinating + * node will send requests for further information to each selected node. + * @server_default false + */ + local?: boolean + /** + * Period to wait for a connection to the master node. + * @server_default 30s + */ + master_timeout?: Duration + } +} diff --git a/specification/cat/circuit_breaker/CatCircuitBreakerResponse.ts b/specification/cat/circuit_breaker/CatCircuitBreakerResponse.ts new file mode 100644 index 0000000000..a2a22bf2a2 --- /dev/null +++ b/specification/cat/circuit_breaker/CatCircuitBreakerResponse.ts @@ -0,0 +1,25 @@ +/* + * Licensed to Elasticsearch B.V. under one or more contributor + * license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright + * ownership. Elasticsearch B.V. licenses this file to you under + * the Apache License, Version 2.0 (the "License"); you may + * not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ + +import { CircuitBreakerRecord } from './types' + +export class Response { + /** @codegen_name statistics */ + body: Array +} diff --git a/specification/cat/circuit_breaker/examples/200_response/CatCircuitBreakerResponseExample1.yaml b/specification/cat/circuit_breaker/examples/200_response/CatCircuitBreakerResponseExample1.yaml new file mode 100644 index 0000000000..a5b2994147 --- /dev/null +++ b/specification/cat/circuit_breaker/examples/200_response/CatCircuitBreakerResponseExample1.yaml @@ -0,0 +1,23 @@ +# summary: +description: > + A successful response from `GET /_cat/circuit_breaker?v=true&format=json`. + It shows two circuit breakers are active on one node. +# type: response +# response_code: 200 +value: |- + [ + { + "breaker": "request", + "estimated": "0b", + "limit": "614.3mb", + "node_id": "ozKxpP9oS3SL0Sp-Mfxc6w", + "tripped": "0" + }, + { + "breaker": "fielddata", + "estimated": "0b", + "limit": "409.5mb", + "node_id": "ozKxpP9oS3SL0Sp-Mfxc6w", + "tripped": "0" + } + ] diff --git a/specification/cat/circuit_breaker/examples/request/CatCircuitBreakerRequestExample1.yaml b/specification/cat/circuit_breaker/examples/request/CatCircuitBreakerRequestExample1.yaml new file mode 100644 index 0000000000..c482c8b02d --- /dev/null +++ b/specification/cat/circuit_breaker/examples/request/CatCircuitBreakerRequestExample1.yaml @@ -0,0 +1 @@ +method_request: GET /_cat/circuit_breaker?v=true&format=json diff --git a/specification/cat/circuit_breaker/types.ts b/specification/cat/circuit_breaker/types.ts new file mode 100644 index 0000000000..b847a5f316 --- /dev/null +++ b/specification/cat/circuit_breaker/types.ts @@ -0,0 +1,68 @@ +/* + * Licensed to Elasticsearch B.V. under one or more contributor + * license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright + * ownership. Elasticsearch B.V. licenses this file to you under + * the Apache License, Version 2.0 (the "License"); you may + * not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ + +import { ByteSize, NodeId } from '@_types/common' + +export class CircuitBreakerRecord { + /** + * Persistent node ID + * @aliases id + */ + node_id?: NodeId + /** + * Node name + * @aliases nn + */ + node_name?: string + /** + * Breaker name + * @aliases br + */ + breaker?: string + /** + * Limit size + * @aliases l + */ + limit?: string + /** + * Limit size in bytes + * @aliases lb + */ + limit_bytes?: ByteSize + /** + * Estimated size + * @aliases e + */ + estimated?: string + /** + * Estimated size in bytes + * @aliases eb + */ + estimated_bytes?: ByteSize + /** + * Tripped count + * @aliases t + */ + tripped?: string + /** + * Overhead + * @aliases o + */ + overhead?: string +}