openapi: 3.2.0
info:
contact:
name: ArangoDB Inc.
url: https://arango.ai
license:
name: Business Source License 1.1
url: https://github.com/arangodb/arangodb/blob/devel/LICENSE
summary: The HTTP API of the ArangoDB graph database system
title: ArangoDB Core Monitoring API
version: 3.12.10 (API v0)
description: Access logs, statistics, and metrics
tags:
- description: Access logs, statistics, and metrics
name: Monitoring
paths:
/_admin/log:
get:
deprecated: true
description: '> **WARNING:**
This endpoint should no longer be used. It is deprecated from version
3.8.0 onward and removed in ArangoDB 4.0.
Use `/_admin/log/entries` instead, which provides the same data in a more
intuitive and easier to process format.
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.
'
operationId: getLog
parameters:
- description: '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`
- `trace` or `5`
'
in: query
name: upto
required: false
schema:
default: info
- description: 'Returns all log entries of log level `level`. Note that the query parameters
`upto` and `level` are mutually exclusive.
'
in: query
name: level
required: false
schema:
type: string
- description: 'Returns all log entries such that their log entry identifier (`lid` value)
is greater or equal to `start`.
'
in: query
name: start
required: false
schema:
default: 0
type: number
- description: 'Restricts the result to at most `size` log entries.
'
in: query
name: size
required: false
schema:
type: number
- description: 'Starts to return log entries skipping the first `offset` log entries. `offset`
and `size` can be used for pagination.
'
in: query
name: offset
required: false
schema:
default: 0
type: number
- description: 'Only return the log entries containing the text specified in `search`.
'
in: query
name: search
required: false
schema:
type: string
- description: '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.
'
in: query
name: sort
required: false
schema:
default: asc
type: string
- description: '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.
'
in: query
name: serverId
required: false
schema:
type: string
responses:
'200':
content:
application/json:
schema:
properties:
level:
description: 'A list of the log levels for all log entries.
'
type: string
lid:
description: 'a list of log entry identifiers. Each log message is uniquely
identified by its @LIT{lid} and the identifiers are in ascending
order.
'
items:
type: string
type: array
text:
description: 'a list of the texts of all log entries
'
type: string
timestamp:
description: 'a list of the timestamps as seconds since 1970-01-01 for all log
entries.
'
items:
type: string
type: array
topic:
description: 'a list of the topics of all log entries
'
type: string
totalAmount:
description: 'the total amount of log entries before pagination.
'
type: integer
required:
- lid
- level
- timestamp
- text
- topic
- totalAmount
type: object
description: ''
'400':
description: 'is returned if invalid values are specified for `upto` or `level`.
'
'403':
description: 'is returned if there are insufficient privileges to access the logs.
'
summary: Get the global server logs (deprecated)
tags:
- Monitoring
/_admin/log/entries:
get:
description: '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.
'
operationId: getLogEntries
parameters:
- description: '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`
- `trace` or `5`
'
in: query
name: upto
required: false
schema:
default: info
- description: 'Returns all log entries of log level `level`. Note that the query parameters
`upto` and `level` are mutually exclusive.
'
in: query
name: level
required: false
schema:
type: string
- description: 'Returns all log entries such that their log entry identifier (`id` value)
is greater or equal to `start`.
'
in: query
name: start
required: false
schema:
default: 0
type: number
- description: 'Restricts the result to at most `size` log entries.
'
in: query
name: size
required: false
schema:
type: number
- description: 'Starts to return log entries skipping the first `offset` log entries. `offset`
and `size` can be used for pagination.
'
in: query
name: offset
required: false
schema:
default: 0
type: number
- description: 'Only return the log entries containing the text specified in `search`.
'
in: query
name: search
required: false
schema:
type: string
- description: '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.
'
in: query
name: sort
required: false
schema:
default: asc
type: string
- description: '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.
'
in: query
name: serverId
required: false
schema:
type: string
responses:
'200':
description: 'is returned if the request is valid.
'
'400':
description: 'is returned if invalid values are specified for `upto` or `level`.
'
'403':
description: 'is returned if there are insufficient privileges to access the logs.
'
summary: Get the global server logs
tags:
- Monitoring
/_admin/log/level:
delete:
description: 'Revert the server''s log level settings to the values they had at startup,
as determined by the startup options specified on the command-line, a
configuration file, and the factory defaults.
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.
'
operationId: resetLogLevel
parameters:
- description: 'Forwards the request to the specified server.
'
in: query
name: serverId
required: false
schema:
type: string
responses:
'200':
description: 'The log levels have been reset successfully.
'
'403':
description: 'You have insufficient privileges to reset the log levels.
'
summary: Reset the server log levels
tags:
- Monitoring
get:
description: '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.
'
operationId: getLogLevel
parameters:
- description: 'Forwards the request to the specified server.
'
in: query
name: serverId
required: false
schema:
type: string
- description: "Set this option to `true` to return the individual log level settings\nof all log outputs (`appenders`) as well as the `global` settings.\n\nThe response structure is as follows:\n\n```json\n{\n \"global\": {\n \"agency\": \"INFO\",\n \"agencycomm\": \"INFO\",\n \"agencystore\": \"WARNING\",\n ...\n },\n \"appenders\": {\n \"-\": {\n \"agency\": \"INFO\",\n \"agencycomm\": \"INFO\",\n \"agencystore\": \"WARNING\",\n ...\n },\n \"file:///path/to/file\": {\n \"agency\": \"INFO\",\n \"agencycomm\": \"INFO\",\n \"agencystore\": \"WARNING\",\n ...\n },\n ...\n }\n}\n```\n"
in: query
name: withAppenders
required: false
schema:
default: false
type: boolean
responses:
'200':
description: 'is returned if the request is valid
'
'403':
description: 'is returned if there are insufficient privileges to read log levels.
'
summary: Get the server log levels
tags:
- Monitoring
put:
description: "Modifies and returns the server's current log level settings.\nThe request body must be a JSON string with a log level or a JSON object with the\nlog topics being the object keys and the log levels being the object values.\n\nIf only a JSON string is specified as input, the log level is adjusted for the\n\"general\" log topic only. If a JSON object is specified as input, the log levels will\nbe set only for the log topic mentioned in the input object, but preserved for every\nother log topic.\nTo set the log level for all log levels to a specific value, it is possible to hand\nin the special pseudo log topic \"all\".\n\nThe result is a JSON object with all available log topics being the object keys, and\nthe adjusted log levels being the object values.\n\nPossible log levels are:\n- `FATAL` - Only critical errors are logged after which the _arangod_\n process terminates.\n- `ERROR` - Only errors are logged. You should investigate and fix errors\n as they may harm your production.\n- `WARNING` - Errors and warnings are logged. Warnings may be serious\n application-wise and can indicate issues that might lead to errors\n later on.\n- `INFO` - Errors, warnings, and general information is logged.\n- `DEBUG` - Outputs debug messages used in the development of ArangoDB\n in addition to the above.\n- `TRACE` - Logs detailed tracing of operations in addition to the above.\n This can flood the log. Don't use this log level in production.\n\nThis API can be turned off via the startup option `--log.api-enabled`. In case\nthe API is disabled, all requests will be responded to with HTTP 403. If the\nAPI is enabled, accessing it requires admin privileges, or even superuser\nprivileges, depending on the value of the `--log.api-enabled` startup option.\n"
operationId: setLogLevel
parameters:
- description: 'Forwards the request to the specified server.
'
in: query
name: serverId
required: false
schema:
type: string
- description: "Set this option to `true` to set individual log level settings\nfor log outputs (`appenders`). The request and response structure is\nas follows:\n\n```json\n{\n \"global\": {\n \"agency\": \"INFO\",\n \"agencycomm\": \"INFO\",\n \"agencystore\": \"WARNING\",\n ...\n },\n \"appenders\": {\n \"-\": {\n \"agency\": \"INFO\",\n \"agencycomm\": \"INFO\",\n \"agencystore\": \"WARNING\",\n ...\n },\n \"file:///path/to/file\": {\n \"agency\": \"INFO\",\n \"agencycomm\": \"INFO\",\n \"agencystore\": \"WARNING\",\n ...\n },\n ...\n }\n}\n```\n\nChanging the `global` settings affects all outputs and is the same\nas setting a log level with this option turned off.\n"
in: query
name: withAppenders
required: false
schema:
default: false
type: boolean
requestBody:
content:
application/json:
schema:
properties:
agency:
description: 'Agents use this log topic to inform about any activity
including the RAFT consensus gossip.
'
type: string
agencycomm:
description: 'DB-Servers and Coordinators log the requests they send to the
Agency.
'
type: string
agencystore:
description: 'Optional verbose logging of Agency write operations.
'
type: string
all:
description: 'Pseudo-topic to address all log topics.
'
type: string
aql:
description: 'Logs information about the AQL query optimization and
execution. DB-Servers and Coordinators log the cluster-internal
communication around AQL queries. It also reports the AQL
memory limit on startup.
'
type: string
arangosearch:
description: 'Logs information related to ArangoSearch including Analyzers,
the column cache, and the commit and consolidation threads.
'
type: string
audit-authentication:
description: 'Controls whether events such as successful logins and
missing or wrong credentials are written to the audit log.
'
type: string
audit-authorization:
description: 'Controls whether events such as users trying to access databases
without the necessary permissions are written to the audit log.
'
type: string
audit-collection:
description: 'Controls whether events about collections creation, truncation,
and deletion are written to the audit log.
'
type: string
audit-database:
description: 'Controls whether events about database creation and deletion
are written to the audit log.
'
type: string
audit-document:
description: 'Controls whether document read and write events are written
to the audit log.
'
type: string
audit-hotbackup:
description: 'Controls whether the Hot Backup creation, restore, and delete
events are written to the audit log.
'
type: string
audit-service:
description: 'Controls whether the start and stop events of the audit
service are written to the audit log.
'
type: string
audit-view:
description: 'Controls whether events about View creation and deletion
are written to the audit log.
'
type: string
authentication:
description: 'Logs events related to authentication, for example, when a
JWT secret is generated or a token is validated against a secret.
'
type: string
authorization:
description: 'Logs when a user has insufficient permissions for a request.
'
type: string
backup:
description: 'Logs events related to Hot Backup.
'
type: string
bench:
description: 'Logs events related to benchmarking with _arangobench_.
'
type: string
cache:
description: 'Logs events related to caching documents and index entries
as well as the cache configuration on startup.
'
type: string
cluster:
description: 'Logs information related to the cluster-internal communication
as well as cluster operations. This includes changes to the
state and readiness of DB-Servers and connectivity checks
on Coordinators.
'
type: string
communication:
description: 'Logs lower-level network connection and communication events.
'
type: string
config:
description: 'Logs information related to the startup options and server
configuration.
'
type: string
crash:
description: 'Logs information about a fatal error including a backtrace
before the process terminates.
'
type: string
deprecation:
description: 'Warns about deprecated features and the usage of options that
will not be allowed or have no effect in a future version.
'
type: string
development:
description: 'This log topic is reserved for the development of ArangoDB.
'
type: string
dump:
description: 'Logs events related to dumping data with _arangodump_.
'
type: string
engines:
description: 'Logs various information related to ArangoDB''s use of the
RocksDB storage engine, like the initialization and
file operations.
RocksDB''s internal log messages are passed through using the
`rocksdb` log topic.
'
type: string
flush:
description: 'Logs events related to flushing data from memory to disk.
'
type: string
general:
description: 'Logs all messages of general interest and that don''t fit
under any of the other log topics. For example, it reports
the ArangoDB version and the detected operating system and
memory on startup.
'
type: string
graphs:
description: 'Logs information related to graph operations including
graph traversal and path search tracing.
'
type: string
heartbeat:
description: 'Logs everything related to the cluster heartbeat for
monitoring the intra-connectivity.
'
type: string
httpclient:
description: 'Logs the activity of the HTTP request subsystem that is used
in replication, client tools, and V8.
'
type: string
libiresearch:
description: 'Logs the internal log messages of IResearch, the underlying
library of ArangoSearch.
'
type: string
license:
description: 'Logs events related to the license management like the
expiration of a license.
'
type: string
maintenance:
description: 'Logs the operations of the cluster maintenance including
shard locking and collection creation.
'
type: string
memory:
description: 'Logs the memory configuration on startup and reports
problems with memory alignment and operating system settings.
'
type: string
queries:
description: 'Logs slow queries as well as internal details about the
execution of AQL queries at low log levels.
'
type: string
replication:
description: 'Logs information related to the data replication within a cluster.
'
type: string
requests:
description: 'Logs the handling of internal and external requests and
can include IP addresses, endpoints, and HTTP headers and
bodies when using low log levels.
It overlaps with the network `communication` log topic.
'
type: string
restore:
description: 'This log topic is only used by _arangorestore_.
'
type: string
rocksdb:
description: 'Logs RocksDB''s internal log messages as well RocksDB
background errors.
Information related to ArangoDB''s use of the
RocksDB storage engine uses the `engines` log topic.
'
type: string
security:
description: 'Logs the security configuration for V8.
'
type: string
ssl:
description: 'Logs information related to the in-transit encryption of
network communication using SSL/TLS.
'
type: string
startup:
description: 'Logs information related to the startup and shutdown of a
server process as well as anything related to upgrading the
database directory.
'
type: string
statistics:
description: 'Logs events related to processing server statistics.
This is independent of server metrics.
'
type: string
supervision:
description: 'Logs information related to the Agency''s cluster supervision.
'
type: string
syscall:
description: 'Logs events related to calling operating system functions.
It reports problems related to file descriptors and the
server process monitoring.
'
type: string
threads:
description: 'Logs information related to the use of operating system
threads and the threading configuration of ArangoDB.
'
type: string
trx:
description: 'Logs information about transaction management.
'
type: string
ttl:
description: 'Logs the activity of the background thread for
time-to-live (TTL) indexes.
'
type: string
v8:
description: 'Logs various information related to ArangoDB''s use of the
V8 JavaScript engine, like the initialization as well as
entering and exiting contexts.
'
type: string
validation:
description: 'Logs when the schema validation fails for a document.
'
type: string
views:
description: 'Logs certain events related to ArangoSearch Views.
'
type: string
type: object
responses:
'200':
description: 'is returned if the request is valid
'
'400':
description: 'is returned when the request body contains invalid JSON.
'
'403':
description: 'is returned if there are insufficient privileges to adjust log levels.
'
'405':
description: 'is returned when an invalid HTTP method is used.
'
summary: Set the server log levels
tags:
- Monitoring
/_admin/log/structured:
get:
description: 'Returns the server''s current structured log settings.
The result is a JSON object with the log parameters being the object keys, and
`true` or `false` being the object values, meaning the parameters are either
enabled or disabled.
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.
'
operationId: getStructuredLog
responses:
'200':
description: 'is returned if the request is valid
'
'403':
description: 'is returned if there are insufficient privileges to read structured log
parameters.
'
'405':
description: 'is returned when an invalid HTTP method is used.
'
summary: Get the structured log settings
tags:
- Monitoring
put:
description: 'Modifies and returns the server''s current structured log settings.
The request body must be a JSON object with the structured log parameters
being the object keys and `true` or `false` object values, for either
enabling or disabling the parameters.
The result is a JSON object with all available structured log parameters being
the object keys, and `true` or `false` being the object values, meaning the
parameter in the object key is either enabled or disabled.
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.
'
operationId: setStructuredLog
requestBody:
content:
application/json:
schema:
properties:
database:
description: 'One of the possible log parameters.
'
type: boolean
url:
description: 'One of the possible log parameters.
'
type: boolean
username:
description: 'One of the possible log parameters.
'
type: boolean
type: object
responses:
'200':
description: 'is returned if the request is valid
'
'403':
description: 'is returned if there are insufficient privileges to adjust log levels.
'
'405':
description: 'is returned when an invalid HTTP method is used.
'
summary: Set the structured log settings
tags:
- Monitoring
/_db/{database-name}/_admin/metrics:
get:
description: 'Returns the instance''s current metrics in Prometheus format. The
returned document collects all instance metrics, which are measured
at any given time and exposes them for collection by Prometheus.
The document contains different metrics and metrics groups dependent
on the role of the queried instance. All exported metrics are
published with a `arangodb_` or `rocksdb_` prefix to distinguish them
from other collected data.
The API then needs to be added to the Prometheus configuration file
for collection.
'
operationId: getMetrics
parameters:
- description: 'The name of a database. Which database you use doesn''t matter as long
as the user account you authenticate with has at least read access
to this database. If the `--server.harden` startup option is enabled,
administrate access to the `_system` database is required.
'
example: _system
in: path
name: database-name
required: true
schema:
type: string
- description: 'Returns metrics of the specified server. If no serverId is given, the asked
server will reply. This parameter is only meaningful on Coordinators.
'
in: query
name: serverId
required: false
schema:
ty
# --- truncated at 32 KB (76 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/arangodb/refs/heads/main/openapi/arangodb-monitoring-api-openapi.yml