.. Licensed 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. .. _api/server/root: ===== ``/`` ===== .. http:get:: / :synopsis: Returns the welcome message and version information Accessing the root of a CouchDB instance returns meta information about the instance. The response is a JSON structure containing information about the server, including a welcome message and the version of the server. :
header Content-Type: - :mimetype:`application/json` - :mimetype:`text/plain; charset=utf-8` :code 200: Request completed successfully **Request**: .. code-block:: http GET / HTTP/1.1 Accept: application/json Host: localhost:5984 **Response**: .. code-block:: http HTTP/1.1 200 OK Cache-Control: must-revalidate Content-Length: 179 Content-Type: application/json Date: Sat, 10 Aug 2013 06:33:33 GMT Server: CouchDB (Erlang/OTP) { "couchdb": "Welcome", "uuid": "85fb71bf700c17267fef77535820e371", "vendor": { "name": "The Apache Software Foundation", "version": "1.3.1" }, "version": "1.3.1" } .. _api/server/active_tasks: ================== ``/_active_tasks`` ================== .. versionchanged:: 2.1.0 Because of how the scheduling replicator works, continuous replication jobs could be periodically stopped and then started later. When they are not running they will not appear in the ``_active_tasks`` endpoint .. versionchanged:: 3.3 Added `"bulk_get_attempts"` and `"bulk_get_docs"` fields for replication jobs. .. http:get:: /_active_tasks :synopsis: Obtains a list of the tasks running in the server List of running tasks, including the task type, name, status and process ID. The result is a JSON array of the currently running tasks, with each task being described with a single object. Depending on operation type set of response object fields might be different. :
header Content-Type: - :mimetype:`application/json` - :mimetype:`text/plain; charset=utf-8` :>json number changes_done: Processed changes :>json string database: Source database :>json string pid: Process ID :>json number progress: Current percentage progress :>json number started_on: Task start time as unix timestamp :>json string status: Task status message :>json string task: Task name :>json number total_changes: Total changes to process :>json string type: Operation Type :>json number updated_on: Unix timestamp of last operation update :code 200: Request completed successfully :code 401: CouchDB Server Administrator privileges required **Request**: .. code-block:: http GET /_active_tasks HTTP/1.1 Accept: application/json Host: localhost:5984 **Response**: .. code-block:: http HTTP/1.1 200 OK Cache-Control: must-revalidate Content-Length: 1690 Content-Type: application/json Date: Sat, 10 Aug 2013 06:37:31 GMT Server: CouchDB (Erlang/OTP) [ { "changes_done": 64438, "database": "mailbox", "pid": "<0.12986.1>", "progress": 84, "started_on": 1376116576, "total_changes": 76215, "type": "database_compaction", "updated_on": 1376116619 }, { "changes_done": 14443, "database": "mailbox", "design_document": "c9753817b3ba7c674d92361f24f59b9f", "pid": "<0.10461.3>", "progress": 18, "started_on": 1376116621, "total_changes": 76215, "type": "indexer", "updated_on": 1376116650 }, { "changes_done": 5454, "database": "mailbox", "design_document": "_design/meta", "pid": "<0.6838.4>", "progress": 7, "started_on": 1376116632, "total_changes": 76215, "type": "indexer", "updated_on": 1376116651 }, { "checkpointed_source_seq": 68585, "continuous": false, "doc_id": null, "doc_write_failures": 0, "bulk_get_attempts": 4524, "bulk_get_docs": 4524, "docs_read": 4524, "docs_written": 4524, "missing_revisions_found": 4524, "pid": "<0.1538.5>", "progress": 44, "replication_id": "9bc1727d74d49d9e157e260bb8bbd1d5", "revisions_checked": 4524, "source": "mailbox", "source_seq": 154419, "started_on": 1376116644, "target": "http://mailsrv:5984/mailbox", "type": "replication", "updated_on": 1376116651 } ] .. _api/server/all_dbs: ============= ``/_all_dbs`` ============= .. http:get:: /_all_dbs :synopsis: Returns a list of all the databases Returns a list of all the databases in the CouchDB instance. :
header Content-Type: - :mimetype:`application/json` - :mimetype:`text/plain; charset=utf-8` :code 200: Request completed successfully **Request**: .. code-block:: http GET /_all_dbs HTTP/1.1 Accept: application/json Host: localhost:5984 **Response**: .. code-block:: http HTTP/1.1 200 OK Cache-Control: must-revalidate Content-Length: 52 Content-Type: application/json Date: Sat, 10 Aug 2013 06:57:48 GMT Server: CouchDB (Erlang/OTP) [ "_users", "contacts", "docs", "invoices", "locations" ] .. _api/server/dbs_info: ============== ``/_dbs_info`` ============== .. versionadded:: 3.2 .. http:get:: /_dbs_info :synopsis: Returns all databases information Returns a list of all the databases information in the CouchDB instance. :
header Content-Type: - :mimetype:`application/json` - :mimetype:`text/plain; charset=utf-8` :code 200: Request completed successfully **Request**: .. code-block:: http GET /_dbs_info HTTP/1.1 Accept: application/json Host: localhost:5984 **Response**: .. code-block:: http HTTP/1.1 200 OK Cache-Control: must-revalidate Content-Type: application/json Date: Thu, 18 Nov 2021 14:37:35 GMT Server: CouchDB (Erlang OTP/23) [ { "key": "animals", "info": { "db_name": "animals", "update_seq": "52232", "sizes": { "file": 1178613587, "external": 1713103872, "active": 1162451555 }, "purge_seq": 0, "doc_del_count": 0, "doc_count": 52224, "disk_format_version": 6, "compact_running": false, "cluster": { "q": 8, "n": 3, "w": 2, "r": 2 }, "instance_start_time": "0" } } ] .. versionadded:: 2.2 .. http:post:: /_dbs_info :synopsis: Returns information of a list of the specified databases Returns information of a list of the specified databases in the CouchDB instance. This enables you to request information about multiple databases in a single request, in place of multiple :get:`/{db}` requests. :
header Content-Type: - :mimetype:`application/json` :header Content-Type: - :mimetype:`application/json` - :mimetype:`text/plain; charset=utf-8` :>json string state: Current ``state`` of the node and/or cluster (see below) :code 200: Request completed successfully The ``state`` returned indicates the current node or cluster state, and is one of the following: - ``cluster_disabled``: The current node is completely unconfigured. - ``single_node_disabled``: The current node is configured as a single (standalone) node (``[cluster] n=1``), but either does not have a server-level admin user defined, or does not have the standard system databases created. If the ``ensure_dbs_exist`` query parameter is specified, the list of databases provided overrides the default list of standard system databases. - ``single_node_enabled``: The current node is configured as a single (standalone) node, has a server-level admin user defined, and has the ``ensure_dbs_exist`` list (explicit or default) of databases created. - ``cluster_enabled``: The current node has ``[cluster] n`` > 1, is not bound to ``127.0.0.1`` and has a server-level admin user defined. However, the full set of standard system databases have not been created yet. If the ``ensure_dbs_exist`` query parameter is specified, the list of databases provided overrides the default list of standard system databases. - ``cluster_finished``: The current node has ``[cluster] n`` > 1, is not bound to ``127.0.0.1``, has a server-level admin user defined *and* has the ``ensure_dbs_exist`` list (explicit or default) of databases created. **Request**: .. code-block:: http GET /_cluster_setup HTTP/1.1 Accept: application/json Host: localhost:5984 **Response**: .. code-block:: http HTTP/1.1 200 OK X-CouchDB-Body-Time: 0 X-Couch-Request-ID: 5c058bdd37 Server: CouchDB/2.1.0-7f17678 (Erlang OTP/17) Date: Sun, 30 Jul 2017 06:33:18 GMT Content-Type: application/json Content-Length: 29 Cache-Control: must-revalidate {"state":"cluster_enabled"} .. http:post:: /_cluster_setup :synopsis: Sets up a node as a single node or as part of a cluster. Configure a node as a single (standalone) node, as part of a cluster, or finalise a cluster. :
`_ format. :query number timeout: Number of *milliseconds* until CouchDB closes the connection. Default is ``60000``. :query number heartbeat: Period in *milliseconds* after which an empty line is sent in the results. Only applicable for ``longpoll``, ``continuous``, and ``eventsource`` feeds. Overrides any timeout to keep the feed alive indefinitely. Default is ``60000``. May be ``true`` to use default value. :query string since: Return only updates since the specified sequence ID. If the sequence ID is specified but does not exist, all changes are returned. May be the string ``now`` to begin showing only new updates. :>header Content-Type: - :mimetype:`application/json` - :mimetype:`text/plain; charset=utf-8` :>header Transfer-Encoding: ``chunked`` :>json array results: An array of database events. For ``longpoll`` and ``continuous`` modes, the entire response is the contents of the ``results`` array. :>json string last_seq: The last sequence ID reported. :code 200: Request completed successfully :code 401: CouchDB Server Administrator privileges required The ``results`` field of database updates: :json string db_name: Database name. :json string type: A database event is one of ``created``, ``updated``, ``deleted``. :json json seq: Update sequence of the event. **Request**: .. code-block:: http GET /_db_updates HTTP/1.1 Accept: application/json Host: localhost:5984 **Response**: .. code-block:: http HTTP/1.1 200 OK Cache-Control: must-revalidate Content-Type: application/json Date: Sat, 18 Mar 2017 19:01:35 GMT Etag: "C1KU98Y6H0LGM7EQQYL6VSL07" Server: CouchDB/2.0.0 (Erlang OTP/17) Transfer-Encoding: chunked X-Couch-Request-ID: ad87efc7ff X-CouchDB-Body-Time: 0 { "results":[ {"db_name":"mailbox","type":"created","seq":"1-g1AAAAFReJzLYWBg4MhgTmHgzcvPy09JdcjLz8gvLskBCjMlMiTJ____PyuDOZExFyjAnmJhkWaeaIquGIf2JAUgmWQPMiGRAZcaB5CaePxqEkBq6vGqyWMBkgwNQAqobD4h"}, {"db_name":"mailbox","type":"deleted","seq":"2-g1AAAAFReJzLYWBg4MhgTmHgzcvPy09JdcjLz8gvLskBCjMlMiTJ____PyuDOZEpFyjAnmJhkWaeaIquGIf2JAUgmWQPMiGRAZcaB5CaePxqEkBq6vGqyWMBkgwNQAqobD4hdQsg6vYTUncAou4-IXUPIOpA7ssCAIFHa60"} ], "last_seq": "2-g1AAAAFReJzLYWBg4MhgTmHgzcvPy09JdcjLz8gvLskBCjMlMiTJ____PyuDOZEpFyjAnmJhkWaeaIquGIf2JAUgmWQPMiGRAZcaB5CaePxqEkBq6vGqyWMBkgwNQAqobD4hdQsg6vYTUncAou4-IXUPIOpA7ssCAIFHa60" } .. _api/server/membership: ================ ``/_membership`` ================ .. versionadded:: 2.0 .. http:get:: /_membership :synopsis: Returns a list of nodes Displays the nodes that are part of the cluster as ``cluster_nodes``. The field ``all_nodes`` displays all nodes this node knows about, including the ones that are part of the cluster. The endpoint is useful when setting up a cluster, see :ref:`cluster/nodes` :
header Content-Type: - :mimetype:`application/json` - :mimetype:`text/plain; charset=utf-8` :code 200: Request completed successfully **Request**: .. code-block:: http GET /_membership HTTP/1.1 Accept: application/json Host: localhost:5984 **Response**: .. code-block:: http HTTP/1.1 200 OK Cache-Control: must-revalidate Content-Type: application/json Date: Sat, 11 Jul 2015 07:02:41 GMT Server: CouchDB (Erlang/OTP) Content-Length: 142 { "all_nodes": [ "node1@127.0.0.1", "node2@127.0.0.1", "node3@127.0.0.1" ], "cluster_nodes": [ "node1@127.0.0.1", "node2@127.0.0.1", "node3@127.0.0.1" ] } .. _api/server/replicate: =============== ``/_replicate`` =============== .. versionchanged:: 3.3 Added `"bulk_get_attempts"` and `"bulk_get_docs"` fields to the replication history response object. .. http:post:: /_replicate :synopsis: Starts or cancels the replication Request, configure, or stop, a replication operation. :
`. ``doc_ids``, ``filter``, and ``selector`` are mutually exclusive. :` to filter documents for synchronization. Has the same behavior as the :ref:`selector objects ` in replication documents. ``doc_ids``, ``filter``, and ``selector`` are mutually exclusive. :header Content-Type: - :mimetype:`application/json` - :mimetype:`text/plain; charset=utf-8` :>json array history: Replication history (see below) :>json boolean ok: Replication status :>json number replication_id_version: Replication protocol version :>json string session_id: Unique session ID :>json number source_last_seq: Last sequence number read from source database :code 200: Replication request successfully completed :code 202: Continuous replication request has been accepted :code 400: Invalid JSON data :code 401: CouchDB Server Administrator privileges required :code 404: Either the source or target DB is not found or attempt to cancel unknown replication task :code 500: JSON specification was invalid The specification of the replication request is controlled through the JSON content of the request. The JSON should be an object with the fields defining the source, target and other options. The `Replication history` is an array of objects with following structure: :json number doc_write_failures: Number of document write failures :json number docs_read: Number of documents read :json number docs_written: Number of documents written to target :json number bulk_get_attempts: The total count of attempted doc revisions fetched with ``_bulk_get``. :json number bulk_get_docs: The total count of successful docs fetched with ``_bulk_get``. :json number end_last_seq: Last sequence number in changes stream :json string end_time: Date/Time replication operation completed in :rfc:`2822` format :json number missing_checked: Number of missing documents checked :json number missing_found: Number of missing documents found :json number recorded_seq: Last recorded sequence number :json string session_id: Session ID for this replication operation :json number start_last_seq: First sequence number in changes stream :json string start_time: Date/Time replication operation started in :rfc:`2822` format .. note:: As of CouchDB 2.0.0, fully qualified URLs are required for both the replication ``source`` and ``target`` parameters. **Request** .. code-block:: http POST /_replicate HTTP/1.1 Accept: application/json Content-Length: 80 Content-Type: application/json Host: localhost:5984 { "source": "http://adm:pass@127.0.0.1:5984/db_a", "target": "http://adm:pass@127.0.0.1:5984/db_b" } **Response** .. code-block:: http HTTP/1.1 200 OK Cache-Control: must-revalidate Content-Length: 692 Content-Type: application/json Date: Sun, 11 Aug 2013 20:38:50 GMT Server: CouchDB (Erlang/OTP) { "history": [ { "doc_write_failures": 0, "docs_read": 10, "bulk_get_attempts": 10, "bulk_get_docs": 10, "docs_written": 10, "end_last_seq": 28, "end_time": "Sun, 11 Aug 2013 20:38:50 GMT", "missing_checked": 10, "missing_found": 10, "recorded_seq": 28, "session_id": "142a35854a08e205c47174d91b1f9628", "start_last_seq": 1, "start_time": "Sun, 11 Aug 2013 20:38:50 GMT" }, { "doc_write_failures": 0, "docs_read": 1, "bulk_get_attempts": 1, "bulk_get_docs": 1, "docs_written": 1, "end_last_seq": 1, "end_time": "Sat, 10 Aug 2013 15:41:54 GMT", "missing_checked": 1, "missing_found": 1, "recorded_seq": 1, "session_id": "6314f35c51de3ac408af79d6ee0c1a09", "start_last_seq": 0, "start_time": "Sat, 10 Aug 2013 15:41:54 GMT" } ], "ok": true, "replication_id_version": 3, "session_id": "142a35854a08e205c47174d91b1f9628", "source_last_seq": 28 } Replication Operation ===================== The aim of the replication is that at the end of the process, all active documents on the source database are also in the destination database and all documents that were deleted in the source databases are also deleted (if they exist) on the destination database. Replication can be described as either push or pull replication: - *Pull replication* is where the ``source`` is the remote CouchDB instance, and the ``target`` is the local database. Pull replication is the most useful solution to use if your source database has a permanent IP address, and your destination (local) database may have a dynamically assigned IP address (for example, through DHCP). This is particularly important if you are replicating to a mobile or other device from a central server. - *Push replication* is where the ``source`` is a local database, and ``target`` is a remote database. Specifying the Source and Target Database ========================================= You must use the URL specification of the CouchDB database if you want to perform replication in either of the following two situations: - Replication with a remote database (i.e. another instance of CouchDB on the same host, or a different host) - Replication with a database that requires authentication For example, to request replication between a database local to the CouchDB instance to which you send the request, and a remote database you might use the following request: .. code-block:: http POST http://couchdb:5984/_replicate HTTP/1.1 Content-Type: application/json Accept: application/json { "source" : "recipes", "target" : "http://coucdb-remote:5984/recipes", } In all cases, the requested databases in the ``source`` and ``target`` specification must exist. If they do not, an error will be returned within the JSON object: .. code-block:: javascript { "error" : "db_not_found" "reason" : "could not open http://couchdb-remote:5984/ol1ka/", } You can create the target database (providing your user credentials allow it) by adding the ``create_target`` field to the request object: .. code-block:: http POST http://couchdb:5984/_replicate HTTP/1.1 Content-Type: application/json Accept: application/json { "create_target" : true "source" : "recipes", "target" : "http://couchdb-remote:5984/recipes", } The ``create_target`` field is not destructive. If the database already exists, the replication proceeds as normal. Single Replication ================== You can request replication of a database so that the two databases can be synchronized. By default, the replication process occurs one time and synchronizes the two databases together. For example, you can request a single synchronization between two databases by supplying the ``source`` and ``target`` fields within the request JSON content. .. code-block:: http POST http://couchdb:5984/_replicate HTTP/1.1 Accept: application/json Content-Type: application/json { "source" : "recipes", "target" : "recipes-snapshot", } In the above example, the databases ``recipes`` and ``recipes-snapshot`` will be synchronized. These databases are local to the CouchDB instance where the request was made. The response will be a JSON structure containing the success (or failure) of the synchronization process, and statistics about the process: .. code-block:: javascript { "ok" : true, "history" : [ { "docs_read" : 1000, "bulk_get_attempts": 1000, "bulk_get_docs": 1000, "session_id" : "52c2370f5027043d286daca4de247db0", "recorded_seq" : 1000, "end_last_seq" : 1000, "doc_write_failures" : 0, "start_time" : "Thu, 28 Oct 2010 10:24:13 GMT", "start_last_seq" : 0, "end_time" : "Thu, 28 Oct 2010 10:24:14 GMT", "missing_checked" : 0, "docs_written" : 1000, "missing_found" : 1000 } ], "session_id" : "52c2370f5027043d286daca4de247db0", "source_last_seq" : 1000 } Continuous Replication ====================== Synchronization of a database with the previously noted methods happens only once, at the time the replicate request is made. To have the target database permanently replicated from the source, you must set the ``continuous`` field of the JSON object within the request to true. With continuous replication changes in the source database are replicated to the target database in perpetuity until you specifically request that replication ceases. .. code-block:: http POST http://couchdb:5984/_replicate HTTP/1.1 Accept: application/json Content-Type: application/json { "continuous" : true "source" : "recipes", "target" : "http://couchdb-remote:5984/recipes", } Changes will be replicated between the two databases as long as a network connection is available between the two instances. .. note:: Two keep two databases synchronized with each other, you need to set replication in both directions; that is, you must replicate from ``source`` to ``target``, and separately from ``target`` to ``source``. Canceling Continuous Replication ================================ You can cancel continuous replication by adding the ``cancel`` field to the JSON request object and setting the value to true. Note that the structure of the request must be identical to the original for the cancellation request to be honoured. For example, if you requested continuous replication, the cancellation request must also contain the ``continuous`` field. For example, the replication request: .. code-block:: http POST http://couchdb:5984/_replicate HTTP/1.1 Content-Type: application/json Accept: application/json { "source" : "recipes", "target" : "http://couchdb-remote:5984/recipes", "create_target" : true, "continuous" : true } Must be canceled using the request: .. code-block:: http POST http://couchdb:5984/_replicate HTTP/1.1 Accept: application/json Content-Type: application/json { "cancel" : true, "continuous" : true "create_target" : true, "source" : "recipes", "target" : "http://couchdb-remote:5984/recipes", } Requesting cancellation of a replication that does not exist results in a 404 error. .. _api/server/_scheduler/jobs: ==================== ``/_scheduler/jobs`` ==================== .. http:get:: /_scheduler/jobs :synopsis: Retrieve information about replication jobs List of replication jobs. Includes replications created via :ref:`api/server/replicate` endpoint as well as those created from replication documents. Does not include replications which have completed or have failed to start because replication documents were malformed. Each job description will include source and target information, replication id, a history of recent event, and a few other things. :
header Content-Type: - :mimetype:`application/json` :query number limit: How many results to return :query number skip: How many result to skip starting at the beginning, ordered by replication ID :>json number offset: How many results were skipped :>json number total_rows: Total number of replication jobs :>json string id: Replication ID. :>json string database: Replication document database :>json string doc_id: Replication document ID :>json list history: Timestamped history of events as a list of objects :>json string pid: Replication process ID :>json string node: Cluster node where the job is running :>json string source: Replication source :>json string target: Replication target :>json string start_time: Timestamp of when the replication was started :code 200: Request completed successfully :code 401: CouchDB Server Administrator privileges required **Request**: .. code-block:: http GET /_scheduler/jobs HTTP/1.1 Accept: application/json Host: localhost:5984 **Response**: .. code-block:: http HTTP/1.1 200 OK Cache-Control: must-revalidate Content-Length: 1690 Content-Type: application/json Date: Sat, 29 Apr 2017 05:05:16 GMT Server: CouchDB (Erlang/OTP) { "jobs": [ { "database": "_replicator", "doc_id": "cdyno-0000001-0000003", "history": [ { "timestamp": "2017-04-29T05:01:37Z", "type": "started" }, { "timestamp": "2017-04-29T05:01:37Z", "type": "added" } ], "id": "8f5b1bd0be6f9166ccfd36fc8be8fc22+continuous", "info": { "changes_pending": 0, "checkpointed_source_seq": "113-g1AAAACTeJzLYWBgYMpgTmHgz8tPSTV0MDQy1zMAQsMckEQiQ1L9____szKYE01ygQLsZsYGqcamiZjKcRqRxwIkGRqA1H-oSbZgk1KMLCzTDE0wdWUBAF6HJIQ", "doc_write_failures": 0, "docs_read": 113, "docs_written": 113, "bulk_get_attempts": 113, "bulk_get_docs": 113, "missing_revisions_found": 113, "revisions_checked": 113, "source_seq": "113-g1AAAACTeJzLYWBgYMpgTmHgz8tPSTV0MDQy1zMAQsMckEQiQ1L9____szKYE01ygQLsZsYGqcamiZjKcRqRxwIkGRqA1H-oSbZgk1KMLCzTDE0wdWUBAF6HJIQ", "through_seq": "113-g1AAAACTeJzLYWBgYMpgTmHgz8tPSTV0MDQy1zMAQsMckEQiQ1L9____szKYE01ygQLsZsYGqcamiZjKcRqRxwIkGRqA1H-oSbZgk1KMLCzTDE0wdWUBAF6HJIQ" }, "node": "node1@127.0.0.1", "pid": "<0.1850.0>", "source": "http://myserver.com/foo", "start_time": "2017-04-29T05:01:37Z", "target": "http://adm:*****@localhost:15984/cdyno-0000003/", "user": null }, { "database": "_replicator", "doc_id": "cdyno-0000001-0000002", "history": [ { "timestamp": "2017-04-29T05:01:37Z", "type": "started" }, { "timestamp": "2017-04-29T05:01:37Z", "type": "added" } ], "id": "e327d79214831ca4c11550b4a453c9ba+continuous", "info": { "changes_pending": null, "checkpointed_source_seq": 0, "doc_write_failures": 0, "docs_read": 12, "docs_written": 12, "bulk_get_attempts": 12, "bulk_get_docs": 12, "missing_revisions_found": 12, "revisions_checked": 12, "source_seq": "12-g1AAAACTeJzLYWBgYMpgTmHgz8tPSTV0MDQy1zMAQsMckEQiQ1L9____szKYE1lzgQLsBsZm5pZJJpjKcRqRxwIkGRqA1H-oSexgk4yMkhITjS0wdWUBADfEJBg", "through_seq": "12-g1AAAACTeJzLYWBgYMpgTmHgz8tPSTV0MDQy1zMAQsMckEQiQ1L9____szKYE1lzgQLsBsZm5pZJJpjKcRqRxwIkGRqA1H-oSexgk4yMkhITjS0wdWUBADfEJBg" }, "node": "node2@127.0.0.1", "pid": "<0.1757.0>", "source": "http://myserver.com/foo", "start_time": "2017-04-29T05:01:37Z", "target": "http://adm:*****@localhost:15984/cdyno-0000002/", "user": null } ], "offset": 0, "total_rows": 2 } .. _api/server/_scheduler/docs: ==================== ``/_scheduler/docs`` ==================== .. versionchanged:: 2.1.0 Use this endpoint to monitor the state of document-based replications. Previously needed to poll both documents and ``_active_tasks`` to get a complete state summary .. versionchanged:: 3.0.0 In error states the `"info"` field switched from being a string to being an object .. versionchanged:: 3.3 Added `"bulk_get_attempts"` and `"bulk_get_docs"` the `"info"` object. .. http:get:: /_scheduler/docs :synopsis: Retrieve information about replication documents from the ``_replicator`` database. List of replication document states. Includes information about all the documents, even in ``completed`` and ``failed`` states. For each document it returns the document ID, the database, the replication ID, source and target, and other information. :
header Content-Type: - :mimetype:`application/json` :query number limit: How many results to return :query number skip: How many result to skip starting at the beginning, if ordered by document ID :>json number offset: How many results were skipped :>json number total_rows: Total number of replication documents. :>json string id: Replication ID, or ``null`` if state is ``completed`` or ``failed`` :>json string state: One of following states (see :ref:`replicator/states` for descriptions): ``initializing``, ``running``, ``completed``, ``pending``, ``crashing``, ``error``, ``failed`` :>json string database: Database where replication document came from :>json string doc_id: Replication document ID :>json string node: Cluster node where the job is running :>json string source: Replication source :>json string target: Replication target :>json string start_time: Timestamp of when the replication was started :>json string last_updated: Timestamp of last state update :>json object info: Will contain additional information about the state. For errors, this will be an object with an ``"error"`` field and string value. For success states, see below. :>json number error_count: Consecutive errors count. Indicates how many times in a row this replication has crashed. Replication will be retried with an exponential backoff based on this number. As soon as the replication succeeds this count is reset to 0. To can be used to get an idea why a particular replication is not making progress. :code 200: Request completed successfully :code 401: CouchDB Server Administrator privileges required The ``info`` field of a scheduler doc: :json number revisions_checked: The count of revisions which have been checked since this replication began. :json number missing_revisions_found: The count of revisions which were found on the source, but missing from the target. :json number docs_read: The count of docs which have been read from the source. :json number docs_written: The count of docs which have been written to the target. :json number bulk_get_attempts: The total count of attempted doc revisions fetched with ``_bulk_get``. :json number bulk_get_docs: The total count of successful docs fetched with ``_bulk_get``. :json number changes_pending: The count of changes not yet replicated. :json number doc_write_failures: The count of docs which failed to be written to the target. :json object checkpointed_source_seq: The source sequence id which was last successfully replicated. **Request**: .. code-block:: http GET /_scheduler/docs HTTP/1.1 Accept: application/json Host: localhost:5984 **Response**: .. code-block:: http HTTP/1.1 200 OK Content-Type: application/json Date: Sat, 29 Apr 2017 05:10:08 GMT Server: Server: CouchDB (Erlang/OTP) Transfer-Encoding: chunked { "docs": [ { "database": "_replicator", "doc_id": "cdyno-0000001-0000002", "error_count": 0, "id": "e327d79214831ca4c11550b4a453c9ba+continuous", "info": { "changes_pending": 15, "checkpointed_source_seq": "60-g1AAAACTeJzLYWBgYMpgTmHgz8tPSTV0MDQy1zMAQsMckEQiQ1L9____szKYEyVygQLsBsZm5pZJJpjKcRqRxwIkGRqA1H-oSSpgk4yMkhITjS0wdWUBAENCJEg", "doc_write_failures": 0, "docs_read": 67, "bulk_get_attempts": 67, "bulk_get_docs": 67, "docs_written": 67, "missing_revisions_found": 67, "revisions_checked": 67, "source_seq": "67-g1AAAACTeJzLYWBgYMpgTmHgz8tPSTV0MDQy1zMAQsMckEQiQ1L9____szKYE2VygQLsBsZm5pZJJpjKcRqRxwIkGRqA1H-oSepgk4yMkhITjS0wdWUBAEVKJE8", "through_seq": "67-g1AAAACTeJzLYWBgYMpgTmHgz8tPSTV0MDQy1zMAQsMckEQiQ1L9____szKYE2VygQLsBsZm5pZJJpjKcRqRxwIkGRqA1H-oSepgk4yMkhITjS0wdWUBAEVKJE8" }, "last_updated": "2017-04-29T05:01:37Z", "node": "node2@127.0.0.1", "source_proxy": null, "target_proxy": null, "source": "http://myserver.com/foo", "start_time": "2017-04-29T05:01:37Z", "state": "running", "target": "http://adm:*****@localhost:15984/cdyno-0000002/" }, { "database": "_replicator", "doc_id": "cdyno-0000001-0000003", "error_count": 0, "id": "8f5b1bd0be6f9166ccfd36fc8be8fc22+continuous", "info": { "changes_pending": null, "checkpointed_source_seq": 0, "doc_write_failures": 0, "bulk_get_attempts": 12, "bulk_get_docs": 12, "docs_read": 12, "docs_written": 12, "missing_revisions_found": 12, "revisions_checked": 12, "source_seq": "12-g1AAAACTeJzLYWBgYMpgTmHgz8tPSTV0MDQy1zMAQsMckEQiQ1L9____szKYE1lzgQLsBsZm5pZJJpjKcRqRxwIkGRqA1H-oSexgk4yMkhITjS0wdWUBADfEJBg", "through_seq": "12-g1AAAACTeJzLYWBgYMpgTmHgz8tPSTV0MDQy1zMAQsMckEQiQ1L9____szKYE1lzgQLsBsZm5pZJJpjKcRqRxwIkGRqA1H-oSexgk4yMkhITjS0wdWUBADfEJBg" }, "last_updated": "2017-04-29T05:01:37Z", "node": "node1@127.0.0.1", "source_proxy": null, "target_proxy": null, "source": "http://myserver.com/foo", "start_time": "2017-04-29T05:01:37Z", "state": "running", "target": "http://adm:*****@localhost:15984/cdyno-0000003/" } ], "offset": 0, "total_rows": 2 } .. http:get:: /_scheduler/docs/{replicator_db} :synopsis: Retrieve information about replication documents from a specific replicator database. Get information about replication documents from a replicator database. The default replicator database is ``_replicator`` but other replicator databases can exist if their name ends with the suffix ``/_replicator``. .. note:: As a convenience slashes (``/``) in replicator db names do not have to be escaped. So ``/_scheduler/docs/other/_replicator`` is valid and equivalent to ``/_scheduler/docs/other%2f_replicator`` :
header Content-Type: - :mimetype:`application/json` :query number limit: How many results to return :query number skip: How many result to skip starting at the beginning, if ordered by document ID :>json number offset: How many results were skipped :>json number total_rows: Total number of replication documents. :>json string id: Replication ID, or ``null`` if state is ``completed`` or ``failed`` :>json string state: One of following states (see :ref:`replicator/states` for descriptions): ``initializing``, ``running``, ``completed``, ``pending``, ``crashing``, ``error``, ``failed`` :>json string database: Database where replication document came from :>json string doc_id: Replication document ID :>json string node: Cluster node where the job is running :>json string source: Replication source :>json string target: Replication target :>json string start_time: Timestamp of when the replication was started :>json string last_update: Timestamp of last state update :>json object info: Will contain additional information about the state. For errors, this will be an object with an ``"error"`` field and string value. For success states, see below. :>json number error_count: Consecutive errors count. Indicates how many times in a row this replication has crashed. Replication will be retried with an exponential backoff based on this number. As soon as the replication succeeds this count is reset to 0. To can be used to get an idea why a particular replication is not making progress. :code 200: Request completed successfully :code 401: CouchDB Server Administrator privileges required The ``info`` field of a scheduler doc: :json number revisions_checked: The count of revisions which have been checked since this replication began. :json number missing_revisions_found: The count of revisions which were found on the source, but missing from the target. :json number docs_read: The count of docs which have been read from the source. :json number docs_written: The count of docs which have been written to the target. :json number bulk_get_attempts: The total count of attempted doc revisions fetched with ``_bulk_get``. :json number bulk_get_docs: The total count of successful docs fetched with ``_bulk_get``. :json number changes_pending: The count of changes not yet replicated. :json number doc_write_failures: The count of docs which failed to be written to the target. :json object checkpointed_source_seq: The source sequence id which was last successfully replicated. **Request**: .. code-block:: http GET /_scheduler/docs/other/_replicator HTTP/1.1 Accept: application/json Host: localhost:5984 **Response**: .. code-block:: http HTTP/1.1 200 OK Content-Type: application/json Date: Sat, 29 Apr 2017 05:10:08 GMT Server: Server: CouchDB (Erlang/OTP) Transfer-Encoding: chunked { "docs": [ { "database": "other/_replicator", "doc_id": "cdyno-0000001-0000002", "error_count": 0, "id": "e327d79214831ca4c11550b4a453c9ba+continuous", "info": { "changes_pending": 0, "checkpointed_source_seq": "60-g1AAAACTeJzLYWBgYMpgTmHgz8tPSTV0MDQy1zMAQsMckEQiQ1L9____szKYEyVygQLsBsZm5pZJJpjKcRqRxwIkGRqA1H-oSSpgk4yMkhITjS0wdWUBAENCJEg", "doc_write_failures": 0, "docs_read": 67, "bulk_get_attempts": 67, "bulk_get_docs": 67, "docs_written": 67, "missing_revisions_found": 67, "revisions_checked": 67, "source_seq": "67-g1AAAACTeJzLYWBgYMpgTmHgz8tPSTV0MDQy1zMAQsMckEQiQ1L9____szKYE2VygQLsBsZm5pZJJpjKcRqRxwIkGRqA1H-oSepgk4yMkhITjS0wdWUBAEVKJE8", "through_seq": "67-g1AAAACTeJzLYWBgYMpgTmHgz8tPSTV0MDQy1zMAQsMckEQiQ1L9____szKYE2VygQLsBsZm5pZJJpjKcRqRxwIkGRqA1H-oSepgk4yMkhITjS0wdWUBAEVKJE8" }, "last_updated": "2017-04-29T05:01:37Z", "node": "node2@127.0.0.1", "source_proxy": null, "target_proxy": null, "source": "http://myserver.com/foo", "start_time": "2017-04-29T05:01:37Z", "state": "running", "target": "http://adm:*****@localhost:15984/cdyno-0000002/" } ], "offset": 0, "total_rows": 1 } .. http:get:: /_scheduler/docs/{replicator_db}/{docid} :synopsis: Retrieve information about a particular replication document .. note:: As a convenience slashes (``/``) in replicator db names do not have to be escaped. So ``/_scheduler/docs/other/_replicator`` is valid and equivalent to ``/_scheduler/docs/other%2f_replicator`` :
header Content-Type: - :mimetype:`application/json` :>json string id: Replication ID, or ``null`` if state is ``completed`` or ``failed`` :>json string state: One of following states (see :ref:`replicator/states` for descriptions): ``initializing``, ``running``, ``completed``, ``pending``, ``crashing``, ``error``, ``failed`` :>json string database: Database where replication document came from :>json string doc_id: Replication document ID :>json string node: Cluster node where the job is running :>json string source: Replication source :>json string target: Replication target :>json string start_time: Timestamp of when the replication was started :>json string last_update: Timestamp of last state update :>json object info: Will contain additional information about the state. For errors, this will be an object with an ``"error"`` field and string value. For success states, see below. :>json number error_count: Consecutive errors count. Indicates how many times in a row this replication has crashed. Replication will be retried with an exponential backoff based on this number. As soon as the replication succeeds this count is reset to 0. To can be used to get an idea why a particular replication is not making progress. :code 200: Request completed successfully :code 401: CouchDB Server Administrator privileges required The ``info`` field of a scheduler doc: :json number revisions_checked: The count of revisions which have been checked since this replication began. :json number missing_revisions_found: The count of revisions which were found on the source, but missing from the target. :json number docs_read: The count of docs which have been read from the source. :json number docs_written: The count of docs which have been written to the target. :json number bulk_get_attempts: The total count of attempted doc revisions fetched with ``_bulk_get``. :json number bulk_get_docs: The total count of successful docs fetched with ``_bulk_get``. :json number changes_pending: The count of changes not yet replicated. :json number doc_write_failures: The count of docs which failed to be written to the target. :json object checkpointed_source_seq: The source sequence id which was last successfully replicated. **Request**: .. code-block:: http GET /_scheduler/docs/other/_replicator/cdyno-0000001-0000002 HTTP/1.1 Accept: application/json Host: localhost:5984 **Response**: .. code-block:: http HTTP/1.1 200 OK Content-Type: application/json Date: Sat, 29 Apr 2017 05:10:08 GMT Server: Server: CouchDB (Erlang/OTP) Transfer-Encoding: chunked { "database": "other/_replicator", "doc_id": "cdyno-0000001-0000002", "error_count": 0, "id": "e327d79214831ca4c11550b4a453c9ba+continuous", "info": { "changes_pending": 0, "checkpointed_source_seq": "60-g1AAAACTeJzLYWBgYMpgTmHgz8tPSTV0MDQy1zMAQsMckEQiQ1L9____szKYEyVygQLsBsZm5pZJJpjKcRqRxwIkGRqA1H-oSSpgk4yMkhITjS0wdWUBAENCJEg", "doc_write_failures": 0, "docs_read": 67, "bulk_get_attempts": 67, "bulk_get_docs": 67, "docs_written": 67, "missing_revisions_found": 67, "revisions_checked": 67, "source_seq": "67-g1AAAACTeJzLYWBgYMpgTmHgz8tPSTV0MDQy1zMAQsMckEQiQ1L9____szKYE2VygQLsBsZm5pZJJpjKcRqRxwIkGRqA1H-oSepgk4yMkhITjS0wdWUBAEVKJE8", "through_seq": "67-g1AAAACTeJzLYWBgYMpgTmHgz8tPSTV0MDQy1zMAQsMckEQiQ1L9____szKYE2VygQLsBsZm5pZJJpjKcRqRxwIkGRqA1H-oSepgk4yMkhITjS0wdWUBAEVKJE8" }, "last_updated": "2017-04-29T05:01:37Z", "node": "node2@127.0.0.1", "source_proxy": null, "target_proxy": null, "source": "http://myserver.com/foo", "start_time": "2017-04-29T05:01:37Z", "state": "running", "target": "http://adm:*****@localhost:15984/cdyno-0000002/" } .. _api/server/name: ====================== ``/_node/{node-name}`` ====================== .. http:get:: /_node/{node-name} :synopsis: Returns node name The ``/_node/{node-name}`` endpoint can be used to confirm the Erlang node name of the server that processes the request. This is most useful when accessing ``/_node/_local`` to retrieve this information. Repeatedly retrieving this information for a CouchDB endpoint can be useful to determine if a CouchDB cluster is correctly proxied through a reverse load balancer. :
header Content-Type: - :mimetype:`application/json` - :mimetype:`text/plain; charset=utf-8` :code 200: Request completed successfully **Request**: .. code-block:: http GET /_node/_local HTTP/1.1 Accept: application/json Host: localhost:5984 **Response**: .. code-block:: http HTTP/1.1 200 OK Cache-Control: must-revalidate Content-Length: 27 Content-Type: application/json Date: Tue, 28 Jan 2020 19:25:51 GMT Server: CouchDB (Erlang OTP) X-Couch-Request-ID: 5b8db6c677 X-CouchDB-Body-Time: 0 {"name":"node1@127.0.0.1"} .. _api/server/stats: ============================= ``/_node/{node-name}/_stats`` ============================= .. http:get:: /_node/{node-name}/_stats :synopsis: Returns server statistics The ``_stats`` resource returns a JSON object containing the statistics for the running server. The object is structured with top-level sections collating the statistics for a range of entries, with each individual statistic being easily identified, and the content of each statistic is self-describing. Statistics are sampled internally on a :ref:`configurable interval `. When monitoring the ``_stats`` endpoint, you need to use a polling frequency of at least twice this to observe accurate results. For example, if the :ref:`interval ` is 10 seconds, poll ``_stats`` at least every 5 seconds. The literal string ``_local`` serves as an alias for the local node name, so for all stats URLs, ``{node-name}`` may be replaced with ``_local``, to interact with the local node's statistics. :
header Content-Type: - :mimetype:`application/json` - :mimetype:`text/plain; charset=utf-8` :code 200: Request completed successfully **Request**: .. code-block:: http GET /_node/_local/_stats/couchdb/request_time HTTP/1.1 Accept: application/json Host: localhost:5984 **Response**: .. code-block:: http HTTP/1.1 200 OK Cache-Control: must-revalidate Content-Length: 187 Content-Type: application/json Date: Sat, 10 Aug 2013 11:41:11 GMT Server: CouchDB (Erlang/OTP) { "value": { "min": 0, "max": 0, "arithmetic_mean": 0, "geometric_mean": 0, "harmonic_mean": 0, "median": 0, "variance": 0, "standard_deviation": 0, "skewness": 0, "kurtosis": 0, "percentile": [ [ 50, 0 ], [ 75, 0 ], [ 90, 0 ], [ 95, 0 ], [ 99, 0 ], [ 999, 0 ] ], "histogram": [ [ 0, 0 ] ], "n": 0 }, "type": "histogram", "desc": "length of a request inside CouchDB without MochiWeb" } The fields provide the current, minimum and maximum, and a collection of statistical means and quantities. The quantity in each case is not defined, but the descriptions below provide sufficient detail to determine units. Statistics are reported by 'group'. The statistics are divided into the following top-level sections: - ``couch_log``: Logging subsystem - ``couch_replicator``: Replication scheduler and subsystem - ``couchdb``: Primary CouchDB database operations - ``fabric``: Cluster-related operations - ``global_changes``: Global changes feed - ``mem3``: Node membership-related statistics - ``pread``: CouchDB file-related exceptions - ``rexi``: Cluster internal RPC-related statistics The type of the statistic is included in the ``type`` field, and is one of the following: - ``counter``: Monotonically increasing counter, resets on restart - ``histogram``: Binned set of values with meaningful subdivisions. Scoped to the current :ref:`collection interval `. - ``gauge``: Single numerical value that can go up and down You can also access individual statistics by quoting the statistics sections and statistic ID as part of the URL path. For example, to get the ``request_time`` statistics within the ``couchdb`` section for the target node, you can use: .. code-block:: http GET /_node/_local/_stats/couchdb/request_time HTTP/1.1 This returns an entire statistics object, as with the full request, but containing only the requested individual statistic. .. _api/server/prometheus: ================================== ``/_node/{node-name}/_prometheus`` ================================== .. http:get:: /_node/{node-name}/_prometheus :synopsis: Returns server statistics in prometheus format The ``_prometheus`` resource returns a text/plain response that consolidates our :ref:`api/server/stats`, and :ref:`api/server/system` endpoints. The format is determined by `Prometheus `_. The format version is 2.0. **Request**: .. code-block:: http GET /_node/_local/_prometheus HTTP/1.1 Accept: text/plain Host: localhost:5984 **Response**: .. code-block:: http HTTP/1.1 200 OK Cache-Control: must-revalidate Content-Length: 187 Content-Type: text/plain; version=2.0 Date: Sat, 10 May 2020 11:41:11 GMT Server: CouchDB (Erlang/OTP) # TYPE couchdb_couch_log_requests_total counter couchdb_couch_log_requests_total{level="alert"} 0 couchdb_couch_log_requests_total{level="critical"} 0 couchdb_couch_log_requests_total{level="debug"} 0 couchdb_couch_log_requests_total{level="emergency"} 0 couchdb_couch_log_requests_total{level="error"} 0 couchdb_couch_log_requests_total{level="info"} 8 couchdb_couch_log_requests_total{level="notice"} 51 couchdb_couch_log_requests_total{level="warning"} 0 # TYPE couchdb_couch_replicator_changes_manager_deaths_total counter couchdb_couch_replicator_changes_manager_deaths_total 0 # TYPE couchdb_couch_replicator_changes_queue_deaths_total counter couchdb_couch_replicator_changes_queue_deaths_total 0 # TYPE couchdb_couch_replicator_changes_read_failures_total counter couchdb_couch_replicator_changes_read_failures_total 0 # TYPE couchdb_couch_replicator_changes_reader_deaths_total counter couchdb_couch_replicator_changes_reader_deaths_total 0 # TYPE couchdb_couch_replicator_checkpoints_failure_total counter couchdb_couch_replicator_checkpoints_failure_total 0 # TYPE couchdb_couch_replicator_checkpoints_total counter couchdb_couch_replicator_checkpoints_total 0 # TYPE couchdb_couch_replicator_cluster_is_stable gauge couchdb_couch_replicator_cluster_is_stable 1 # TYPE couchdb_couch_replicator_connection_acquires_total counter couchdb_couch_replicator_connection_acquires_total 0 # TYPE couchdb_couch_replicator_connection_closes_total counter couchdb_couch_replicator_connection_closes_total 0 # TYPE couchdb_couch_replicator_connection_creates_total counter couchdb_couch_replicator_connection_creates_total 0 # TYPE couchdb_couch_replicator_connection_owner_crashes_total counter couchdb_couch_replicator_connection_owner_crashes_total 0 # TYPE couchdb_couch_replicator_connection_releases_total counter couchdb_couch_replicator_connection_releases_total 0 # TYPE couchdb_couch_replicator_connection_worker_crashes_total counter couchdb_couch_replicator_connection_worker_crashes_total 0 # TYPE couchdb_couch_replicator_db_scans_total counter couchdb_couch_replicator_db_scans_total 1 # TYPE couchdb_couch_replicator_docs_completed_state_updates_total counter couchdb_couch_replicator_docs_completed_state_updates_total 0 # TYPE couchdb_couch_replicator_docs_db_changes_total counter couchdb_couch_replicator_docs_db_changes_total 0 # TYPE couchdb_couch_replicator_docs_dbs_deleted_total counter couchdb_couch_replicator_docs_dbs_deleted_total 0 # TYPE couchdb_couch_replicator_docs_dbs_found_total counter couchdb_couch_replicator_docs_dbs_found_total 2 # TYPE couchdb_couch_replicator_docs_failed_state_updates_total counter couchdb_couch_replicator_docs_failed_state_updates_total 0 # TYPE couchdb_couch_replicator_failed_starts_total counter couchdb_couch_replicator_failed_starts_total 0 # TYPE couchdb_couch_replicator_jobs_adds_total counter couchdb_couch_replicator_jobs_adds_total 0 # TYPE couchdb_couch_replicator_jobs_crashed gauge couchdb_couch_replicator_jobs_crashed 0 # TYPE couchdb_couch_replicator_jobs_crashes_total counter couchdb_couch_replicator_jobs_crashes_total 0 # TYPE couchdb_couch_replicator_jobs_duplicate_adds_total counter couchdb_couch_replicator_jobs_duplicate_adds_total 0 # TYPE couchdb_couch_replicator_jobs_pending gauge couchdb_couch_replicator_jobs_pending 0 # TYPE couchdb_couch_replicator_jobs_removes_total counter couchdb_couch_replicator_jobs_removes_total 0 # TYPE couchdb_couch_replicator_jobs_running gauge couchdb_couch_replicator_jobs_running 0 # TYPE couchdb_couch_replicator_jobs_starts_total counter couchdb_couch_replicator_jobs_starts_total 0 # TYPE couchdb_couch_replicator_jobs_stops_total counter couchdb_couch_replicator_jobs_stops_total 0 # TYPE couchdb_couch_replicator_jobs_total gauge couchdb_couch_replicator_jobs_total 0 # TYPE couchdb_couch_replicator_requests_total counter couchdb_couch_replicator_requests_total 0 # TYPE couchdb_couch_replicator_responses_failure_total counter couchdb_couch_replicator_responses_failure_total 0 # TYPE couchdb_couch_replicator_responses_total counter couchdb_couch_replicator_responses_total 0 # TYPE couchdb_couch_replicator_stream_responses_failure_total counter couchdb_couch_replicator_stream_responses_failure_total 0 # TYPE couchdb_couch_replicator_stream_responses_total counter couchdb_couch_replicator_stream_responses_total 0 # TYPE couchdb_couch_replicator_worker_deaths_total counter couchdb_couch_replicator_worker_deaths_total 0 # TYPE couchdb_couch_replicator_workers_started_total counter couchdb_couch_replicator_workers_started_total 0 # TYPE couchdb_auth_cache_requests_total counter couchdb_auth_cache_requests_total 0 # TYPE couchdb_auth_cache_misses_total counter couchdb_auth_cache_misses_total 0 # TYPE couchdb_collect_results_time_seconds summary couchdb_collect_results_time_seconds{quantile="0.5"} 0.0 couchdb_collect_results_time_seconds{quantile="0.75"} 0.0 couchdb_collect_results_time_seconds{quantile="0.9"} 0.0 couchdb_collect_results_time_seconds{quantile="0.95"} 0.0 couchdb_collect_results_time_seconds{quantile="0.99"} 0.0 couchdb_collect_results_time_seconds{quantile="0.999"} 0.0 couchdb_collect_results_time_seconds_sum 0.0 couchdb_collect_results_time_seconds_count 0 # TYPE couchdb_couch_server_lru_skip_total counter couchdb_couch_server_lru_skip_total 0 # TYPE couchdb_database_purges_total counter couchdb_database_purges_total 0 # TYPE couchdb_database_reads_total counter couchdb_database_reads_total 0 # TYPE couchdb_database_writes_total counter couchdb_database_writes_total 0 # TYPE couchdb_db_open_time_seconds summary couchdb_db_open_time_seconds{quantile="0.5"} 0.0 couchdb_db_open_time_seconds{quantile="0.75"} 0.0 couchdb_db_open_time_seconds{quantile="0.9"} 0.0 couchdb_db_open_time_seconds{quantile="0.95"} 0.0 couchdb_db_open_time_seconds{quantile="0.99"} 0.0 couchdb_db_open_time_seconds{quantile="0.999"} 0.0 couchdb_db_open_time_seconds_sum 0.0 couchdb_db_open_time_seconds_count 0 # TYPE couchdb_dbinfo_seconds summary couchdb_dbinfo_seconds{quantile="0.5"} 0.0 couchdb_dbinfo_seconds{quantile="0.75"} 0.0 couchdb_dbinfo_seconds{quantile="0.9"} 0.0 couchdb_dbinfo_seconds{quantile="0.95"} 0.0 couchdb_dbinfo_seconds{quantile="0.99"} 0.0 couchdb_dbinfo_seconds{quantile="0.999"} 0.0 couchdb_dbinfo_seconds_sum 0.0 couchdb_dbinfo_seconds_count 0 # TYPE couchdb_document_inserts_total counter couchdb_document_inserts_total 0 # TYPE couchdb_document_purges_failure_total counter couchdb_document_purges_failure_total 0 # TYPE couchdb_document_purges_success_total counter couchdb_document_purges_success_total 0 # TYPE couchdb_document_purges_total_total counter couchdb_document_purges_total_total 0 # TYPE couchdb_document_writes_total counter couchdb_document_writes_total 0 # TYPE couchdb_httpd_aborted_requests_total counter couchdb_httpd_aborted_requests_total 0 # TYPE couchdb_httpd_all_docs_timeouts_total counter couchdb_httpd_all_docs_timeouts_total 0 # TYPE couchdb_httpd_bulk_docs_seconds summary couchdb_httpd_bulk_docs_seconds{quantile="0.5"} 0.0 couchdb_httpd_bulk_docs_seconds{quantile="0.75"} 0.0 couchdb_httpd_bulk_docs_seconds{quantile="0.9"} 0.0 couchdb_httpd_bulk_docs_seconds{quantile="0.95"} 0.0 couchdb_httpd_bulk_docs_seconds{quantile="0.99"} 0.0 couchdb_httpd_bulk_docs_seconds{quantile="0.999"} 0.0 couchdb_httpd_bulk_docs_seconds_sum 0.0 couchdb_httpd_bulk_docs_seconds_count 0 ...remaining couchdb metrics from _stats and _system If an additional port config option is specified, then a client can call this API using that port which does not require authentication. This option is ``false`` (OFF) by default. When the option is ``true`` (ON), the default ports for a 3 node cluster are ``17986``, ``27986``, ``37986``. See :ref:`Configuration of Prometheus Endpoint ` for details. .. code-block:: http GET /_node/_local/_prometheus HTTP/1.1 Accept: text/plain Host: localhost:17986 .. _api/server/smoosh/status: ===================================== ``/_node/{node-name}/_smoosh/status`` ===================================== .. versionadded:: 3.4 .. http:get:: /_node/{node-name}/_smoosh/status :synopsis: Returns metrics of the CouchDB's auto-compaction daemon This prints the state of each channel, how many jobs they are currently running and how many jobs are enqueued (as well as the lowest and highest priority of those enqueued items). The idea is to provide, at a glance, sufficient insight into ``smoosh`` that an operator can assess whether ``smoosh`` is adequately targeting the reclaimable space in the cluster. In general, a healthy status output will have items in the ``ratio_dbs`` and ``ratio_views`` channels. Owing to the default settings, the ``slack_dbs`` and ``slack_views`` will almost certainly have items in them. Historically, we've not found that the slack channels, on their own, are particularly adept at keeping things well compacted. :code 200: Request completed successfully :code 401: CouchDB Server Administrator privileges required **Request**: .. code-block:: http GET /_node/_local/_smoosh/status HTTP/1.1 Host: 127.0.0.1:5984 Accept: */* **Response**: .. code-block:: http HTTP/1.1 200 OK Content-Type: application/json { "channels": { "slack_dbs": { "starting": 0, "waiting": { "size": 0, "min": 0, "max": 0 }, "active": 0 }, "ratio_dbs": { "starting": 0, "waiting": { "size": 56, "min": 1.125, "max": 11.0625 }, "active": 0 }, "ratio_views": { "starting": 0, "waiting": { "size": 0, "min": 0, "max": 0 }, "active": 0 }, "upgrade_dbs": { "starting": 0, "waiting": { "size": 0, "min": 0, "max": 0 }, "active": 0 }, "slack_views": { "starting": 0, "waiting": { "size": 0, "min": 0, "max": 0 }, "active": 0 }, "upgrade_views": { "starting": 0, "waiting": { "size": 0, "min": 0, "max": 0 }, "active": 0 }, "index_cleanup": { "starting": 0, "waiting": { "size": 0, "min": 0, "max": 0 }, "active": 0 } } } .. _api/server/system: ============================== ``/_node/{node-name}/_system`` ============================== .. http:get:: /_node/{node-name}/_system :synopsis: Returns system-level server statistics The ``_system`` resource returns a JSON object containing various system-level statistics for the running server. The object is structured with top-level sections collating the statistics for a range of entries, with each individual statistic being easily identified, and the content of each statistic is self-describing. The literal string ``_local`` serves as an alias for the local node name, so for all stats URLs, ``{node-name}`` may be replaced with ``_local``, to interact with the local node's statistics. :
header Content-Type: - :mimetype:`application/json` - :mimetype:`text/plain; charset=utf-8` :code 200: Request completed successfully **Request**: .. code-block:: http GET /_node/_local/_system HTTP/1.1 Accept: application/json Host: localhost:5984 **Response**: .. code-block:: http HTTP/1.1 200 OK Cache-Control: must-revalidate Content-Length: 187 Content-Type: application/json Date: Sat, 10 Aug 2013 11:41:11 GMT Server: CouchDB (Erlang/OTP) { "uptime": 259, "memory": {} } These statistics are generally intended for CouchDB developers only. .. _api/server/restart: =============================== ``/_node/{node-name}/_restart`` =============================== .. http:post:: /_node/{node-name}/_restart :synopsis: Restarts CouchDB application on a given node This API is to facilitate integration testing only it is not meant to be used in production :code 200: Request completed successfully .. _api/server/versions: ================================ ``/_node/{node-name}/_versions`` ================================ .. http:get:: /_node/{node-name}/_versions :synopsis: Returns system-level server version informations The ``_versions`` resource returns a JSON object containing various system-level informations for the running server. The literal string ``_local`` serves as an alias for the local node name, so for all stats URLs, ``{node-name}`` may be replaced with ``_local``, to interact with the local node's informations. :
header Content-Type: - :mimetype:`application/json` :code 200: Request completed successfully **Request**: .. code-block:: http GET /_node/_local/_versions HTTP/1.1 Accept: application/json Host: localhost:5984 **Response**: .. code-block:: http HTTP/1.1 200 OK Cache-Control: must-revalidate Content-Length: 368 Content-Type: application/json Date: Sat, 03 Sep 2022 08:12:12 GMT Server: CouchDB/3.2.2-ea382cf (Erlang OTP/25) { "javascript_engine": { "version": "91", "name": "spidermonkey" }, "erlang": { "version": "25.0.4", "supported_hashes": [ "sha", "sha224", "sha256", ] }, "collation_driver": { "name": "libicu", "library_version": "70.1", "collator_version": "153.112", "collation_algorithm_version": "14" } } .. _api/server/search_analyze: ========================================== ``/_search_analyze`` ========================================== .. warning:: Search endpoints require a running search plugin connected to each cluster node. See :ref:`Search Plugin Installation ` for details. .. versionadded:: 3.0 .. http:post:: /_search_analyze :synopsis: Tests the results of analyzer tokenization Tests the results of Lucene analyzer tokenization on sample text. :param analyzer: Type of analyzer :param text: Analyzer token you want to test :code 200: Request completed successfully :code 400: Request body is wrong (malformed or missing one of the mandatory fields) :code 500: A server error (or other kind of error) occurred **Request**: .. code-block:: http POST /_search_analyze HTTP/1.1 Host: localhost:5984 Content-Type: application/json {"analyzer":"english", "text":"running"} **Response**: .. code-block:: javascript { "tokens": [ "run" ] } .. _api/server/nouveau_analyze: ========================================== ``/_nouveau_analyze`` ========================================== .. warning:: Nouveau is an experimental feature. Future releases might change how the endpoints work and might invalidate existing indexes. .. warning:: Nouveau endpoints require a running nouveau server. See :ref:`Nouveau Server Installation ` for details. .. versionadded:: 4.0 .. http:post:: /_nouveau_analyze :synopsis: Tests the results of analyzer tokenization Tests the results of Lucene analyzer tokenization on sample text. :param analyzer: Name of analyzer :param text: Analyzer token you want to test :code 200: Request completed successfully :code 400: Request body is wrong (malformed or missing one of the mandatory fields) :code 500: A server error (or other kind of error) occurred **Request**: .. code-block:: http POST /_nouveau_analyze HTTP/1.1 Host: localhost:5984 Content-Type: application/json {"analyzer":"english", "text":"running"} **Response**: .. code-block:: javascript { "tokens": [ "run" ] } .. _api/server/utils: =========== ``/_utils`` =========== .. http:get:: /_utils :synopsis: Redirects to /_utils/ Accesses the built-in Fauxton administration interface for CouchDB. :>header Location: New URI location :code 301: Redirects to :get:`/_utils/` .. http:get:: /_utils/ :synopsis: CouchDB administration interface (Fauxton) :>header Content-Type: :mimetype:`text/html` :>header Last-Modified: Static files modification timestamp :code 200: Request completed successfully .. _api/server/up: ======== ``/_up`` ======== .. versionadded:: 2.0 .. http:get:: /_up :synopsis: Health check endpoint Confirms that the server is up, running, and ready to respond to requests. If :config:option:`maintenance_mode ` is ``true`` or ``nolb``, the endpoint will return a 404 response. :>header Content-Type: :mimetype:`application/json` :code 200: Request completed successfully :code 404: The server is unavailable for requests at this time. **Response**: .. code-block:: http HTTP/1.1 200 OK Cache-Control: must-revalidate Content-Length: 16 Content-Type: application/json Date: Sat, 17 Mar 2018 04:46:26 GMT Server: CouchDB/2.2.0-f999071ec (Erlang OTP/19) X-Couch-Request-ID: c57a3b2787 X-CouchDB-Body-Time: 0 {"status":"ok"} .. _api/server/uuids: =========== ``/_uuids`` =========== .. versionchanged:: 2.0.0 .. http:get:: /_uuids :synopsis: Generates a list of UUIDs from the server Requests one or more Universally Unique Identifiers (UUIDs) from the CouchDB instance. The response is a JSON object providing a list of UUIDs. :
header Content-Type: - :mimetype:`application/json` - :mimetype:`text/plain; charset=utf-8` :>header ETag: Response hash :code 200: Request completed successfully :code 400: Requested more UUIDs than is :config:option:`allowed ` to retrieve **Request**: .. code-block:: http GET /_uuids?count=10 HTTP/1.1 Accept: application/json Host: localhost:5984 **Response**: .. code-block:: http HTTP/1.1 200 OK Content-Length: 362 Content-Type: application/json Date: Sat, 10 Aug 2013 11:46:25 GMT ETag: "DGRWWQFLUDWN5MRKSLKQ425XV" Expires: Fri, 01 Jan 1990 00:00:00 GMT Pragma: no-cache Server: CouchDB (Erlang/OTP) { "uuids": [ "75480ca477454894678e22eec6002413", "75480ca477454894678e22eec600250b", "75480ca477454894678e22eec6002c41", "75480ca477454894678e22eec6003b90", "75480ca477454894678e22eec6003fca", "75480ca477454894678e22eec6004bef", "75480ca477454894678e22eec600528f", "75480ca477454894678e22eec6005e0b", "75480ca477454894678e22eec6006158", "75480ca477454894678e22eec6006161" ] } The UUID type is determined by the :config:option:`UUID algorithm ` setting in the CouchDB configuration. The UUID type may be changed at any time through the :ref:`Configuration API `. For example, the UUID type could be changed to ``random`` by sending this HTTP request: .. code-block:: http PUT http://couchdb:5984/_node/nonode@nohost/_config/uuids/algorithm HTTP/1.1 Content-Type: application/json Accept: */* "random" You can verify the change by obtaining a list of UUIDs: .. code-block:: javascript { "uuids" : [ "031aad7b469956cf2826fcb2a9260492", "6ec875e15e6b385120938df18ee8e496", "cff9e881516483911aa2f0e98949092d", "b89d37509d39dd712546f9510d4a9271", "2e0dbf7f6c4ad716f21938a016e4e59f" ] } .. _api/server/favicon: ================ ``/favicon.ico`` ================ .. http:get:: /favicon.ico :synopsis: Returns the site icon Binary content for the `favicon.ico` site icon. :>header Content-Type: :mimetype:`image/x-icon` :code 200: Request completed successfully :code 404: The requested content could not be found .. _api/server/reshard: ============= ``/_reshard`` ============= .. versionadded:: 2.4 .. http:get:: /_reshard :synopsis: Retrieve summary information about resharding on the cluster Returns a count of completed, failed, running, stopped, and total jobs along with the state of resharding on the cluster. :
header Content-Type: - :mimetype:`application/json` :>json string state: ``stopped`` or ``running`` :>json string state_reason: ``null`` or string describing additional information or reason associated with the state :>json number completed: Count of completed resharding jobs :>json number failed: Count of failed resharding jobs :>json number running: Count of running resharding jobs :>json number stopped: Count of stopped resharding jobs :>json number total: Total count of resharding jobs :code 200: Request completed successfully :code 401: CouchDB Server Administrator privileges required **Request**: .. code-block:: http GET /_reshard HTTP/1.1 Accept: application/json Host: localhost:5984 **Response**: .. code-block:: http HTTP/1.1 200 OK Content-Type: application/json { "completed": 21, "failed": 0, "running": 3, "state": "running", "state_reason": null, "stopped": 0, "total": 24 } .. http:get:: /_reshard/state :synopsis: Retrieve the state of resharding on the cluster Returns the resharding state and optional information about the state. :
header Content-Type: - :mimetype:`application/json` :>json string state: ``stopped`` or ``running`` :>json string state_reason: Additional information or reason associated with the state :code 200: Request completed successfully :code 401: CouchDB Server Administrator privileges required **Request**: .. code-block:: http GET /_reshard/state HTTP/1.1 Accept: application/json Host: localhost:5984 **Response**: .. code-block:: http HTTP/1.1 200 OK Content-Type: application/json { "reason": null, "state": "running" } .. http:put:: /_reshard/state :synopsis: Change resharding state on the cluster Change the resharding state on the cluster. The states are ``stopped`` or ``running``. This starts and stops global resharding on all the nodes of the cluster. If there are any running jobs, they will be stopped when the state changes to ``stopped``. When the state changes back to ``running`` those job will continue running. :
header Content-Type: - :mimetype:`application/json` :json boolean ok: ``true`` :code 200: Request completed successfully :code 400: Invalid request. Could be a bad or missing state name. :code 401: CouchDB Server Administrator privileges required **Request**: .. code-block:: http PUT /_reshard/state HTTP/1.1 Accept: application/json Host: localhost:5984 { "state": "stopped", "reason": "Rebalancing in progress" } **Response**: .. code-block:: http HTTP/1.1 200 OK Content-Type: application/json { "ok": true } .. http:get:: /_reshard/jobs :synopsis: Retrieve information about all the resharding jobs on the cluster .. note:: The shape of the response and the ``total_rows`` and ``offset`` field in particular are meant to be consistent with the ``_scheduler/jobs`` endpoint. :
header Content-Type: - :mimetype:`application/json` :>json list jobs: Array of json objects, one for each resharding job. For the fields of each job see the /_reshard/job/{jobid} endpoint. :>json number offset: Offset in the list of jobs object. Currently hard-coded at ``0``. :>json number total_rows: Total number of resharding jobs on the cluster. :code 200: Request completed successfully :code 401: CouchDB Server Administrator privileges required **Request**: .. code-block:: http GET /_reshard/jobs HTTP/1.1 Accept: application/json **Response**: .. code-block:: http HTTP/1.1 200 OK Content-Type: application/json { "jobs": [ { "history": [ { "detail": null, "timestamp": "2019-03-28T15:28:02Z", "type": "new" }, { "detail": "initial_copy", "timestamp": "2019-03-28T15:28:02Z", "type": "running" } ], "id": "001-171d1211418996ff47bd610b1d1257fc4ca2628868def4a05e63e8f8fe50694a", "job_state": "completed", "node": "node1@127.0.0.1", "source": "shards/00000000-1fffffff/d1.1553786862", "split_state": "completed", "start_time": "2019-03-28T15:28:02Z", "state_info": {}, "target": [ "shards/00000000-0fffffff/d1.1553786862", "shards/10000000-1fffffff/d1.1553786862" ], "type": "split", "update_time": "2019-03-28T15:28:08Z" } ], "offset": 0, "total_rows": 24 } .. http:get:: /_reshard/jobs/{jobid} :synopsis: Retrieve information about a particular resharding job Get information about the resharding job identified by ``jobid``. :
header Content-Type: - :mimetype:`application/json` :>json string id: Job ID. :>json string type: Currently only ``split`` is implemented. :>json string job_state: The running state of the job. Could be one of ``new``, ``running``, ``stopped``, ``completed`` or ``failed``. :>json string split_state: State detail specific to shard splitting. It indicates how far has shard splitting progressed, and can be one of ``new``, ``initial_copy``, ``topoff1``, ``build_indices``, ``topoff2``, ``copy_local_docs``, ``update_shardmap``, ``wait_source_close``, ``topoff3``, ``source_delete`` or ``completed``. :>json object state_info: Optional additional info associated with the current state. :>json string source: For ``split`` jobs this will be the source shard. :>json list target: For ``split`` jobs this will be a list of two or more target shards. :>json list history: List of json objects recording a job's state transition history. :code 200: Request completed successfully :code 401: CouchDB Server Administrator privileges required **Request**: .. code-block:: http GET /_reshard/jobs/001-171d1211418996ff47bd610b1d1257fc4ca2628868def4a05e63e8f8fe50694a HTTP/1.1 Accept: application/json **Response**: .. code-block:: http HTTP/1.1 200 OK Content-Type: application/json { "id": "001-171d1211418996ff47bd610b1d1257fc4ca2628868def4a05e63e8f8fe50694a", "job_state": "completed", "node": "node1@127.0.0.1", "source": "shards/00000000-1fffffff/d1.1553786862", "split_state": "completed", "start_time": "2019-03-28T15:28:02Z", "state_info": {}, "target": [ "shards/00000000-0fffffff/d1.1553786862", "shards/10000000-1fffffff/d1.1553786862" ], "type": "split", "update_time": "2019-03-28T15:28:08Z", "history": [ { "detail": null, "timestamp": "2019-03-28T15:28:02Z", "type": "new" }, { "detail": "initial_copy", "timestamp": "2019-03-28T15:28:02Z", "type": "running" } ] } .. http:post:: /_reshard/jobs :synopsis: Create one or more resharding jobs Depending on what fields are specified in the request, one or more resharding jobs will be created. The response is a json array of results. Each result object represents a single resharding job for a particular node and range. Some of the responses could be successful and some could fail. Successful results will have the ``"ok": true`` key and and value, and failed jobs will have the ``"error": "{error_message}"`` key and value. :
header Content-Type: - :mimetype:`application/json` :json boolean ok: ``true`` if job created successfully. :json boolean ok: ``true`` if the job was removed successfully. :code 200: The job was removed successfully :code 401: CouchDB Server Administrator privileges required :code 404: The job was not found **Request**: .. code-block:: http DELETE /_reshard/jobs/001-171d1211418996ff47bd610b1d1257fc4ca2628868def4a05e63e8f8fe50694a HTTP/1.1 **Response**: .. code-block:: http HTTP/1.1 200 OK Content-Type: application/json { "ok": true } .. http:get:: /_reshard/jobs/{jobid}/state :synopsis: Retrieve the state of a single resharding job Returns the running state of a resharding job identified by ``jobid``. :
header Content-Type: - :mimetype:`application/json` :header Content-Type: - :mimetype:`application/json` :json boolean ok: ``true`` :code 200: Request completed successfully :code 400: Invalid request. Could be a bad state name, for example. :code 401: CouchDB Server Administrator privileges required :code 404: The job was not found **Request**: .. code-block:: http PUT /_reshard/state/001-b3da04f969bbd682faaab5a6c373705cbcca23f732c386bb1a608cfbcfe9faff/state HTTP/1.1 Accept: application/json Host: localhost:5984 { "state": "stopped", "reason": "Rebalancing in progress" } **Response**: .. code-block:: http HTTP/1.1 200 OK Content-Type: application/json { "ok": true }