Apache log4j is a widely used, open source, Java logging utility used to instrument Java applications. It can be configured to output selected information in a variety of forms and this output can be used to monitor application health, progress or problems. In addition to producing textual logs, Apache log4j can generate real time logging events.
With RTView, you can connect to a configured application instrumented with Apache log4j and receive generated logging events in real time. You can then use RTView to build sophisticated monitoring and management applications that allow you to:
§ Present real-time business content included in Apache log4j logging events,
§ Archive business metrics in the RTView Historian for trend analysis, and
§ Provide a look at application health and troubleshooting by analyzing message content.
This section includes:
§ “System Requirements - Apache log4j” on page 588
§ “Setup - Apache log4j” on page 588
§ “Attach to Log4j Data” on page 588
§ “Application Options - Apache Log4j” on page 592
§ “Deployment - Apache Log4j” on page 594
System Requirements - Apache log4j
In addition to basic “System Requirements”, this data source requires Apache log4j. See the README_sysreq.txt file in your installation’s home directory for the current version(s) supported.
In addition to general environment variables (see “Setup”), this data source includes the log4j.jar file on the RTV_HOME classpath.
For an instrumented application to be monitored by the Apache log4j data source, the application must be configured (using the standard log4j configuration mechanism - typically a properties or XML file) to use the built in SocketHubAppender on a known port. RTView will then use a named connection to connect to the specified port for the SocketHubAppender.
Note: Due to the fact that communication to the log4 SocketHubAppender is via sockets on a known port, firewalls may have to be configured to allow access to that port.
Note: The Apache log4j data source may not be licensed in your RTView installation.
From the Object Properties window you can access the Attach to LOG4J Data dialog, which allows you to choose a connection that connects to a stream of log4j logging events, generated by a configured log4j instrumented Java application. The received logging events can be filtered (client side row and column filtering) using standard client side fields.
Once an object property has been attached to a log4j logging event, it receives continuous updates. It updates whenever a new logging event is received.
Right-click on the Property Name from the Object Properties window and select Attach to Data>LOG4J to display the Attach to LOG4J Data dialog. The Attach to LOG4J Data dialog provides several drop down menus that allow you to specify information. If the drop down menu does not contain the item you require, type your selection into the text field.
|
Field Name |
Description |
|
Connection |
The connection name. You may define a connection on the “LOG4J Connections Tab” of the Application Options dialog. Enter * to aggregate log4j logging events from all defined connections. |
|
Column(s) |
Select which columns to display. To bring up the Select Column(s) dialog, click on the ellipses button |
|
Filter Rows |
Check box to indicate whether or not to filter rows in the log4j logging event. See “Row Filtering” for more information. |
|
Filter Column |
Name of the log4j logging event column to use as a filter. Multiple column names should be entered as a semicolon (;) delimited list (i.e. col1;col2;col 3). If your column name contains a space or a semicolon, then the entire name must be enclosed in single quotes. |
|
Filter Value |
Value that the Filter Column must equal. Multiple filter values should be entered as a nested list, where values for a given column are separated by commas within a semicolon (;) delimited list (i.e. val1,val2;val3,val4;val5,val6). If your filter value contains a space or a semicolon, then the entire value must be enclosed in single quotes. When * is entered as a filter field value, data for all values in the specified filter column will be used to update the object property. When "*" is entered, only the literal comparative value will be used. These are only allowed for objects which display tabular data. |
|
Data Server |
Select to read data through your configured Data Server and not directly from the Apache log4j data source. Default - Select the default Data Server you configured in Application Options>“Data Server Tab”. None - Bypass data being redirected through the specified data server(s) for this attachment and instead attach directly to the data source. Named Data Servers - Select a Named Data Server that you configured in Application Options>“Data Server Tab”. Multi-Server Attachment - To configure multiple data servers, enter a semicolon (;) delimited list containing two or more Named Data Servers (e.g. ds101;ds102). Each name specified must correspond with a Named Data Server that you configured in Application Options>Data Server. It is also possible to specify __default and __none (e.g. __default;ds101;ds102). Note: The values __default and __none begin with two underscore characters. |
|
|
Alternatively, a value of * can be entered to specify all data servers, including __default and __none. When multiple data servers are specified, the data attachment will be directed to each data server in the list. For tabular data attachments, a column named DataServerName will be added as the first column of the table and contain the name of the server from which the data was received. A multi-server attachment will receive data independently from each of the servers it specifies, so in most cases it will be necessary to combine the tables received into a single table. This can be accomplished in two ways: 1. The multi-server attachment can be applied to a local cache that has the DataServerName column specified as an index column. The current table of that cache will contain the combination of the tables received from all servers. Note: It may also be necessary to configure cache row expiration settings to remove defunct rows. 2. The multi-server attachment can be applied as the Table argument of the RTView function named Combine Multi-Server Tables. See “Tabular Functions” for more information. |
When an object property has been attached to data, the Property Name and Value in the Object Properties window will be displayed in green. This indicates that editing values from the Object Properties window is no longer possible. To remove the data attachment and resume editing capabilities in the Object Properties window, right-click on the Property Name and select Detach from Data. You will recognize that an object property has been detached from the data source when the Property Name and Value are no longer green.
Fields in the dialog change colors according to the information entered. These colors indicate whether or not information is valid. Information entered into the dialog is validated against the selected server.
Note: Filters are not validated.
|
Blue |
Unknown |
Cannot validate entry. |
|
White |
Valid state |
Entry is valid. |
|
Red |
Invalid state |
Incomplete or invalid entry. |
The Substitutions feature allows you to build open-ended displays in which data attachments depend on values defined at the time the display is run. A generic connection such as $conn is used instead of a specific connection. Later when the display is running, this generic value is defined by the actual name of a specific connection, such as samplelog4japp. In this way, a single display can be reused to show data from a number of different sources. Substitutions can be used in any field in this dialog. For more information on creating displays using substitution values, see “Substitutions”.
From the Attach to Data dialog you can specify which columns to search in log4j logging event, as well as which columns to display in your resulting data and in what order they will appear. To view the list of Available Column(s), click on the ellipses button 
to open the Select Column(s) dialog.
To add a column, select an item from the Available Column(s) list and click on the Add button. If the item you require is not listed, type your selection into the Enter Column field. Click the Remove button to delete an item previously added to the Selected Column(s) list. You can control the order of fields in a table by arranging the items in the Selected Column(s) list with the Move Up and Move Down buttons.
Validation colors indicate whether selected columns are valid. However if even one column selected is invalid, the Column(s) field in the Attach to LOG4J Data dialog will register as an invalid entry.
If no data is available for a table row within a selected column, the table cell will display one of the following values: N/A, false, 0, or 0.0.
The following describes Attach to LOG4J Data dialog commands:
|
Command |
Description |
|
OK |
Applies values and closes the dialog. |
|
Apply |
Applies values without closing the dialog. |
|
Reset |
Resets all fields to last values applied. |
|
Clear |
Clears all fields. Detaches object from data source (once Apply or OK is selected). |
|
Cancel |
Closes the dialog with last values applied. |
Application Options - Apache Log4j
To access the Application Options dialog, in the Display Builder select Tools>Options. There are two Log4j options tabs: LOG4J Connections and LOG4J Options.
Options specified in the LOG4J options tabs can be saved in an initialization file (LOG4JOPTIONS.ini). On startup, the initialization file is read by the Display Builder, Display Viewer, Display Server, Data Server and Historian to set initial values. If no directory has been specified for your initialization files and LOG4JOPTIONS.ini is not found in the directory where you started the application, then RTView will search under lib in your installation directory. See “RTV_JAVAOPTS” for more information.
This tab allows you to add or remove connections and set your default connection.
When you add an Apache log4j connection to the list it will be highlighted in yellow indicating that RTView has not connected to it. To attempt to connect, click OK, Apply, or Save. If the background remains yellow, then RTView was unable make a connection. Check that your log4j connection was setup correctly.
Note: Regardless of which tab you are currently working from in the Application Options dialog, RTView will attempt to connect to all unconnected connections each time you click OK, Apply, or Save.
|
Field Name |
Description |
|
Default Connection |
Name of connection used as the default for data attachments. Select from drop down menu to change default setting. |
|
Add Connection |
Click to open the Add LOG4J Connection dialog. To edit, select a connection from the list and double-click. Connections that are updating objects in a current display cannot be renamed. 
|
|
|
Connection Name - Name to use when referencing this Apache log4j connection in your data attachments. Source - Event source of the connection. Choose SocketAppender or SocketHubAppender. SocketAppender - Connect to port on local host. SocketHubAppender - Connect to port on remote host. Host - Host name or IP address. Note: If the Source selected is SocketAppender, this field auto-populates with IP address of local host (127.0.0.1). Port - Port number of the connection. |
|
Remove Connection |
Select a connection from the list and click Remove Connection to delete. Connections that are updating objects in a current display cannot be removed. |
This tab allows you to define a separator between multi-element Throwable information.
|
Field Name |
Description |
|
Throwable Separator |
Choose a separator between elements: Space or NewLine. Space - Use a Space as a separator between elements. The resulting field will be a single line value. NewLine - Use a NewLine as a separator between elements. The resulting field will be a multi-line value. |
This page contains details about the deployment process that are specific to your data source. Please go to the Deployment section of this documentation for instructions on how to implement your RTView deployment option. Return to this page whenever you are instructed to refer to deployment information that is specific to your data source.
The Apache log4j data source has additional System Requirements and Setup. See “System Requirements - Apache log4j” and “Setup - Apache log4j” for more information.
Data Source Configuration File
RTView saves general application settings as well as data source configuration options in initialization files that are read at startup. If no directory has been specified for your initialization files and files are not found in the directory where you started the application, then RTView will search under lib in your installation directory. See “Application Options”, “Application Options - Apache Log4j”, and “RTV_JAVAOPTS” for more information.
Include the following initialization file when you deploy RTView with this data source:
|
File Name |
Description |
|
LOG4JOPTIONS.ini |
Contains data source options for log4j. |
Note: Options specified using command line and applet parameters override values set in these initialization files.
Rich Client Browser Deployment Setup for Direct Data Connection
This deployment is supported by your data source.
Note: A direct data connection requires opening a socket on a machine other than the webserver from which the applet was downloaded, therefore the applet must be signed.
in the