arangovpack Options

While the syscall is generally available since Linux 2.6.x, it is also required that the underlying filesystem supports the splice operation. This is not true for some encrypted filesystems (e.g. ecryptfs), on which splice() calls can fail.

You can set the --use-splice-syscall startup option to false to use a less efficient, but more portable file copying method instead, which should work on all filesystems.

This option applies to the control characters, that have hex codes below \x20, and also the character DEL with hex code \x7f.

If you set this option to false, control characters are retained when they have a visible representation, and replaced with a space character in case they do not have a visible representation. For example, the control character \n is visible, so a \n is displayed in the log. Contrary, the control character BEL is not visible, so a space is displayed instead.

If you set this option to true, the hex code for the character is displayed, for example, the BEL character is displayed as \x07.

The default value for this option is true to ensure compatibility with previous versions.

A side effect of turning off the escaping is that it reduces the CPU overhead for the logging. However, this is only noticeable if logging is set to a very verbose level (e.g. debug or trace).

If you set this option to false, Unicode characters are retained and written to the log as-is. For example, 犬 is logged as 犬.

If you set this options to true, any Unicode characters are escaped, and the hex codes for all Unicode characters are logged instead. For example, 犬 is logged as \u72AC.

The default value for this option is set to false for compatibility with previous versions.

A side effect of turning off the escaping is that it reduces the CPU overhead for the logging. However, this is only noticeable if logging is set to a very verbose level (e.g. debug or trace).

You can specify a hostname to be logged at the beginning of each log message (for regular logging) or inside the hostname attribute (for JSON-based logging).

The default value is an empty string, meaning no hostnames is logged. If you set this option to auto, the hostname is automatically determined.

Each log invocation in the ArangoDB source code contains a unique log ID, which can be used to quickly find the location in the source code that produced a specific log message.

Log IDs are printed as 5-digit hexadecimal identifiers in square brackets between the log level and the log topic:

2020-06-22T21:16:48Z [39028] INFO [144fe] {general} using storage engine 'rocksdb' (where 144fe is the log ID).

ArangoDB’s log output is grouped by topics. --log.level can be specified multiple times at startup, for as many topics as needed. The log verbosity and output files can be adjusted per log topic.

arangod --log.level all=warning --log.level queries=trace --log.level startup=trace

This sets a global log level of warning and two topic-specific levels (trace for queries and info for startup). Note that --log.level warning does not set a log level globally for all existing topics, but only the general topic. Use the pseudo-topic all to set a global log level.

The same in a configuration file:

[log]
level = all=warning
level = queries=trace
level = startup=trace

The available log levels are:

• fatal: Only log fatal errors.
• error: Only log errors.
• warning: Only log warnings and errors.
• info: Log information messages, warnings, and errors.
• debug: Log debug and information messages, warnings, and errors.
• trace: Logs trace, debug, and information messages, warnings, and errors.

Note that the debug and trace levels are very verbose.

Some relevant log topics available in ArangoDB 3 are:

• agency: Information about the cluster Agency.
• performance: Performance-related messages.
• queries: Executed AQL queries, slow queries.
• replication: Replication-related information.
• requests: HTTP requests.
• startup: Information about server startup and shutdown.
• threads: Information about threads.

You can adjust the log levels at runtime via the PUT /_admin/log/level HTTP API endpoint.

Audit logging (Enterprise Edition): The server logs all audit events by default. Low priority events, such as statistics operations, are logged with the debug log level. To keep such events from cluttering the log, set the appropriate log topics to the info log level.

Note: This option does not include audit log messages. See --audit.max-entry-length instead.

Any log messages longer than the specified value are truncated and the suffix ... is added to them.

The purpose of this option is to shorten long log messages in case there is not a lot of space for log files, and to keep rogue log messages from overusing resources.

The default value is 128 MB, which is very high and should effectively mean downwards-compatibility with previous arangod versions, which did not restrict the maximum size of log messages.

Log entries are pushed on a queue for asynchronous writing unless you enable the --log.force-direct startup option. If you use a slow log output (e.g. syslog), the queue might grow and eventually overflow.

You can configure the upper bound of the queue with this option. If the queue is full, log entries are written synchronously until the queue has space again.

This option allows you to direct the global or per-topic log messages to different outputs. The output definition can be one of the following:

• - for stdin
• + for stderr
• syslog://<syslog-facility>
• syslog://<syslog-facility>/<application-name>
• file://<relative-or-absolute-path>

To set up a per-topic output configuration, use --log.output <topic>=<definition>:

--log.output queries=file://queries.log

The above example logs query-related messages to the file queries.log.

You can specify the option multiple times in order to configure the output for different log topics:

--log.level queries=trace --log.output queries=file:///queries.log --log.level requests=info --log.output requests=file:///requests.log

The above example logs all query-related messages to the file queries.log and HTTP requests with a level of info or higher to the file requests.log.

Any occurrence of $PID in the log output value is replaced at runtime with the actual process ID. This enables logging to process-specific files:

--log.output 'file://arangod.log.$PID'

Note that dollar sign may need extra escaping when specified on a command-line such as Bash.

If you specify --log.file-mode <octalvalue>, then any newly created log file uses octalvalue as file mode. Please note that the umask value is applied as well.

If you specify --log.file-group <name>, then any newly created log file tries to use <name> as the group name. Note that you have to be a member of that group. Otherwise, the group ownership is not changed. This option is only available under Linux and macOS. It is not available under Windows.

The old --log.file option is still available for convenience. It is a shortcut for the more general option --log.output file://filename.

The old --log.requests-file option is still available. It is a shortcut for the more general option --log.output requests=file://....

Example: arangod ... --log.prefix "-->"

2020-07-23T09:46:03Z --> [17493] INFO ...

If you set this option to true, log messages contains a single character with the server’s role. The roles are:

• U: Undefined / unclear (used at startup)
• S: Single server
• C: Coordinator
• P: Primary / DB-Server
• A: Agent

Some log messages can be displayed together with additional information in a structured form. The following parameters are available:

• database: The name of the database.
• username: The name of the user.
• url: The endpoint path.
• pregelID: The ID of the Pregel job.

The format to enable or disable a parameter is <parameter>=<bool>, or <parameter> to enable it. You can specify the option multiple times to configure multiple parameters:

arangod --log.structured-param database=true --log.structured-param url --log.structured-param username=false

You can adjust the parameter settings at runtime using the /_admin/log/structured HTTP API.

Overview over the different options:

You can use this option to switch the log output to the JSON format. Each log message then produces a separate line with JSON-encoded log data, which can be consumed by other applications.

The object attributes produced for each log message are:

• 1: a pseudo-random number generator using an implication of the Mersenne Twister MT19937 algorithm
• 2: use a blocking random (or pseudo-random) number generator
• 3: use the non-blocking random (or pseudo-random) number generator supplied by the operating system
• 4: a combination of the blocking random number generator and the Mersenne Twister (not available on Windows)
• 5: use WinCrypt (Windows only)