= CDCR API
// Licensed to the Apache Software Foundation (ASF) under one
// or more contributor license agreements.  See the NOTICE file
// distributed with this work for additional information
// regarding copyright ownership.  The ASF licenses this file
// to you under the Apache License, Version 2.0 (the
// "License"); you may not use this file except in compliance
// with the License.  You may obtain a copy of the License at
//
//   http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing,
// software distributed under the License is distributed on an
// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
// KIND, either express or implied.  See the License for the
// specific language governing permissions and limitations
// under the License.

The CDCR API is used to control and monitor the replication process. Control actions are performed at a collection level, i.e., by using the following base URL for API calls: `\http://localhost:8983/solr/<collection>/cdcr`.

Monitor actions are performed at a core level, i.e., by using the following base URL for API calls: `\http://localhost:8983/solr/<core>/cdcr`.

Currently, none of the CDCR API calls have parameters.

== API Entry Points

*Control*

* `<collection>/cdcr?action=STATUS`: <<CDCR STATUS,Returns the current state>> of CDCR.
* `<collection>/cdcr?action=START`: <<CDCR START,Starts CDCR>> replication
* `<collection>/cdcr?action=STOP`: <<CDCR STOP,Stops CDCR>> replication.
* `<collection>/cdcr?action=ENABLEBUFFER`: <<ENABLEBUFFER,Enables the buffering>> of updates.
* `<collection>/cdcr?action=DISABLEBUFFER`: <<DISABLEBUFFER,Disables the buffering>> of updates.

*Monitoring*

* `core/cdcr?action=QUEUES`: <<QUEUES,Fetches statistics about the queue>> for each replica and about the update logs.
* `core/cdcr?action=OPS`: <<OPS,Fetches statistics about the replication performance>> (operations per second) for each replica.
* `core/cdcr?action=ERRORS`: <<ERRORS,Fetches statistics and other information about replication errors>> for each replica.

== Control Commands

=== CDCR STATUS

`solr/<collection>/cdcr?action=STATUS`

==== CDCR Status Example

*Input*

[source,text]
----
http://localhost:8983/solr/techproducts/cdcr?action=STATUS
----

*Output*

[source,json]
----
{
  "responseHeader": {
  "status": 0,
  "QTime": 0
  },
  "status": {
  "process": "stopped",
  "buffer": "enabled"
  }
}
----

=== ENABLEBUFFER

`solr/<collection>/cdcr?action=ENABLEBUFFER`

==== Enable Buffer Example

*Input*

[source,text]
----
http://localhost:8983/solr/techproducts/cdcr?action=ENABLEBUFFER
----

*Output*

[source,json]
----
{
  "responseHeader": {
  "status": 0,
  "QTime": 0
  },
  "status": {
  "process": "started",
  "buffer": "enabled"
  }
}
----

=== DISABLEBUFFER

`solr/<collection>/cdcr?action=DISABLEBUFFER`

==== Disable Buffer Example

*Input*

[source,text]
----
http://localhost:8983/solr/techproducts/cdcr?action=DISABLEBUFFER
----

*Output*

[source,json]
----
{
  "responseHeader": {
  "status": 0,
  "QTime": 0
  },
  "status": {
  "process": "started",
  "buffer": "disabled"
  }
}
----

=== CDCR START

`solr/<collection>/cdcr?action=START`

==== CDCR Start Examples

*Input*

[source,text]
----
http://localhost:8983/solr/techproducts/cdcr?action=START
----

*Output*

[source,json]
----
{
  "responseHeader": {
  "status": 0,
  "QTime": 0
  },
  "status": {
  "process": "started",
  "buffer": "enabled"
  }
}
----

=== CDCR STOP

`solr/<collection>/cdcr?action=STOP`

==== CDCR Stop Examples

*Input*

[source,text]
----
http://localhost:8983/solr/techproducts/cdcr?action=STOP
----

*Output*

[source,json]
----
{
  "responseHeader": {
  "status": 0,
  "QTime": 0
  },
  "status": {
  "process": "stopped",
  "buffer": "enabled"
  }
}
----


== CDCR Monitoring Commands

=== QUEUES

`solr/<core>/cdcr?action=QUEUES`

==== QUEUES Response

The output is composed of a list “queues” which contains a list of (ZooKeeper) Target hosts, themselves containing a list of Target collections. For each collection, the current size of the queue and the timestamp of the last update operation successfully processed is provided. The timestamp of the update operation is the original timestamp, i.e., the time this operation was processed on the Source SolrCloud. This allows an estimate the latency of the replication process.

The “queues” object also contains information about the update logs, such as the size (in bytes) of the update logs on disk (`tlogTotalSize`), the number of transaction log files (`tlogTotalCount`) and the status of the update logs synchronizer (`updateLogSynchronizer`).

==== QUEUES Examples

*Input*

[source,text]
----
http://localhost:8983/solr/<replica_name>/cdcr?action=QUEUES
----

*Output*

[source,json]
----
{
  "responseHeader":{
    "status": 0,
    "QTime": 1
  },
  "queues":{
    "127.0.0.1: 40342/solr":{
    "Target_collection":{
        "queueSize": 104,
        "lastTimestamp": "2014-12-02T10:32:15.879Z"
      }
    }
  },
  "tlogTotalSize":3817,
  "tlogTotalCount":1,
  "updateLogSynchronizer": "stopped"
}
----

=== OPS

`solr/<core>/cdcr?action=OPS`


==== OPS Response

Provides the average number of operations as a sum and broken down by adds/deletes.

==== OPS Examples

*Input*

[source,text]
----
http://localhost:8983/solr/<replica_name>/cdcr?action=OPS
----

*Output*

[source,json]
----
{
  "responseHeader":{
    "status":0,
    "QTime":1
  },
  "operationsPerSecond":{
    "127.0.0.1: 59661/solr":{
      "Target_collection":{
          "all": 297.102944952749052,
          "adds": 297.102944952749052,
          "deletes": 0.0
      }
    }
  }
}
----

=== ERRORS

`solr/<core>/cdcr?action=ERRORS`

==== ERRORS Response

Provides the number of consecutive errors encountered by the replicator thread, the number of bad requests or internal errors since the start of the replication process, and a list of the last errors encountered ordered by timestamp.

==== ERRORS Examples

*Input*

[source,text]
----
http://localhost:8983/solr/<replica_name>/cdcr?action=ERRORS
----

*Output*

[source,json]
----
{
  "responseHeader":{
    "status":0,
    "QTime":2
  },
  "errors": {
    "127.0.0.1: 36872/solr":{
      "Target_collection":{
        "consecutiveErrors":3,
        "bad_request":0,
        "internal":3,
        "last":{
          "2014-12-02T11:04:42.523Z":"internal",
          "2014-12-02T11:04:39.223Z":"internal",
          "2014-12-02T11:04:38.22Z":"internal"
        }
      }
    }
  }
}
----
