CAT segment replication

Introduced 2.7

The CAT segment replication operation returns information about active and last completed segment replication events on each replica shard, including related shard-level metrics. These metrics provide information about how far behind the primary shard the replicas are lagging.

Call the CAT Segment Replication API only on indexes with segment replication enabled.

Path and HTTP methods

GET /_cat/segment_replication
GET /_cat/segment_replication/<index>

Path parameters

The following table lists the available optional path parameter.

Query parameters

The CAT segment replication API operation supports the following optional query parameters.

Examples

The following examples illustrate various segment replication responses.

Example 1: No active segment replication events

The following query requests segment replication metrics with column headings for all indexes:

GET /_cat/segment_replication?v=true

The response contains the metrics for the preceding request:

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

Example 2: Shard ID specified

The following query requests segment replication metrics with column headings for shards with the ID 0 from indexes index1 and index2:

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

The response contains the metrics for the preceding request. The column headings correspond to the metric names:

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

Example 3: Detailed response

The following query requests detailed segment replication metrics with column headings for all indexes:

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

The response contains additional metrics about the files and stages of a segment replication event:

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

Example 4: Sorting the results

The following query requests segment replication metrics with column headings for all indexes, sorted by shard ID in descending order:

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

The response contains the sorted results:

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

Example 5: Using a metric alias

In a request, you can either use a metric’s full name or one of its aliases. The following query is the same as the preceding query, but it uses the alias s instead of shardID for sorting:

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

Response metrics

The following table lists the response metrics that are returned for all requests. When referring to a metric in a query parameter, you can provide either the metric’s full name or any of its aliases, as shown in the previous example.

Additional detailed response metrics

The following table lists the additional response fields returned if detailed is set to true.