From e37604c04c5054fb7c47613434678d21b50b71e0 Mon Sep 17 00:00:00 2001 From: Jeremy Dahlgren Date: Fri, 23 May 2025 16:20:28 -0400 Subject: [PATCH 1/3] Allow missing shard stats for restarted nodes for _snapshot/_status Adds a note explaining the change made in elasticsearch PR #128399 to reduce latency when getting stats for currently running snapshots. Relates ES-10982 --- specification/snapshot/status/SnapshotStatusRequest.ts | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/specification/snapshot/status/SnapshotStatusRequest.ts b/specification/snapshot/status/SnapshotStatusRequest.ts index 613025958b..b8e12e5c3d 100644 --- a/specification/snapshot/status/SnapshotStatusRequest.ts +++ b/specification/snapshot/status/SnapshotStatusRequest.ts @@ -30,6 +30,11 @@ import { Duration } from '@_types/Time' * * If you omit the `` request path parameter, the request retrieves information only for currently running snapshots. * This usage is preferred. + * Note that if a node has been restarted or has left the cluster since completing a shard snapshot the stats for that shard will be unavailable. + * Loading the stats from the repository is an expensive operation (see the WARNING below), so to minimize latency for returning stats for currently + * running snapshots the stats values will be zero for these shards even though the "stage" value will be "DONE". A "description" field will be set + * on these shard stats instances indicating why they are empty. Note that the total stats for the index will be less than expected due to the + * missing values from these shards. * If needed, you can specify `` and `` to retrieve information for specific snapshots, even if they're not currently running. * * WARNING: Using the API to return the status of any snapshots other than currently running snapshots can be expensive. From 5e7bab86804ea06676e7b33c19ae957c8290d537 Mon Sep 17 00:00:00 2001 From: Jeremy Dahlgren Date: Fri, 30 May 2025 15:26:56 -0400 Subject: [PATCH 2/3] Fix message to show -1 for missing stats values --- specification/snapshot/status/SnapshotStatusRequest.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/snapshot/status/SnapshotStatusRequest.ts b/specification/snapshot/status/SnapshotStatusRequest.ts index b8e12e5c3d..10b83213bf 100644 --- a/specification/snapshot/status/SnapshotStatusRequest.ts +++ b/specification/snapshot/status/SnapshotStatusRequest.ts @@ -32,7 +32,7 @@ import { Duration } from '@_types/Time' * This usage is preferred. * Note that if a node has been restarted or has left the cluster since completing a shard snapshot the stats for that shard will be unavailable. * Loading the stats from the repository is an expensive operation (see the WARNING below), so to minimize latency for returning stats for currently - * running snapshots the stats values will be zero for these shards even though the "stage" value will be "DONE". A "description" field will be set + * running snapshots the stats values will be -1 for these shards even though the "stage" value will be "DONE". A "description" field will be set * on these shard stats instances indicating why they are empty. Note that the total stats for the index will be less than expected due to the * missing values from these shards. * If needed, you can specify `` and `` to retrieve information for specific snapshots, even if they're not currently running. From 2b0fdab65a0a7bdbe97d79ae661f771267da55a1 Mon Sep 17 00:00:00 2001 From: Jeremy Dahlgren Date: Fri, 30 May 2025 15:46:08 -0400 Subject: [PATCH 3/3] Add generated output files --- output/openapi/elasticsearch-openapi.json | 6 +++--- output/schema/schema.json | 6 +++--- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/output/openapi/elasticsearch-openapi.json b/output/openapi/elasticsearch-openapi.json index 758446e708..ca16ae9794 100644 --- a/output/openapi/elasticsearch-openapi.json +++ b/output/openapi/elasticsearch-openapi.json @@ -39027,7 +39027,7 @@ "snapshot" ], "summary": "Get the snapshot status", - "description": "Get a detailed description of the current state for each shard participating in the snapshot.\n\nNote that this API should be used only to obtain detailed shard-level information for ongoing snapshots.\nIf this detail is not needed or you want to obtain information about one or more existing snapshots, use the get snapshot API.\n\nIf you omit the `` request path parameter, the request retrieves information only for currently running snapshots.\nThis usage is preferred.\nIf needed, you can specify `` and `` to retrieve information for specific snapshots, even if they're not currently running.\n\nWARNING: Using the API to return the status of any snapshots other than currently running snapshots can be expensive.\nThe API requires a read from the repository for each shard in each snapshot.\nFor example, if you have 100 snapshots with 1,000 shards each, an API request that includes all snapshots will require 100,000 reads (100 snapshots x 1,000 shards).\n\nDepending on the latency of your storage, such requests can take an extremely long time to return results.\nThese requests can also tax machine resources and, when using cloud storage, incur high processing costs.", + "description": "Get a detailed description of the current state for each shard participating in the snapshot.\n\nNote that this API should be used only to obtain detailed shard-level information for ongoing snapshots.\nIf this detail is not needed or you want to obtain information about one or more existing snapshots, use the get snapshot API.\n\nIf you omit the `` request path parameter, the request retrieves information only for currently running snapshots.\nThis usage is preferred.\nNote that if a node has been restarted or has left the cluster since completing a shard snapshot the stats for that shard will be unavailable.\nLoading the stats from the repository is an expensive operation (see the WARNING below), so to minimize latency for returning stats for currently\nrunning snapshots the stats values will be -1 for these shards even though the \"stage\" value will be \"DONE\". A \"description\" field will be set\non these shard stats instances indicating why they are empty. Note that the total stats for the index will be less than expected due to the\nmissing values from these shards.\nIf needed, you can specify `` and `` to retrieve information for specific snapshots, even if they're not currently running.\n\nWARNING: Using the API to return the status of any snapshots other than currently running snapshots can be expensive.\nThe API requires a read from the repository for each shard in each snapshot.\nFor example, if you have 100 snapshots with 1,000 shards each, an API request that includes all snapshots will require 100,000 reads (100 snapshots x 1,000 shards).\n\nDepending on the latency of your storage, such requests can take an extremely long time to return results.\nThese requests can also tax machine resources and, when using cloud storage, incur high processing costs.", "operationId": "snapshot-status", "parameters": [ { @@ -39051,7 +39051,7 @@ "snapshot" ], "summary": "Get the snapshot status", - "description": "Get a detailed description of the current state for each shard participating in the snapshot.\n\nNote that this API should be used only to obtain detailed shard-level information for ongoing snapshots.\nIf this detail is not needed or you want to obtain information about one or more existing snapshots, use the get snapshot API.\n\nIf you omit the `` request path parameter, the request retrieves information only for currently running snapshots.\nThis usage is preferred.\nIf needed, you can specify `` and `` to retrieve information for specific snapshots, even if they're not currently running.\n\nWARNING: Using the API to return the status of any snapshots other than currently running snapshots can be expensive.\nThe API requires a read from the repository for each shard in each snapshot.\nFor example, if you have 100 snapshots with 1,000 shards each, an API request that includes all snapshots will require 100,000 reads (100 snapshots x 1,000 shards).\n\nDepending on the latency of your storage, such requests can take an extremely long time to return results.\nThese requests can also tax machine resources and, when using cloud storage, incur high processing costs.", + "description": "Get a detailed description of the current state for each shard participating in the snapshot.\n\nNote that this API should be used only to obtain detailed shard-level information for ongoing snapshots.\nIf this detail is not needed or you want to obtain information about one or more existing snapshots, use the get snapshot API.\n\nIf you omit the `` request path parameter, the request retrieves information only for currently running snapshots.\nThis usage is preferred.\nNote that if a node has been restarted or has left the cluster since completing a shard snapshot the stats for that shard will be unavailable.\nLoading the stats from the repository is an expensive operation (see the WARNING below), so to minimize latency for returning stats for currently\nrunning snapshots the stats values will be -1 for these shards even though the \"stage\" value will be \"DONE\". A \"description\" field will be set\non these shard stats instances indicating why they are empty. Note that the total stats for the index will be less than expected due to the\nmissing values from these shards.\nIf needed, you can specify `` and `` to retrieve information for specific snapshots, even if they're not currently running.\n\nWARNING: Using the API to return the status of any snapshots other than currently running snapshots can be expensive.\nThe API requires a read from the repository for each shard in each snapshot.\nFor example, if you have 100 snapshots with 1,000 shards each, an API request that includes all snapshots will require 100,000 reads (100 snapshots x 1,000 shards).\n\nDepending on the latency of your storage, such requests can take an extremely long time to return results.\nThese requests can also tax machine resources and, when using cloud storage, incur high processing costs.", "operationId": "snapshot-status-1", "parameters": [ { @@ -39078,7 +39078,7 @@ "snapshot" ], "summary": "Get the snapshot status", - "description": "Get a detailed description of the current state for each shard participating in the snapshot.\n\nNote that this API should be used only to obtain detailed shard-level information for ongoing snapshots.\nIf this detail is not needed or you want to obtain information about one or more existing snapshots, use the get snapshot API.\n\nIf you omit the `` request path parameter, the request retrieves information only for currently running snapshots.\nThis usage is preferred.\nIf needed, you can specify `` and `` to retrieve information for specific snapshots, even if they're not currently running.\n\nWARNING: Using the API to return the status of any snapshots other than currently running snapshots can be expensive.\nThe API requires a read from the repository for each shard in each snapshot.\nFor example, if you have 100 snapshots with 1,000 shards each, an API request that includes all snapshots will require 100,000 reads (100 snapshots x 1,000 shards).\n\nDepending on the latency of your storage, such requests can take an extremely long time to return results.\nThese requests can also tax machine resources and, when using cloud storage, incur high processing costs.", + "description": "Get a detailed description of the current state for each shard participating in the snapshot.\n\nNote that this API should be used only to obtain detailed shard-level information for ongoing snapshots.\nIf this detail is not needed or you want to obtain information about one or more existing snapshots, use the get snapshot API.\n\nIf you omit the `` request path parameter, the request retrieves information only for currently running snapshots.\nThis usage is preferred.\nNote that if a node has been restarted or has left the cluster since completing a shard snapshot the stats for that shard will be unavailable.\nLoading the stats from the repository is an expensive operation (see the WARNING below), so to minimize latency for returning stats for currently\nrunning snapshots the stats values will be -1 for these shards even though the \"stage\" value will be \"DONE\". A \"description\" field will be set\non these shard stats instances indicating why they are empty. Note that the total stats for the index will be less than expected due to the\nmissing values from these shards.\nIf needed, you can specify `` and `` to retrieve information for specific snapshots, even if they're not currently running.\n\nWARNING: Using the API to return the status of any snapshots other than currently running snapshots can be expensive.\nThe API requires a read from the repository for each shard in each snapshot.\nFor example, if you have 100 snapshots with 1,000 shards each, an API request that includes all snapshots will require 100,000 reads (100 snapshots x 1,000 shards).\n\nDepending on the latency of your storage, such requests can take an extremely long time to return results.\nThese requests can also tax machine resources and, when using cloud storage, incur high processing costs.", "operationId": "snapshot-status-2", "parameters": [ { diff --git a/output/schema/schema.json b/output/schema/schema.json index 7f06a39e4a..11b68ef7af 100644 --- a/output/schema/schema.json +++ b/output/schema/schema.json @@ -21287,7 +21287,7 @@ "stability": "stable" } }, - "description": "Get the snapshot status.\nGet a detailed description of the current state for each shard participating in the snapshot.\n\nNote that this API should be used only to obtain detailed shard-level information for ongoing snapshots.\nIf this detail is not needed or you want to obtain information about one or more existing snapshots, use the get snapshot API.\n\nIf you omit the `` request path parameter, the request retrieves information only for currently running snapshots.\nThis usage is preferred.\nIf needed, you can specify `` and `` to retrieve information for specific snapshots, even if they're not currently running.\n\nWARNING: Using the API to return the status of any snapshots other than currently running snapshots can be expensive.\nThe API requires a read from the repository for each shard in each snapshot.\nFor example, if you have 100 snapshots with 1,000 shards each, an API request that includes all snapshots will require 100,000 reads (100 snapshots x 1,000 shards).\n\nDepending on the latency of your storage, such requests can take an extremely long time to return results.\nThese requests can also tax machine resources and, when using cloud storage, incur high processing costs.", + "description": "Get the snapshot status.\nGet a detailed description of the current state for each shard participating in the snapshot.\n\nNote that this API should be used only to obtain detailed shard-level information for ongoing snapshots.\nIf this detail is not needed or you want to obtain information about one or more existing snapshots, use the get snapshot API.\n\nIf you omit the `` request path parameter, the request retrieves information only for currently running snapshots.\nThis usage is preferred.\nNote that if a node has been restarted or has left the cluster since completing a shard snapshot the stats for that shard will be unavailable.\nLoading the stats from the repository is an expensive operation (see the WARNING below), so to minimize latency for returning stats for currently\nrunning snapshots the stats values will be -1 for these shards even though the \"stage\" value will be \"DONE\". A \"description\" field will be set\non these shard stats instances indicating why they are empty. Note that the total stats for the index will be less than expected due to the\nmissing values from these shards.\nIf needed, you can specify `` and `` to retrieve information for specific snapshots, even if they're not currently running.\n\nWARNING: Using the API to return the status of any snapshots other than currently running snapshots can be expensive.\nThe API requires a read from the repository for each shard in each snapshot.\nFor example, if you have 100 snapshots with 1,000 shards each, an API request that includes all snapshots will require 100,000 reads (100 snapshots x 1,000 shards).\n\nDepending on the latency of your storage, such requests can take an extremely long time to return results.\nThese requests can also tax machine resources and, when using cloud storage, incur high processing costs.", "docId": "snapshot-status", "docUrl": "https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-snapshot-status", "name": "snapshot.status", @@ -228383,7 +228383,7 @@ "body": { "kind": "no_body" }, - "description": "Get the snapshot status.\nGet a detailed description of the current state for each shard participating in the snapshot.\n\nNote that this API should be used only to obtain detailed shard-level information for ongoing snapshots.\nIf this detail is not needed or you want to obtain information about one or more existing snapshots, use the get snapshot API.\n\nIf you omit the `` request path parameter, the request retrieves information only for currently running snapshots.\nThis usage is preferred.\nIf needed, you can specify `` and `` to retrieve information for specific snapshots, even if they're not currently running.\n\nWARNING: Using the API to return the status of any snapshots other than currently running snapshots can be expensive.\nThe API requires a read from the repository for each shard in each snapshot.\nFor example, if you have 100 snapshots with 1,000 shards each, an API request that includes all snapshots will require 100,000 reads (100 snapshots x 1,000 shards).\n\nDepending on the latency of your storage, such requests can take an extremely long time to return results.\nThese requests can also tax machine resources and, when using cloud storage, incur high processing costs.", + "description": "Get the snapshot status.\nGet a detailed description of the current state for each shard participating in the snapshot.\n\nNote that this API should be used only to obtain detailed shard-level information for ongoing snapshots.\nIf this detail is not needed or you want to obtain information about one or more existing snapshots, use the get snapshot API.\n\nIf you omit the `` request path parameter, the request retrieves information only for currently running snapshots.\nThis usage is preferred.\nNote that if a node has been restarted or has left the cluster since completing a shard snapshot the stats for that shard will be unavailable.\nLoading the stats from the repository is an expensive operation (see the WARNING below), so to minimize latency for returning stats for currently\nrunning snapshots the stats values will be -1 for these shards even though the \"stage\" value will be \"DONE\". A \"description\" field will be set\non these shard stats instances indicating why they are empty. Note that the total stats for the index will be less than expected due to the\nmissing values from these shards.\nIf needed, you can specify `` and `` to retrieve information for specific snapshots, even if they're not currently running.\n\nWARNING: Using the API to return the status of any snapshots other than currently running snapshots can be expensive.\nThe API requires a read from the repository for each shard in each snapshot.\nFor example, if you have 100 snapshots with 1,000 shards each, an API request that includes all snapshots will require 100,000 reads (100 snapshots x 1,000 shards).\n\nDepending on the latency of your storage, such requests can take an extremely long time to return results.\nThese requests can also tax machine resources and, when using cloud storage, incur high processing costs.", "inherits": { "type": { "name": "RequestBase", @@ -228448,7 +228448,7 @@ } } ], - "specLocation": "snapshot/status/SnapshotStatusRequest.ts#L24-L90" + "specLocation": "snapshot/status/SnapshotStatusRequest.ts#L24-L95" }, { "kind": "response",