스냅샷 상태 조회 API

스냅샷 상태 조회 API (Get Snapshot Status API)

스냅샷 생성 중과 생성 후 스냅샷 상태에 대한 세부 정보를 반환해요.

도입 버전 1.0

스냅샷 생성에 대해 알아보려면 Create snapshot을 참고하세요.

Security 플러그인을 사용한다면 monitor_snapshot, create_snapshot 또는 manage cluster 권한이 있어야 해요.

엔드포인트

GET _snapshot/{repository}/{snapshot}/_status

경로 파라미터

경로 파라미터는 선택 사항이에요.

파라미터 데이터 타입 설명
repository String 스냅샷이 들어 있는 저장소예요.
snapshot List 반환할 스냅샷이에요.
index List 응답에 포함할 인덱스예요.

유연성을 제공하는 세 가지 요청 변형이 있어요:

  • GET _snapshot/_status는 모든 저장소에서 현재 실행 중인 모든 스냅샷의 상태를 반환해요.
  • GET _snapshot/<repository>/_status는 지정한 저장소에서 현재 실행 중인 모든 스냅샷을 반환해요. 이 변형이 권장돼요.
  • GET _snapshot/<repository>/<snapshot>/_status는 현재 실행 중인지 여부와 관계없이 지정한 저장소의 특정 스냅샷에 대한 상세 상태 정보를 반환해요.
  • GET /_snapshot/<repository>/<snapshot>/<index>/_status는 지정한 저장소의 특정 스냅샷에 있는 지정한 인덱스에 대해서만 상세 상태 정보를 반환해요. 이 엔드포인트는 특정 스냅샷에 속한 인덱스에 대해서만 작동한다는 점에 주의하세요.

Snapshot API 호출은 요청된 리소스(예: 스냅샷, 그리고 스냅샷에서 만든 인덱스) 전체의 총 샤드 수가 다음 클러스터 설정이 지정하는 한도보다 작을 때만 작동해요:

  • snapshot.max_shards_allowed_in_status_api(동적, 정수): Snapshot Status API 응답에 포함할 수 있는 최대 샤드 수예요. 기본값은 200000이에요. 파일의 총 개수와 크기가 0으로 반환되는 shallow snapshots v2에는 적용되지 않아요.

API를 사용해 현재 실행 중이지 않은 스냅샷의 상태를 반환하는 것은 클라우드의 데이터를 조회할 때 머신 리소스와 처리 시간 측면에서 비용이 매우 많이 들 수 있어요. 스냅샷마다 각 요청이 해당 스냅샷의 모든 샤드에 대한 파일 읽기를 발생시켜요.

요청 본문 필드

필드 데이터 타입 설명
ignore_unavailable Boolean 사용할 수 없는 스냅샷과 인덱스에 대한 요청을 처리하는 방법이에요. false 면 사용할 수 없는 스냅샷과 인덱스에 대해 요청이 오류를 반환해요. true 면 손상되었거나 일시적으로 반환할 수 없는 것 같은 사용할 수 없는 스냅샷과 인덱스를 요청이 무시해요. 기본값은 false 예요.

예제 요청

다음 요청은 my-opensearch-repo 저장소에 있는 my-first-snapshot의 상태를 반환해요. 사용할 수 없는 스냅샷은 무시돼요.

GET /_snapshot/my-opensearch-repo/my-first-snapshot/_status
{
  "ignore_unavailable": true
}

예제 응답

다음 예제는 앞의 예제 요청에 해당하는 응답이에요.

GET _snapshot/my-opensearch-repo/my-first-snapshot/_status 요청은 다음 필드를 반환해요:

{
  "snapshots" : [
    {
      "snapshot" : "my-first-snapshot",
      "repository" : "my-opensearch-repo",
      "uuid" : "dCK4Qth-TymRQ7Tu7Iga0g",
      "state" : "SUCCESS",
      "include_global_state" : true,
      "shards_stats" : {
        "initializing" : 0,
        "started" : 0,
        "finalizing" : 0,
        "done" : 7,
        "failed" : 0,
        "total" : 7
      },
      "stats" : {
        "incremental" : {
          "file_count" : 31,
          "size_in_bytes" : 24488927
        },
        "total" : {
          "file_count" : 31,
          "size_in_bytes" : 24488927
        },
        "start_time_in_millis" : 1660666841667,
        "time_in_millis" : 14054
      },
      "indices" : {
        ".opensearch-observability" : {
          "shards_stats" : {
            "initializing" : 0,
            "started" : 0,
            "finalizing" : 0,
            "done" : 1,
            "failed" : 0,
            "total" : 1
          },
          "stats" : {
            "incremental" : {
              "file_count" : 1,
              "size_in_bytes" : 208
            },
            "total" : {
              "file_count" : 1,
              "size_in_bytes" : 208
            },
            "start_time_in_millis" : 1660666841868,
            "time_in_millis" : 201
          },
          "shards" : {
            "0" : {
              "stage" : "DONE",
              "stats" : {
                "incremental" : {
                  "file_count" : 1,
                  "size_in_bytes" : 208
                },
                "total" : {
                  "file_count" : 1,
                  "size_in_bytes" : 208
                },
                "start_time_in_millis" : 1660666841868,
                "time_in_millis" : 201
              }
            }
          }
        },
        "shakespeare" : {
          "shards_stats" : {
            "initializing" : 0,
            "started" : 0,
            "finalizing" : 0,
            "done" : 1,
            "failed" : 0,
            "total" : 1
          },
          "stats" : {
            "incremental" : {
              "file_count" : 4,
              "size_in_bytes" : 18310117
            },
            "total" : {
              "file_count" : 4,
              "size_in_bytes" : 18310117
            },
            "start_time_in_millis" : 1660666842470,
            "time_in_millis" : 13050
          },
          "shards" : {
            "0" : {
              "stage" : "DONE",
              "stats" : {
                "incremental" : {
                  "file_count" : 4,
                  "size_in_bytes" : 18310117
                },
                "total" : {
                  "file_count" : 4,
                  "size_in_bytes" : 18310117
                },
                "start_time_in_millis" : 1660666842470,
                "time_in_millis" : 13050
              }
            }
          }
        },
        "opensearch_dashboards_sample_data_flights" : {
          "shards_stats" : {
            "initializing" : 0,
            "started" : 0,
            "finalizing" : 0,
            "done" : 1,
            "failed" : 0,
            "total" : 1
          },
          "stats" : {
            "incremental" : {
              "file_count" : 10,
              "size_in_bytes" : 6132245
            },
            "total" : {
              "file_count" : 10,
              "size_in_bytes" : 6132245
            },
            "start_time_in_millis" : 1660666843476,
            "time_in_millis" : 6221
          },
          "shards" : {
            "0" : {
              "stage" : "DONE",
              "stats" : {
                "incremental" : {
                  "file_count" : 10,
                  "size_in_bytes" : 6132245
                },
                "total" : {
                  "file_count" : 10,
                  "size_in_bytes" : 6132245
                },
                "start_time_in_millis" : 1660666843476,
                "time_in_millis" : 6221
              }
            }
          }
        },
        ".opendistro-reports-definitions" : {
          "shards_stats" : {
            "initializing" : 0,
            "started" : 0,
            "finalizing" : 0,
            "done" : 1,
            "failed" : 0,
            "total" : 1
          },
          "stats" : {
            "incremental" : {
              "file_count" : 1,
              "size_in_bytes" : 208
            },
            "total" : {
              "file_count" : 1,
              "size_in_bytes" : 208
            },
            "start_time_in_millis" : 1660666843076,
            "time_in_millis" : 200
          },
          "shards" : {
            "0" : {
              "stage" : "DONE",
              "stats" : {
                "incremental" : {
                  "file_count" : 1,
                  "size_in_bytes" : 208
                },
                "total" : {
                  "file_count" : 1,
                  "size_in_bytes" : 208
                },
                "start_time_in_millis" : 1660666843076,
                "time_in_millis" : 200
              }
            }
          }
        },
        ".opendistro-reports-instances" : {
          "shards_stats" : {
            "initializing" : 0,
            "started" : 0,
            "finalizing" : 0,
            "done" : 1,
            "failed" : 0,
            "total" : 1
          },
          "stats" : {
            "incremental" : {
              "file_count" : 1,
              "size_in_bytes" : 208
            },
            "total" : {
              "file_count" : 1,
              "size_in_bytes" : 208
            },
            "start_time_in_millis" : 1660666841667,
            "time_in_millis" : 201
          },
          "shards" : {
            "0" : {
              "stage" : "DONE",
              "stats" : {
                "incremental" : {
                  "file_count" : 1,
                  "size_in_bytes" : 208
                },
                "total" : {
                  "file_count" : 1,
                  "size_in_bytes" : 208
                },
                "start_time_in_millis" : 1660666841667,
                "time_in_millis" : 201
              }
            }
          }
        },
        ".kibana_1" : {
          "shards_stats" : {
            "initializing" : 0,
            "started" : 0,
            "finalizing" : 0,
            "done" : 1,
            "failed" : 0,
            "total" : 1
          },
          "stats" : {
            "incremental" : {
              "file_count" : 13,
              "size_in_bytes" : 45733
            },
            "total" : {
              "file_count" : 13,
              "size_in_bytes" : 45733
            },
            "start_time_in_millis" : 1660666842673,
            "time_in_millis" : 2007
          },
          "shards" : {
            "0" : {
              "stage" : "DONE",
              "stats" : {
                "incremental" : {
                  "file_count" : 13,
                  "size_in_bytes" : 45733
                },
                "total" : {
                  "file_count" : 13,
                  "size_in_bytes" : 45733
                },
                "start_time_in_millis" : 1660666842673,
                "time_in_millis" : 2007
              }
            }
          }
        },
        ".opensearch-notifications-config" : {
          "shards_stats" : {
            "initializing" : 0,
            "started" : 0,
            "finalizing" : 0,
            "done" : 1,
            "failed" : 0,
            "total" : 1
          },
          "stats" : {
            "incremental" : {
              "file_count" : 1,
              "size_in_bytes" : 208
            },
            "total" : {
              "file_count" : 1,
              "size_in_bytes" : 208
            },
            "start_time_in_millis" : 1660666842270,
            "time_in_millis" : 200
          },
          "shards" : {
            "0" : {
              "stage" : "DONE",
              "stats" : {
                "incremental" : {
                  "file_count" : 1,
                  "size_in_bytes" : 208
                },
                "total" : {
                  "file_count" : 1,
                  "size_in_bytes" : 208
                },
                "start_time_in_millis" : 1660666842270,
                "time_in_millis" : 200
              }
            }
          }
        }
      }
    }
  ]
}

응답 본문 필드

필드 데이터 타입 설명
repository String 스냅샷이 들어 있는 저장소의 이름이에요.
snapshot String 스냅샷 이름이에요.
uuid String 스냅샷의 범용 고유 식별자(UUID)예요.
state String 스냅샷의 현재 상태예요. 스냅샷 상태 를 참고하세요.
include_global_state Boolean 현재 클러스터 상태가 스냅샷에 포함되는지 여부예요.
shards_stats Object 스냅샷의 샤드 수예요. 샤드 통계 를 참고하세요.
stats Object 스냅샷에 포함된 파일에 대한 정보예요. file_count : 파일 수. size_in_bytes : 모든 파일의 총 크기. 스냅샷 파일 통계 를 참고하세요.
index 객체 목록 스냅샷의 인덱스에 대한 정보를 담은 객체 목록이에요. 인덱스 객체 를 참고하세요.

스냅샷 상태 (Snapshot states)

상태 설명
FAILED 스냅샷이 오류로 종료되었고 저장된 데이터가 없어요.
IN_PROGRESS 스냅샷이 현재 실행 중이에요.
PARTIAL 전역 클러스터 상태는 저장되었지만 하나 이상의 샤드 데이터는 저장되지 않았어요. Create snapshot 응답의 failures 속성에 추가 세부 정보가 있어요.
SUCCESS 스냅샷이 완료되었고 모든 샤드가 성공적으로 저장되었어요.

샤드 통계 (Shard stats)

모든 속성 값은 정수예요.

속성 설명
initializing 아직 초기화 중인 샤드 수예요.
started 시작되었지만 아직 마무리되지 않은 샤드 수예요.
finalizing 마무리 중이지만 완료되지 않은 샤드 수예요.
done 초기화, 시작, 마무리를 모두 성공적으로 완료한 샤드 수예요.
failed 스냅샷에 포함되지 못한 샤드 수예요.
total 스냅샷에 포함된 총 샤드 수예요.

스냅샷 파일 통계 (Snapshot file stats)

속성 유형 설명
incremental Object 스냅샷 생성 중 아직 복사해야 할 파일의 개수와 크기예요. 완료된 스냅샷의 경우 incremental는 이미 저장소에 없어 증분 스냅샷의 일부로 복사된 파일의 개수와 크기를 제공해요.
processed Object 이미 스냅샷에 업로드된 파일의 개수와 크기예요. 파일이 업로드된 후 stats의 processed file_count 와 size_in_bytes 가 증가해요.
total Object 스냅샷이 참조하는 총 파일 개수와 크기예요.
start_time_in_millis Long 스냅샷 생성이 시작된 시간(밀리초)이에요.
time_in_millis Long 스냅샷이 완료되는 데 걸린 총 시간(밀리초)이에요.

인덱스 객체 (Index objects)

속성 유형 설명
shards_stats Object 샤드 통계 를 참고하세요.
stats Object 스냅샷 파일 통계 를 참고하세요.
shards 객체 목록 스냅샷에 포함된 샤드에 대한 정보를 담고 있어요. OpenSearch는 샤드에 대해 다음 속성을 반환해요. stage : 스냅샷 안의 샤드 현재 상태. 샤드 상태는 다음과 같아요: * DONE: 스냅샷에서 저장소에 성공적으로 저장된 샤드 수. * FAILURE: 스냅샷에서 저장소에 성공적으로 저장되지 않은 샤드 수. * FINALIZE: 스냅샷에서 저장소에 저장되는 마무리 단계에 있는 샤드 수. * INIT: 스냅샷에서 저장소에 저장되는 초기화 단계에 있는 샤드 수. * STARTED: 스냅샷에서 저장소에 저장되는 시작 단계에 있는 샤드 수. stats : 스냅샷 파일 통계 를 참고하세요. total : 스냅샷이 참조하는 총 파일 개수와 크기. start_time_in_millis : 스냅샷 생성이 시작된 시간(밀리초). time_in_millis : 스냅샷이 완료되는 데 걸린 총 시간(밀리초).

필요한 권한

Security 플러그인을 사용한다면 적절한 권한이 있는지 확인하세요: cluster:admin/snapshot/status 및 cluster:admin/snapshot/status*.

출처: 문서