Configuring System Logs

The log files contain important information about how the server is running. If you suspect a problem or cannot pinpoint an error, you can change log levels to capture verbose messages while you test your issue.

JasperReports Server now uses the Apache Log4j 2 package to generate log files. JasperReports Server also uses the SLF4J facade (Simple Logging Facade for Java) and the Log4j 2 SLF4J Binding.

To view the log file, you must have access to the file system where JasperReports Server is installed. This section describes the settings that control what information JasperReports Server writes to its logs.

Log Levels

A logger is a Java class that implements a logging interface for sending messages related to internal events of the server. The various features or internal modules of the server have separate loggers that can be controlled independantly. The level of a logger determines the number and types of events it writes to the log file.

Log levels may be set in two places, either the log4j2.properties configuration file or the Log Settings UI page, or both. Because there may be multiple settings for a given logger, the effective level is determined in the following order:

All loggers that are not explicitly set to another level will have the root level. Jaspersoft does not recommend changing the root level because any other level than ERROR will generate huge log files and affect performance. Setting a log level in the log4j2.properties configuration file requires restarting the server. Setting a log level on the Log Settings UI page will take effect immediately and override any level set in the log4j2.properties file.

These settings are described in the following sections.

Editing the Log Configuration File

The log configuration file can be used to define new loggers, logging levels, log output, and log format, but you must restart the server for your changes to take effect.

The configuration file for logging depends on whether you want to define loggers for import or export operations or all other server functionality.

Loggers are based on the Java classname of the functionality that you want to log. To find an existing logger or create a new one, you must know the corresponding classname. A logger in the configuration file is defined by three related definitions with the following syntax:

logger.<logger-name>.name=<Java-classname>
logger.<logger-name>.level=<log-level>
logger.<logger-name>.appenderRef.<output-type>.ref=<output-name>

where:

logger.net_sf_jasperreports_engine_query_JRJdbcQueryExecuter.name=net.sf.jasperreports.engine.query.JRJdbcQueryExecuter
logger.net_sf_jasperreports_engine_query_JRJdbcQueryExecuter.level=debug
logger.net_sf_jasperreports_engine_query_JRJdbcQueryExecuter.appenderRef.stdout.ref = stdout
logger.net_sf_jasperreports_engine_query_JRJdbcQueryExecuter.appenderRef.rolling.ref = fileout

Some common loggers are given as comments in the configuration file, simply remove the comment character (#) from each line to add the logger. Otherwise, add all three properties to create a new logger.

Restart the server for your changes to take effect.

If you've made modifications in the Log Settings UI, those settings are persistent in the repository and take precedence over the configuration files. However, changes in the UI are not written to the configuration files. Each setting is independent. For more information, see Log Levels.

Configuring the Log Format

The available parameters for JasperReports Server logs include:

JasperReports Server logs follow the following format, for example, for Log4j:

<Log4j pattern> <Request type> <Session Id> <User Id> <Resource URI> <Request Status> <TimeTaken> - <Actual text log message>

Here is an example log from jasperserver.log when Data source fails:

2023-07-14T03:22:13,469 ERROR SecureExceptionHandlerImpl,http-nio-8080-exec-6:135 -

{REQUEST_STATUS=200, REQUEST_TYPE=POST, SESSION_ID=7F1DCDC110417960C651152A80E1877E, TIME_TAKEN=13, USER_ID=superuser}

- FATAL: no PostgreSQL user name specified in startup packet org.postgresql.util.PSQLException: FATAL: no PostgreSQL user name specified in startup packet

To configure the log format, use the log4j.properties file located in the WEB-INF folder. You can log all available parameters, or log a specific parameter.

Notes:

To log all parameters of Log4j's ThreadContext, use %X in layout pattern.

For example, use %X in log4j2.properties:

appender.fileout.layout.pattern=%d{ISO8601}%5p %c{1},%t:%L - %X - %m%ex%n

To log a specific parameter, use:

%X{parameter_name}

For example:

%X{USER_ID}

To log more than 1 parameter, use:

%X{parameter_name1}, %X{parameter_name2}, %X{parameter_name3}

For example:

appender.fileout.layout.pattern=%d {ISO8601} %5p %c {1},%t:%L - %X{USER_ID}, %X{SESSION_ID}- %m%ex%n

Setting Log Levels in the UI

JasperReports Server provides a simple way to set log levels through the UI, and these settings take effect immediately on the server. Log settings in the UI are also stored persistently in the repository. This is useful for debugging any issues by setting the log level temporarily to avoid too much log output. However, you must remember to set it back or remove the setting when done.

To set the current logging levels:

com.jaspersoft.ji.adhoc.action.AdhocCrosstabAjaxController

After creating a logger in this manner, the logger appears on the page and you can change its level again when necessary. The new logger is also stored in the repository and is persistent when the server is restarted, but it will no longer appear in the Log Settings Page. You can however enter its classname again with the desired log level.

When viewing and setting loggers on the Log Settings page, keep the following in mind:

The following table describes the loggers presented on the Log Settings page. To change which loggers appear permanently on the page, see Adding a Logger to the Log Settings Page.

Adding a Logger to the Log Settings Page

If you know of a Log4j 2 logger that JasperReports Server uses, you can edit a configuration file to add it to the Log Settings page available to the superuser.

To edit the list of loggers on the Log Settings page:

Entries should be in the form <Java-classname> = <description>.

See the other properties in the file for guidance, for example:

com.jaspersoft.ji.adhoc.action.AdhocCrosstabAjaxController = Crosstab controller

The logger_descriptions_pro.properties file does not set any logger levels, it only determines which loggers are listed in the Log Settings UI. Loggers are shown in the UI with their currently active level, as described in Log Levels.

Using the Monitoring Tool

JasperReports Server Professional Edition includes a monitoring tool that you can configure and launch to allow you to view diagnostic JMX and hardware details in a file generated by the tool.

Prerequisites

Configuration

Otherwise, the output file path is configured, and then default output file name is jrs-monitoring-report.txt.

Example of Output file path configuration

a. Configuring environment variable:

export TOOL_OUTPUT_FILE_PATH=/tmp/myreport.txt

b. While executing tool jar, provide system property option:

-Dtool.output.file.path=/tmp/myreport.txt

Launching the executable tool jar

Configuration

To launch the executable tool jar using environment variable configuration:

Once all the configuration are done by setting appropriate environment variables, launch the tool using:

java -jar monitoring-tool.jar

To launch using System properties configuration java, run:

Dtool.jmx.url=service:jmx:rmi://localhost/jndi/rmi://localhost:10990/jasperserver -Dtool.jmx.username=superuser -Dtool.jmx.password=superuser -jar monitoring-tool.jar