HTTP Interface for Administration and Monitoring

This is an introduction to ArangoDB’s HTTP interface for administration and monitoring of the server.

Logs

Read global logs from the server

returns the server logs

GET /_admin/log/entries

Query Parameters

• upto (string, optional): Returns all log entries up to log level upto. Note that upto must be:
  • fatal or 0
  • error or 1
  • warning or 2
  • info or 3
  • debug or 4 The default value is info.

• level (string, optional): Returns all log entries of log level level. Note that the query parameters upto and level are mutually exclusive.

• start (number, optional): Returns all log entries such that their log entry identifier (lid value) is greater or equal to start.

• size (number, optional): Restricts the result to at most size log entries.

• offset (number, optional): Starts to return log entries skipping the first offset log entries. offset and size can be used for pagination.

• search (string, optional): Only return the log entries containing the text specified in search.

• sort (string, optional): Sort the log entries either ascending (if sort is asc) or descending (if sort is desc) according to their id values. Note that the id imposes a chronological order. The default value is asc.

• serverId (string, optional): Returns all log entries of the specified server. All other query parameters remain valid. If no serverId is given, the asked server will reply. This parameter is only meaningful on Coordinators.

Returns fatal, error, warning or info log messages from the server’s global log. The result is a JSON object with the following properties:

• total: the total amount of log entries before pagination
• messages: an array with log messages that matched the criteria

This API can be turned off via the startup option --log.api-enabled. In case the API is disabled, all requests will be responded to with HTTP 403. If the API is enabled, accessing it requires admin privileges, or even superuser privileges, depending on the value of the --log.api-enabled startup option.

Responses

HTTP 200: is returned if the request is valid.

HTTP 400: is returned if invalid values are specified for upto or level.

HTTP 403: is returned if there are insufficient privileges to access the logs.

Read global logs from the server (deprecated)

returns the server logs

GET /_admin/log

Query Parameters

• upto (string, optional): Returns all log entries up to log level upto. Note that upto must be:
  • fatal or 0
  • error or 1
  • warning or 2
  • info or 3
  • debug or 4 The default value is info.

• level (string, optional): Returns all log entries of log level level. Note that the query parameters upto and level are mutually exclusive.

• start (number, optional): Returns all log entries such that their log entry identifier (lid value) is greater or equal to start.

• size (number, optional): Restricts the result to at most size log entries.

• offset (number, optional): Starts to return log entries skipping the first offset log entries. offset and size can be used for pagination.

• search (string, optional): Only return the log entries containing the text specified in search.

• sort (string, optional): Sort the log entries either ascending (if sort is asc) or descending (if sort is desc) according to their lid values. Note that the lid imposes a chronological order. The default value is asc.

• serverId (string, optional): Returns all log entries of the specified server. All other query parameters remain valid. If no serverId is given, the asked server will reply. This parameter is only meaningful on Coordinators.

Returns fatal, error, warning or info log messages from the server’s global log. The result is a JSON object with the attributes described below.

This API can be turned off via the startup option --log.api-enabled. In case the API is disabled, all requests will be responded to with HTTP 403. If the API is enabled, accessing it requires admin privileges, or even superuser privileges, depending on the value of the --log.api-enabled startup option.

Responses

HTTP 200:

• lid (array of strings): a list of log entry identifiers. Each log message is uniquely identified by its @LIT{lid} and the identifiers are in ascending order.

• level (string): A list of the log levels for all log entries.

• timestamp (array of strings): a list of the timestamps as seconds since 1970-01-01 for all log entries.

• text (string): a list of the texts of all log entries

• topic (string): a list of the topics of all log entries

• totalAmount (integer): the total amount of log entries before pagination.

HTTP 400: is returned if invalid values are specified for upto or level.

HTTP 403: is returned if there are insufficient privileges to access the logs.

Return the current server log level

returns the current log level settings

GET /_admin/log/level

Returns the server’s current log level settings. The result is a JSON object with the log topics being the object keys, and the log levels being the object values.

This API can be turned off via the startup option --log.api-enabled. In case the API is disabled, all requests will be responded to with HTTP 403. If the API is enabled, accessing it requires admin privileges, or even superuser privileges, depending on the value of the --log.api-enabled startup option.

Responses

HTTP 200: is returned if the request is valid

HTTP 403: is returned if there are insufficient privileges to read log levels.

Modify and return the current server log level

modifies the current log level settings

PUT /_admin/log/level

Request Body

• all (string, optional): Pseudo-topic to address all log topics.

• agency (string, optional): One of the possible log topics.

• agencycomm (string, optional): One of the possible log topics.

• agencystore (string, optional): One of the possible log topics.

• aql (string, optional): One of the possible log topics.

• arangosearch (string, optional): One of the possible log topics.

• audit-authentication (string, optional): One of the possible log topics (Enterprise Edition only).

• audit-authorization (string, optional): One of the possible log topics (Enterprise Edition only).

• audit-collection (string, optional): One of the possible log topics (Enterprise Edition only).

• audit-database (string, optional): One of the possible log topics (Enterprise Edition only).

• audit-document (string, optional): One of the possible log topics (Enterprise Edition only).

• audit-hotbackup (string, optional): One of the possible log topics (Enterprise Edition only).

• audit-service (string, optional): One of the possible log topics (Enterprise Edition only).

• audit-view (string, optional): One of the possible log topics (Enterprise Edition only).

• authentication (string, optional): One of the possible log topics.

• authorization (string, optional): One of the possible log topics.

• backup (string, optional): One of the possible log topics.

• bench (string, optional): One of the possible log topics.

• cache (string, optional): One of the possible log topics.

• cluster (string, optional): One of the possible log topics.

• clustercomm (string, optional): One of the possible log topics.

• collector (string, optional): One of the possible log topics.

• communication (string, optional): One of the possible log topics.

• config (string, optional): One of the possible log topics.

• crash (string, optional): One of the possible log topics.

• development (string, optional): One of the possible log topics.

• dump (string, optional): One of the possible log topics.

• engines (string, optional): One of the possible log topics.

• flush (string, optional): One of the possible log topics.

• general (string, optional): One of the possible log topics.

• graphs (string, optional): One of the possible log topics.

• heartbeat (string, optional): One of the possible log topics.

• httpclient (string, optional): One of the possible log topics.

• ldap (string, optional): One of the possible log topics (Enterprise Edition only).

• libiresearch (string, optional): One of the possible log topics.

• license (string, optional): One of the possible log topics (Enterprise Edition only).

• maintenance (string, optional): One of the possible log topics.

• memory (string, optional): One of the possible log topics.

• mmap (string, optional): One of the possible log topics.

• performance (string, optional): One of the possible log topics.

• pregel (string, optional): One of the possible log topics.

• queries (string, optional): One of the possible log topics.

• replication (string, optional): One of the possible log topics.

• requests (string, optional): One of the possible log topics.

• restore (string, optional): One of the possible log topics.

• rocksdb (string, optional): One of the possible log topics.

• security (string, optional): One of the possible log topics.

• ssl (string, optional): One of the possible log topics.

• startup (string, optional): One of the possible log topics.

• statistics (string, optional): One of the possible log topics.

• supervision (string, optional): One of the possible log topics.

• syscall (string, optional): One of the possible log topics.

• threads (string, optional): One of the possible log topics.

• trx (string, optional): One of the possible log topics.

• ttl (string, optional): One of the possible log topics.

• validation (string, optional): One of the possible log topics.

• v8 (string, optional): One of the possible log topics.

• views (string, optional): One of the possible log topics.

Modifies and returns the server’s current log level settings. The request body must be a JSON string with a log level or a JSON object with the log topics being the object keys and the log levels being the object values.

If only a JSON string is specified as input, the log level is adjusted for the “general” log topic only. If a JSON object is specified as input, the log levels will be set only for the log topic mentioned in the input object, but preserved for every other log topic. To set the log level for all log levels to a specific value, it is possible to hand in the special pseudo log topic “all”.

The result is a JSON object with all available log topics being the object keys, and the adjusted log levels being the object values.

Possible log levels are:

• FATAL - There will be no way out of this. ArangoDB will go down after this message.
• ERROR - This is an error. you should investigate and fix it. It may harm your production.
• WARNING - This may be serious application-wise, but we don’t know.
• INFO - Something has happened, take notice, but no drama attached.
• DEBUG - output debug messages
• TRACE - trace - prepare your log to be flooded - don’t use in production.

This API can be turned off via the startup option --log.api-enabled. In case the API is disabled, all requests will be responded to with HTTP 403. If the API is enabled, accessing it requires admin privileges, or even superuser privileges, depending on the value of the --log.api-enabled startup option.

Responses

HTTP 200: is returned if the request is valid

HTTP 400: is returned when the request body contains invalid JSON.

HTTP 403: is returned if there are insufficient privileges to adjust log levels.

HTTP 405: is returned when an invalid HTTP method is used.

Statistics

Read the statistics

return the statistics information

GET /_admin/statistics

Returns the statistics information. The returned object contains the statistics figures grouped together according to the description returned by _admin/statistics-description. For instance, to access a figure userTime from the group system, you first select the sub-object describing the group stored in system and in that sub-object the value for userTime is stored in the attribute of the same name.

In case of a distribution, the returned object contains the total count in count and the distribution list in counts. The sum (or total) of the individual values is returned in sum.

The transaction statistics show the local started, committed and aborted transactions as well as intermediate commits done for the server queried. The intermediate commit count will only take non zero values for the RocksDB storage engine. Coordinators do almost no local transactions themselves in their local databases, therefor cluster transactions (transactions started on a Coordinator that require DB-Servers to finish before the transactions is committed cluster wide) are just added to their local statistics. This means that the statistics you would see for a single server is roughly what you can expect in a cluster setup using a single Coordinator querying this Coordinator. Just with the difference that cluster transactions have no notion of intermediate commits and will not increase the value.

Responses

HTTP 200: Statistics were returned successfully.

HTTP 404: Statistics are disabled on the instance.

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

• code (integer): the HTTP status code - 200 in this case

• time (integer): the current server timestamp

• errorMessage (string): a descriptive error message

• enabled (boolean): true if the server has the statistics module enabled. If not, don’t expect any values.

• system (object): metrics gathered from the system about this process; may depend on the host OS

  • minorPageFaults (integer): pagefaults

  • majorPageFaults (integer): pagefaults

  • userTime (number): the user CPU time used by the server process

  • systemTime (number): the system CPU time used by the server process

  • numberOfThreads (integer): the number of threads in the server

  • residentSize (integer): RSS of process

  • residentSizePercent (number): RSS of process in %

  • virtualSize (integer): VSS of the process

• client (object): information about the connected clients and their resource usage

  • connectionTime (object): total connection times

    • sum (number): summarized value of all counts

    • count (integer): number of values summarized

    • counts (array of integers): array containing the values

  • totalTime (object): the system time

    • sum (number): summarized value of all counts

    • count (integer): number of values summarized

    • counts (array of integers): array containing the values

  • requestTime (object): the request times

    • sum (number): summarized value of all counts

    • count (integer): number of values summarized

    • counts (array of integers): array containing the values

  • queueTime (object): the time requests were queued waiting for processing

    • sum (number): summarized value of all counts

    • count (integer): number of values summarized

    • counts (array of integers): array containing the values

  • ioTime (object): IO Time

    • sum (number): summarized value of all counts

    • count (integer): number of values summarized

    • counts (array of integers): array containing the values

  • bytesSent (object): number of bytes sent to the clients

    • sum (number): summarized value of all counts

    • count (integer): number of values summarized

    • counts (array of integers): array containing the values

  • bytesReceived (object): number of bytes received from the clients

    • sum (number): summarized value of all counts

    • count (integer): number of values summarized

    • counts (array of integers): array containing the values

  • httpConnections (integer): the number of open http connections

• http (object): the numbers of requests by Verb

  • requestsTotal (integer): total number of http requests

  • requestsAsync (integer): total number of asynchronous http requests

  • requestsGet (integer): No of requests using the GET-verb

  • requestsHead (integer): No of requests using the HEAD-verb

  • requestsPost (integer): No of requests using the POST-verb

  • requestsPut (integer): No of requests using the PUT-verb

  • requestsPatch (integer): No of requests using the PATCH-verb

  • requestsDelete (integer): No of requests using the DELETE-verb

  • requestsOptions (integer): No of requests using the OPTIONS-verb

  • requestsOther (integer): No of requests using the none of the above identified verbs

• server (object): statistics of the server

  • uptime (integer): time the server is up and running

  • physicalMemory (integer): available physical memory on the server

  • transactions (object): Statistics about transactions

    • started (integer): the number of started transactions

    • committed (integer): the number of committed transactions

    • aborted (integer): the number of aborted transactions

    • intermediateCommits (integer): the number of intermediate commits done

  • v8Context (object): Statistics about the V8 javascript contexts

    • available (integer): the number of currently spawnen V8 contexts

    • busy (integer): the number of currently active V8 contexts

    • dirty (integer): the number of contexts that were previously used, and should now be garbage collected before being re-used

    • free (integer): the number of V8 contexts that are free to use

    • max (integer): the maximum number of V8 concurrent contexts we may spawn as configured by --javascript.v8-contexts

    • min (integer): the minimum number of V8 contexts that are spawned as configured by --javascript.v8-contexts-minimum

    • memory (array): a list of V8 memory / garbage collection watermarks; Refreshed on every garbage collection run; Preserves min/max memory used at that time for 10 seconds

      • contextId (integer): ID of the context this set of memory statistics is from

      • tMax (number): the timestamp where the 10 seconds interval started

      • countOfTimes (integer): how many times was the garbage collection run in these 10 seconds

      • heapMax (integer): High watermark of all garbage collection runs in 10 seconds

      • heapMin (integer): Low watermark of all garbage collection runs in these 10 seconds

  • threads (object): Statistics about the server worker threads (excluding V8 specific or jemalloc specific threads and system threads)

    • scheduler-threads (integer): The number of spawned worker threads

    • in-progress (integer): The number of currently busy worker threads

    • queued (integer): The number of jobs queued up waiting for worker threads becomming available

Examples

shell> curl --header 'accept: application/json' --dump - http://localhost:8529/_admin/statistics

HTTP/1.1 200 OK
content-type: application/json
connection: Keep-Alive
content-length: 2262
server: ArangoDB
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff

{ 
  "time" : 1652867725.2702882, 
  "enabled" : true, 
  "system" : { 
    "minorPageFaults" : 78620, 
    "majorPageFaults" : 0, 
    "userTime" : 3.42, 
    "systemTime" : 0.95, 
    "numberOfThreads" : 89, 
    "residentSize" : 324599808, 
    "residentSizePercent" : 0.004408027072477192, 
    "virtualSize" : 1633304576 
  }, 
  "client" : { 
    "httpConnections" : 2, 
    "connectionTime" : { 
      "sum" : 0, 
      "count" : 0, 
      "counts" : [ 
        0, 
        0, 
        0, 
        0 
      ] 
    }, 
    "totalTime" : { 
      "sum" : 2.759242296218872, 
      "count" : 33092, 
      "counts" : [ 
        33086, 
        5, 
        0, 
        0, 
        0, 
        1, 
        0, 
        0, 
        0, 
        0 
      ] 
    }, 
    "requestTime" : { 
      "sum" : 1.9382190704345703, 
      "count" : 33092, 
      "counts" : [ 
        33086, 
        5, 
        0, 
        0, 
        0, 
        1, 
        0, 
        0, 
        0, 
        0 
      ] 
    }, 
    "queueTime" : { 
      "sum" : 0.16420340538024902, 
      "count" : 33092, 
      "counts" : [ 
        33092, 
        0, 
        0, 
        0, 
        0, 
        0, 
        0, 
        0, 
        0, 
        0 
      ] 
    }, 
    "ioTime" : { 
      "sum" : 0.6568198204040527, 
      "count" : 33092, 
      "counts" : [ 
        33092, 
        0, 
        0, 
        0, 
        0, 
        0, 
        0, 
        0, 
        0, 
        0 
      ] 
    }, 
    "bytesSent" : { 
      "sum" : 11292454, 
      "count" : 33092, 
      "counts" : [ 
        136, 
        32490, 
        433, 
        25, 
        4, 
        4 
      ] 
    }, 
    "bytesReceived" : { 
      "sum" : 7732952, 
      "count" : 33092, 
      "counts" : [ 
        31894, 
        1198, 
        0, 
        0, 
        0, 
        0 
      ] 
    } 
  }, 
  "clientUser" : { 
    "httpConnections" : 2, 
    "connectionTime" : { 
      "sum" : 0, 
      "count" : 0, 
      "counts" : [ 
        0, 
        0, 
        0, 
        0 
      ] 
    }, 
    "totalTime" : { 
      "sum" : 2.759242296218872, 
      "count" : 33092, 
      "counts" : [ 
        33086, 
        5, 
        0, 
        0, 
        0, 
        1, 
        0, 
        0, 
        0, 
        0 
      ] 
    }, 
    "requestTime" : { 
      "sum" : 1.9382190704345703, 
      "count" : 33092, 
      "counts" : [ 
        33086, 
        5, 
        0, 
        0, 
        0, 
        1, 
        0, 
        0, 
        0, 
        0 
      ] 
    }, 
    "queueTime" : { 
      "sum" : 0.16420340538024902, 
      "count" : 33092, 
      "counts" : [ 
        33092, 
        0, 
        0, 
        0, 
        0, 
        0, 
        0, 
        0, 
        0, 
        0 
      ] 
    }, 
    "ioTime" : { 
      "sum" : 0.6568198204040527, 
      "count" : 33092, 
      "counts" : [ 
        33092, 
        0, 
        0, 
        0, 
        0, 
        0, 
        0, 
        0, 
        0, 
        0 
      ] 
    }, 
    "bytesSent" : { 
      "sum" : 11292454, 
      "count" : 33092, 
      "counts" : [ 
        136, 
        32490, 
        433, 
        25, 
        4, 
        4 
      ] 
    }, 
    "bytesReceived" : { 
      "sum" : 7732952, 
      "count" : 33092, 
      "counts" : [ 
        31894, 
        1198, 
        0, 
        0, 
        0, 
        0 
      ] 
    } 
  }, 
  "http" : { 
    "requestsTotal" : 33092, 
    "requestsSuperuser" : 0, 
    "requestsUser" : 33092, 
    "requestsAsync" : 0, 
    "requestsGet" : 1026, 
    "requestsHead" : 0, 
    "requestsPost" : 31919, 
    "requestsPut" : 30, 
    "requestsPatch" : 2, 
    "requestsDelete" : 115, 
    "requestsOptions" : 0, 
    "requestsOther" : 0 
  }, 
  "server" : { 
    "uptime" : 6.536187410354614, 
    "physicalMemory" : 73638342656, 
    "transactions" : { 
      "started" : 32221, 
      "aborted" : 233, 
      "committed" : 33113, 
      "intermediateCommits" : 0, 
      "readOnly" : 1220 
    }, 
    "v8Context" : { 
      "available" : 2, 
      "busy" : 0, 
      "dirty" : 0, 
      "free" : 2, 
      "max" : 16, 
      "min" : 1, 
      "memory" : [ 
        { 
          "contextId" : 0, 
          "tMax" : 1652867719.1380978, 
          "countOfTimes" : 7, 
          "heapMax" : 11976248, 
          "heapMin" : 0, 
          "invocations" : 17 
        }, 
        { 
          "contextId" : 1, 
          "tMax" : 1652867724.3911169, 
          "countOfTimes" : 7, 
          "heapMax" : 11952168, 
          "heapMin" : 0, 
          "invocations" : 3 
        } 
      ] 
    }, 
    "threads" : { 
      "scheduler-threads" : 4, 
      "blocked" : 0, 
      "queued" : 1, 
      "in-progress" : 1, 
      "direct-exec" : 0 
    } 
  }, 
  "error" : false, 
  "code" : 200 
}

shell> curl --header 'accept: application/json' --dump - http://localhost:8529/_admin/statistics

HTTP/1.1 200 OK
content-type: application/json
connection: Keep-Alive
content-length: 2262
server: ArangoDB
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff

Statistics description

fetch descriptive info of statistics

GET /_admin/statistics-description

Returns a description of the statistics returned by /_admin/statistics. The returned objects contains an array of statistics groups in the attribute groups and an array of statistics figures in the attribute figures.

A statistics group is described by

• group: The identifier of the group.
• name: The name of the group.
• description: A description of the group.

A statistics figure is described by

• group: The identifier of the group to which this figure belongs.
• identifier: The identifier of the figure. It is unique within the group.
• name: The name of the figure.
• description: A description of the figure.
• type: Either current, accumulated, or distribution.
• cuts: The distribution vector.
• units: Units in which the figure is measured.

Responses

HTTP 200: Description was returned successfully.

• groups (array): A statistics group

  • group (string): The identifier of the group.

  • name (string): The name of the group.

  • description (string): A description of the group.

• figures (array): A statistics figure

  • group (string): The identifier of the group to which this figure belongs.

  • identifier (string): The identifier of the figure. It is unique within the group.

  • name (string): The name of the figure.

  • description (string): A description of the figure.

  • type (string): Either current, accumulated, or distribution.

  • cuts (string): The distribution vector.

  • units (string): Units in which the figure is measured.

• code (integer): the HTTP status code

• error (boolean): the error, false in this case

Examples

shell> curl --header 'accept: application/json' --dump - http://localhost:8529/_admin/statistics-description

HTTP/1.1 200 OK
content-type: application/json
connection: Keep-Alive
content-length: 7892
server: ArangoDB
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff

{ 
  "groups" : [ 
    { 
      "group" : "system", 
      "name" : "Process Statistics", 
      "description" : "Statistics about the ArangoDB process" 
    }, 
    { 
      "group" : "client", 
      "name" : "Client Connection Statistics", 
      "description" : "Statistics about the connections." 
    }, 
    { 
      "group" : "clientUser", 
      "name" : "Client User Connection Statistics", 
      "description" : "Statistics about the connections, only user traffic (ignoring superuser JWT traffic)." 
    }, 
    { 
      "group" : "http", 
      "name" : "HTTP Request Statistics", 
      "description" : "Statistics about the HTTP requests." 
    }, 
    { 
      "group" : "server", 
      "name" : "Server Statistics", 
      "description" : "Statistics about the ArangoDB server" 
    } 
  ], 
  "figures" : [ 
    { 
      "group" : "system", 
      "identifier" : "userTime", 
      "name" : "User Time", 
      "description" : "Amount of time that this process has been scheduled in user mode, measured in seconds.", 
      "type" : "accumulated", 
      "units" : "seconds" 
    }, 
    { 
      "group" : "system", 
      "identifier" : "systemTime", 
      "name" : "System Time", 
      "description" : "Amount of time that this process has been scheduled in kernel mode, measured in seconds.", 
      "type" : "accumulated", 
      "units" : "seconds" 
    }, 
    { 
      "group" : "system", 
      "identifier" : "numberOfThreads", 
      "name" : "Number of Threads", 
      "description" : "Number of threads in the arangod process.", 
      "type" : "current", 
      "units" : "number" 
    }, 
    { 
      "group" : "system", 
      "identifier" : "residentSize", 
      "name" : "Resident Set Size", 
      "description" : "The total size of the number of pages the process has in real memory. This is just the pages which count toward text, data, or stack space. This does not include pages which have not been demand-loaded in, or which are swapped out. The resident set size is reported in bytes.", 
      "type" : "current", 
      "units" : "bytes" 
    }, 
    { 
      "group" : "system", 
      "identifier" : "residentSizePercent", 
      "name" : "Resident Set Size", 
      "description" : "The percentage of physical memory used by the process as resident set size.", 
      "type" : "current", 
      "units" : "percent" 
    }, 
    { 
      "group" : "system", 
      "identifier" : "virtualSize", 
      "name" : "Virtual Memory Size", 
      "description" : "On Windows, this figure contains the total amount of memory that the memory manager has committed for the arangod process. On other systems, this figure contains The size of the virtual memory the process is using.", 
      "type" : "current", 
      "units" : "bytes" 
    }, 
    { 
      "group" : "system", 
      "identifier" : "minorPageFaults", 
      "name" : "Minor Page Faults", 
      "description" : "The number of minor faults the process has made which have not required loading a memory page from disk. This figure is not reported on Windows.", 
      "type" : "accumulated", 
      "units" : "number" 
    }, 
    { 
      "group" : "system", 
      "identifier" : "majorPageFaults", 
      "name" : "Major Page Faults", 
      "description" : "On Windows, this figure contains the total number of page faults. On other system, this figure contains the number of major faults the process has made which have required loading a memory page from disk.", 
      "type" : "accumulated", 
      "units" : "number" 
    }, 
    { 
      "group" : "client", 
      "identifier" : "httpConnections", 
      "name" : "Client Connections", 
      "description" : "The number of connections that are currently open.", 
      "type" : "current", 
      "units" : "number" 
    }, 
    { 
      "group" : "client", 
      "identifier" : "totalTime", 
      "name" : "Total Time", 
      "description" : "Total time needed to answer a request.", 
      "type" : "distribution", 
      "cuts" : [ 
        0.01, 
        0.05, 
        0.1, 
        0.2, 
        0.5, 
        1, 
        5, 
        15, 
        30 
      ], 
      "units" : "seconds" 
    }, 
    { 
      "group" : "client", 
      "identifier" : "requestTime", 
      "name" : "Request Time", 
      "description" : "Request time needed to answer a request.", 
      "type" : "distribution", 
      "cuts" : [ 
        0.01, 
        0.05, 
        0.1, 
        0.2, 
        0.5, 
        1, 
        5, 
        15, 
        30 
      ], 
      "units" : "seconds" 
    }, 
    { 
      "group" : "client", 
      "identifier" : "queueTime", 
      "name" : "Queue Time", 
      "description" : "Queue time needed to answer a request.", 
      "type" : "distribution", 
      "cuts" : [ 
        0.01, 
        0.05, 
        0.1, 
        0.2, 
        0.5, 
        1, 
        5, 
        15, 
        30 
      ], 
      "units" : "seconds" 
    }, 
    { 
      "group" : "client", 
      "identifier" : "bytesSent", 
      "name" : "Bytes Sent", 
      "description" : "Bytes sents for a request.", 
      "type" : "distribution", 
      "cuts" : [ 
        250, 
        1000, 
        2000, 
        5000, 
        10000 
      ], 
      "units" : "bytes" 
    }, 
    { 
      "group" : "client", 
      "identifier" : "bytesReceived", 
      "name" : "Bytes Received", 
      "description" : "Bytes received for a request.", 
      "type" : "distribution", 
      "cuts" : [ 
        250, 
        1000, 
        2000, 
        5000, 
        10000 
      ], 
      "units" : "bytes" 
    }, 
    { 
      "group" : "client", 
      "identifier" : "connectionTime", 
      "name" : "Connection Time", 
      "description" : "Total connection time of a client.", 
      "type" : "distribution", 
      "cuts" : [ 
        0.1, 
        1, 
        60 
      ], 
      "units" : "seconds" 
    }, 
    { 
      "group" : "clientUser", 
      "identifier" : "httpConnections", 
      "name" : "Client Connections", 
      "description" : "The number of connections that are currently open (only user traffic).", 
      "type" : "current", 
      "units" : "number" 
    }, 
    { 
      "group" : "clientUser", 
      "identifier" : "totalTime", 
      "name" : "Total Time", 
      "description" : "Total time needed to answer a request (only user traffic).", 
      "type" : "distribution", 
      "cuts" : [ 
        0.01, 
        0.05, 
        0.1, 
        0.2, 
        0.5, 
        1, 
        5, 
        15, 
        30 
      ], 
      "units" : "seconds" 
    }, 
    { 
      "group" : "clientUser", 
      "identifier" : "requestTime", 
      "name" : "Request Time", 
      "description" : "Request time needed to answer a request (only user traffic).", 
      "type" : "distribution", 
      "cuts" : [ 
        0.01, 
        0.05, 
        0.1, 
        0.2, 
        0.5, 
        1, 
        5, 
        15, 
        30 
      ], 
      "units" : "seconds" 
    }, 
    { 
      "group" : "clientUser", 
      "identifier" : "queueTime", 
      "name" : "Queue Time", 
      "description" : "Queue time needed to answer a request (only user traffic).", 
      "type" : "distribution", 
      "cuts" : [ 
        0.01, 
        0.05, 
        0.1, 
        0.2, 
        0.5, 
        1, 
        5, 
        15, 
        30 
      ], 
      "units" : "seconds" 
    }, 
    { 
      "group" : "clientUser", 
      "identifier" : "bytesSent", 
      "name" : "Bytes Sent", 
      "description" : "Bytes sents for a request (only user traffic).", 
      "type" : "distribution", 
      "cuts" : [ 
        250, 
        1000, 
        2000, 
        5000, 
        10000 
      ], 
      "units" : "bytes" 
    }, 
    { 
      "group" : "clientUser", 
      "identifier" : "bytesReceived", 
      "name" : "Bytes Received", 
      "description" : "Bytes received for a request (only user traffic).", 
      "type" : "distribution", 
      "cuts" : [ 
        250, 
        1000, 
        2000, 
        5000, 
        10000 
      ], 
      "units" : "bytes" 
    }, 
    { 
      "group" : "clientUser", 
      "identifier" : "connectionTime", 
      "name" : "Connection Time", 
      "description" : "Total connection time of a client (only user traffic).", 
      "type" : "distribution", 
      "cuts" : [ 
        0.1, 
        1, 
        60 
      ], 
      "units" : "seconds" 
    }, 
    { 
      "group" : "http", 
      "identifier" : "requestsTotal", 
      "name" : "Total requests", 
      "description" : "Total number of HTTP requests.", 
      "type" : "accumulated", 
      "units" : "number" 
    }, 
    { 
      "group" : "http", 
      "identifier" : "requestsSuperuser", 
      "name" : "Total superuser requests", 
      "description" : "Total number of HTTP requests executed by superuser/JWT.", 
      "type" : "accumulated", 
      "units" : "number" 
    }, 
    { 
      "group" : "http", 
      "identifier" : "requestsUser", 
      "name" : "Total user requests", 
      "description" : "Total number of HTTP requests executed by clients.", 
      "type" : "accumulated", 
      "units" : "number" 
    }, 
    { 
      "group" : "http", 
      "identifier" : "requestsAsync", 
      "name" : "Async requests", 
      "description" : "Number of asynchronously executed HTTP requests.", 
      "type" : "accumulated", 
      "units" : "number" 
    }, 
    { 
      "group" : "http", 
      "identifier" : "requestsGet", 
      "name" : "HTTP GET requests", 
      "description" : "Number of HTTP GET requests.", 
      "type" : "accumulated", 
      "units" : "number" 
    }, 
    { 
      "group" : "http", 
      "identifier" : "requestsHead", 
      "name" : "HTTP HEAD requests", 
      "description" : "Number of HTTP HEAD requests.", 
      "type" : "accumulated", 
      "units" : "number" 
    }, 
    { 
      "group" : "http", 
      "identifier" : "requestsPost", 
      "name" : "HTTP POST requests", 
      "description" : "Number of HTTP POST requests.", 
      "type" : "accumulated", 
      "units" : "number" 
    }, 
    { 
      "group" : "http", 
      "identifier" : "requestsPut", 
      "name" : "HTTP PUT requests", 
      "description" : "Number of HTTP PUT requests.", 
      "type" : "accumulated", 
      "units" : "number" 
    }, 
    { 
      "group" : "http", 
      "identifier" : "requestsPatch", 
      "name" : "HTTP PATCH requests", 
      "description" : "Number of HTTP PATCH requests.", 
      "type" : "accumulated", 
      "units" : "number" 
    }, 
    { 
      "group" : "http", 
      "identifier" : "requestsDelete", 
      "name" : "HTTP DELETE requests", 
      "description" : "Number of HTTP DELETE requests.", 
      "type" : "accumulated", 
      "units" : "number" 
    }, 
    { 
      "group" : "http", 
      "identifier" : "requestsOptions", 
      "name" : "HTTP OPTIONS requests", 
      "description" : "Number of HTTP OPTIONS requests.", 
      "type" : "accumulated", 
      "units" : "number" 
    }, 
    { 
      "group" : "http", 
      "identifier" : "requestsOther", 
      "name" : "other HTTP requests", 
      "description" : "Number of other HTTP requests.", 
      "type" : "accumulated", 
      "units" : "number" 
    }, 
    { 
      "group" : "server", 
      "identifier" : "uptime", 
      "name" : "Server Uptime", 
      "description" : "Number of seconds elapsed since server start.", 
      "type" : "current", 
      "units" : "seconds" 
    }, 
    { 
      "group" : "server", 
      "identifier" : "physicalMemory", 
      "name" : "Physical Memory", 
      "description" : "Physical memory in bytes.", 
      "type" : "current", 
      "units" : "bytes" 
    } 
  ], 
  "error" : false, 
  "code" : 200 
}

shell> curl --header 'accept: application/json' --dump - http://localhost:8529/_admin/statistics-description

HTTP/1.1 200 OK
content-type: application/json
connection: Keep-Alive
content-length: 7892
server: ArangoDB
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff

TLS

Return a summary of the TLS data

Return the TLS data of this server (server key, client-auth CA)

GET /_admin/server/tls

Return a summary of the TLS data. The JSON response will contain a field result with the following components:

• keyfile: Information about the key file.
• clientCA: Information about the CA for client certificate verification.

If server name indication (SNI) is used and multiple key files are configured for different server names, then there is an additional attribute SNI, which contains for each configured server name the corresponding information about the key file for that server name.

In all cases the value of the attribute will be a JSON object, which has a subset of the following attributes (whatever is appropriate):

• sha256: The value is a string with the SHA256 of the whole input file.
• certificates: The value is a JSON array with the public certificates in the chain in the file.
• privateKeySha256: In cases where there is a private key (keyfile but not clientCA), this field is present and contains a JSON string with the SHA256 of the private key.

This API requires authentication.

Responses

HTTP 200: This API will return HTTP 200 if everything is ok

Trigger a reload of the TLS data and return a summary

Trigger a reload of the TLS data of this server (server key, client-auth CA) and return the new data as a summary.

POST /_admin/server/tls

This API call triggers a reload of all the TLS data and then returns a summary. The JSON response is exactly as in the corresponding GET request (see there).

This is a protected API and can only be executed with superuser rights.

Responses

HTTP 200: This API will return HTTP 200 if everything is ok

HTTP 403: This API will return HTTP 403 FORBIDDEN if it is not called with superuser rights.

Encryption at Rest

Rotate the encryption at rest keystore

Rotate encryption at rest key

POST /_admin/server/encryption

Change the user supplied encryption at rest key by sending a request without payload to this endpoint. The file supplied via --rocksdb.encryption-keyfolder will be reloaded and the internal encryption key will be re-encrypted with the new user key.

This is a protected API and can only be executed with superuser rights. This API is not available on coordinator nodes.

The API returns HTTP 404 in case encryption key rotation is disabled.

Responses

HTTP 200: This API will return HTTP 200 if everything is ok

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

• code (integer): the HTTP status code - 200 in this case

• result (object): The result object.

  • encryption-keys (array of objects): An array of objects with the SHA-256 hashes of the key secrets. Can be empty.

HTTP 403: This API will return HTTP 403 FORBIDDEN if it is not called with superuser rights.

HTTP 404: This API will return HTTP 404 in case encryption key rotation is disabled.

Cluster

Return whether or not a server is in read-only mode

Return the mode of this server (read-only or default)

GET /_admin/server/mode

Return mode information about a server. The json response will contain a field mode with the value readonly or default. In a read-only server all write operations will fail with an error code of 1004 (ERROR_READ_ONLY). Creating or dropping of databases and collections will also fail with error code 11 (ERROR_FORBIDDEN).

This API requires authentication.

Responses

HTTP 200: This API will return HTTP 200 if everything is ok

Update whether or not a server is in read-only mode

Update the mode of this server (read-only or default)

PUT /_admin/server/mode

Request Body

• mode (string, required): The mode of the server readonly or default.

Update mode information about a server. The json response will contain a field mode with the value readonly or default. In a read-only server all write operations will fail with an error code of 1004 (ERROR_READ_ONLY). Creating or dropping of databases and collections will also fail with error code 11 (ERROR_FORBIDDEN).

This is a protected API. It requires authentication and administrative server rights.

Responses

HTTP 200: This API will return HTTP 200 if everything is ok

HTTP 401: if the request was not authenticated as a user with sufficient rights

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]

Return whether or not a server is available

Return whether or not a server is available

GET /_admin/server/availability

Return availability information about a server.

This is a public API so it does not require authentication. It is meant to be used only in the context of server monitoring.

Responses

HTTP 200: This API will return HTTP 200 in case the server is up and running and usable for arbitrary operations, is not set to read-only mode and is currently not a follower in case of an active failover setup.

HTTP 503: HTTP 503 will be returned in case the server is during startup or during shutdown, is set to read-only mode or is currently a follower in an active failover setup.

In addition, HTTP 503 will be returned in case the fill grade of the scheduler queue exceeds the configured high-water mark (adjustable via startup option --server.unavailability-queue-fill-grade), which by default is set to 75 % of the maximum queue length.

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):

Queries the statistics of the given DB-Server

Responses

HTTP 200: is returned when everything went well.

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

HTTP 403: 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:

Other

Compact the entire database system data

compact all databases

PUT /_admin/compact

Request Body

• changeLevel (boolean, optional): whether or not compacted data should be moved to the minimum possible level. The default value is false.

• compactBottomMostLevel (boolean, optional): Whether or not to compact the bottommost level of data. The default value is false.

This endpoint can be used to reclaim disk space after substantial data deletions have taken place. It requires superuser access.

Responses

HTTP 200: Compaction started successfully

HTTP 401: if the request was not authenticated as a user with sufficient rights

Examples

shell> curl -X PUT --header 'accept: application/json' --dump - http://localhost:8529/_admin/compact

HTTP/1.1 200 OK
content-type: application/json
connection: Keep-Alive
content-length: 2
server: ArangoDB
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff

{ 
}

Reloads the routing information

Reload the routing table.

POST /_admin/routing/reload

Reloads the routing information from the collection routing.

Responses

HTTP 200: Routing information was reloaded successfully.