17. Logging

RDFox supports two types of logging: API logging, which can be used with any RDFox interface, and HTTP request logging, which is specific to the RDFox endpoint. This section describes the purpose of each type of logging and provides guidance on usage.

17.1. API Logging

API logging has been designed in order to simplify the reproduction of issues with importation, querying or reasoning, regardless of which RDFox API is being used when an issue is encountered. To support reproducing a problem, API logging can be switched on, after which all calls to the core RDFox API are logged into a shell script. This script can later be run in the RDFox shell, and this will produce exactly the same sequence of internal calls to RDFox. Hence, replaying the script will hopefully reproduce the original problem, which is the first important step towards analysing the problem and providing support.

Each shell command written to the script is surrounded by comments containing the time and date of the API call, the duration of the call, and the details of any exception arising as a result of the call. This information is intended to help with analysing the problem.

When API logging is enabled, each RDFox server session creates a subdirectory of the configured logging directory whose name is derived from the date and time that the server was started. The directory will contain a single script file named script.txt. Additionally, each distinct input imported during the session is recorded as a separate file in the directory so that the shell script can repeat the relevant import operations. An exception to this is inputs imported as files: since these are already available from the local filesystem and may be large, API logging does not create copies.

API logging is configured via the server parameters whose names begin with api-log (see Section 7.2).

17.2. HTTP Request Logging

HTTP request logging provides standardised logging of HTTP requests serviced by the RDFox endpoint. Both the common and extended log formats are supported. In contrast to API logging, request logging has been implemented to minimise the impact on performance as much as possible, and so the use of HTTP request logging in production is recommended.

HTTP request logging is configured via the endpoint parameters request-logger and, when the extended log format logger is active, elf-logger-fields (see Section 13.2).

17.2.1. Errors and Exceptions

The endpoint attempts to ensure that, when a logger is configured, a single log entry is created for each attempted request, regardless of any errors that have occurred. For example, if a client connects and then sends arbitrary data not conforming to the HTTP protocol, a log entry is still made with dashes (-) in place of, for example, the request method or URI.

In the case of an error which prevents RDFox accepting a new connection, the extended log format logger supports the proprietary field identifier x-socket-exception which can be used to specify that the textual representation of such errors should be included in the log. This can be useful for diagnosing problems with the configuration of the endpoint such as when the number of concurrent connections to the endpoint exhausts the allowed limit for open file descriptors.