diff --git a/docs/overlays/elasticsearch-openapi-overlays.yaml b/docs/overlays/elasticsearch-openapi-overlays.yaml index a163f41de2..e3cc23110d 100644 --- a/docs/overlays/elasticsearch-openapi-overlays.yaml +++ b/docs/overlays/elasticsearch-openapi-overlays.yaml @@ -199,6 +199,74 @@ actions: examples: resumeFollowIndexResponseExample1: $ref: "../../specification/ccr/resume_follow/examples/response/ResumeFollowIndexResponseExample1.yaml" + - target: "$.paths['/{index}/_ccr/unfollow']['post']" + description: "Add examples for unfollow an index" + update: + responses: + 200: + content: + application/json: + examples: + ccrUnfollowIndexResponseExample1: + $ref: "../../specification/ccr/unfollow/examples/response/UnfollowIndexResponseExample1.yaml" + - target: "$.paths['/_ccr/stats']['get']" + description: "Add examples for get ccr stats" + update: + responses: + 200: + content: + application/json: + examples: + ccrStatsResponseExample1: + $ref: "../../specification/ccr/stats/examples/response/CcrStatsResponseExample1.yaml" + - target: "$.paths['/_ccr/auto_follow/{name}/resume']['post']" + description: "Add examples for resume auto-follow pattern" + update: + responses: + 200: + content: + application/json: + examples: + ccrResumeAutoFollowResponseExample1: + $ref: "../../specification/ccr/resume_auto_follow_pattern/examples/response/ResumeAutoFollowPatternResponseExample1.yaml" + - target: "$.paths['/{index}/_ccr/pause_follow']['post']" + description: "Add examples for resume auto-follow pattern" + update: + responses: + 200: + content: + application/json: + examples: + ccrPauseFollowResponseExample1: + $ref: "../../specification/ccr/pause_follow/examples/response/PauseFollowIndexResponseExample1.yaml" + - target: "$.paths['/_ccr/auto_follow/{name}/pause']['post']" + description: "Add examples for pause auto-follow pattern" + update: + responses: + 200: + content: + application/json: + examples: + ccrPauseAutoFollowPatternResponseExample1: + $ref: "../../specification/ccr/pause_auto_follow_pattern/examples/response/PauseAutoFollowPatternResponseExample1.yaml" + - target: "$.components['responses']['ccr.get_auto_follow_pattern#200']" + description: "Add examples for get auto-follow pattern" + update: + content: + application/json: + examples: + ccrPauseAutoFollowPatternResponseExample1: + $ref: "../../specification/ccr/get_auto_follow_pattern/examples/response/GetAutoFollowPatternResponseExample1.yaml" + - target: "$.paths['/{index}/_ccr/stats']['get']" + description: "Add examples for get follower stats" + update: + responses: + 200: + content: + application/json: + examples: + ccrFollowerStatsResponseExample1: + $ref: "../../specification/ccr/follow_stats/examples/response/FollowIndexStatsResponseExample1.yaml" ## Examples for cluster - target: "$.components['requestBodies']['cluster.allocation_explain']" description: "Add examples for cluster allocation explain operation" @@ -496,14 +564,13 @@ actions: - target: "$.components['responses']['indices.resolve_cluster#200']" description: "Add examples for resolve cluster operation" update: - responses: - content: - application/json: - examples: - resolveClusterResponseExample1: - $ref: "../../specification/indices/resolve_cluster/examples/200_response/ResolveClusterResponseExample1.yaml" - resolveClusterResponseExample2: - $ref: "../../specification/indices/resolve_cluster/examples/200_response/ResolveClusterResponseExample2.yaml" + content: + application/json: + examples: + resolveClusterResponseExample1: + $ref: "../../specification/indices/resolve_cluster/examples/200_response/ResolveClusterResponseExample1.yaml" + resolveClusterResponseExample2: + $ref: "../../specification/indices/resolve_cluster/examples/200_response/ResolveClusterResponseExample2.yaml" - target: "$.components['requestBodies']['indices.shrink']" description: "Add example for shrink index request" update: diff --git a/output/openapi/elasticsearch-openapi.json b/output/openapi/elasticsearch-openapi.json index 795406fb12..4f256bf8dd 100644 --- a/output/openapi/elasticsearch-openapi.json +++ b/output/openapi/elasticsearch-openapi.json @@ -2819,7 +2819,7 @@ { "in": "path", "name": "index", - "description": "A comma-separated list of index patterns; use `_all` to perform the operation on all indices", + "description": "A comma-delimited list of index patterns.", "required": true, "deprecated": false, "schema": { @@ -2830,7 +2830,7 @@ { "in": "query", "name": "timeout", - "description": "Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error.", + "description": "The period to wait for a response.\nIf no response is received before the timeout expires, the request fails and returns an error.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:Duration" @@ -2847,6 +2847,7 @@ "type": "object", "properties": { "indices": { + "description": "An array of follower index statistics.", "type": "array", "items": { "$ref": "#/components/schemas/ccr._types:FollowIndexStats" @@ -2984,7 +2985,7 @@ { "in": "path", "name": "name", - "description": "The name of the auto follow pattern that should pause discovering new indices to follow.", + "description": "The name of the auto-follow pattern to pause.", "required": true, "deprecated": false, "schema": { @@ -2995,7 +2996,7 @@ { "in": "query", "name": "master_timeout", - "description": "Period to wait for a connection to the master node.", + "description": "The period to wait for a connection to the master node.\nIf the master node is not available before the timeout expires, the request fails and returns an error.\nIt can also be set to `-1` to indicate that the request should never timeout.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:Duration" @@ -3030,7 +3031,7 @@ { "in": "path", "name": "index", - "description": "The name of the follower index that should pause following its leader index.", + "description": "The name of the follower index.", "required": true, "deprecated": false, "schema": { @@ -3041,7 +3042,7 @@ { "in": "query", "name": "master_timeout", - "description": "Period to wait for a connection to the master node.", + "description": "The period to wait for a connection to the master node.\nIf the master node is not available before the timeout expires, the request fails and returns an error.\nIt can also be set to `-1` to indicate that the request should never timeout.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:Duration" @@ -3079,7 +3080,7 @@ { "in": "path", "name": "name", - "description": "The name of the auto follow pattern to resume discovering new indices to follow.", + "description": "The name of the auto-follow pattern to resume.", "required": true, "deprecated": false, "schema": { @@ -3090,7 +3091,7 @@ { "in": "query", "name": "master_timeout", - "description": "Period to wait for a connection to the master node.", + "description": "The period to wait for a connection to the master node.\nIf the master node is not available before the timeout expires, the request fails and returns an error.\nIt can also be set to `-1` to indicate that the request should never timeout.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:Duration" @@ -3215,7 +3216,7 @@ { "in": "query", "name": "master_timeout", - "description": "Period to wait for a connection to the master node.", + "description": "The period to wait for a connection to the master node.\nIf the master node is not available before the timeout expires, the request fails and returns an error.\nIt can also be set to `-1` to indicate that the request should never timeout.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:Duration" @@ -3225,7 +3226,7 @@ { "in": "query", "name": "timeout", - "description": "Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error.", + "description": "The period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:Duration" @@ -3266,7 +3267,7 @@ "ccr" ], "summary": "Unfollow an index", - "description": "Convert a cross-cluster replication follower index to a regular index.\nThe API stops the following task associated with a follower index and removes index metadata and settings associated with cross-cluster replication.\nThe follower index must be paused and closed before you call the unfollow API.\n\nNOTE: Currently cross-cluster replication does not support converting an existing regular index to a follower index. Converting a follower index to a regular index is an irreversible operation.", + "description": "Convert a cross-cluster replication follower index to a regular index.\nThe API stops the following task associated with a follower index and removes index metadata and settings associated with cross-cluster replication.\nThe follower index must be paused and closed before you call the unfollow API.\n\n> info\n> Currently cross-cluster replication does not support converting an existing regular index to a follower index. Converting a follower index to a regular index is an irreversible operation.", "externalDocs": { "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/xpack-ccr.html" }, @@ -3275,7 +3276,7 @@ { "in": "path", "name": "index", - "description": "The name of the follower index that should be turned into a regular index.", + "description": "The name of the follower index.", "required": true, "deprecated": false, "schema": { @@ -3286,7 +3287,7 @@ { "in": "query", "name": "master_timeout", - "description": "Period to wait for a connection to the master node.", + "description": "The period to wait for a connection to the master node.\nIf the master node is not available before the timeout expires, the request fails and returns an error.\nIt can also be set to `-1` to indicate that the request should never timeout.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:Duration" @@ -61991,6 +61992,7 @@ "$ref": "#/components/schemas/_types:IndexName" }, "shards": { + "description": "An array of shard-level following task statistics.", "type": "array", "items": { "$ref": "#/components/schemas/ccr._types:ShardStats" @@ -62006,12 +62008,15 @@ "type": "object", "properties": { "bytes_read": { + "description": "The total of transferred bytes read from the leader.\nThis is only an estimate and does not account for compression if enabled.", "type": "number" }, "failed_read_requests": { + "description": "The number of failed reads.", "type": "number" }, "failed_write_requests": { + "description": "The number of failed bulk write requests on the follower.", "type": "number" }, "fatal_exception": { @@ -62021,9 +62026,11 @@ "$ref": "#/components/schemas/_types:VersionNumber" }, "follower_global_checkpoint": { + "description": "The current global checkpoint on the follower.\nThe difference between the `leader_global_checkpoint` and the `follower_global_checkpoint` is an indication of how much the follower is lagging the leader.", "type": "number" }, "follower_index": { + "description": "The name of the follower index.", "type": "string" }, "follower_mapping_version": { @@ -62039,42 +62046,53 @@ "$ref": "#/components/schemas/_types:SequenceNumber" }, "leader_global_checkpoint": { + "description": "The current global checkpoint on the leader known to the follower task.", "type": "number" }, "leader_index": { + "description": "The name of the index in the leader cluster being followed.", "type": "string" }, "leader_max_seq_no": { "$ref": "#/components/schemas/_types:SequenceNumber" }, "operations_read": { + "description": "The total number of operations read from the leader.", "type": "number" }, "operations_written": { + "description": "The number of operations written on the follower.", "type": "number" }, "outstanding_read_requests": { + "description": "The number of active read requests from the follower.", "type": "number" }, "outstanding_write_requests": { + "description": "The number of active bulk write requests on the follower.", "type": "number" }, "read_exceptions": { + "description": "An array of objects representing failed reads.", "type": "array", "items": { "$ref": "#/components/schemas/ccr._types:ReadException" } }, "remote_cluster": { + "description": "The remote cluster containing the leader index.", "type": "string" }, "shard_id": { + "description": "The numerical shard ID, with values from 0 to one less than the number of replicas.", "type": "number" }, "successful_read_requests": { + "description": "The number of successful fetches.", "type": "number" }, "successful_write_requests": { + "description": "The number of bulk write requests run on the follower.", "type": "number" }, "time_since_last_read": { @@ -62102,6 +62120,7 @@ "$ref": "#/components/schemas/_types:DurationValueUnitMillis" }, "write_buffer_operation_count": { + "description": "The number of write operations queued on the follower.", "type": "number" }, "write_buffer_size_in_bytes": { @@ -62149,6 +62168,7 @@ "$ref": "#/components/schemas/_types:SequenceNumber" }, "retries": { + "description": "The number of times the batch has been retried.", "type": "number" } }, @@ -62224,15 +62244,19 @@ } }, "number_of_failed_follow_indices": { + "description": "The number of indices that the auto-follow coordinator failed to automatically follow.\nThe causes of recent failures are captured in the logs of the elected master node and in the `auto_follow_stats.recent_auto_follow_errors` field.", "type": "number" }, "number_of_failed_remote_cluster_state_requests": { + "description": "The number of times that the auto-follow coordinator failed to retrieve the cluster state from a remote cluster registered in a collection of auto-follow patterns.", "type": "number" }, "number_of_successful_follow_indices": { + "description": "The number of indices that the auto-follow coordinator successfully followed.", "type": "number" }, "recent_auto_follow_errors": { + "description": "An array of objects representing failures by the auto-follow coordinator.", "type": "array", "items": { "$ref": "#/components/schemas/_types:ErrorCause" @@ -99480,7 +99504,7 @@ "ccr.get_auto_follow_pattern#name": { "in": "path", "name": "name", - "description": "Specifies the auto-follow pattern collection that you want to retrieve. If you do not specify a name, the API returns information for all collections.", + "description": "The auto-follow pattern collection that you want to retrieve.\nIf you do not specify a name, the API returns information for all collections.", "required": true, "deprecated": false, "schema": { @@ -99491,7 +99515,7 @@ "ccr.get_auto_follow_pattern#master_timeout": { "in": "query", "name": "master_timeout", - "description": "Period to wait for a connection to the master node.", + "description": "The period to wait for a connection to the master node.\nIf the master node is not available before the timeout expires, the request fails and returns an error.\nIt can also be set to `-1` to indicate that the request should never timeout.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:Duration" diff --git a/output/schema/schema.json b/output/schema/schema.json index 3917103c29..1a0df1b9c3 100644 --- a/output/schema/schema.json +++ b/output/schema/schema.json @@ -1822,12 +1822,17 @@ "stability": "stable" } }, - "description": "Get follower stats.\nGet cross-cluster replication follower stats.\nThe API returns shard-level stats about the \"following tasks\" associated with each shard for the specified indices.", + "description": "Get follower stats.\n\nGet cross-cluster replication follower stats.\nThe API returns shard-level stats about the \"following tasks\" associated with each shard for the specified indices.", "docId": "ccr-get-follow-stats", "docUrl": "https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-ccr-follow-stats", "extDocId": "ccr", "extDocUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/current/xpack-ccr.html", "name": "ccr.follow_stats", + "privileges": { + "cluster": [ + "monitor" + ] + }, "request": { "name": "Request", "namespace": "ccr.follow_stats" @@ -1893,12 +1898,17 @@ "stability": "stable" } }, - "description": "Get auto-follow patterns.\nGet cross-cluster replication auto-follow patterns.", + "description": "Get auto-follow patterns.\n\nGet cross-cluster replication auto-follow patterns.", "docId": "ccr-get-auto-follow-pattern", "docUrl": "https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-ccr-get-auto-follow-pattern-1", "extDocId": "ccr-auto-follow", "extDocUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/current/ccr-auto-follow.html", "name": "ccr.get_auto_follow_pattern", + "privileges": { + "cluster": [ + "manage_ccr" + ] + }, "request": { "name": "Request", "namespace": "ccr.get_auto_follow_pattern" @@ -1933,12 +1943,17 @@ "stability": "stable" } }, - "description": "Pause an auto-follow pattern.\nPause a cross-cluster replication auto-follow pattern.\nWhen the API returns, the auto-follow pattern is inactive.\nNew indices that are created on the remote cluster and match the auto-follow patterns are ignored.\n\nYou can resume auto-following with the resume auto-follow pattern API.\nWhen it resumes, the auto-follow pattern is active again and automatically configures follower indices for newly created indices on the remote cluster that match its patterns.\nRemote indices that were created while the pattern was paused will also be followed, unless they have been deleted or closed in the interim.", + "description": "Pause an auto-follow pattern.\n\nPause a cross-cluster replication auto-follow pattern.\nWhen the API returns, the auto-follow pattern is inactive.\nNew indices that are created on the remote cluster and match the auto-follow patterns are ignored.\n\nYou can resume auto-following with the resume auto-follow pattern API.\nWhen it resumes, the auto-follow pattern is active again and automatically configures follower indices for newly created indices on the remote cluster that match its patterns.\nRemote indices that were created while the pattern was paused will also be followed, unless they have been deleted or closed in the interim.", "docId": "ccr-pause-auto-follow-pattern", "docUrl": "https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-ccr-pause-auto-follow-pattern", "extDocId": "ccr-auto-follow", "extDocUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/current/ccr-auto-follow.html", "name": "ccr.pause_auto_follow_pattern", + "privileges": { + "cluster": [ + "manage_ccr" + ] + }, "request": { "name": "Request", "namespace": "ccr.pause_auto_follow_pattern" @@ -1967,10 +1982,15 @@ "stability": "stable" } }, - "description": "Pause a follower.\nPause a cross-cluster replication follower index.\nThe follower index will not fetch any additional operations from the leader index.\nYou can resume following with the resume follower API.\nYou can pause and resume a follower index to change the configuration of the following task.", + "description": "Pause a follower.\n\nPause a cross-cluster replication follower index.\nThe follower index will not fetch any additional operations from the leader index.\nYou can resume following with the resume follower API.\nYou can pause and resume a follower index to change the configuration of the following task.", "docId": "ccr-post-pause-follow", "docUrl": "https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-ccr-pause-follow", "name": "ccr.pause_follow", + "privileges": { + "cluster": [ + "manage_ccr" + ] + }, "request": { "name": "Request", "namespace": "ccr.pause_follow" @@ -2036,12 +2056,17 @@ "stability": "stable" } }, - "description": "Resume an auto-follow pattern.\nResume a cross-cluster replication auto-follow pattern that was paused.\nThe auto-follow pattern will resume configuring following indices for newly created indices that match its patterns on the remote cluster.\nRemote indices created while the pattern was paused will also be followed unless they have been deleted or closed in the interim.", + "description": "Resume an auto-follow pattern.\n\nResume a cross-cluster replication auto-follow pattern that was paused.\nThe auto-follow pattern will resume configuring following indices for newly created indices that match its patterns on the remote cluster.\nRemote indices created while the pattern was paused will also be followed unless they have been deleted or closed in the interim.", "docId": "ccr-resume-auto-follow-pattern", "docUrl": "https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-ccr-resume-auto-follow-pattern", "extDocId": "ccr-auto-follow", "extDocUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/current/ccr-auto-follow.html", "name": "ccr.resume_auto_follow_pattern", + "privileges": { + "cluster": [ + "manage_ccr" + ] + }, "request": { "name": "Request", "namespace": "ccr.resume_auto_follow_pattern" @@ -2107,10 +2132,15 @@ "stability": "stable" } }, - "description": "Get cross-cluster replication stats.\nThis API returns stats about auto-following and the same shard-level stats as the get follower stats API.", + "description": "Get cross-cluster replication stats.\n\nThis API returns stats about auto-following and the same shard-level stats as the get follower stats API.", "docId": "ccr-get-stats", "docUrl": "https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-ccr-stats", "name": "ccr.stats", + "privileges": { + "cluster": [ + "monitor" + ] + }, "request": { "name": "Request", "namespace": "ccr.stats" @@ -2139,12 +2169,17 @@ "stability": "stable" } }, - "description": "Unfollow an index.\nConvert a cross-cluster replication follower index to a regular index.\nThe API stops the following task associated with a follower index and removes index metadata and settings associated with cross-cluster replication.\nThe follower index must be paused and closed before you call the unfollow API.\n\nNOTE: Currently cross-cluster replication does not support converting an existing regular index to a follower index. Converting a follower index to a regular index is an irreversible operation.", + "description": "Unfollow an index.\n\nConvert a cross-cluster replication follower index to a regular index.\nThe API stops the following task associated with a follower index and removes index metadata and settings associated with cross-cluster replication.\nThe follower index must be paused and closed before you call the unfollow API.\n\n> info\n> Currently cross-cluster replication does not support converting an existing regular index to a follower index. Converting a follower index to a regular index is an irreversible operation.", "docId": "ccr-post-unfollow", "docUrl": "https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-ccr-unfollow", "extDocId": "ccr", "extDocUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/current/xpack-ccr.html", "name": "ccr.unfollow", + "privileges": { + "index": [ + "manage_follow_index" + ] + }, "request": { "name": "Request", "namespace": "ccr.unfollow" @@ -105719,6 +105754,7 @@ }, "properties": [ { + "description": "The name of the follower index.", "name": "index", "required": true, "type": { @@ -105730,6 +105766,7 @@ } }, { + "description": "An array of shard-level following task statistics.", "name": "shards", "required": true, "type": { @@ -105744,7 +105781,7 @@ } } ], - "specLocation": "ccr/_types/FollowIndexStats.ts#L30-L33" + "specLocation": "ccr/_types/FollowIndexStats.ts#L30-L35" }, { "kind": "interface", @@ -105754,6 +105791,7 @@ }, "properties": [ { + "description": "The exception that caused the read to fail.", "name": "exception", "required": true, "type": { @@ -105765,6 +105803,7 @@ } }, { + "description": "The starting sequence number of the batch requested from the leader.", "name": "from_seq_no", "required": true, "type": { @@ -105776,6 +105815,7 @@ } }, { + "description": "The number of times the batch has been retried.", "name": "retries", "required": true, "type": { @@ -105787,7 +105827,7 @@ } } ], - "specLocation": "ccr/_types/FollowIndexStats.ts#L71-L75" + "specLocation": "ccr/_types/FollowIndexStats.ts#L111-L118" }, { "kind": "interface", @@ -105797,6 +105837,7 @@ }, "properties": [ { + "description": "The total of transferred bytes read from the leader.\nThis is only an estimate and does not account for compression if enabled.", "name": "bytes_read", "required": true, "type": { @@ -105808,6 +105849,7 @@ } }, { + "description": "The number of failed reads.", "name": "failed_read_requests", "required": true, "type": { @@ -105819,6 +105861,7 @@ } }, { + "description": "The number of failed bulk write requests on the follower.", "name": "failed_write_requests", "required": true, "type": { @@ -105841,6 +105884,7 @@ } }, { + "description": "The index aliases version the follower is synced up to.", "name": "follower_aliases_version", "required": true, "type": { @@ -105852,6 +105896,7 @@ } }, { + "description": "The current global checkpoint on the follower.\nThe difference between the `leader_global_checkpoint` and the `follower_global_checkpoint` is an indication of how much the follower is lagging the leader.", "name": "follower_global_checkpoint", "required": true, "type": { @@ -105863,6 +105908,7 @@ } }, { + "description": "The name of the follower index.", "name": "follower_index", "required": true, "type": { @@ -105874,6 +105920,7 @@ } }, { + "description": "The mapping version the follower is synced up to.", "name": "follower_mapping_version", "required": true, "type": { @@ -105885,6 +105932,7 @@ } }, { + "description": "The current maximum sequence number on the follower.", "name": "follower_max_seq_no", "required": true, "type": { @@ -105896,6 +105944,7 @@ } }, { + "description": "The index settings version the follower is synced up to.", "name": "follower_settings_version", "required": true, "type": { @@ -105907,6 +105956,7 @@ } }, { + "description": "The starting sequence number of the last batch of operations requested from the leader.", "name": "last_requested_seq_no", "required": true, "type": { @@ -105918,6 +105968,7 @@ } }, { + "description": "The current global checkpoint on the leader known to the follower task.", "name": "leader_global_checkpoint", "required": true, "type": { @@ -105929,6 +105980,7 @@ } }, { + "description": "The name of the index in the leader cluster being followed.", "name": "leader_index", "required": true, "type": { @@ -105940,6 +105992,7 @@ } }, { + "description": "The current maximum sequence number on the leader known to the follower task.", "name": "leader_max_seq_no", "required": true, "type": { @@ -105951,6 +106004,7 @@ } }, { + "description": "The total number of operations read from the leader.", "name": "operations_read", "required": true, "type": { @@ -105962,6 +106016,7 @@ } }, { + "description": "The number of operations written on the follower.", "name": "operations_written", "required": true, "type": { @@ -105973,6 +106028,7 @@ } }, { + "description": "The number of active read requests from the follower.", "name": "outstanding_read_requests", "required": true, "type": { @@ -105984,6 +106040,7 @@ } }, { + "description": "The number of active bulk write requests on the follower.", "name": "outstanding_write_requests", "required": true, "type": { @@ -105995,6 +106052,7 @@ } }, { + "description": "An array of objects representing failed reads.", "name": "read_exceptions", "required": true, "type": { @@ -106009,6 +106067,7 @@ } }, { + "description": "The remote cluster containing the leader index.", "name": "remote_cluster", "required": true, "type": { @@ -106020,6 +106079,7 @@ } }, { + "description": "The numerical shard ID, with values from 0 to one less than the number of replicas.", "name": "shard_id", "required": true, "type": { @@ -106031,6 +106091,7 @@ } }, { + "description": "The number of successful fetches.", "name": "successful_read_requests", "required": true, "type": { @@ -106042,6 +106103,7 @@ } }, { + "description": "The number of bulk write requests run on the follower.", "name": "successful_write_requests", "required": true, "type": { @@ -106064,6 +106126,7 @@ } }, { + "description": "The number of milliseconds since a read request was sent to the leader.\nWhen the follower is caught up to the leader, this number will increase up to the configured `read_poll_timeout` at which point another read request will be sent to the leader.", "name": "time_since_last_read_millis", "required": true, "type": { @@ -106095,6 +106158,7 @@ } }, { + "description": "The total time reads spent running on the remote cluster.", "name": "total_read_remote_exec_time_millis", "required": true, "type": { @@ -106126,6 +106190,7 @@ } }, { + "description": "The total time reads were outstanding, measured from the time a read was sent to the leader to the time a reply was returned to the follower.", "name": "total_read_time_millis", "required": true, "type": { @@ -106157,6 +106222,7 @@ } }, { + "description": "The total time spent writing on the follower.", "name": "total_write_time_millis", "required": true, "type": { @@ -106177,6 +106243,7 @@ } }, { + "description": "The number of write operations queued on the follower.", "name": "write_buffer_operation_count", "required": true, "type": { @@ -106188,6 +106255,7 @@ } }, { + "description": "The total number of bytes of operations currently queued for writing.", "name": "write_buffer_size_in_bytes", "required": true, "type": { @@ -106199,7 +106267,7 @@ } } ], - "specLocation": "ccr/_types/FollowIndexStats.ts#L35-L69" + "specLocation": "ccr/_types/FollowIndexStats.ts#L37-L109" }, { "kind": "request", @@ -106843,7 +106911,7 @@ "body": { "kind": "no_body" }, - "description": "Get follower stats.\nGet cross-cluster replication follower stats.\nThe API returns shard-level stats about the \"following tasks\" associated with each shard for the specified indices.", + "description": "Get follower stats.\n\nGet cross-cluster replication follower stats.\nThe API returns shard-level stats about the \"following tasks\" associated with each shard for the specified indices.", "inherits": { "type": { "name": "RequestBase", @@ -106856,7 +106924,7 @@ }, "path": [ { - "description": "A comma-separated list of index patterns; use `_all` to perform the operation on all indices", + "description": "A comma-delimited list of index patterns.", "name": "index", "required": true, "type": { @@ -106870,7 +106938,7 @@ ], "query": [ { - "description": "Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error.", + "description": "The period to wait for a response.\nIf no response is received before the timeout expires, the request fails and returns an error.", "name": "timeout", "required": false, "serverDefault": "30s", @@ -106883,7 +106951,7 @@ } } ], - "specLocation": "ccr/follow_stats/FollowIndexStatsRequest.ts#L24-L50" + "specLocation": "ccr/follow_stats/FollowIndexStatsRequest.ts#L24-L54" }, { "kind": "response", @@ -106891,6 +106959,7 @@ "kind": "properties", "properties": [ { + "description": "An array of follower index statistics.", "name": "indices", "required": true, "type": { @@ -106910,7 +106979,7 @@ "name": "Response", "namespace": "ccr.follow_stats" }, - "specLocation": "ccr/follow_stats/FollowIndexStatsResponse.ts#L22-L24" + "specLocation": "ccr/follow_stats/FollowIndexStatsResponse.ts#L22-L27" }, { "kind": "request", @@ -107159,7 +107228,7 @@ "body": { "kind": "no_body" }, - "description": "Get auto-follow patterns.\nGet cross-cluster replication auto-follow patterns.", + "description": "Get auto-follow patterns.\n\nGet cross-cluster replication auto-follow patterns.", "inherits": { "type": { "name": "RequestBase", @@ -107172,7 +107241,7 @@ }, "path": [ { - "description": "Specifies the auto-follow pattern collection that you want to retrieve. If you do not specify a name, the API returns information for all collections.", + "description": "The auto-follow pattern collection that you want to retrieve.\nIf you do not specify a name, the API returns information for all collections.", "name": "name", "required": false, "type": { @@ -107186,7 +107255,7 @@ ], "query": [ { - "description": "Period to wait for a connection to the master node.", + "description": "The period to wait for a connection to the master node.\nIf the master node is not available before the timeout expires, the request fails and returns an error.\nIt can also be set to `-1` to indicate that the request should never timeout.", "name": "master_timeout", "required": false, "serverDefault": "30s", @@ -107199,7 +107268,7 @@ } } ], - "specLocation": "ccr/get_auto_follow_pattern/GetAutoFollowPatternRequest.ts#L24-L54" + "specLocation": "ccr/get_auto_follow_pattern/GetAutoFollowPatternRequest.ts#L24-L60" }, { "kind": "response", @@ -107236,7 +107305,7 @@ "body": { "kind": "no_body" }, - "description": "Pause an auto-follow pattern.\nPause a cross-cluster replication auto-follow pattern.\nWhen the API returns, the auto-follow pattern is inactive.\nNew indices that are created on the remote cluster and match the auto-follow patterns are ignored.\n\nYou can resume auto-following with the resume auto-follow pattern API.\nWhen it resumes, the auto-follow pattern is active again and automatically configures follower indices for newly created indices on the remote cluster that match its patterns.\nRemote indices that were created while the pattern was paused will also be followed, unless they have been deleted or closed in the interim.", + "description": "Pause an auto-follow pattern.\n\nPause a cross-cluster replication auto-follow pattern.\nWhen the API returns, the auto-follow pattern is inactive.\nNew indices that are created on the remote cluster and match the auto-follow patterns are ignored.\n\nYou can resume auto-following with the resume auto-follow pattern API.\nWhen it resumes, the auto-follow pattern is active again and automatically configures follower indices for newly created indices on the remote cluster that match its patterns.\nRemote indices that were created while the pattern was paused will also be followed, unless they have been deleted or closed in the interim.", "inherits": { "type": { "name": "RequestBase", @@ -107249,7 +107318,7 @@ }, "path": [ { - "description": "The name of the auto follow pattern that should pause discovering new indices to follow.", + "description": "The name of the auto-follow pattern to pause.", "name": "name", "required": true, "type": { @@ -107263,7 +107332,7 @@ ], "query": [ { - "description": "Period to wait for a connection to the master node.", + "description": "The period to wait for a connection to the master node.\nIf the master node is not available before the timeout expires, the request fails and returns an error.\nIt can also be set to `-1` to indicate that the request should never timeout.", "name": "master_timeout", "required": false, "serverDefault": "30s", @@ -107276,7 +107345,7 @@ } } ], - "specLocation": "ccr/pause_auto_follow_pattern/PauseAutoFollowPatternRequest.ts#L24-L55" + "specLocation": "ccr/pause_auto_follow_pattern/PauseAutoFollowPatternRequest.ts#L24-L60" }, { "kind": "response", @@ -107304,7 +107373,7 @@ "body": { "kind": "no_body" }, - "description": "Pause a follower.\nPause a cross-cluster replication follower index.\nThe follower index will not fetch any additional operations from the leader index.\nYou can resume following with the resume follower API.\nYou can pause and resume a follower index to change the configuration of the following task.", + "description": "Pause a follower.\n\nPause a cross-cluster replication follower index.\nThe follower index will not fetch any additional operations from the leader index.\nYou can resume following with the resume follower API.\nYou can pause and resume a follower index to change the configuration of the following task.", "inherits": { "type": { "name": "RequestBase", @@ -107317,7 +107386,7 @@ }, "path": [ { - "description": "The name of the follower index that should pause following its leader index.", + "description": "The name of the follower index.", "name": "index", "required": true, "type": { @@ -107331,7 +107400,7 @@ ], "query": [ { - "description": "Period to wait for a connection to the master node.", + "description": "The period to wait for a connection to the master node.\nIf the master node is not available before the timeout expires, the request fails and returns an error.\nIt can also be set to `-1` to indicate that the request should never timeout.", "name": "master_timeout", "required": false, "serverDefault": "30s", @@ -107344,7 +107413,7 @@ } } ], - "specLocation": "ccr/pause_follow/PauseFollowIndexRequest.ts#L24-L51" + "specLocation": "ccr/pause_follow/PauseFollowIndexRequest.ts#L24-L56" }, { "kind": "response", @@ -107641,7 +107710,7 @@ "body": { "kind": "no_body" }, - "description": "Resume an auto-follow pattern.\nResume a cross-cluster replication auto-follow pattern that was paused.\nThe auto-follow pattern will resume configuring following indices for newly created indices that match its patterns on the remote cluster.\nRemote indices created while the pattern was paused will also be followed unless they have been deleted or closed in the interim.", + "description": "Resume an auto-follow pattern.\n\nResume a cross-cluster replication auto-follow pattern that was paused.\nThe auto-follow pattern will resume configuring following indices for newly created indices that match its patterns on the remote cluster.\nRemote indices created while the pattern was paused will also be followed unless they have been deleted or closed in the interim.", "inherits": { "type": { "name": "RequestBase", @@ -107654,7 +107723,7 @@ }, "path": [ { - "description": "The name of the auto follow pattern to resume discovering new indices to follow.", + "description": "The name of the auto-follow pattern to resume.", "name": "name", "required": true, "type": { @@ -107668,7 +107737,7 @@ ], "query": [ { - "description": "Period to wait for a connection to the master node.", + "description": "The period to wait for a connection to the master node.\nIf the master node is not available before the timeout expires, the request fails and returns an error.\nIt can also be set to `-1` to indicate that the request should never timeout.", "name": "master_timeout", "required": false, "serverDefault": "30s", @@ -107681,7 +107750,7 @@ } } ], - "specLocation": "ccr/resume_auto_follow_pattern/ResumeAutoFollowPatternRequest.ts#L24-L51" + "specLocation": "ccr/resume_auto_follow_pattern/ResumeAutoFollowPatternRequest.ts#L24-L56" }, { "kind": "response", @@ -107903,6 +107972,7 @@ } }, { + "description": "The number of indices that the auto-follow coordinator failed to automatically follow.\nThe causes of recent failures are captured in the logs of the elected master node and in the `auto_follow_stats.recent_auto_follow_errors` field.", "name": "number_of_failed_follow_indices", "required": true, "type": { @@ -107914,6 +107984,7 @@ } }, { + "description": "The number of times that the auto-follow coordinator failed to retrieve the cluster state from a remote cluster registered in a collection of auto-follow patterns.", "name": "number_of_failed_remote_cluster_state_requests", "required": true, "type": { @@ -107925,6 +107996,7 @@ } }, { + "description": "The number of indices that the auto-follow coordinator successfully followed.", "name": "number_of_successful_follow_indices", "required": true, "type": { @@ -107936,6 +108008,7 @@ } }, { + "description": "An array of objects representing failures by the auto-follow coordinator.", "name": "recent_auto_follow_errors", "required": true, "type": { @@ -107950,7 +108023,7 @@ } } ], - "specLocation": "ccr/stats/types.ts.ts#L32-L38" + "specLocation": "ccr/stats/types.ts.ts#L32-L47" }, { "kind": "interface", @@ -108026,7 +108099,7 @@ } } ], - "specLocation": "ccr/stats/types.ts.ts#L40-L42" + "specLocation": "ccr/stats/types.ts.ts#L49-L51" }, { "kind": "request", @@ -108036,7 +108109,7 @@ "body": { "kind": "no_body" }, - "description": "Get cross-cluster replication stats.\nThis API returns stats about auto-following and the same shard-level stats as the get follower stats API.", + "description": "Get cross-cluster replication stats.\n\nThis API returns stats about auto-following and the same shard-level stats as the get follower stats API.", "inherits": { "type": { "name": "RequestBase", @@ -108050,7 +108123,7 @@ "path": [], "query": [ { - "description": "Period to wait for a connection to the master node.", + "description": "The period to wait for a connection to the master node.\nIf the master node is not available before the timeout expires, the request fails and returns an error.\nIt can also be set to `-1` to indicate that the request should never timeout.", "name": "master_timeout", "required": false, "serverDefault": "30s", @@ -108063,7 +108136,7 @@ } }, { - "description": "Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error.", + "description": "The period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error.", "name": "timeout", "required": false, "serverDefault": "30s", @@ -108076,7 +108149,7 @@ } } ], - "specLocation": "ccr/stats/CcrStatsRequest.ts#L23-L49" + "specLocation": "ccr/stats/CcrStatsRequest.ts#L23-L53" }, { "kind": "response", @@ -108084,6 +108157,7 @@ "kind": "properties", "properties": [ { + "description": "Statistics for the auto-follow coordinator.", "name": "auto_follow_stats", "required": true, "type": { @@ -108095,6 +108169,7 @@ } }, { + "description": "Shard-level statistics for follower indices.", "name": "follow_stats", "required": true, "type": { @@ -108111,7 +108186,7 @@ "name": "Response", "namespace": "ccr.stats" }, - "specLocation": "ccr/stats/CcrStatsResponse.ts#L22-L27" + "specLocation": "ccr/stats/CcrStatsResponse.ts#L22-L29" }, { "kind": "request", @@ -108121,7 +108196,7 @@ "body": { "kind": "no_body" }, - "description": "Unfollow an index.\nConvert a cross-cluster replication follower index to a regular index.\nThe API stops the following task associated with a follower index and removes index metadata and settings associated with cross-cluster replication.\nThe follower index must be paused and closed before you call the unfollow API.\n\nNOTE: Currently cross-cluster replication does not support converting an existing regular index to a follower index. Converting a follower index to a regular index is an irreversible operation.", + "description": "Unfollow an index.\n\nConvert a cross-cluster replication follower index to a regular index.\nThe API stops the following task associated with a follower index and removes index metadata and settings associated with cross-cluster replication.\nThe follower index must be paused and closed before you call the unfollow API.\n\n> info\n> Currently cross-cluster replication does not support converting an existing regular index to a follower index. Converting a follower index to a regular index is an irreversible operation.", "inherits": { "type": { "name": "RequestBase", @@ -108134,7 +108209,7 @@ }, "path": [ { - "description": "The name of the follower index that should be turned into a regular index.", + "description": "The name of the follower index.", "name": "index", "required": true, "type": { @@ -108148,7 +108223,7 @@ ], "query": [ { - "description": "Period to wait for a connection to the master node.", + "description": "The period to wait for a connection to the master node.\nIf the master node is not available before the timeout expires, the request fails and returns an error.\nIt can also be set to `-1` to indicate that the request should never timeout.", "name": "master_timeout", "required": false, "serverDefault": "30s", @@ -108161,7 +108236,7 @@ } } ], - "specLocation": "ccr/unfollow/UnfollowIndexRequest.ts#L24-L53" + "specLocation": "ccr/unfollow/UnfollowIndexRequest.ts#L24-L59" }, { "kind": "response", diff --git a/specification/ccr/_types/FollowIndexStats.ts b/specification/ccr/_types/FollowIndexStats.ts index d923c23a84..0e0b992b0d 100644 --- a/specification/ccr/_types/FollowIndexStats.ts +++ b/specification/ccr/_types/FollowIndexStats.ts @@ -28,48 +28,91 @@ import { integer, long } from '@_types/Numeric' import { Duration, DurationValue, UnitMillis } from '@_types/Time' export class FollowIndexStats { + /** The name of the follower index. */ index: IndexName + /** An array of shard-level following task statistics. */ shards: ShardStats[] } export class ShardStats { + /** + * The total of transferred bytes read from the leader. + * This is only an estimate and does not account for compression if enabled. + */ bytes_read: long + /** The number of failed reads. */ failed_read_requests: long + /** The number of failed bulk write requests on the follower. */ failed_write_requests: long fatal_exception?: ErrorCause + /** The index aliases version the follower is synced up to. */ follower_aliases_version: VersionNumber + /** + * The current global checkpoint on the follower. + * The difference between the `leader_global_checkpoint` and the `follower_global_checkpoint` is an indication of how much the follower is lagging the leader. + */ follower_global_checkpoint: long + /** The name of the follower index. */ follower_index: string + /** The mapping version the follower is synced up to. */ follower_mapping_version: VersionNumber + /** The current maximum sequence number on the follower. */ follower_max_seq_no: SequenceNumber + /** The index settings version the follower is synced up to. */ follower_settings_version: VersionNumber + /** The starting sequence number of the last batch of operations requested from the leader. */ last_requested_seq_no: SequenceNumber + /** The current global checkpoint on the leader known to the follower task. */ leader_global_checkpoint: long + /** The name of the index in the leader cluster being followed. */ leader_index: string + /** The current maximum sequence number on the leader known to the follower task. */ leader_max_seq_no: SequenceNumber + /** The total number of operations read from the leader. */ operations_read: long + /** The number of operations written on the follower. */ operations_written: long + /** The number of active read requests from the follower. */ outstanding_read_requests: integer + /** The number of active bulk write requests on the follower. */ outstanding_write_requests: integer + /** An array of objects representing failed reads. */ read_exceptions: ReadException[] + /** The remote cluster containing the leader index. */ remote_cluster: string + /** The numerical shard ID, with values from 0 to one less than the number of replicas. */ shard_id: integer + /** The number of successful fetches. */ successful_read_requests: long + /** The number of bulk write requests run on the follower.*/ successful_write_requests: long time_since_last_read?: Duration + /** The number of milliseconds since a read request was sent to the leader. + * When the follower is caught up to the leader, this number will increase up to the configured `read_poll_timeout` at which point another read request will be sent to the leader. + */ time_since_last_read_millis: DurationValue total_read_remote_exec_time?: Duration + /** The total time reads spent running on the remote cluster. */ total_read_remote_exec_time_millis: DurationValue total_read_time?: Duration + /** + * The total time reads were outstanding, measured from the time a read was sent to the leader to the time a reply was returned to the follower. + */ total_read_time_millis: DurationValue total_write_time?: Duration + /** The total time spent writing on the follower. */ total_write_time_millis: DurationValue + /** The number of write operations queued on the follower. */ write_buffer_operation_count: long + /** The total number of bytes of operations currently queued for writing. */ write_buffer_size_in_bytes: ByteSize } export class ReadException { + /** The exception that caused the read to fail. */ exception: ErrorCause + /** The starting sequence number of the batch requested from the leader. */ from_seq_no: SequenceNumber + /** The number of times the batch has been retried. */ retries: integer } diff --git a/specification/ccr/follow_stats/FollowIndexStatsRequest.ts b/specification/ccr/follow_stats/FollowIndexStatsRequest.ts index 64909205ab..420ee63a34 100644 --- a/specification/ccr/follow_stats/FollowIndexStatsRequest.ts +++ b/specification/ccr/follow_stats/FollowIndexStatsRequest.ts @@ -23,10 +23,12 @@ import { Duration } from '@_types/Time' /** * Get follower stats. + * * Get cross-cluster replication follower stats. * The API returns shard-level stats about the "following tasks" associated with each shard for the specified indices. * @rest_spec_name ccr.follow_stats * @availability stack since=6.5.0 stability=stable + * @cluster_privileges monitor * @doc_id ccr-get-follow-stats * @ext_doc_id ccr */ @@ -38,11 +40,13 @@ export interface Request extends RequestBase { } ] path_parts: { + /** A comma-delimited list of index patterns. */ index: Indices } query_parameters: { /** - * Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error. + * The period to wait for a response. + * If no response is received before the timeout expires, the request fails and returns an error. * @server_default 30s */ timeout?: Duration diff --git a/specification/ccr/follow_stats/FollowIndexStatsResponse.ts b/specification/ccr/follow_stats/FollowIndexStatsResponse.ts index 3e0a710838..a25b796ca8 100644 --- a/specification/ccr/follow_stats/FollowIndexStatsResponse.ts +++ b/specification/ccr/follow_stats/FollowIndexStatsResponse.ts @@ -20,5 +20,8 @@ import { FollowIndexStats } from '@ccr/_types/FollowIndexStats' export class Response { - body: { indices: FollowIndexStats[] } + body: { + /** An array of follower index statistics. */ + indices: FollowIndexStats[] + } } diff --git a/specification/ccr/follow_stats/ccrApisFollowGetFollowStatsResponseExample1.json b/specification/ccr/follow_stats/ccrApisFollowGetFollowStatsResponseExample1.json deleted file mode 100644 index 84c2f738fe..0000000000 --- a/specification/ccr/follow_stats/ccrApisFollowGetFollowStatsResponseExample1.json +++ /dev/null @@ -1,7 +0,0 @@ -{ - "summary": "A successful response for retrieving follower stats.", - "description": "", - "type": "response", - "response_code": 200, - "value": "{\n \"indices\" : [\n {\n \"index\" : \"follower_index\",\n \"total_global_checkpoint_lag\" : 256,\n \"shards\" : [\n {\n \"remote_cluster\" : \"remote_cluster\",\n \"leader_index\" : \"leader_index\",\n \"follower_index\" : \"follower_index\",\n \"shard_id\" : 0,\n \"leader_global_checkpoint\" : 1024,\n \"leader_max_seq_no\" : 1536,\n \"follower_global_checkpoint\" : 768,\n \"follower_max_seq_no\" : 896,\n \"last_requested_seq_no\" : 897,\n \"outstanding_read_requests\" : 8,\n \"outstanding_write_requests\" : 2,\n \"write_buffer_operation_count\" : 64,\n \"follower_mapping_version\" : 4,\n \"follower_settings_version\" : 2,\n \"follower_aliases_version\" : 8,\n \"total_read_time_millis\" : 32768,\n \"total_read_remote_exec_time_millis\" : 16384,\n \"successful_read_requests\" : 32,\n \"failed_read_requests\" : 0,\n \"operations_read\" : 896,\n \"bytes_read\" : 32768,\n \"total_write_time_millis\" : 16384,\n \"write_buffer_size_in_bytes\" : 1536,\n \"successful_write_requests\" : 16,\n \"failed_write_requests\" : 0,\n \"operations_written\" : 832,\n \"read_exceptions\" : [ ],\n \"time_since_last_read_millis\" : 8\n }\n ]\n }\n ]\n}" -} diff --git a/specification/ccr/follow_stats/examples/response/FollowIndexStatsResponseExample1.yaml b/specification/ccr/follow_stats/examples/response/FollowIndexStatsResponseExample1.yaml new file mode 100644 index 0000000000..4079daa8a7 --- /dev/null +++ b/specification/ccr/follow_stats/examples/response/FollowIndexStatsResponseExample1.yaml @@ -0,0 +1,45 @@ +# summary: +description: A successful response from `GET /follower_index/_ccr/stats`, which retrieves follower stats. +# type: response +# response_code: 200 +value: |- + { + "indices" : [ + { + "index" : "follower_index", + "total_global_checkpoint_lag" : 256, + "shards" : [ + { + "remote_cluster" : "remote_cluster", + "leader_index" : "leader_index", + "follower_index" : "follower_index", + "shard_id" : 0, + "leader_global_checkpoint" : 1024, + "leader_max_seq_no" : 1536, + "follower_global_checkpoint" : 768, + "follower_max_seq_no" : 896, + "last_requested_seq_no" : 897, + "outstanding_read_requests" : 8, + "outstanding_write_requests" : 2, + "write_buffer_operation_count" : 64, + "follower_mapping_version" : 4, + "follower_settings_version" : 2, + "follower_aliases_version" : 8, + "total_read_time_millis" : 32768, + "total_read_remote_exec_time_millis" : 16384, + "successful_read_requests" : 32, + "failed_read_requests" : 0, + "operations_read" : 896, + "bytes_read" : 32768, + "total_write_time_millis" : 16384, + "write_buffer_size_in_bytes" : 1536, + "successful_write_requests" : 16, + "failed_write_requests" : 0, + "operations_written" : 832, + "read_exceptions" : [ ], + "time_since_last_read_millis" : 8 + } + ] + } + ] + } diff --git a/specification/ccr/get_auto_follow_pattern/GetAutoFollowPatternRequest.ts b/specification/ccr/get_auto_follow_pattern/GetAutoFollowPatternRequest.ts index ff6ff14993..976fd20d32 100644 --- a/specification/ccr/get_auto_follow_pattern/GetAutoFollowPatternRequest.ts +++ b/specification/ccr/get_auto_follow_pattern/GetAutoFollowPatternRequest.ts @@ -23,9 +23,11 @@ import { Duration } from '@_types/Time' /** * Get auto-follow patterns. + * * Get cross-cluster replication auto-follow patterns. * @rest_spec_name ccr.get_auto_follow_pattern * @availability stack since=6.5.0 stability=stable + * @cluster_privileges manage_ccr * @doc_id ccr-get-auto-follow-pattern * @ext_doc_id ccr-auto-follow */ @@ -41,12 +43,16 @@ export interface Request extends RequestBase { } ] path_parts: { - /** Specifies the auto-follow pattern collection that you want to retrieve. If you do not specify a name, the API returns information for all collections. */ + /** + * The auto-follow pattern collection that you want to retrieve. + * If you do not specify a name, the API returns information for all collections. */ name?: Name } query_parameters: { /** - * Period to wait for a connection to the master node. + * The period to wait for a connection to the master node. + * If the master node is not available before the timeout expires, the request fails and returns an error. + * It can also be set to `-1` to indicate that the request should never timeout. * @server_default 30s */ master_timeout?: Duration diff --git a/specification/ccr/get_auto_follow_pattern/ccrApisAutoFollowGetAutoFollowPatternResponseExample1.json b/specification/ccr/get_auto_follow_pattern/ccrApisAutoFollowGetAutoFollowPatternResponseExample1.json deleted file mode 100644 index a5c328bc55..0000000000 --- a/specification/ccr/get_auto_follow_pattern/ccrApisAutoFollowGetAutoFollowPatternResponseExample1.json +++ /dev/null @@ -1,7 +0,0 @@ -{ - "summary": "A successful response for retrieving an auto-follow pattern.", - "description": "This may be a respons to `GET /_ccr/auto_follow/my_auto_follow_pattern`. ", - "type": "response", - "response_code": 200, - "value": "{\n \"patterns\": [\n {\n \"name\": \"my_auto_follow_pattern\",\n \"pattern\": {\n \"active\": true,\n \"remote_cluster\" : \"remote_cluster\",\n \"leader_index_patterns\" :\n [\n \"leader_index*\"\n ],\n \"leader_index_exclusion_patterns\":\n [\n \"leader_index_001\"\n ],\n \"follow_index_pattern\" : \"{{leader_index}}-follower\"\n }\n }\n ]\n}" -} diff --git a/specification/ccr/get_auto_follow_pattern/examples/response/GetAutoFollowPatternResponseExample1.yaml b/specification/ccr/get_auto_follow_pattern/examples/response/GetAutoFollowPatternResponseExample1.yaml new file mode 100644 index 0000000000..63b4b66f95 --- /dev/null +++ b/specification/ccr/get_auto_follow_pattern/examples/response/GetAutoFollowPatternResponseExample1.yaml @@ -0,0 +1,25 @@ +# summary: +description: A successful response from `GET /_ccr/auto_follow/my_auto_follow_pattern`, which gets auto-follow patterns. +# type: response +# response_code: 200 +value: |- + { + "patterns": [ + { + "name": "my_auto_follow_pattern", + "pattern": { + "active": true, + "remote_cluster" : "remote_cluster", + "leader_index_patterns" : + [ + "leader_index*" + ], + "leader_index_exclusion_patterns": + [ + "leader_index_001" + ], + "follow_index_pattern" : "{{leader_index}}-follower" + } + } + ] + } diff --git a/specification/ccr/pause_auto_follow_pattern/PauseAutoFollowPatternRequest.ts b/specification/ccr/pause_auto_follow_pattern/PauseAutoFollowPatternRequest.ts index 1fe5cdb136..e9e3335c5b 100644 --- a/specification/ccr/pause_auto_follow_pattern/PauseAutoFollowPatternRequest.ts +++ b/specification/ccr/pause_auto_follow_pattern/PauseAutoFollowPatternRequest.ts @@ -23,6 +23,7 @@ import { Duration } from '@_types/Time' /** * Pause an auto-follow pattern. + * * Pause a cross-cluster replication auto-follow pattern. * When the API returns, the auto-follow pattern is inactive. * New indices that are created on the remote cluster and match the auto-follow patterns are ignored. @@ -32,6 +33,7 @@ import { Duration } from '@_types/Time' * Remote indices that were created while the pattern was paused will also be followed, unless they have been deleted or closed in the interim. * @rest_spec_name ccr.pause_auto_follow_pattern * @availability stack since=7.5.0 stability=stable + * @cluster_privileges manage_ccr * @doc_id ccr-pause-auto-follow-pattern * @ext_doc_id ccr-auto-follow */ @@ -43,11 +45,14 @@ export interface Request extends RequestBase { } ] path_parts: { + /** The name of the auto-follow pattern to pause. */ name: Name } query_parameters: { /** - * Period to wait for a connection to the master node. + * The period to wait for a connection to the master node. + * If the master node is not available before the timeout expires, the request fails and returns an error. + * It can also be set to `-1` to indicate that the request should never timeout. * @server_default 30s */ master_timeout?: Duration diff --git a/specification/ccr/pause_auto_follow_pattern/ccrApisAutoFollowPauseAutoFollowPatternResponseExample1.json b/specification/ccr/pause_auto_follow_pattern/ccrApisAutoFollowPauseAutoFollowPatternResponseExample1.json deleted file mode 100644 index 05d29b79e8..0000000000 --- a/specification/ccr/pause_auto_follow_pattern/ccrApisAutoFollowPauseAutoFollowPatternResponseExample1.json +++ /dev/null @@ -1,7 +0,0 @@ -{ - "summary": "A successful response for pausing an auto-follow pattern.", - "description": "", - "type": "response", - "response_code": 200, - "value": "{\n \"acknowledged\" : true\n}" -} diff --git a/specification/ccr/pause_auto_follow_pattern/examples/response/PauseAutoFollowPatternResponseExample1.yaml b/specification/ccr/pause_auto_follow_pattern/examples/response/PauseAutoFollowPatternResponseExample1.yaml new file mode 100644 index 0000000000..b0bb0f358d --- /dev/null +++ b/specification/ccr/pause_auto_follow_pattern/examples/response/PauseAutoFollowPatternResponseExample1.yaml @@ -0,0 +1,8 @@ +# summary: +description: A successful response from `POST /_ccr/auto_follow/my_auto_follow_pattern/pause`, which pauses an auto-follow pattern. +# type: response +# response_code: 200 +value: |- + { + "acknowledged" : true + } diff --git a/specification/ccr/pause_follow/PauseFollowIndexRequest.ts b/specification/ccr/pause_follow/PauseFollowIndexRequest.ts index 60974b6859..f2ac1d3255 100644 --- a/specification/ccr/pause_follow/PauseFollowIndexRequest.ts +++ b/specification/ccr/pause_follow/PauseFollowIndexRequest.ts @@ -23,12 +23,14 @@ import { Duration } from '@_types/Time' /** * Pause a follower. + * * Pause a cross-cluster replication follower index. * The follower index will not fetch any additional operations from the leader index. * You can resume following with the resume follower API. * You can pause and resume a follower index to change the configuration of the following task. * @rest_spec_name ccr.pause_follow * @availability stack since=6.5.0 stability=stable + * @cluster_privileges manage_ccr * @doc_id ccr-post-pause-follow */ export interface Request extends RequestBase { @@ -39,11 +41,14 @@ export interface Request extends RequestBase { } ] path_parts: { + /** The name of the follower index. */ index: IndexName } query_parameters: { /** - * Period to wait for a connection to the master node. + * The period to wait for a connection to the master node. + * If the master node is not available before the timeout expires, the request fails and returns an error. + * It can also be set to `-1` to indicate that the request should never timeout. * @server_default 30s */ master_timeout?: Duration diff --git a/specification/ccr/pause_follow/ccrApisFollowPostPauseFollowResponseExample1.json b/specification/ccr/pause_follow/ccrApisFollowPostPauseFollowResponseExample1.json deleted file mode 100644 index 7084ad5783..0000000000 --- a/specification/ccr/pause_follow/ccrApisFollowPostPauseFollowResponseExample1.json +++ /dev/null @@ -1,7 +0,0 @@ -{ - "summary": "A successful response for pausing a follower index.", - "description": "", - "type": "response", - "response_code": 200, - "value": "{\n \"acknowledged\" : true\n}" -} diff --git a/specification/ccr/pause_follow/examples/response/PauseFollowIndexResponseExample1.yaml b/specification/ccr/pause_follow/examples/response/PauseFollowIndexResponseExample1.yaml new file mode 100644 index 0000000000..df592307a8 --- /dev/null +++ b/specification/ccr/pause_follow/examples/response/PauseFollowIndexResponseExample1.yaml @@ -0,0 +1,8 @@ +# summary: +description: A successful response from `POST /follower_index/_ccr/pause_follow`, which pauses a follower index. +# type: response +# response_code: 200 +value: |- + { + "acknowledged" : true + } diff --git a/specification/ccr/resume_auto_follow_pattern/ResumeAutoFollowPatternRequest.ts b/specification/ccr/resume_auto_follow_pattern/ResumeAutoFollowPatternRequest.ts index 358003df1c..71045499f9 100644 --- a/specification/ccr/resume_auto_follow_pattern/ResumeAutoFollowPatternRequest.ts +++ b/specification/ccr/resume_auto_follow_pattern/ResumeAutoFollowPatternRequest.ts @@ -23,11 +23,13 @@ import { Duration } from '@_types/Time' /** * Resume an auto-follow pattern. + * * Resume a cross-cluster replication auto-follow pattern that was paused. * The auto-follow pattern will resume configuring following indices for newly created indices that match its patterns on the remote cluster. * Remote indices created while the pattern was paused will also be followed unless they have been deleted or closed in the interim. * @rest_spec_name ccr.resume_auto_follow_pattern * @availability stack since=7.5.0 stability=stable + * @cluster_privileges manage_ccr * @doc_id ccr-resume-auto-follow-pattern * @ext_doc_id ccr-auto-follow */ @@ -39,11 +41,14 @@ export interface Request extends RequestBase { } ] path_parts: { + /** The name of the auto-follow pattern to resume. */ name: Name } query_parameters: { /** - * Period to wait for a connection to the master node. + * The period to wait for a connection to the master node. + * If the master node is not available before the timeout expires, the request fails and returns an error. + * It can also be set to `-1` to indicate that the request should never timeout. * @server_default 30s */ master_timeout?: Duration diff --git a/specification/ccr/resume_auto_follow_pattern/ccrApisAutoFollowResumeAutoFollowPatternResponseExample1.json b/specification/ccr/resume_auto_follow_pattern/ccrApisAutoFollowResumeAutoFollowPatternResponseExample1.json deleted file mode 100644 index 118c48137c..0000000000 --- a/specification/ccr/resume_auto_follow_pattern/ccrApisAutoFollowResumeAutoFollowPatternResponseExample1.json +++ /dev/null @@ -1,7 +0,0 @@ -{ - "summary": "A successful response for resuming an auto-follow pattern.", - "description": "", - "type": "response", - "response_code": 200, - "value": "{\n \"acknowledged\" : true\n}" -} diff --git a/specification/ccr/resume_auto_follow_pattern/examples/response/ResumeAutoFollowPatternResponseExample1.yaml b/specification/ccr/resume_auto_follow_pattern/examples/response/ResumeAutoFollowPatternResponseExample1.yaml new file mode 100644 index 0000000000..e2ab7bb500 --- /dev/null +++ b/specification/ccr/resume_auto_follow_pattern/examples/response/ResumeAutoFollowPatternResponseExample1.yaml @@ -0,0 +1,9 @@ +# summary: +description: > + A successful response `POST /_ccr/auto_follow/my_auto_follow_pattern/resume`, which resumes an auto-follow pattern. +# type: response +# response_code: 200 +value: |- + { + "acknowledged" : true + } diff --git a/specification/ccr/stats/CcrStatsRequest.ts b/specification/ccr/stats/CcrStatsRequest.ts index 6065a964a0..39e31b08c9 100644 --- a/specification/ccr/stats/CcrStatsRequest.ts +++ b/specification/ccr/stats/CcrStatsRequest.ts @@ -22,9 +22,11 @@ import { Duration } from '@_types/Time' /** * Get cross-cluster replication stats. + * * This API returns stats about auto-following and the same shard-level stats as the get follower stats API. * @rest_spec_name ccr.stats * @availability stack since=6.5.0 stability=stable + * @cluster_privileges monitor * @doc_id ccr-get-stats */ export interface Request extends RequestBase { @@ -36,12 +38,14 @@ export interface Request extends RequestBase { ] query_parameters: { /** - * Period to wait for a connection to the master node. + * The period to wait for a connection to the master node. + * If the master node is not available before the timeout expires, the request fails and returns an error. + * It can also be set to `-1` to indicate that the request should never timeout. * @server_default 30s */ master_timeout?: Duration /** - * Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error. + * The period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error. * @server_default 30s */ timeout?: Duration diff --git a/specification/ccr/stats/CcrStatsResponse.ts b/specification/ccr/stats/CcrStatsResponse.ts index e22682073a..afb4b8c69e 100644 --- a/specification/ccr/stats/CcrStatsResponse.ts +++ b/specification/ccr/stats/CcrStatsResponse.ts @@ -21,7 +21,9 @@ import { AutoFollowStats, FollowStats } from './types.ts' export class Response { body: { + /** Statistics for the auto-follow coordinator. */ auto_follow_stats: AutoFollowStats + /** Shard-level statistics for follower indices. */ follow_stats: FollowStats } } diff --git a/specification/ccr/stats/ccrApisGetCcrStatsResponseExample1.json b/specification/ccr/stats/ccrApisGetCcrStatsResponseExample1.json deleted file mode 100644 index 92c423b739..0000000000 --- a/specification/ccr/stats/ccrApisGetCcrStatsResponseExample1.json +++ /dev/null @@ -1,7 +0,0 @@ -{ - "summary": "A successful response for retrieving cross-cluster replication stats.", - "description": "", - "type": "response", - "response_code": 200, - "value": "{\n \"auto_follow_stats\" : {\n \"number_of_failed_follow_indices\" : 0,\n \"number_of_failed_remote_cluster_state_requests\" : 0,\n \"number_of_successful_follow_indices\" : 1,\n \"recent_auto_follow_errors\" : [],\n \"auto_followed_clusters\" : []\n },\n \"follow_stats\" : {\n \"indices\" : [\n {\n \"index\" : \"follower_index\",\n \"total_global_checkpoint_lag\" : 256,\n \"shards\" : [\n {\n \"remote_cluster\" : \"remote_cluster\",\n \"leader_index\" : \"leader_index\",\n \"follower_index\" : \"follower_index\",\n \"shard_id\" : 0,\n \"leader_global_checkpoint\" : 1024,\n \"leader_max_seq_no\" : 1536,\n \"follower_global_checkpoint\" : 768,\n \"follower_max_seq_no\" : 896,\n \"last_requested_seq_no\" : 897,\n \"outstanding_read_requests\" : 8,\n \"outstanding_write_requests\" : 2,\n \"write_buffer_operation_count\" : 64,\n \"follower_mapping_version\" : 4,\n \"follower_settings_version\" : 2,\n \"follower_aliases_version\" : 8,\n \"total_read_time_millis\" : 32768,\n \"total_read_remote_exec_time_millis\" : 16384,\n \"successful_read_requests\" : 32,\n \"failed_read_requests\" : 0,\n \"operations_read\" : 896,\n \"bytes_read\" : 32768,\n \"total_write_time_millis\" : 16384,\n \"write_buffer_size_in_bytes\" : 1536,\n \"successful_write_requests\" : 16,\n \"failed_write_requests\" : 0,\n \"operations_written\" : 832,\n \"read_exceptions\" : [ ],\n \"time_since_last_read_millis\" : 8\n }\n ]\n }\n ]\n }\n}" -} diff --git a/specification/ccr/stats/examples/response/CcrStatsResponseExample1.yaml b/specification/ccr/stats/examples/response/CcrStatsResponseExample1.yaml new file mode 100644 index 0000000000..1f0ab038c5 --- /dev/null +++ b/specification/ccr/stats/examples/response/CcrStatsResponseExample1.yaml @@ -0,0 +1,54 @@ +# summary: +description: A successful response from `GET /_ccr/stats` that returns cross-cluster replication stats. +# type: response +# response_code: 200 +value: |- + { + "auto_follow_stats" : { + "number_of_failed_follow_indices" : 0, + "number_of_failed_remote_cluster_state_requests" : 0, + "number_of_successful_follow_indices" : 1, + "recent_auto_follow_errors" : [], + "auto_followed_clusters" : [] + }, + "follow_stats" : { + "indices" : [ + { + "index" : "follower_index", + "total_global_checkpoint_lag" : 256, + "shards" : [ + { + "remote_cluster" : "remote_cluster", + "leader_index" : "leader_index", + "follower_index" : "follower_index", + "shard_id" : 0, + "leader_global_checkpoint" : 1024, + "leader_max_seq_no" : 1536, + "follower_global_checkpoint" : 768, + "follower_max_seq_no" : 896, + "last_requested_seq_no" : 897, + "outstanding_read_requests" : 8, + "outstanding_write_requests" : 2, + "write_buffer_operation_count" : 64, + "follower_mapping_version" : 4, + "follower_settings_version" : 2, + "follower_aliases_version" : 8, + "total_read_time_millis" : 32768, + "total_read_remote_exec_time_millis" : 16384, + "successful_read_requests" : 32, + "failed_read_requests" : 0, + "operations_read" : 896, + "bytes_read" : 32768, + "total_write_time_millis" : 16384, + "write_buffer_size_in_bytes" : 1536, + "successful_write_requests" : 16, + "failed_write_requests" : 0, + "operations_written" : 832, + "read_exceptions" : [ ], + "time_since_last_read_millis" : 8 + } + ] + } + ] + } + } diff --git a/specification/ccr/stats/types.ts.ts b/specification/ccr/stats/types.ts.ts index 9522232c4a..53d9eee553 100644 --- a/specification/ccr/stats/types.ts.ts +++ b/specification/ccr/stats/types.ts.ts @@ -31,9 +31,18 @@ export class AutoFollowedCluster { export class AutoFollowStats { auto_followed_clusters: AutoFollowedCluster[] + /** + * The number of indices that the auto-follow coordinator failed to automatically follow. + * The causes of recent failures are captured in the logs of the elected master node and in the `auto_follow_stats.recent_auto_follow_errors` field. + */ number_of_failed_follow_indices: long + /** + * The number of times that the auto-follow coordinator failed to retrieve the cluster state from a remote cluster registered in a collection of auto-follow patterns. + */ number_of_failed_remote_cluster_state_requests: long + /** The number of indices that the auto-follow coordinator successfully followed. */ number_of_successful_follow_indices: long + /** An array of objects representing failures by the auto-follow coordinator. */ recent_auto_follow_errors: ErrorCause[] } diff --git a/specification/ccr/unfollow/UnfollowIndexRequest.ts b/specification/ccr/unfollow/UnfollowIndexRequest.ts index 7fbdb6d65d..ec469d7633 100644 --- a/specification/ccr/unfollow/UnfollowIndexRequest.ts +++ b/specification/ccr/unfollow/UnfollowIndexRequest.ts @@ -23,13 +23,16 @@ import { Duration } from '@_types/Time' /** * Unfollow an index. + * * Convert a cross-cluster replication follower index to a regular index. * The API stops the following task associated with a follower index and removes index metadata and settings associated with cross-cluster replication. * The follower index must be paused and closed before you call the unfollow API. * - * NOTE: Currently cross-cluster replication does not support converting an existing regular index to a follower index. Converting a follower index to a regular index is an irreversible operation. + * > info + * > Currently cross-cluster replication does not support converting an existing regular index to a follower index. Converting a follower index to a regular index is an irreversible operation. * @rest_spec_name ccr.unfollow * @availability stack since=6.5.0 stability=stable + * @index_privileges manage_follow_index * @doc_id ccr-post-unfollow * @ext_doc_id ccr */ @@ -41,11 +44,14 @@ export interface Request extends RequestBase { } ] path_parts: { + /** The name of the follower index. */ index: IndexName } query_parameters: { /** - * Period to wait for a connection to the master node. + * The period to wait for a connection to the master node. + * If the master node is not available before the timeout expires, the request fails and returns an error. + * It can also be set to `-1` to indicate that the request should never timeout. * @server_default 30s */ master_timeout?: Duration diff --git a/specification/ccr/unfollow/ccrApisFollowPostUnfollowResponseExample1.json b/specification/ccr/unfollow/ccrApisFollowPostUnfollowResponseExample1.json deleted file mode 100644 index 8fa74c6ccb..0000000000 --- a/specification/ccr/unfollow/ccrApisFollowPostUnfollowResponseExample1.json +++ /dev/null @@ -1,7 +0,0 @@ -{ - "summary": "A successful response for converting a follower index to a regular index.", - "description": "", - "type": "response", - "response_code": 200, - "value": "{\n \"acknowledged\" : true\n}" -} diff --git a/specification/ccr/unfollow/examples/response/UnfollowIndexResponseExample1.yaml b/specification/ccr/unfollow/examples/response/UnfollowIndexResponseExample1.yaml new file mode 100644 index 0000000000..81e3b6a1fd --- /dev/null +++ b/specification/ccr/unfollow/examples/response/UnfollowIndexResponseExample1.yaml @@ -0,0 +1,8 @@ +# summary: +description: A successful response from `POST /follower_index/_ccr/unfollow`. +# type: response +# response_code: 200 +value: |- + { + "acknowledged" : true + }