# Logging

JReport provides a robust, flexible and configurable logging system which is based on log4j version 1.2.8, and supports versions from log4j version 1.2.8 to 1.3alpha7.

The logging system is used for obtaining meaningful and helpful JReport logging information in a convenient way. It is easy to configure and manage. The following are the significant benefits of the JReport logging system:

- It is compatible with your application which is based on log4j.
- It can be configured to output the logging information of different modules separately or to output them all together.
- It supports setting trace and error types' levels separately.

## Configuring logs

Log configuration tasks can be achieved in two ways. They are:

- Using the LogConfig.properties file located in `<install_root>\bin` directory.
- Using command options.

  In comparison with earlier versions, the command options used for log configuration have undergone a considerable change. The following are descriptions of these options:

  Options | Description
  --- | ---
  -vDebug | Sets all log files' trace levels to INFO and error level to WARN.
  -vError | Sets all log files' trace levels to OFF and error level to ERROR.
  -log[:<file>] | Outputs message to the file as specified and uses the -vDebug level.

  Note: Any settings made using the command options will override the trace and error type level settings in the LogConfig.properties file. To log on console when using the two commands above: -vDebug or -vError, configure the appender in LogConfig.properties first.

## Configuring output log appenders

JReport logging system provides certain appenders to which log content can be output and by default, the output file is located in `<install_root>\logs` directory. For example:

- JReportRollingFile
- JReportDailyRollingFile
- JReportConsole

By default, all log categories use one appender, JReportRollingFile. However, you can also define different output appenders or files for different log categories in the LogConfig.properties file, which is located in `<install_root>\bin`. For example, to add another log appender - JReportConsole for the Designer, edit the LogConfig.properties file as follows:

    log4j.logger.com.jinfonet.designer=, JReportRollingFile, JReportConsole
    ...
    log4j.appender.RootConsole=org.apache.log4j.ConsoleAppender
    log4j.appender.RootConsole.layout=com.jinfonet.util.JRPatternLayout
    log4j.appender.RootConsole.layout.ConversionPattern=%m [%t][%p][%d{HH:mm:ss,SSS}]%n
    log4j.appender.RootConsole.threshold=ON
    log4j.appender.RootConsole.target=System.out
    ...

## Logging information using the trace and error type

The JReport logging system enables you to log situations by using the trace and error type. Trace is used for logging something expectable or regular, such as tracing a program workflow, logging runtime information and associated elements. Error is used for logging something unexpected or irregular. For example, when a URL is unreachable, a file does not exist, or a table cannot be found in a data source.

Trace type is divided into four levels, and is ordered according to the amount of information logged, from the least to the most. These levels are OFF, OUTLINE, INFO, and TRIVIAL. Similarly, error type is also divided into four levels, and is ordered according to the amount of information logged, from the least to the most. These levels are OFF, FATAL, ERROR, and WARN.

If you want the least amount of information to be logged, you can set trace level to OUTLINE and error level to ERROR. If you want the most amount of information to be logged, you can set trace level to TRIVIAL and error level to WARN. Setting these to the highest level could affect system performance as well as disk usage.

Trace levels

- OFF
  Specifies not to use the trace level.
- OUTLINE
  The OUTLINE level specifies an outline of program workflow, and dump global variables, including a single thread, multiple threads, the time for when to begin to fetch data, and success in exporting to the specified result format.
- INFO
  The INFO level specifies informational messages that highlight the application progress at a coarse-grained level, and important local variables, such as query, parameter, formula value used when running report sets, connection information, and SQL statement.
- TRIVIAL
  The TRIVIAL Level specifies fine-grained informational events most useful in tracing an application. Such as the report structure dump, or the result set dump.

Error levels

- OFF
  Specifies not to use the Error level.
- FATAL
  The FATAL level specifies severe error events that will presumably lead the application to abort, for example, failing to read the valid key, and exceptions that result in feature incompleted.
- ERROR
  The ERROR level specifies error events that may allow the application to continue running, such as failing to load a report set, failing to find a catalog file, failing to parse a parameter, and failing to create db buffer.
- WARN
  The WARN level specifies potentially harmful situations, such as failing to find the resource, or having found invalid query or formula with grammar error when loading a catalog.

## Configuration settings - effect on performance

The following are configuration properties which have an effect on performance:

- If the showTitle property is set to true in the LogConfig.properties file, the log file size will increase. However, the effect on performance is negligible.
- The levels of trace and error affect the amount of logging output. The higher the level, the more the output. However, the effect on performance is negligible.
- The use of the following conversion characters in ConversionPattern property results in the slow generation of caller class or location information: %C, %F, %L and %M. Their use should be avoided unless execution speed is not an issue. For information about the ConversionPattern property, see comments in the LogConfig.properties file, which is located in the `<install_root>\bin` directory.