CAT 세그먼트 복제 API

CAT 세그먼트 복제 API (CAT Segment Replication API)

2.7 버전에서 도입되었어요. CAT segment replication 작업은 각 복제(replica) 샤드에서 활성 및 마지막으로 완료된 세그먼트 복제 이벤트에 대한 정보를 관련 샤드 수준 메트릭과 함께 반환해요. 이 메트릭들은 복제본이 기본(primary) 샤드보다 얼마나 뒤처져 있는지에 대한 정보를 제공해요.

CAT Segment Replication API는 세그먼트 복제가 활성화된 인덱스에서만 호출하세요.

출처: 문서

본문

엔드포인트 (Endpoints)

GET /_cat/segment_replication
GET /_cat/segment_replication/{index}

경로 파라미터 (Path parameters)

아래 표는 사용 가능한 경로 파라미터를 정리한 거예요. 모든 경로 파라미터는 선택 사항이에요.

파라미터 데이터 타입 설명
index List 요청 범위를 제한하는 데 사용하는 데이터 스트림, 인덱스, 별칭의 쉼표로 구분된 목록. 와일드카드(*)를 지원해요. 모든 데이터 스트림과 인덱스를 대상으로 하려면 이 파라미터를 생략하거나 * 또는 _all을 사용하세요.

쿼리 파라미터 (Query parameters)

아래 표는 사용 가능한 쿼리 파라미터를 정리한 거예요. 모든 쿼리 파라미터는 선택 사항이에요.

파라미터 데이터 타입 설명 기본값
active_only Boolean true면 응답에 진행 중인 세그먼트 복제 이벤트만 포함돼요. false
allow_no_indices Boolean 와일드카드 인덱스 표현식이 구체적인 인덱스로 해석되지 않을 때 인덱스를 무시할지 여부. 여기에는 _all 문자열 또는 인덱스가 지정되지 않은 경우도 포함돼요. N/A
bytes String 바이트 값을 표시하는 데 사용하는 단위. 유효한 값은 b, kb, k, mb, m, gb, g, tb, t, pb, p예요. N/A
completed_only Boolean true면 응답에 마지막으로 완료된 세그먼트 복제 이벤트만 포함돼요. false
detailed Boolean true면 응답에 세그먼트 복제 이벤트의 각 단계에 대한 추가 메트릭이 포함돼요. false
expand_wildcards List 또는 String 와일드카드 표현식이 매칭할 수 있는 인덱스 타입. 쉼표로 구분된 값을 지원해요. 유효한 값은: - all: 숨겨진 인덱스를 포함한 모든 인덱스와 매칭. - closed: 닫힌, 숨겨지지 않은 인덱스와 매칭. - hidden: 숨겨진 인덱스와 매칭. open, closed 또는 둘 다와 결합해야 해요. - none: 와일드카드 표현식이 허용되지 않음. - open: 열린, 숨겨지지 않은 인덱스와 매칭. N/A
format String json 또는 yaml 같은 Accept 헤더의 짧은 버전. N/A
h List 표시할 열 이름의 쉼표로 구분된 목록. N/A
help Boolean 도움말 정보를 반환해요. false
ignore_throttled Boolean 스로틀링될 때 지정된 구체적, 확장된 또는 별칭된 인덱스를 무시할지 여부. N/A
ignore_unavailable Boolean 지정된 구체적 인덱스가 없거나 닫혀 있을 때 무시할지 여부. N/A
index List 요청 범위를 제한하는 데 사용하는 데이터 스트림, 인덱스, 별칭의 쉼표로 구분된 목록. 와일드카드(*)를 지원해요. 모든 데이터 스트림과 인덱스를 대상으로 하려면 이 파라미터를 생략하거나 * 또는 _all을 사용하세요. N/A
s List 정렬 기준이 될 열 이름 또는 열 별칭의 쉼표로 구분된 목록. N/A
shards List 표시할 샤드의 쉼표로 구분된 목록. N/A
time String 시간 단위를 지정해요. 예: 5d 또는 7h. 자세한 내용은 Supported units 문서를 참고하세요. 유효한 값은 nanos, micros, ms, s, m, h, d예요. N/A
timeout String 작업 타임아웃. N/A
v Boolean 열 머리글을 표시하는 자세한(verbose) 모드를 활성화해요. false

예제 요청 (Example requests)

다음 예제들은 다양한 세그먼트 복제 응답을 보여줘요.

활성 세그먼트 복제 이벤트 없음 (No active segment replication events)

다음 쿼리는 모든 인덱스에 대해 열 머리글이 있는 세그먼트 복제 메트릭을 요청해요:

GET /_cat/segment_replication?v=true

응답에는 앞선 요청의 메트릭이 포함돼요:

shardId target_node target_host checkpoints_behind bytes_behind current_lag last_completed_lag rejected_requests
[index-1][0] runTask-1 127.0.0.1 0 0b 0s 7ms 0

샤드 ID 지정 (Shard ID specified)

다음 쿼리는 index1과 index2에서 ID가 0인 샤드에 대해 열 머리글이 있는 세그먼트 복제 메트릭을 요청해요:

GET /_cat/segment_replication/index1,index2?v=true&shards=0

응답에는 앞선 요청의 메트릭이 포함돼요. 열 머리글은 메트릭 이름과 일치해요:

shardId target_node target_host checkpoints_behind bytes_behind current_lag last_completed_lag rejected_requests
[index-1][0] runTask-1 127.0.0.1 0 0b 0s 3ms 0
[index-2][0] runTask-1 127.0.0.1 0 0b 0s 5ms 0

상세 응답 (Detailed response)

다음 쿼리는 모든 인덱스에 대해 열 머리글이 있는 상세 세그먼트 복제 메트릭을 요청해요:

GET /_cat/segment_replication?v=true&detailed=true

응답에는 세그먼트 복제 이벤트의 파일과 단계에 대한 추가 메트릭이 포함돼요:

shardId target_node target_host checkpoints_behind bytes_behind current_lag last_completed_lag rejected_requests stage time files_fetched files_percent bytes_fetched bytes_percent start_time stop_time files files_total bytes bytes_total replicating_stage_time_taken get_checkpoint_info_stage_time_taken file_diff_stage_time_taken get_files_stage_time_taken finalize_replication_stage_time_taken
[index-1][0] runTask-1 127.0.0.1 0 0b 0s 3ms 0 done 10ms 6 100.0% 4753 100.0% 2023-03-16T13:46:16.802Z 2023-03-16T13:46:16.812Z 6 6 4.6kb 4.6kb 0s 2ms 0s 3ms 3ms
[index-2][0] runTask-1 127.0.0.1 0 0b 0s 5ms 0 done 7ms 3 100.0% 3664 100.0% 2023-03-16T13:53:33.466Z 2023-03-16T13:53:33.474Z 3 3 3.5kb 3.5kb 0s 1ms 0s 2ms 2ms

결과 정렬 (Sorting the results)

다음 쿼리는 모든 인덱스에 대해 열 머리글이 있는 세그먼트 복제 메트릭을 샤드 ID 내림차순으로 정렬해 요청해요:

GET /_cat/segment_replication?v&s=shardId:desc

응답에는 정렬된 결과가 포함돼요:

shardId    target_node  target_host checkpoints_behind bytes_behind current_lag last_completed_lag rejected_requests
[test6][1] runTask-2   127.0.0.1   0                  0b           0s          5ms                0
[test6][0] runTask-2   127.0.0.1   0                  0b           0s          4ms                0

메트릭 별칭 사용 (Using a metric alias)

요청에서 메트릭의 전체 이름 또는 별칭 중 하나를 사용할 수 있어요. 다음 쿼리는 앞선 쿼리와 동일하지만 정렬에 shardID 대신 s 별칭을 사용해요:

GET /_cat/segment_replication?v&s=s:desc

예제 응답 메트릭 (Example response metrics)

아래 표는 모든 요청에 대해 반환되는 응답 메트릭을 정리한 거예요. 쿼리 파라미터에서 메트릭을 참조할 때는 앞선 예제에서 본 것처럼 메트릭의 전체 이름이나 별칭 중 아무거나 제공할 수 있어요.

메트릭 별칭 설명
shardId s 특정 샤드의 ID.
target_host thost 대상 호스트 IP 주소.
target_node tnode 대상 노드 이름.
checkpoints_behind cpb 복제 샤드가 기본 샤드보다 뒤처진 체크포인트 수.
bytes_behind bb 복제 샤드가 기본 샤드보다 뒤처진 바이트 수.
current_lag clag 복제 샤드가 기본 샤드를 따라잡기를 기다리는 동안 경과한 시간.
last_completed_lag lcl 복제 샤드가 최신 기본 샤드 리프레시를 따라잡는 데 걸린 시간.
rejected_requests rr 복제 그룹에 대해 거부된 요청 수.

추가 상세 응답 메트릭 (Additional detailed response metrics)

아래 표는 detailed가 true로 설정되었을 때 반환되는 추가 응답 필드를 정리한 거예요.

메트릭 별칭 설명
stage st 세그먼트 복제 이벤트의 현재 단계.
time t, ti 세그먼트 복제 이벤트가 완료되는 데 걸린 시간(밀리초).
files_fetched ff 세그먼트 복제 이벤트에 대해 지금까지 가져온 파일 수.
files_percent fp 세그먼트 복제 이벤트에 대해 지금까지 가져온 파일의 백분율.
bytes_fetched bf 세그먼트 복제 이벤트에 대해 지금까지 가져온 바이트 수.
bytes_percent bp 세그먼트 복제 이벤트에 대해 지금까지 가져온 바이트 수(백분율).
start_time start 세그먼트 복제 시작 시간.
stop_time stop 세그먼트 복제 종료 시간.
files f 세그먼트 복제 이벤트에 대해 가져와야 하는 파일 수.
files_total tf 재사용된 파일과 복구된 파일을 모두 포함한 이 리커버리에 포함된 총 파일 수.
bytes b 세그먼트 복제 이벤트에 대해 가져와야 하는 바이트 수.
bytes_total tb 샤드의 총 바이트 수.
replicating_stage_time_taken rstt 세그먼트 복제 이벤트의 replicating 단계가 완료되는 데 걸린 시간.
get_checkpoint_info_stage_time_taken gcistt 세그먼트 복제 이벤트의 get checkpoint info 단계가 완료되는 데 걸린 시간.
file_diff_stage_time_taken fdstt 세그먼트 복제 이벤트의 file diff 단계가 완료되는 데 걸린 시간.
get_files_stage_time_taken gfstt 세그먼트 복제 이벤트의 get files 단계가 완료되는 데 걸린 시간.
finalize_replication_stage_time_taken frstt 세그먼트 복제 이벤트의 finalize replication 단계가 완료되는 데 걸린 시간.

더 알아보기 (Learn more)