Logging
This page discusses the different types of logging available Stardog.
Page Contents
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