Link Search Menu Expand Document
Start for Free

Logging

This page discusses the different types of logging available Stardog.

Page Contents
  1. stardog.log
  2. Access and Audit Logging
    1. Access Log
    2. Audit Log
  3. Slow Query Log

stardog.log

Stardog’s server log is the stardog.log which can be found inside your $STARDOG_HOME directory.

Unlike the other logs mentioned in this section (access, audit, and slow query), the stardog.log can be configured via log4j2. A default log4j2.xml can be found in the <stardog-installation-directory>/server/dbms directory. You can copy this file to your $STARDOG_HOME directory to make any modifications you’d like (e.g. log rotation).

$ cp <stardog/installation-directory>/server/dbms/log4j2.xml $STARDOG_HOME

Access and Audit Logging

Audit logging is a superset of the events in access logging. Access logging covers the most often required logging events; you should consider enabling audit logging if you really need to log every server event. Logging generally doesn’t have much impact on performance; but the safest way to insure that impact is negligible is to log to a separate disk (or to a centralized logging server, etc.).

The important configuration choices are whether logs should be binary or plain text (both based on ProtocolBuffer message formats); the type of logging (audit or access); the logging location (which may be “off disk” or even “off machine”). Logging to a centralized logging facility requires a Java plugin that implements the Stardog Server logging interface; see Java Programming for more information; and the log rotation policy (file size or time).

We walk through how to setup both the Access and Audit log sections below and discuss their configuration in more detail.

An example stardog.properties file containing configuration for access and audit is provided in our stardog-examples Github repository.

Access Log

The access log logs all connection-based events, such as queries and transactional changes, and authentication events. Connection boundary events, that is open and closing of the actual connection, are not logged.

The access log is disabled by default and should be enabled explicitly in the stardog.properties configuration file by adding:

logging.access.enabled = true

The type of the access log is required. There are two allowed values: text and binary, both based on Protobuf.

  • In text logs, entries are serialized as key-value pairs in plain text and log entries are delimited by the ASCII Start of Text and ASCII End of Text bytes.
  • In binary logs, entries are written as size delimited protobuf binary messages.

We can add the type of access log by adding the following to the stardog.properties:

logging.access.type = text

Here we’ve chosed to set the type of log as text as opposed to binary.

Optionally you can specify a custom file name for the access log. By default, the access log is saved as a file named access.log inside the $STARDOG_HOME directory. If desired, a different file name can be provided as follows. An absolute path can be provided to save the file in a different directory.

logging.access.file = my_access.log

It is possible to define a file rotation strategy so that log entries will be split into multiple files. One possibility is to define a limit on file size and start a new file when the size limit is reached. The file that exceeds the limit will be renamed with a unique suffix and all the subsequent entries will be added to the newly created file. The size limit is defined in bytes as follows. See the audit log example for defining an alternative way of rotating files based on fixed-time intervals.

logging.access.rotation.type = size
logging.access.rotation.limit = 1000000

The server configuration properties for access logging are documented in completion in the server configuration

Audit Log

As noted earlier, the audit log logs all server events and is a superset of the access log. Access logging covers the most often required logging events; you should only consider enabling audit logging if you really need to log every server event. Logging generally doesn’t have much impact on performance; but the safest way to insure that impact is negligible is to log to a separate disk (or to a centralized logging server, etc.).

The audit log is disabled by default and should be enabled explicitly in the stardog.properties configuration file by adding:

logging.audit.enabled = true

Similar to the access log, the type of the audit log is required. There are two allowed values: text and binary, both based on Protobuf.

  • In text logs, entries are serialized as key-value pairs in plain text and log entries are delimited by the ASCII Start of Text and ASCII End of Text bytes.
  • In binary logs, entries are written as size delimited protobuf binary messages.

We can add the type of audit log by adding the following to the stardog.properties:

logging.audit.type = binary

By default, the audit log is saved as a file named audit.log inside the $STARDOG_HOME directory. Optionally, a different file name can be provided as follows. An absolute path can be provided to save the file in a different directory.

logging.audit.file = my_audit.log

Audit logs can be rotated similar to access logs. Size limit can be used as described above. Alternately, log files can be rotated at fixed time intervals. The interval value should be a positive integer followed by either letter ‘d’ (for days) or letter ‘h’ (for hours). Below is an example to get daily logs:

logging.audit.rotation.type = time
logging.audit.rotation.interval = 1d

The server configuration properties for audit logging are documented in completion in the server configuration

Slow Query Log

As the name suggests, the slow query logs all slow queries. A query is considered to be slow if its execution time exceeds the slow_query.time defined below.

The slow log query should be enabled similar to the access and audit logs:

logging.slow_query.enabled = true

Slow query time is specified as follows. Any query whose execution time exceed this limit will be logged in the slow query log. The time value should be a positive integer followed by either letter ‘h’ (for hours), letter ‘m’ (for minutes), letter ‘s’ (for seconds), or letters ‘ms’ (for milliseconds). Examples intervals are 1h for 1 hour, 5m for 5 minutes, 90s for 90 seconds, and 500ms for 500 milliseconds. If no time is specified in the configuration, the default value of 1 minute will be used.

logging.slow_query.time = 10s

Unlike access or audit logs, slow query log has a default type for formatting the slow query events which is intended to be human-readable. If no log type is specified, this default type will be used. This default format is not suitable for machine-processing and meant to be only for developers to read. For a machine-processable format, the type of the slow query log can be set similar to the access and audit logs (binary).

logging.slow_query.type = text

The server configuration properties for slow query logging are documented in completion in the server configuration