Getting Statistics
- reference
XDCR replication-statistics can be returned by the REST API.
HTTP method and URI
GET /pools/default/buckets/<source_or_target_bucket>/stats/ GET /pools/default/buckets/[source_bucket]/stats/[replications/<remote_UUID>/<source_bucket>/<target_bucket>/<statistic_name>]
The endpoint /pools/default/buckets/<source_or_target_bucket>/stats/
returns all statistical information for replications either from or to the specified bucket — depending on whether the replication’s source or target bucket is specified.
Information on a statistic for a replication proceeding from a specific source bucket to a specific target bucket is returned by specifying the source bucket as the value of source_or_target_bucket
and appending the replication-identifier replications/<remote_UUID>/<source_bucket>/<target_bucket>/<statistic_name>
to the URI.
Within the replication-identifier, remote_UUID
is the universally unique identifier for the reference supporting the replication — this can be obtained by means of the GET /pools/default/remoteClusters
method and URI — see Getting a Reference.
The source_bucket
and target_bucket
are the source and target buckets for the replication, respectively.
The statistic_name
specifies the statistic to be returned.
Note that all elements in the replication-identifier following replications
must be encoded: thus, each forward-slash must be represented as %2F
.
A list of the values that can be specified as statistic_name
is provided in Curl Syntax, below.
To return statistics for the source bucket (whether or not the replication-identifier is used), the source cluster’s Full Admin, Cluster Admin, XDCR Inbound, or XDCR Admin role is required. To return statistics for the target bucket, the target cluster’s Full Admin, XDCR Admin, or XDCR Inbound role is required.
Curl Syntax
curl -u <source-or-target-username>:<source-or-target-password> \ -X GET http://[ <source-or-target-ip-address-or-domain-name>:8091\ /pools/default/buckets/<source_or_target_bucket>/stats curl -u <source-username>:<source-password> \ -X GET http://<source-ip-address-or-domain-name>:8091\ /pools/default/buckets/<source_bucket>/stats\ /replications%2F<remote_UUID>%2F<source_bucket>%2F<target_bucket>%2F<statistic_name>
If the replication-identifier is not used, and the target cluster’s IP address or domain-name is applied, the target cluster’s username and password must be provided, and the target bucket must be specified.
The remote_UUID
is the universally unique identifier for the replication, which is obtained by means of the GET /pools/default/remoteClusters
method and URI — see Getting a Reference.
Possible values for statistic_name
that correspond to the source of a replication are as follows:
Statistic | Description |
---|---|
|
Bandwidth used during replication, measured in bytes per second. |
|
Number of updates still pending replication. |
|
Size of data replicated in bytes. |
|
The number of documents checked for changes. |
|
The number of documents that have failed conflict resolution on the source cluster and have not been replicated to the target cluster. |
|
The number of documents that have been filtered out and have not been replicated to the target cluster. |
|
The number of documents sent optimistically. |
|
The number of documents received from DCP. |
|
The number of documents in the replication queue. |
|
The number of documents processed by pipeline, since the start or resumption of the current replication. |
|
The number of documents written to the destination cluster, since the start or resumption of the current replication. |
|
The weighted average time for requesting document metadata. XDCR uses this for conflict resolution, prior to sending the document into the replication queue. |
|
The number of checkpoints issued in the replication queue. |
|
The number of checkpoints failed during replication. |
|
The number of documents received from DCP, per second. |
|
The rate of documents being replicated, measured in documents per second. |
|
The size of the replication queue, in bytes. |
|
The seconds elapsed during replication. |
|
The average time-period to elapse between the point at which a document is ready to be sent from the source to the target, and the point at which the source receives confirmation from the target that the document has been received and successfully written. The average is calculated continuously, from the sum of the elapsed time-periods for the last 1000 documents to have been sent and acknowledged. |
|
The weighted average time for requesting document metadata. XDCR uses this for conflict resolution prior to sending the document into the replication queue. |
Note that when the target bucket is specified as the value of source-or-target-bucket
, a variety of statistics for the target are returned.
For XDCR, the most directly significant is xdcr_ops
, which indicates numbers of write-operations performed.
All the statistics for the target should be returned, and the values for xdcr_ops
retrieved from that output.
Responses
Success returns 200 OK
and an object containing information pertaining to the specified statistic, or to all statistics.
Incorrect specification of any element of the replication-identifier returns 200 OK
and an object containing only metadata: no timestamp or node-statistical information is included.
Incorrect specification of the URI returns 404 Object Not Found
and the message Not found.
Failure to attempt authentication returns 401 Unauthorized
.
Failure to authenticate correctly returns 403 Forbidden
and the message: {"message":"Forbidden. User needs the following permissions","permissions":["cluster.bucket[travel-sample].stats!read"]}
.
Examples
The following examples demonstrate how to return statistical information.
All use source and target buckets named travel_sample
and ts
respectively.
All Statistics
The following example shows how to return all XDCR statistics for the source bucket.
curl -u Administrator:password -X GET \ http://10.144.220.101:8091/pools/default/buckets/travel-sample/stats/
The IP address specifies the source cluster.
If successful, execution returns an object containing all statistical information for the source bucket travel_sample
.
This can be represented in unformatted, truncated form, as follows:
{"op":{"samples":{"couch_total_disk_size":[95122081,95122081,95122081,95122081,95122081,95122081,95122081, 95122081,95122081,95122081,95122081,95122081,95122081,95122081,95122081,95122081,95122081,95122081,95122081, 95122081.....],"couch_docs_fragmentation":[30,30,30,30,30,30.....30],"hit_ratio":[0,0,0,0,0,0,0,0,0,0,0,0, 0,0,0,0,0,0,0.....100],"vb_avg_active_queue_age":[0,0,0,0,0,0,0.... . . . .....274350080]},"samplesCount":60,"isPersistent":true,"lastTStamp":1656087218437,"interval":1000}}
docs_written
The following example shows how to return information provided by the docs_written
statistic.
curl -u Administrator:password \ http://10.5.2.54:8091/pools/default/buckets/default/stats\ /replications%2F8ba6870d88cd72b3f1db113fc8aee675%2Ftravel_sample%2Fts%2Fdocs_written
The IP address specifies the source cluster.
If successful, execution returns output such as the following:
{"samplesCount":60,"isPersistent":true,"lastTStamp":1371685106753,"interval":1000, "timestamp":[1371685048753,1371685049754,1371685050753,1371685051753,1371685052753,1371685053753,1371685054753, 1371685055753,1371685056753,1371685057753,1371685058752,1371685059753,1371685060753,1371685061753,1371685062753, 1371685063753,1371685064753,1371685065753,1371685066753,1371685067753,1371685068753,1371685069753,1371685070753, 1371685071753,1371685072753,1371685073753,1371685074753,1371685075753,1371685076753,1371685077753,1371685078753, 1371685079753,1371685080753,1371685081753,1371685082753,1371685083753,1371685084753,1371685085753,1371685086753, 1371685087753,1371685088753,1371685089753,1371685090753,1371685091754,1371685092753,1371685093753,1371685094753, 1371685095753,1371685096753,1371685097753,1371685098753,1371685099753,1371685100753,1371685101753,1371685102753, 1371685103753,1371685104753,1371685105753,1371685106753], "nodeStats":{"127.0.0.1:8091":[1000000,1000000,1000000,1000000,1000000,1000000,1000000,1000000,1000000,1000000, 1000000,1000000,1000000,1000000,1000000,1000000,1000000,1000000,1000000,1000000,1000000,1000000,1000000,1000000, 1000000,1000000,1000000,1000000,1000000,1000000,1000000,1000000,1000000,1000000,1000000,1000000,1000000,1000000, 1000000,1000000,1000000,1000000,1000000,1000000,1000000,1000000,1000000,1000000,1000000,1000000,1000000,1000000, 1000000,1000000,1000000,1000000,1000000,1000000,1000000]}}
The output shows that 60
samples were taken.
A sample was taken every 1000
milliseconds, and each sample is represented by its timestamp
.
1 million documents are shown already to have been written when the first sample was taken; and this number is shown to have remained consistent at the time of each successive sample.
rate_replicated
The following example returns information from the rate_replicated
statistic.
curl -u Administrator:password \ http://10.5.2.54:8091/pools/default/buckets/default/stats\ /replications%2F8ba6870d88cd72b3f1db113fc8aee675%2Fdefault%2Fdefault%2Frate_replicated
The IP address specifies the source cluster.
If successful, execution provides output such as the following:
{"samplesCount":60,"isPersistent":true,"lastTStamp":1371685006753,"interval":1000, "timestamp":[1371684948753,1371684949753,1371684950753,1371684951753,1371684952753,1371684953753,1371684954753, 1371684955754,1371684956753,1371684957753,1371684958753,1371684959753,1371684960753,1371684961753,1371684962753, 1371684963753,1371684964753,1371684965753,1371684966753,1371684967753,1371684968752,1371684969753,1371684970753, 1371684971753,1371684972753,1371684973753,1371684974753,1371684975753,1371684976753,1371684977753,1371684978753, 1371684979753,1371684980753,1371684981753,1371684982753,1371684983753,1371684984753,1371684985754,1371684986753, 1371684987754,1371684988753,1371684989753,1371684990753,1371684991753,1371684992753,1371684993753,1371684994753, 1371684995753,1371684996753,1371684997753,1371684998776,1371684999753,1371685000753,1371685001753,1371685002753, 1371685003753,1371685004753,1371685005753,1371685006753], "nodeStats":{"127.0.0.1:8091":[0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0, 0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0]}}
docs_opt_repd
The following example returns information from the docs_opt_repd
statistic.
curl -u Administrator:password \ http://10.3.121.119:8091/pools/default/buckets/default/stats\ /replications%2fdef03dbf5e968a47309194ebe052ed21%2ftravel_sample%2fts%2fdocs_opt_repd
The IP address specifies the source cluster.
If execution is successful, output such as the following is returned:
{"samplesCount":60,"isPersistent":true,"lastTStamp":1656078113453,"interval":1000,"timestamp":[1656078054956,1656078055948, 1656078056940,1656078057931,1656078058922,1656078059914,1656078060905,1656078061897,1656078062889,1656078063880,1656078064872, 1656078065863,1656078066854,1656078067846,1656078068837,1656078069828,1656078070820,1656078071812,1656078072804,1656078073795, 1656078074787,1656078075779,1656078076771,1656078077763,1656078078754,1656078079745,1656078080736,1656078081728,1656078082719, 1656078083711,1656078084703,1656078085695,1656078086686,1656078087677,1656078088669,1656078089660,1656078090651,1656078091643, 1656078092634,1656078093625,1656078094617,1656078095608,1656078096599,1656078097591,1656078098582,1656078099573,1656078100565, 1656078101556,1656078102547,1656078103538,1656078104530,1656078105521,1656078106512,1656078107504,1656078108495,1656078109486, 1656078110478,1656078111470,1656078112461,1656078113453],"nodeStats":{"10.144.220.101:8091":[1105,1105,1105,1105,1105,1105,1105, 1105,1105,1105,1105,1105,1105,1105,1105,1105,1105,1105,1105,1105,1105,1105,1105,1105,1105,1105,1105,1105,1105,1105,1105,1105, 1105,1105,1105,1105,1105,1105,1105,1105,1105,1105,1105,1105,1105,1105,1105,1105,1105,1105,1105,1105,1105,1105,1105,1105,1105, 1105,1105,1105]}
Retrieving Incoming Write Operations
The following example returns all the statistics for the target bucket ts
.
curl -u targetUsermane:targetPassword -X GET \ http://10.5.2.117:8091/pools/default/buckets/ts/stats
The IP address specifies the target cluster.
Successful execution returns information on all statistics for ts
.
To retrieve information on incoming write operations, manually locate the array xdc_ops
, within the JSON response.
The value for this attribute is the last sampling of write operations on the target cluster.
{ . . . "xdc_ops":[0.0,0.0,0.0,0.0,633.3666333666333,1687.6876876876877, 2610.3896103896104,3254.254254254254,3861.138861138861,4420.420420420421, . . . }
See Also
See Getting a Reference for information on returning the uuid of a reference. See Cross Data Center Replication (XDCR) for an overview of XDCR.