mirror of
https://github.com/elastic/elasticsearch.git
synced 2025-06-29 09:54:06 -04:00
c8fb9aad40
This commit adds some per-index statistics to the `SnapshotInfo` blob: - number of shards - total size in bytes - maximum number of segments per shard It also exposes these statistics in the get snapshot API.
292 lines
8.1 KiB
Text
292 lines
8.1 KiB
Text
[[get-snapshot-api]]
|
|
=== Get snapshot API
|
|
++++
|
|
<titleabbrev>Get snapshot</titleabbrev>
|
|
++++
|
|
|
|
Retrieves information about one or more snapshots.
|
|
|
|
////
|
|
[source,console]
|
|
----
|
|
PUT /_snapshot/my_repository
|
|
{
|
|
"type": "fs",
|
|
"settings": {
|
|
"location": "my_backup_location"
|
|
}
|
|
}
|
|
|
|
PUT /_snapshot/my_repository/my_snapshot?wait_for_completion=true
|
|
|
|
PUT /_snapshot/my_repository/snapshot_2?wait_for_completion=true
|
|
----
|
|
// TESTSETUP
|
|
////
|
|
|
|
[source,console]
|
|
----
|
|
GET /_snapshot/my_repository/my_snapshot
|
|
----
|
|
|
|
[[get-snapshot-api-request]]
|
|
==== {api-request-title}
|
|
|
|
`GET /_snapshot/<repository>/<snapshot>`
|
|
|
|
[[get-snapshot-api-prereqs]]
|
|
==== {api-prereq-title}
|
|
|
|
* If the {es} {security-features} are enabled, you must have the
|
|
`monitor_snapshot`, `create_snapshot`, or `manage`
|
|
<<privileges-list-cluster,cluster privilege>> to use this API.
|
|
|
|
[[get-snapshot-api-desc]]
|
|
==== {api-description-title}
|
|
|
|
Use the get snapshot API to return information about one or more snapshots, including:
|
|
|
|
* Start and end time values
|
|
* Version of {es} that created the snapshot
|
|
* List of included indices
|
|
* Current state of the snapshot
|
|
* List of failures that occurred during the snapshot
|
|
|
|
[[get-snapshot-api-path-params]]
|
|
==== {api-path-parms-title}
|
|
|
|
`<repository>`::
|
|
(Required, string)
|
|
Comma-separated list of snapshot repository names used to limit the request.
|
|
Wildcard (`*`) expressions are supported.
|
|
+
|
|
To get information about all snapshot repositories registered in the
|
|
cluster, omit this parameter or use `*` or `_all`.
|
|
|
|
`<snapshot>`::
|
|
(Required, string)
|
|
Comma-separated list of snapshot names to retrieve. Also accepts wildcards (`*`).
|
|
+
|
|
* To get information about all snapshots in a registered repository, use a wildcard (`*`) or `_all`.
|
|
* To get information about any snapshots that are currently running, use `_current`.
|
|
+
|
|
NOTE: Using `_all` in a request fails if any snapshots are unavailable.
|
|
Set <<get-snapshot-api-ignore-unavailable,`ignore_unavailable`>> to `true` to return only available snapshots.
|
|
|
|
[role="child_attributes"]
|
|
[[get-snapshot-api-request-body]]
|
|
==== {api-request-body-title}
|
|
|
|
[[get-snapshot-api-ignore-unavailable]]
|
|
`ignore_unavailable`::
|
|
(Optional, Boolean)
|
|
If `false`, the request returns an error for any snapshots that are unavailable. Defaults to `false`.
|
|
+
|
|
If `true`, the request ignores snapshots that are unavailable, such as those that are corrupted or temporarily cannot be returned.
|
|
|
|
`verbose`::
|
|
(Optional, Boolean)
|
|
If `true`, returns additional information about each snapshot such as the
|
|
version of Elasticsearch which took the snapshot, the start and end times of
|
|
the snapshot, and the number of shards snapshotted. Defaults to `true`. If
|
|
`false`, omits the additional information.
|
|
|
|
`index_details`::
|
|
(Optional, Boolean)
|
|
If `true`, returns additional information about each index in the snapshot
|
|
comprising the number of shards in the index, the total size of the index in
|
|
bytes, and the maximum number of segments per shard in the index. Defaults to
|
|
`false`, meaning that this information is omitted.
|
|
|
|
[role="child_attributes"]
|
|
[[get-snapshot-api-response-body]]
|
|
==== {api-response-body-title}
|
|
|
|
`snapshot`::
|
|
(string)
|
|
Name of the snapshot.
|
|
|
|
`uuid`::
|
|
(string)
|
|
Universally unique identifier (UUID) of the snapshot.
|
|
|
|
`version_id`::
|
|
(int)
|
|
Build ID of the {es} version used to create the snapshot.
|
|
|
|
`version`::
|
|
(float)
|
|
{es} version used to create the snapshot.
|
|
|
|
`indices`::
|
|
(array)
|
|
List of indices included in the snapshot.
|
|
|
|
`index_details`::
|
|
(object)
|
|
Details of each index in the snapshot, keyed by index name. Only present if the
|
|
`?index_details` query parameter is set, and only contains details for indices
|
|
that were completely snapshotted in a sufficiently recent version of {es}.
|
|
+
|
|
.Properties of `index_details`
|
|
[%collapsible%open]
|
|
====
|
|
`shard_count`::
|
|
(integer)
|
|
Number of shards in this index.
|
|
|
|
`size`::
|
|
(string)
|
|
Total size of all shards in this index. Only present if the `?human` query
|
|
paramter is set.
|
|
|
|
`size_in_bytes`::
|
|
(long)
|
|
Total size of all shards in this index, in bytes.
|
|
|
|
`max_segments_per_shard`::
|
|
(integer)
|
|
Maximum number of segments per shard in this index snapshot.
|
|
====
|
|
|
|
`data_streams`::
|
|
(array)
|
|
List of <<data-streams,data streams>> included in the snapshot.
|
|
|
|
`include_global_state`::
|
|
(Boolean)
|
|
Indicates whether the current cluster state is included in the snapshot.
|
|
|
|
[[get-snapshot-api-feature-states]]
|
|
`feature_states`::
|
|
(array)
|
|
List of feature states which were included when the snapshot was taken,
|
|
including the list of system indices included as part of the feature state. The
|
|
`feature_name` field of each can be used in the `feature_states` parameter when
|
|
restoring the snapshot to restore a subset of feature states. Only present if
|
|
the snapshot includes one or more feature states.
|
|
|
|
`start_time`::
|
|
(string)
|
|
Date timestamp of when the snapshot creation process started.
|
|
|
|
`start_time_in_millis`::
|
|
(long)
|
|
The time, in milliseconds, when the snapshot creation process started.
|
|
|
|
`end_time`::
|
|
(string)
|
|
Date timestamp of when the snapshot creation process ended.
|
|
|
|
`end_time_in_millis`::
|
|
(long)
|
|
The time, in milliseconds, when the snapshot creation process ended.
|
|
|
|
`duration_in_millis`::
|
|
(long)
|
|
How long, in milliseconds, it took to create the snapshot.
|
|
|
|
[[get-snapshot-api-response-failures]]
|
|
`failures`::
|
|
(array)
|
|
Lists any failures that occurred when creating the snapshot.
|
|
|
|
`shards`::
|
|
(object)
|
|
Contains a count of shards in the snapshot.
|
|
+
|
|
.Properties of `shards`
|
|
[%collapsible%open]
|
|
====
|
|
`total`::
|
|
(integer)
|
|
Total number of shards included in the snapshot.
|
|
|
|
`successful`::
|
|
(integer)
|
|
Number of shards that were successfully included in the snapshot.
|
|
|
|
`failed`::
|
|
(integer)
|
|
Number of shards that failed to be included in the snapshot.
|
|
====
|
|
|
|
`state`::
|
|
+
|
|
--
|
|
(string)
|
|
The snapshot `state` can be one of the following values:
|
|
|
|
.Values for `state`
|
|
[%collapsible%open]
|
|
====
|
|
`IN_PROGRESS`::
|
|
The snapshot is currently running.
|
|
|
|
`SUCCESS`::
|
|
The snapshot finished and all shards were stored successfully.
|
|
|
|
`FAILED`::
|
|
The snapshot finished with an error and failed to store any data.
|
|
|
|
`PARTIAL`::
|
|
The global cluster state was stored, but data of at least one shard was not stored successfully.
|
|
The <<get-snapshot-api-response-failures,`failures`>> section of the response contains more detailed information about shards
|
|
that were not processed correctly.
|
|
====
|
|
--
|
|
|
|
[[get-snapshot-api-example]]
|
|
==== {api-examples-title}
|
|
|
|
The following request returns information for `snapshot_2` in the `my_repository` repository.
|
|
|
|
[source,console]
|
|
----
|
|
GET /_snapshot/my_repository/snapshot_2
|
|
----
|
|
|
|
The API returns the following response:
|
|
|
|
[source,console-result]
|
|
----
|
|
{
|
|
"responses": [
|
|
{
|
|
"repository": "my_repository",
|
|
"snapshots": [
|
|
{
|
|
"snapshot": "snapshot_2",
|
|
"uuid": "vdRctLCxSketdKb54xw67g",
|
|
"version_id": <version_id>,
|
|
"version": <version>,
|
|
"indices": [],
|
|
"data_streams": [],
|
|
"feature_states": [],
|
|
"include_global_state": true,
|
|
"state": "SUCCESS",
|
|
"start_time": "2020-07-06T21:55:18.129Z",
|
|
"start_time_in_millis": 1593093628850,
|
|
"end_time": "2020-07-06T21:55:18.129Z",
|
|
"end_time_in_millis": 1593094752018,
|
|
"duration_in_millis": 0,
|
|
"failures": [],
|
|
"shards": {
|
|
"total": 0,
|
|
"failed": 0,
|
|
"successful": 0
|
|
}
|
|
}
|
|
]
|
|
}
|
|
]
|
|
}
|
|
----
|
|
// TESTRESPONSE[s/"uuid": "vdRctLCxSketdKb54xw67g"/"uuid": $body.responses.0.snapshots.0.uuid/]
|
|
// TESTRESPONSE[s/"version_id": <version_id>/"version_id": $body.responses.0.snapshots.0.version_id/]
|
|
// TESTRESPONSE[s/"version": <version>/"version": $body.responses.0.snapshots.0.version/]
|
|
// TESTRESPONSE[s/"start_time": "2020-07-06T21:55:18.129Z"/"start_time": $body.responses.0.snapshots.0.start_time/]
|
|
// TESTRESPONSE[s/"start_time_in_millis": 1593093628850/"start_time_in_millis": $body.responses.0.snapshots.0.start_time_in_millis/]
|
|
// TESTRESPONSE[s/"end_time": "2020-07-06T21:55:18.129Z"/"end_time": $body.responses.0.snapshots.0.end_time/]
|
|
// TESTRESPONSE[s/"end_time_in_millis": 1593094752018/"end_time_in_millis": $body.responses.0.snapshots.0.end_time_in_millis/]
|
|
// TESTRESPONSE[s/"duration_in_millis": 0/"duration_in_millis": $body.responses.0.snapshots.0.duration_in_millis/]
|