OpenSearch/docs/reference/ccr/apis/follow/get-follow-stats.asciidoc

[role="xpack"]
[testenv="platinum"]
[[ccr-get-follow-stats]]
=== Get follower stats API
++++
<titleabbrev>Get follower stats</titleabbrev>
++++

Get follower stats.

[[ccr-get-follow-stats-request]]
==== {api-request-title}

//////////////////////////

[source,console]
--------------------------------------------------
PUT /follower_index/_ccr/follow?wait_for_active_shards=1
{
  "remote_cluster" : "remote_cluster",
  "leader_index" : "leader_index"
}
--------------------------------------------------
// TESTSETUP
// TEST[setup:remote_cluster_and_leader_index]

[source,console]
--------------------------------------------------
POST /follower_index/_ccr/pause_follow
--------------------------------------------------
// TEARDOWN

//////////////////////////

[source,console]
--------------------------------------------------
GET /<index>/_ccr/stats
--------------------------------------------------
// TEST[s/<index>/follower_index/]

[[ccr-get-follow-stats-prereqs]]
==== {api-prereq-title}

* If the {es} {security-features} are enabled, you must have `monitor` cluster
privileges on the cluster that contains the follower index. For more information,
see {stack-ov}/security-privileges.html[Security privileges].

[[ccr-get-follow-stats-desc]]
==== {api-description-title}

This API gets follower stats. This API will return shard-level stats about the
following tasks associated with each shard for the specified indices.

[[ccr-get-follow-stats-path-parms]]
==== {api-path-parms-title}

`<index>`::
  (Required, string) A comma-delimited list of index patterns.

[[ccr-get-follow-stats-response-body]]
==== {api-response-body-title}

This API returns the following information:

`indices`::
  (array) An array of follower index statistics.

The `indices` array consists of objects containing two fields:

`indices[].index`::
  (string) The name of the follower index.

`indices[].shards`::
  (array) An array of shard-level following task statistics.

The `shards` array consists of objects containing the following fields:

`indices[].shards[].remote_cluster`::
  (string) The <<modules-remote-clusters,remote cluster>> containing the leader
  index.

`indices[].shards[].leader_index`::
  (string) The name of the index in the leader cluster being followed.

`indices[].shards[].follower_index`::
  (string) The name of the follower index.

`indices[].shards[].shard_id`::
  (integer) The numerical shard ID, with values from 0 to one less than the
  number of replicas.

`indices[].shards[].leader_global_checkpoint`::
  (long) The current global checkpoint on the leader known to the follower task.

`indices[].shards[].leader_max_seq_no`::
  (long) The current maximum sequence number on the leader known to the follower
  task.

`indices[].shards[].follower_global_checkpoint`::
  (long) The current global checkpoint on the follower. The difference between the
  `leader_global_checkpoint` and the `follower_global_checkpoint` is an
  indication of how much the follower is lagging the leader.

`indices[].shards[].follower_max_seq_no`::
  (long) The current maximum sequence number on the follower.

`indices[].shards[].last_requested_seq_no`::
  (long) The starting sequence number of the last batch of operations requested
  from the leader.

`indices[].shards[].outstanding_read_requests`::
  (integer) The number of active read requests from the follower.

`indices[].shards[].outstanding_write_requests`::
  (integer) The number of active bulk write requests on the follower.

`indices[].shards[].write_buffer_operation_count`::
  (integer) The number of write operations queued on the follower.

`indices[].shards[].follower_mapping_version`::
  (long) The mapping version the follower is synced up to.

`indices[].shards[].follower_settings_version`::
  (long) The index settings version the follower is synced up to.

`indices[].shards[].follower_aliases_version`::
  (long) The index aliases version the follower is synced up to.

`indices[].shards[].total_read_time_millis`::
  (long) The total time reads were outstanding, measured from the time a read
  was sent to the leader to the time a reply was returned to the follower.

`indices[].shards[].total_read_remote_exec_time_millis`::
  (long) The total time reads spent executing on the remote cluster.

`indices[].shards[].successful_read_requests`::
  (long) The number of successful fetches.

`indices[].shards[].failed_read_requests`::
  (long) The number of failed reads.

`indices[].shards[].operations_read`::
  (long) The total number of operations read from the leader.

`indices[].shards[].bytes_read`::
  (long) The total of transferred bytes read from the leader.
+
--
NOTE: This is only an estimate and does not account for compression if enabled.

--

`indices[].shards[].total_write_time_millis`::
  (long) The total time spent writing on the follower.

`indices[].shards[].write_buffer_size_in_bytes`::
  (long) The total number of bytes of operations currently queued for writing.

`indices[].shards[].successful_write_requests`::
  (long) The number of bulk write requests executed on the follower.

`indices[].shards[].failed_write_requests`::
  (long) The number of failed bulk write requests executed on the follower.

`indices[].shards[].operations_written`::
  (long) The number of operations written on the follower.

`indices[].shards[].read_exceptions`::
  (array) An array of objects representing failed reads.

The `read_exceptions` array consists of objects containing the following
fields:

`indices[].shards[].read_exceptions[].from_seq_no`::
  (long) The starting sequence number of the batch requested from the leader.

`indices[].shards[].read_exceptions[].retries`::
  (integer) The number of times the batch has been retried.

`indices[].shards[].read_exceptions[].exception`::
  (object) Represents the exception that caused the read to fail.

Continuing with the fields from `shards`:

`indices[].shards[].time_since_last_read_millis`::
  (long) The number of milliseconds since a read request was sent to the leader.
+
--
NOTE: When the follower is caught up to the leader, this number will
  increase up to the configured `read_poll_timeout` at which point another read
  request will be sent to the leader.

--

`indices[].fatal_exception`::
  (object) An object representing a fatal exception that cancelled the following
  task. In this situation, the following task must be resumed manually with the
  <<ccr-post-resume-follow,resume follower API>>.

[[ccr-get-follow-stats-examples]]
==== {api-examples-title}

This example retrieves follower stats:

[source,console]
--------------------------------------------------
GET /follower_index/_ccr/stats
--------------------------------------------------

The API returns the following results:

[source,console-result]
--------------------------------------------------
{
  "indices" : [
    {
      "index" : "follower_index",
      "shards" : [
        {
          "remote_cluster" : "remote_cluster",
          "leader_index" : "leader_index",
          "follower_index" : "follower_index",
          "shard_id" : 0,
          "leader_global_checkpoint" : 1024,
          "leader_max_seq_no" : 1536,
          "follower_global_checkpoint" : 768,
          "follower_max_seq_no" : 896,
          "last_requested_seq_no" : 897,
          "outstanding_read_requests" : 8,
          "outstanding_write_requests" : 2,
          "write_buffer_operation_count" : 64,
          "follower_mapping_version" : 4,
          "follower_settings_version" : 2,
          "follower_aliases_version" : 8,
          "total_read_time_millis" : 32768,
          "total_read_remote_exec_time_millis" : 16384,
          "successful_read_requests" : 32,
          "failed_read_requests" : 0,
          "operations_read" : 896,
          "bytes_read" : 32768,
          "total_write_time_millis" : 16384,
          "write_buffer_size_in_bytes" : 1536,
          "successful_write_requests" : 16,
          "failed_write_requests" : 0,
          "operations_written" : 832,
          "read_exceptions" : [ ],
          "time_since_last_read_millis" : 8
        }
      ]
    }
  ]
}
--------------------------------------------------
// TESTRESPONSE[s/"leader_global_checkpoint" : 1024/"leader_global_checkpoint" : $body.indices.0.shards.0.leader_global_checkpoint/]
// TESTRESPONSE[s/"leader_max_seq_no" : 1536/"leader_max_seq_no" : $body.indices.0.shards.0.leader_max_seq_no/]
// TESTRESPONSE[s/"follower_global_checkpoint" : 768/"follower_global_checkpoint" : $body.indices.0.shards.0.follower_global_checkpoint/]
// TESTRESPONSE[s/"follower_max_seq_no" : 896/"follower_max_seq_no" : $body.indices.0.shards.0.follower_max_seq_no/]
// TESTRESPONSE[s/"last_requested_seq_no" : 897/"last_requested_seq_no" : $body.indices.0.shards.0.last_requested_seq_no/]
// TESTRESPONSE[s/"outstanding_read_requests" : 8/"outstanding_read_requests" : $body.indices.0.shards.0.outstanding_read_requests/]
// TESTRESPONSE[s/"outstanding_write_requests" : 2/"outstanding_write_requests" : $body.indices.0.shards.0.outstanding_write_requests/]
// TESTRESPONSE[s/"write_buffer_operation_count" : 64/"write_buffer_operation_count" : $body.indices.0.shards.0.write_buffer_operation_count/]
// TESTRESPONSE[s/"follower_mapping_version" : 4/"follower_mapping_version" : $body.indices.0.shards.0.follower_mapping_version/]
// TESTRESPONSE[s/"follower_settings_version" : 2/"follower_settings_version" : $body.indices.0.shards.0.follower_settings_version/]
// TESTRESPONSE[s/"follower_aliases_version" : 8/"follower_aliases_version" : $body.indices.0.shards.0.follower_aliases_version/]
// TESTRESPONSE[s/"total_read_time_millis" : 32768/"total_read_time_millis" : $body.indices.0.shards.0.total_read_time_millis/]
// TESTRESPONSE[s/"total_read_remote_exec_time_millis" : 16384/"total_read_remote_exec_time_millis" : $body.indices.0.shards.0.total_read_remote_exec_time_millis/]
// TESTRESPONSE[s/"successful_read_requests" : 32/"successful_read_requests" : $body.indices.0.shards.0.successful_read_requests/]
// TESTRESPONSE[s/"failed_read_requests" : 0/"failed_read_requests" : $body.indices.0.shards.0.failed_read_requests/]
// TESTRESPONSE[s/"operations_read" : 896/"operations_read" : $body.indices.0.shards.0.operations_read/]
// TESTRESPONSE[s/"bytes_read" : 32768/"bytes_read" : $body.indices.0.shards.0.bytes_read/]
// TESTRESPONSE[s/"total_write_time_millis" : 16384/"total_write_time_millis" : $body.indices.0.shards.0.total_write_time_millis/]
// TESTRESPONSE[s/"write_buffer_size_in_bytes" : 1536/"write_buffer_size_in_bytes" : $body.indices.0.shards.0.write_buffer_size_in_bytes/]
// TESTRESPONSE[s/"successful_write_requests" : 16/"successful_write_requests" : $body.indices.0.shards.0.successful_write_requests/]
// TESTRESPONSE[s/"failed_write_requests" : 0/"failed_write_requests" : $body.indices.0.shards.0.failed_write_requests/]
// TESTRESPONSE[s/"operations_written" : 832/"operations_written" : $body.indices.0.shards.0.operations_written/]
// TESTRESPONSE[s/"time_since_last_read_millis" : 8/"time_since_last_read_millis" : $body.indices.0.shards.0.time_since_last_read_millis/]