HTTP interface for clusters

The cluster-specific endpoints let you get information about individual cluster nodes and the cluster as a whole, as well as monitor and administrate cluster deployments

Monitoring

Queries statistics of a DB-Server

allows to query the statistics of a DB-Server in the cluster

GET /_admin/cluster/statistics

Query Parameters

  • DBserver (string, required): The ID of a DB-Server.

Queries the statistics of the given DB-Server

Responses

HTTP 200: is returned when everything went well.

HTTP 400: The DBserver parameter was not specified or is not the ID of a DB-Server.

HTTP 403: The specified server is not a DB-Server.

Queries the health of cluster for monitoring

Returns the health of the cluster as assessed by the supervision (Agency)

GET /_admin/cluster/health

Queries the health of the cluster for monitoring purposes. The response is a JSON object, containing the standard code, error, errorNum, and errorMessage fields as appropriate. The endpoint-specific fields are as follows:

  • ClusterId: A UUID string identifying the cluster
  • Health: An object containing a descriptive sub-object for each node in the cluster.
    • <nodeID>: Each entry in Health will be keyed by the node ID and contain the following attributes:
      • Endpoint: A string representing the network endpoint of the server.
      • Role: The role the server plays. Possible values are "AGENT", "COORDINATOR", and "DBSERVER".
      • CanBeDeleted: Boolean representing whether the node can safely be removed from the cluster.
      • Version: Version String of ArangoDB used by that node.
      • Engine: Storage Engine used by that node.
      • Status: A string indicating the health of the node as assessed by the supervision (Agency). This should be considered primary source of truth for Coordinator and DB-Servers node health. If the node is responding normally to requests, it is "GOOD". If it has missed one heartbeat, it is "BAD". If it has been declared failed by the supervision, which occurs after missing heartbeats for about 15 seconds, it will be marked "FAILED".

      Additionally it will also have the following attributes for:

      Coordinators and DB-Servers

      • SyncStatus: The last sync status reported by the node. This value is primarily used to determine the value of Status. Possible values include "UNKNOWN", "UNDEFINED", "STARTUP", "STOPPING", "STOPPED", "SERVING", "SHUTDOWN".
      • LastAckedTime: ISO 8601 timestamp specifying the last heartbeat received.
      • ShortName: A string representing the shortname of the server, e.g. "Coordinator0001".
      • Timestamp: ISO 8601 timestamp specifying the last heartbeat received. (deprecated)
      • Host: An optional string, specifying the host machine if known.

      Coordinators only

      • AdvertisedEndpoint: A string representing the advertised endpoint, if set. (e.g. external IP address or load balancer, optional)

      Agents

      • Leader: ID of the Agent this node regards as leader.
      • Leading: Whether this Agent is the leader (true) or not (false).
      • LastAckedTime: Time since last acked in seconds.

Responses

HTTP 200: is returned when everything went well.

Endpoints

Get information about all Coordinator endpoints

This API call returns information about all Coordinator endpoints (cluster only).

GET /_api/cluster/endpoints

Returns an object with an attribute endpoints, which contains an array of objects, which each have the attribute endpoint, whose value is a string with the endpoint description. There is an entry for each Coordinator in the cluster. This method only works on Coordinators in cluster mode. In case of an error the error attribute is set to true.

Responses

HTTP 200: is returned when everything went well.

  • error (boolean): boolean flag to indicate whether an error occurred (true in this case)

  • code (integer): the HTTP status code - 200

  • endpoints (array): A list of active cluster endpoints.

    • endpoint (string): The bind of the Coordinator, like tcp://[::1]:8530

HTTP 501: server is not a Coordinator or method was not GET.

Cluster node information

Return id of a server in a cluster

Get to know the internal id of the server

GET /_admin/server/id

Returns the id of a server in a cluster. The request will fail if the server is not running in cluster mode.

Responses

HTTP 200: Is returned when the server is running in cluster mode.

HTTP 500: Is returned when the server is not running in cluster mode.

Return the role of a server in a cluster

Return the role of a server in a cluster

GET /_admin/server/role

Returns the role of a server in a cluster. The role is returned in the role attribute of the result. Possible return values for role are:

  • SINGLE: the server is a standalone server without clustering
  • COORDINATOR: the server is a Coordinator in a cluster
  • PRIMARY: the server is a DB-Server in a cluster
  • SECONDARY: this role is not used anymore
  • AGENT: the server is an Agency node in a cluster
  • UNDEFINED: in a cluster, UNDEFINED is returned if the server role cannot be determined.

Responses

HTTP 200: Is returned in all cases.

  • error (boolean): always false

  • code (integer): the HTTP status code, always 200

  • errorNum (integer): the server error number

  • role (string): one of [ SINGLE, COORDINATOR, PRIMARY, SECONDARY, AGENT, UNDEFINED]

Maintenance

Enable or disable the supervision maintenance mode

Enable or disable the cluster supervision (Agency) maintenance mode

PUT /_admin/cluster/maintenance

This API allows to temporarily enable the supervision maintenance mode. Please be aware that no automatic failovers of any kind will take place while the maintenance mode is enabled. The cluster supervision reactivates itself automatically at some point after disabling it.

To enable the maintenance mode the request body must contain the string "on" (Please note it must be lowercase as well as include the quotes). This will enable the maintenance mode for 60 minutes, i.e. the supervision maintenance will reactivate itself after 60 minutes.

Since ArangoDB 3.8.3 it is possible to enable the maintenance mode for a different duration than 60 minutes, it is possible to send the desired duration value (in seconds) as a string in the request body. For example, sending "7200" (including the quotes) will enable the maintenance mode for 7200 seconds, i.e. 2 hours.

To disable the maintenance mode the request body must contain the string "off" (Please note it must be lowercase as well as include the quotes).

Responses

HTTP 200: is returned when everything went well.

HTTP 400: if the request contained an invalid body

HTTP 501: if the request was sent to a node other than a Coordinator or single-server

HTTP 504: if the request timed out while enabling the maintenance mode

Query the maintenance status of a DB-Server

Check what the maintenance status of a DB-Server is

GET /_admin/cluster/maintenance/{DB-Server-ID}

Path Parameters

  • DB-Server-ID (string, required): The ID of a DB-Server.

Check whether the specified DB-Server is in maintenance mode and until when.

Responses

HTTP 200: The request was successful.

  • error (boolean): Whether an error occurred. false in this case.

  • code (integer): The status code. 200 in this case.

  • result (object): The result object with the status. This attribute is omitted if the DB-Server is in normal mode.

    • Mode (string): The mode of the DB-Server. The value is "maintenance".

    • Until (string): Until what date and time the maintenance mode currently lasts, in the ISO 8601 date/time format.

HTTP 400: if the request contained an invalid body

HTTP 412: if the request was sent to an Agent node

HTTP 504: if the request timed out while enabling the maintenance mode

Enable or disable the DB-Server maintenance mode

Enable or disable the maintenance mode of a DB-Server

PUT /_admin/cluster/maintenance/{DB-Server-ID}

Path Parameters

  • DB-Server-ID (string, required): The ID of a DB-Server.

Request Body

  • mode (string, required): The mode to put the DB-Server in. Possible values:
    • "maintenance"
    • "normal"
  • timeout (integer, optional): After how many seconds the maintenance mode shall automatically end. You can send another request when the DB-Server is already in maintenance mode to extend the timeout.

For rolling upgrades or rolling restarts, DB-Servers can be put into maintenance mode, so that no attempts are made to re-distribute the data in a cluster for such planned events. DB-Servers in maintenance mode are not considered viable failover targets because they are likely restarted soon.

Responses

HTTP 200: The request was successful.

  • error (boolean): Whether an error occurred. false in this case.

  • code (integer): The status code. 200 in this case.

HTTP 400: if the request contained an invalid body

HTTP 412: if the request was sent to an Agency node

HTTP 504: if the request timed out while enabling the maintenance mode

Rebalance

Compute the current cluster imbalance

Computes the current cluster imbalance.

GET /_admin/cluster/rebalance

Computes the current cluster imbalance and returns the result. It additionally shows the amount of ongoing and pending move shard operations.

Responses

HTTP 200: This API returns HTTP 200.

  • code (number): The status code.

  • error (boolean): Whether an error occurred. false in this case.

  • result (object): The result object.

    • leader (object): Information about the leader imbalance.

      • weightUsed (array of integers): The weight of leader shards per DB-Server. A leader has a weight of 1 by default but it is higher if collections can only be moved together because of distributeShardsLike.

      • targetWeight (array of integers): The ideal weight of leader shards per DB-Server.

      • numberShards (array of integers): The number of leader shards per DB-Server.

      • leaderDupl (array of integers): The measure of the leader shard distribution. The higher the number, the worse the distribution.

      • totalWeight (integer): The sum of all weights.

      • imbalance (integer): The measure of the total imbalance. A high value indicates a high imbalance.

      • totalShards (integer): The sum of shards, counting leader shards only.

    • shards (object): Information about the shard imbalance.

      • sizeUsed (array of integers): The size of shards per DB-Server.

      • targetSize (array of integers): The ideal size of shards per DB-Server.

      • numberShards (array of integers): The number of leader and follower shards per DB-Server.

      • totalUsed (integer): The sum of the sizes.

      • totalShards (integer): The sum of shards, counting leader and follower shards.

      • imbalance (integer): The measure of the total imbalance. A high value indicates a high imbalance.

  • pendingMoveShards (number): The number of pending move shard operations.

  • todoMoveShards (number): The number of planned move shard operations.

Compute a set of move shard operations to improve balance

Compute a set of move shard operations to improve balance.

POST /_admin/cluster/rebalance

Request Body

  • version (number, required): Must be set to 1.

  • maximumNumberOfMoves (number, optional): Maximum number of moves to be computed. (Default: 1000)

  • leaderChanges (boolean, optional): Allow leader changes without moving data. (Default: true)

  • moveLeaders (boolean, optional): Allow moving leaders. (Default: false)

  • moveFollowers (boolean, optional): Allow moving followers. (Default: false)

  • piFactor (number, optional): (Default: 256e6)

  • databasesExcluded (array of strings, optional): A list of database names to exclude from the analysis. (Default: [])

Compute a set of move shard operations to improve balance.

Responses

HTTP 200: This API returns HTTP 200.

  • code (number): The status code.

  • error (boolean): Whether an error occurred. false in this case.

  • result (object): The result object.

    • imbalanceBefore (object): Imbalance before the suggested move shard operations are applied.

      • leader (object): Information about the leader imbalance.

        • weightUsed (array of integers): The weight of leader shards per DB-Server. A leader has a weight of 1 by default but it is higher if collections can only be moved together because of distributeShardsLike.

        • targetWeight (array of integers): The ideal weight of leader shards per DB-Server.

        • numberShards (array of integers): The number of leader shards per DB-Server.

        • leaderDupl (array of integers): The measure of the leader shard distribution. The higher the number, the worse the distribution.

        • totalWeight (integer): The sum of all weights.

        • imbalance (integer): The measure of the total imbalance. A high value indicates a high imbalance.

        • totalShards (integer): The sum of shards, counting leader shards only.

      • shards (object): Information about the shard imbalance.

        • sizeUsed (array of integers): The size of shards per DB-Server.

        • targetSize (array of integers): The ideal size of shards per DB-Server.

        • numberShards (array of integers): The number of leader and follower shards per DB-Server.

        • totalUsed (integer): The sum of the sizes.

        • totalShards (integer): The sum of shards, counting leader and follower shards.

        • imbalance (integer): The measure of the total imbalance. A high value indicates a high imbalance.

    • imbalanceAfter (object): Expected imbalance after the suggested move shard operations are applied.

      • leader (object): Information about the leader imbalance.

        • weightUsed (array of integers): The weight of leader shards per DB-Server. A leader has a weight of 1 by default but it is higher if collections can only be moved together because of distributeShardsLike.

        • targetWeight (array of integers): The ideal weight of leader shards per DB-Server.

        • numberShards (array of integers): The number of leader shards per DB-Server.

        • leaderDupl (array of integers): The measure of the leader shard distribution. The higher the number, the worse the distribution.

        • totalWeight (integer): The sum of all weights.

        • imbalance (integer): The measure of the total imbalance. A high value indicates a high imbalance.

        • totalShards (integer): The sum of shards, counting leader shards only.

      • shards (object): Information about the shard imbalance.

        • sizeUsed (array of integers): The size of shards per DB-Server.

        • targetSize (array of integers): The ideal size of shards per DB-Server.

        • numberShards (array of integers): The number of leader and follower shards per DB-Server.

        • totalUsed (integer): The sum of the sizes.

        • totalShards (integer): The sum of shards, counting leader and follower shards.

        • imbalance (integer): The measure of the total imbalance. A high value indicates a high imbalance.

    • moves (array): The suggested move shard operations.

      • from (string): The server name from which to move.

      • to (string): The ID of the destination server.

      • shard (string): Shard ID of the shard to be moved.

      • collection (number): Collection ID of the collection the shard belongs to.

      • isLeader (boolean): True if this is a leader move shard operation.

Execute a set of move shard operations

Executes the given set of move shard operations.

POST /_admin/cluster/rebalance/execute

Request Body

  • version (number, required): Must be set to 1.

  • moves (array, required): A set of move shard operations to execute.

    • from (string, required): The server name from which to move.

    • to (string, required): The ID of the destination server.

    • shard (string, required): Shard ID of the shard to be moved.

    • collection (number, required): Collection ID of the collection the shard belongs to.

    • isLeader (boolean, required): True if this is a leader move shard operation.

Execute the given set of move shard operations. You can use the POST /_admin/cluster/rebalance endpoint to calculate these operations to improve the balance of shards, leader shards, and follower shards.

Responses

HTTP 200: This API returns HTTP 200 if no operations are provided.

HTTP 202: This API returns HTTP 202 if the operations have been accepted and scheduled for execution.

Compute and execute a set of move shard operations to improve balance

Computes and executes a set of move shard operations to improve balance.

PUT /_admin/cluster/rebalance

Request Body

  • version (number, required): Must be set to 1.

  • maximumNumberOfMoves (number, optional): Maximum number of moves to be computed. (Default: 1000)

  • leaderChanges (boolean, optional): Allow leader changes without moving data. (Default: true)

  • moveLeaders (boolean, optional): Allow moving leaders. (Default: false)

  • moveFollowers (boolean, optional): Allow moving followers. (Default: false)

  • piFactor (number, optional): (Default: 256e6)

  • databasesExcluded (array of strings, optional): A list of database names to exclude from the analysis. (Default: [])

Compute a set of move shard operations to improve balance. These moves are then immediately executed.

Responses

HTTP 200: This API returns HTTP 200.

  • code (number): The status code.

  • error (boolean): Whether an error occurred. false in this case.

  • result (object): The result object.

    • imbalanceBefore (object): Imbalance before the suggested move shard operations are applied.

      • leader (object): Information about the leader imbalance.

        • weightUsed (array of integers): The weight of leader shards per DB-Server. A leader has a weight of 1 by default but it is higher if collections can only be moved together because of distributeShardsLike.

        • targetWeight (array of integers): The ideal weight of leader shards per DB-Server.

        • numberShards (array of integers): The number of leader shards per DB-Server.

        • leaderDupl (array of integers): The measure of the leader shard distribution. The higher the number, the worse the distribution.

        • totalWeight (integer): The sum of all weights.

        • imbalance (integer): The measure of the total imbalance. A high value indicates a high imbalance.

        • totalShards (integer): The sum of shards, counting leader shards only.

      • shards (object): Information about the shard imbalance.

        • sizeUsed (array of integers): The size of shards per DB-Server.

        • targetSize (array of integers): The ideal size of shards per DB-Server.

        • numberShards (array of integers): The number of leader and follower shards per DB-Server.

        • totalUsed (integer): The sum of the sizes.

        • totalShards (integer): The sum of shards, counting leader and follower shards.

        • imbalance (integer): The measure of the total imbalance. A high value indicates a high imbalance.

    • imbalanceAfter (object): Expected imbalance after the suggested move shard operations are applied.

      • leader (object): Information about the leader imbalance.

        • weightUsed (array of integers): The weight of leader shards per DB-Server. A leader has a weight of 1 by default but it is higher if collections can only be moved together because of distributeShardsLike.

        • targetWeight (array of integers): The ideal weight of leader shards per DB-Server.

        • numberShards (array of integers): The number of leader shards per DB-Server.

        • leaderDupl (array of integers): The measure of the leader shard distribution. The higher the number, the worse the distribution.

        • totalWeight (integer): The sum of all weights.

        • imbalance (integer): The measure of the total imbalance. A high value indicates a high imbalance.

        • totalShards (integer): The sum of shards, counting leader shards only.

      • shards (object): Information about the shard imbalance.

        • sizeUsed (array of integers): The size of shards per DB-Server.

        • targetSize (array of integers): The ideal size of shards per DB-Server.

        • numberShards (array of integers): The number of leader and follower shards per DB-Server.

        • totalUsed (integer): The sum of the sizes.

        • totalShards (integer): The sum of shards, counting leader and follower shards.

        • imbalance (integer): The measure of the total imbalance. A high value indicates a high imbalance.

    • moves (array): The suggested move shard operations.

      • from (string): The server name from which to move.

      • to (string): The ID of the destination server.

      • shard (string): Shard ID of the shard to be moved.

      • collection (number): Collection ID of the collection the shard belongs to.

      • isLeader (boolean): True if this is a leader move shard operation.

❮  Administration

© ArangoDB - Graph and Beyond