Logs

Server events and errors are logged depending on the defined log levels for the available log topics

Whether events are logged to a file, syslog, or only an attached terminal depends on the log startup options.

See Log levels for a detailed description of the FATAL, ERROR, and other levels of log messages.

The permissions required to use the /_admin/log* endpoints depends on the setting of the --log.api-enabled startup option.

Get the global server logs

GET /_admin/log/entries

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.

Path Parameters
    Query Parameters
    • 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.

    • Returns all log entries of log level level. Note that the query parameters upto and level are mutually exclusive.

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

    • Restricts the result to at most size log entries.

    • Starts to return log entries skipping the first offset log entries. offset and size can be used for pagination.

    • 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.

    • 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.

    HTTP Headers
      Responses
      • is returned if the request is valid.

      • is returned if invalid values are specified for upto or level.

      • is returned if there are insufficient privileges to access the logs.

      Get the global server logs (deprecated)

      GET /_admin/log
      This endpoint should no longer be used. It is deprecated from version 3.8.0 on. 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.

      Path Parameters
        Query Parameters
        • 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.

        • Returns all log entries of log level level. Note that the query parameters upto and level are mutually exclusive.

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

        • Restricts the result to at most size log entries.

        • Starts to return log entries skipping the first offset log entries. offset and size can be used for pagination.

        • 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.

        • 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.

        HTTP Headers
          Responses
            • Response Body application/json object
            • A list of the log levels for all log entries.

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

            • a list of the texts of all log entries

            • a list of the timestamps as seconds since 1970-01-01 for all log entries.

            • a list of the topics of all log entries

            • the total amount of log entries before pagination.

          • is returned if invalid values are specified for upto or level.

          • is returned if there are insufficient privileges to access the logs.

          Get the server log levels

          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.

          Path Parameters
            Query Parameters
            • Forwards the request to the specified server.

            • Set this option to true to return the individual log level settings of all log outputs (appenders) as well as the global settings.

              The response structure is as follows:

              {
                "global": {
                  "agency": "INFO",
                  "agencycomm": "INFO",
                  "agencystore": "WARNING",
                  ...
                },
                "appenders": {
                  "-": {
                    "agency": "INFO",
                    "agencycomm": "INFO",
                    "agencystore": "WARNING",
                    ...
                  },
                  "file:///path/to/file": {
                    "agency": "INFO",
                    "agencycomm": "INFO",
                    "agencystore": "WARNING",
                    ...
                  },
                  ...
                }
              }
              

            HTTP Headers
              Responses
              • is returned if the request is valid

              • is returned if there are insufficient privileges to read log levels.

              Set the server log levels

              PUT /_admin/log/level

              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 - Only critical errors are logged after which the arangod process terminates.
              • ERROR - Only errors are logged. You should investigate and fix errors as they may harm your production.
              • WARNING - Errors and warnings are logged. Warnings may be serious application-wise and can indicate issues that might lead to errors later on.
              • INFO - Errors, warnings, and general information is logged.
              • DEBUG - Outputs debug messages used in the development of ArangoDB in addition to the above.
              • TRACE - Logs detailed tracing of operations in addition to the above. This can flood the log. Don’t use this log level 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.

              Path Parameters
                Query Parameters
                • Forwards the request to the specified server.

                • Set this option to true to set individual log level settings for log outputs (appenders). The request and response structure is as follows:

                  {
                    "global": {
                      "agency": "INFO",
                      "agencycomm": "INFO",
                      "agencystore": "WARNING",
                      ...
                    },
                    "appenders": {
                      "-": {
                        "agency": "INFO",
                        "agencycomm": "INFO",
                        "agencystore": "WARNING",
                        ...
                      },
                      "file:///path/to/file": {
                        "agency": "INFO",
                        "agencycomm": "INFO",
                        "agencystore": "WARNING",
                        ...
                      },
                      ...
                    }
                  }
                  

                  Changing the global settings affects all outputs and is the same as setting a log level with this option turned off.

                HTTP Headers
                  Request Body application/json object
                  • Agents use this log topic to inform about any activity including the RAFT consensus gossip.

                  • DB-Servers and Coordinators log the requests they send to the Agency.

                  • Optional verbose logging of Agency write operations.

                  • Pseudo-topic to address all log topics.

                  • 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.

                  • Logs information related to ArangoSearch including Analyzers, the column cache, and the commit and consolidation threads.

                  • Controls whether events such as successful logins and missing or wrong credentials are written to the audit log (Enterprise Edition only).

                  • Controls whether events such as users trying to access databases without the necessary permissions are written to the audit log (Enterprise Edition only).

                  • Controls whether events about collections creation, truncation, and deletion are written to the audit log (Enterprise Edition only).

                  • Controls whether events about database creation and deletion are written to the audit log (Enterprise Edition only).

                  • Controls whether document read and write events are written to the audit log (Enterprise Edition only).

                  • Controls whether the Hot Backup creation, restore, and delete events are written to the audit log (Enterprise Edition only).

                  • Controls whether the start and stop events of the audit service are written to the audit log (Enterprise Edition only).

                  • Controls whether events about View creation and deletion are written to the audit log (Enterprise Edition only).

                  • Logs events related to authentication, for example, when a JWT secret is generated or a token is validated against a secret.

                  • Logs when a user has insufficient permissions for a request.

                  • Logs events related to Hot Backup (Enterprise Edition only).

                  • Logs events related to benchmarking with arangobench.

                  • Logs events related to caching documents and index entries as well as the cache configuration on startup.

                  • 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.

                  • Logs lower-level network connection and communication events.

                  • Logs information related to the startup options and server configuration.

                  • Logs information about a fatal error including a backtrace before the process terminates.

                  • Warns about deprecated features and the usage of options that will not be allowed or have no effect in a future version.

                  • This log topic is reserved for the development of ArangoDB.

                  • Logs events related to dumping data with arangodump.

                  • 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.

                  • Logs events related to flushing data from memory to disk.

                  • 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.

                  • Logs information related to graph operations including graph traversal and path search tracing.

                  • Logs everything related to the cluster heartbeat for monitoring the intra-connectivity.

                  • Logs the activity of the HTTP request subsystem that is used in replication, client tools, and V8.

                  • Logs the internal log messages of IResearch, the underlying library of ArangoSearch.

                  • Logs events related to the license management like the expiration of a license (Enterprise Edition only).

                  • Logs the operations of the cluster maintenance including shard locking and collection creation.

                  • Logs the memory configuration on startup and reports problems with memory alignment and operating system settings.

                  • Logs slow queries as well as internal details about the execution of AQL queries at low log levels.

                  • Logs information related to the data replication within a cluster.

                  • 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.

                  • This log topic is only used by arangorestore.

                  • 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.

                  • Logs the security configuration for V8.

                  • Logs information related to the in-transit encryption of network communication using SSL/TLS.

                  • Logs information related to the startup and shutdown of a server process as well as anything related to upgrading the database directory.

                  • Logs events related to processing server statistics. This is independent of server metrics.

                  • Logs information related to the Agency’s cluster supervision.

                  • Logs events related to calling operating system functions. It reports problems related to file descriptors and the server process monitoring.

                  • Logs information related to the use of operating system threads and the threading configuration of ArangoDB.

                  • Logs information about transaction management.

                  • Logs the activity of the background thread for time-to-live (TTL) indexes.

                  • Logs various information related to ArangoDB’s use of the V8 JavaScript engine, like the initialization as well as entering and exiting contexts.

                  • Logs when the schema validation fails for a document.

                  • Logs certain events related to ArangoSearch Views.

                  Responses
                  • is returned if the request is valid

                  • is returned when the request body contains invalid JSON.

                  • is returned if there are insufficient privileges to adjust log levels.

                  • is returned when an invalid HTTP method is used.

                  Reset the server log levels

                  Introduced in: v3.12.1

                  DELETE /_admin/log/level

                  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.

                  Path Parameters
                    Query Parameters
                    • Forwards the request to the specified server.

                    HTTP Headers
                      Responses
                      • The log levels have been reset successfully.

                      • You have insufficient privileges to reset the log levels.

                      Get the structured log settings

                      GET /_admin/log/structured

                      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.

                      Responses
                      • is returned if the request is valid

                      • is returned if there are insufficient privileges to read structured log parameters.

                      • is returned when an invalid HTTP method is used.

                      Set the structured log settings

                      PUT /_admin/log/structured

                      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.

                      Request Body application/json object
                      • One of the possible log parameters.

                      • One of the possible log parameters.

                      • One of the possible log parameters.

                      Responses
                      • is returned if the request is valid

                      • is returned if there are insufficient privileges to adjust log levels.

                      • is returned when an invalid HTTP method is used.