Diagnosing and Reporting Critical Errors

It is essential to gather as many details as possible about an issue once it appears. For this purpose, we provide utilities that generate such issue reports by collecting data from various log files, JVM, etc. Using these issue reports helps us to investigate the problem and provide an appropriate solution as quickly as possible.

Report

GraphDB provides an easy way to gather all important system information and package it as an archive that can be sent to graphdb-support@ontotext.com. Run the report using the GraphDB Workbench, or from the generate-report script in the bin directory of your distribution. The report is saved in the GraphDB-Work/report directory. There is always one report - the one that has been generated most recently.

Report content

• GraphDB version

• recursive directory list of the files in GraphDB-Home as home.txt

• recursive directory list of the files in GraphDB-Work as work.txt

• recursive directory list of the files in GraphDB-Data data.txt

• the 30 most recent logs files from GraphDB-Logs ordered by time of creation

• full copy of the content of GraphDB-Conf

• the output from jcmd GC.class_histogram as jcmd_histogram.txt

• the output from jcmd Thread.print as thread_dump.txt

• the System Properties for the GraphDB instance

• the repository configurations info as system.ttl. All repositories can be found in this file.

• the owlim.properties file for each repository if found. It exists only when the repository has been initialized at least once.

In a cluster, the report can be run from each node in the group. It adds the following to the standard report:

• Report data for each node in the cluster

• Information about the cluster status in the graphdb-server-report-<timestamp>/cluster/cluster-status.json file: endpoints, status, and state of each node

• cluster-config.ttl: The cluster configuration in Turtle format

Each node where a report is requested triggers the report for other nodes, and waits for the result until it is ready, or until a certain time limit is reached. The maximum time to wait is configured via the graphdb.wait.report.minutes property in the graphdb.properties with a default of 120 minutes. In case of a timeout or an error, it will be written to the info.txt file for the corresponding node.

Create report from the Workbench

Go to Help ‣ System information. Click on New report in the Application info tab to obtain a new one, wait until it is ready, and download it. It is downloaded in .zip format as graphdb-server-report-<timestamp>.

Create report through the report script

The generate-report script can be found in the bin folder in the GraphDB distribution. It needs graphdb-pid - the GraphDB for which you want a report. An optional argument is output-file, the default for which is graphdb-server-report.zip.

Logs

GraphDB uses slf4j for logging through the Logback implementation (the RDF4J facilities for log configuration discovery are no longer used). Instead, the whole distribution has a central place for the logback.xml configuration file in GraphDB-HOME/conf/logback.xml. If you use the .war file setup, you can provide the log file location through a system parameter, or we will pick it up from the generated .war file.

Note

Check the Logback configuration location rules for more information.

On startup, GraphDB logs the logback configuration file location:

[INFO ] 2022-06-06 09:44:26,179 [main | c.o.g.Config] Using 'file:/opt/graphdb/conf/logback.xml' as logback's configuration file

Setting up the root logger

The default root logger is set to info. You can change it in several ways:

• Edit the logback.xml configuration file.

  Note

  You do not have to restart the database as it will check the file for changes every 30 seconds, and will reconfigure the logger.

• Change the log level through the logback JMX configurator. For more information, see the Logback manual chapter 10.

• Start each component with graphdb.logger.root.level set to your desired root logging level. For example:

  bin/graphdb -Dgraphdb.logger.root.level=WARN
  

Logs location

By default, all database components and tools log in GraphDB-HOME/logs when run from the bin folder. If you set up GraphDB by deploying .war files into a standalone servlet container, the following rules apply:

1. To log in a specified directory, set the logDestinationDirectory system property.

2. If GraphDB is run in Tomcat, the logs can be found in $catalina.base/logs/graphdb.

3. If GraphDB is run in Jetty, the logs can be found in $jetty.base/logs/graphdb.

4. Otherwise, all logs are in the logs subdirectory of the current working directory for the process.

Log files

Different information is logged in different files. This makes it easier to follow what goes on in different parts of the system.

File name	Description
audit-log.log	On a running GraphDB instance with security ON, this file contains a log of all operations performed on the instance and who performed them. To start an audit trail, at least one of the graphdb.audit.role and graphdb.audit.repository parameters should be enabled.
error.log	Contains a log of all ERROR messages returned while the instance was running.
main.log	Contains all messages coming from the main part of the engine.
query-log.log	Contains all queries that were sent to the database. The format is machine-readable and allows you to replay the queries when debugging a problem.
slow-query-log.log	Contains slow queries as per the SlowOpThresholdMs parameter.