Log Files

There are several types of log files available for troubleshooting your RTView system. Display Server and Data Server log files contain output stream and error stream content. If your Display Server or Data Server is not   operating properly, search for   errors and exceptions in the RTView log file as well as the Tomcat application (or other application server) log file. If the RTView Data Servlet is used to provide HTTP access to your Data Server, also   search for   errors and exceptions in both types of log files.

This section contains:

“RTView Log Files”:   Describes how to use Log4j. This section includes:

•        “Obtaining Log Files”

•        “Formatting Log Files”

•        “Rolling Log Files”

•        “Windows Service Viewer”

•        “Using JMX Access to Log Trace Levels”

“Tomcat Log Files” (or other application server):   Describes how to obtain Tomcat log files.

RTView Log Files

This section describes how to use Apache Log4j v.1.2.x to generate log files for troubleshooting and debugging RTView applications. You can view RTView application output and error streams while testing or while operating in the production environment. Log4j enables you to format log files and make them searchable, and also allows log file output to multiple destinations.

By default, RTView processes (Builder, Viewer, Data Server, Display Server, or Historian) print log messages to the console. To obtain log files, redirect the RTView application output and error streams to a log file using Log4j.

The log file format is specified by a configuration file. By default, the sl.log4j.properties configuration file is used which is suitable for most use cases. We recommend using the sl.log4j.properties configuration file as it ensures that the Log4j features are available for RTView applications. You can modify the log file format by editing the sl.log4j.properties configuration file.

Note: To run the application as a background process use the sl-bg.log4j.properties configuration file (which only outputs to a log file rather than to a console) and the -bg command line argument. See “Obtaining Log Files”, next.

This section includes:

§        “Obtaining Log Files”

§        “Formatting Log Files”

§        “Rolling Log Files”

§        “Windows Service Viewer”

§        “Using JMX Access to Log Trace Levels”

Obtaining Log Files

To obtain Log4j log files, turn on Log4j using the -log4j option when you start the RTView application from a Windows Command Prompt or UNIX terminal window. The following example illustrates how to start Log4j for the Data Server.

RTView v.6.0.1+

Windows: 

In an initialized command window (see “Initializing a Command Prompt or Terminal Window”), type:

run_dataserver –log4j   

To run the application as a background process, type:

run_dataserver –bg –log4j –log4jprops:sl-bg.log4j.properties 

UNIX: 

In an initialized command window (see “Initializing a Command Prompt or Terminal Window”), type:

run_dataserver –log4j

 To run the application as a background process, type:

run_dataserver –bg –log4j –log4jprops:sl-bg.log4j.properties

The following arguments are also available:

For example:

run_dataserver –log4j

run_dataserver –log4j –log4jlevel:INFO –showlogcat

After executing this command, the first time-stamped row in the log file appears as follows:

2012-02-02 14:00:54,693 INFO – [rtview] Log4j is being used with sl.log4j.properties as the configuration file.

When Log4j is not in use, the first time-stamped row in the log file appears as follows:

2012-02-03 10:40:31.866 [rtview] Logging redirected for System.out and System.err. Log4j is not in use.

(Note the missing INFO column when Log4j is not in use.)

Note: The logging method from previous versions of RTView does not use Log4j. This previous method of logging is enabled with -logfile and –logdir and is still supported. Do not use both the previous logging method and Log4j or you receive the following error message: ERROR: log4j configuration ERROR - com.sl.rtview.useLog4j is set to true but -logfile redirection is in use. Log4j will not be used.

Formatting Log Files

To modify log file settings edit the .properties configuration file, located in the RTV_HOME\lib directory. To format log files, edit appenders and layouts in the .properties file.

§        Appenders: Specify the output destination for a log file. Appenders exist for the console, files, GUI components, remote socket servers, JMS, NT Event Loggers, and remote UNIX Syslog daemons. Logging can also be performed asynchronously. Multiple appenders can be attached to a logger. By default, the .properties file has two appenders. The first appender is output to the console and the second appender is output to the log file.

§        Layouts: Specify the output format by associating layouts with appenders. Use the PatternLayout to specify the output format according to conversion patterns similar to the C language printf function.

For example, the PatternLayout with the conversion pattern:

%r [%t] %-5p %c - %m%n

outputs something similar to:

176 [main] INFO org.foo.Bar - Located nearest gas station.

The first field is the number of milliseconds elapsed since the start of the program. The second field is the thread making the log request. The third field is the level of the log statement. The fourth field is the name of the logger associated with the log request. The text after the '-' is the message of the statement.

For details about PatternLayout specifications, see: http://logging.apache.org/log4j/1.2/apidocs/org/apache/log4j/PatternLayout.html

The following is an example sl.log4j.properties configuration file with default settings. The log file generated by these settings follows.

sl.log4j.properties With Default Settings

log4j.rootLogger=ALL

log4j.logger.com.sl.gmsjrtview.RTVLog=ALL, rtv_stdout, R

log4j.additivity.com.sl.gmsjrtview.RTVLog=false

log4j.appender.rtv_stdout=org.apache.log4j.ConsoleAppender

log4j.appender.rtv_stdout.layout=org.apache.log4j.PatternLayout

log4j.appender.rtv_stdout.layout.ConversionPattern=%d{yyyy-MM-dd HH:mm:ss.SSS} %-5p - %m%n

log4j.appender.rtv_stdout.threshold=info

log4j.appender.R=org.apache.log4j.RollingFileAppender

log4j.appender.R.File=rtview.log

log4j.appender.R.MaxFileSize=1000KB

log4j.appender.R.MaxBackupIndex=1

log4j.appender.R.layout=org.apache.log4j.PatternLayout

log4j.appender.R.layout.ConversionPattern =%d{yyyy-MM-dd HH:mm:ss.SSS} %-5p %t - %m%n

log4j.appender.R.threshold=info

The following is the log file generated by the default sl.log4j.properties file.

Example Log File With Default Settings

The default settings have the following fields (listed in bold):

(Date            Time          Level   Category     Logging Message)

2012-03-08 16:19:44.702 INFO - [rtview] Log4j is being used with C:\rtview_svn_trunk\core\lib\sl.log4j.properties as the configuration file.

2012-03-08 16:19:45.882 INFO - [rtview] ... processMainArgument: jmx -jmxdstrace:5

2012-03-08 16:19:45.882 INFO - ... traceLevel: 3 false

2012-03-08 16:19:45.882 INFO - [rtview] ... processMainArgument: cache -cachedstrace:5

2012-03-08 16:19:45.882 INFO - [cache] ... cacheDs.traceLevel: 3 false

 2012-03-08 16:19:45.891 INFO - [rtview] ERROR: GmsRtViewXmlDs -- jmx_constants.xml not found.

2012-03-08 16:19:45.892 INFO - [jmx] *** JmxDs.initializeData()

2012-03-08 16:19:45.892 INFO - [jmx] ... Connection <Logging> connecting to server via host:port: localhost:9990

Formatting Notes:

§        appender.R=org.apache.log4j.RollingFileAppender specifies to rollover log file according to the MaxFileSize. For details, see http://logging.apache.org/log4j/1.2/apidocs/org/apache/log4j/DailyRollingFileAppender.html.

§        appender.R.File=rtview.log specifies the name of the log file in use (rtview.log).

§        appender.R.MaxFileSize=1000KB specifies log file rolling to occur when the log file reaches a size of 1000KB.

§        appender.R.layout, the line in bold in the above .properties file example, specifies the PatternLayout that formats the log file:

%d{yyyy-MM-dd HH:mm:ss.SSS} %-5p %t - %m%n

The converted code creates the following format:

Date, Time, Level, Category, Logging Message.

For details about code conversion for PatternLayout, see http://logging.apache.org/log4j/1.2/apidocs/org/apache/log4j/PatternLayout.html.

§        To setup log file rollover to occur every 24 hours at midnight, replace RollingFileAppender with DailyRollingFileAppender, and remove the following two lines:

log4j.appender.R.MaxFileSize=1000KB

log4j.appender.R.MaxBackupIndex=1 (keep only one older file)

For details about code conversion for DailyRollingFileAppender, see http://logging.apache.org/log4j/1.2/apidocs/org/apache/log4j/DailyRollingFileAppender.html.

Log File Fields

For more information, see http://logging.apache.org/log4j/1.2/apidocs/org/apache/log4j/Level.html.

For more information about Log4j, see http://logging.apache.org/log4j/1.2/manual.html, and Log4j tutorial.

Rolling Log Files

Log files grow large very quickly with obsolete data. There are two methods for managing log file size, one method is time-based and the other is file size-based:

§        Rolling File Appender - With this method the log file rolls over when it reaches a certain size. For example, if you specify a maximum size of 1024kb for a log file, the oldest line is removed when that size is exceeded. The log file always contains only the latest entries. For details, see http://logging.apache.org/log4j/1.2/apidocs/org/apache/log4j/RollingFileAppender.html.

§        Daily Rolling File Appender - With this method log files store data for a specified period of time and subsequently saved with a new file name. For example, if you specify the time for midnight, every day at 11:59:59 PM the date and time is appended to the log file name. The original log file continues logging for the next 24 hours and the process repeats. Each log file contains entries for a 24 hour period. For details, see http://logging.apache.org/log4j/1.2/apidocs/org/apache/log4j/DailyRollingFileAppender.html

Windows Service Viewer

For details about how to use Log4j with Windows Service, see “Log4j and Windows Service”.

Using JMX Access to Log Trace Levels

This section describes how to use JMX Access to log trace levels. JMX Access enables you to increase logging information output while an application is running.

If you are using Log4j as your logger you can dynamically set logging trace levels for the different “Logging Categories”. This is accomplished with the RTView Manager JMX MBean RTView:name=Manager. To gain access to the RTView process MBeans you must first start the process with a defined JMX port (see the jmxport command line properties documentation for the RTView process you want to set up logging for in Appendix C).

You can connect to this MBean via the JConsole utility. The screen shots show JConsole for JDK 1.5.n (J2SE 5.0). You can also connect to the MBean from your own Java code.

1.     In an initialized command window (see “Initializing a Command Prompt or Terminal Window”), turn on Log4j JMX Access by adding –jmxport:9991 to the script that starts the RTView application. Choose a different port number if using multiple applications (such as 9990 for the Display Viewer, 9991 for the Builder and so forth). The following example uses the Data Server run_builder.bat file:

run_builder –log4j –jmxport:9991 

2.     In an initialized command window (see “Initializing a Command Prompt or Terminal Window”), open JConsole by typing:

C:> jconsole 

The JConsole Connect to Agent dialog opens.

3.     Choose the RTView process that you want to control and click Connect (note that this example is connecting to an RTView Builder process). The following JConsole connections dialog shows the two MBean Servers that should appear.

The JConsole Connection dialog opens.

4.     Select the MBeans tab, then select the Attributes tab from the table.

5.     In the JConsole tree, open the RTView folder and select the Manager.

6.     In the Attributes table, double-click the LogTable Value (for example, javax.management.openmbean.TabularDataSupport).

The LogTable Value field expands. If there is more than one LogTable, click the Tabular Navigation arrows to view them.

7.     Click the Operations tab and make the following entries:

•        Key - Specifies the logging category to be logged (see “Logging Categories”). For example, jmx.

•        TraceLevel - Specifies the amount of logging to perform for the logging category. Valid values are 0, 1, 2, and 3 where 0 equals no logging and 3 is the maximum possible logging.

•        TraceUpdates - Specifies whether to provide log messages containing details about logging category. Valid values are true and false.

8.     Click Refresh when finished.

Logging Categories

9.     Modify TraceLevel or TraceUpdates for a category by selecting the MBeans Operations tab.

Tomcat Log Files

If your Display Server or Data Server is not operating properly, search for errors and exceptions in the Tomcat application (or other application server) log file.

If an application server other than Tomcat is used, consult that application server documentation to determine where the log files are located. Typically, Tomcat log files are located in CATALINA_HOME/logs, where CATALINA_HOME is the Tomcat installation directory.

Display Server

The log file with relevant information for the RTView Display Servlet is output by the servlet when it starts. For example:

rtvdisplay servlet: <version_string>

rtvdisplay: DisplayServerHost=localhost:3279, timeout=15000

Data Server

The output from the RTView Data Servlet (used to provide HTTP access to the Data Server) is output when the first client connects. For example:

RTVDataServlet: <version_string>

RTVDataServlet: ServiceHost=localhost:3278, timeout=15000

Tomcat and Linux

Tomcat logging is configurable, as described in Tomcat documentation. On Linux, by default the log file of interest is catalina.out. Every run of Tomcat appends its output to the same catalina.out file. Because the file can get very large, consider rotating this log file periodically, or when   Tomcat   is restarted.

Tomcat and Windows

On Windows, if the default Tomcat   startup script is used, the Tomcat   output simply goes to the console window from which the script is run. It might be necessary to redirect this output to a file, use a custom startup script, or customize the Tomcat logging.

If Tomcat is run as a Windows service, look for files named stdout*.log and stderr*.log in the Tomcat logs directory.