Viewer for Log XML files

This document describes how to install and use version 2.1.3 of the Log XML Viewer.

Table of Contents

Overview

Tivoli applications support a common XML format in which they log messages and traces. This common format is called LOG XML. This viewer processes logs in that format.

The viewer can filter messages and traces by time window, severity, thread id, component, etc, correlate messages and traces produced by different products, and convert the logged messages into ASCII or HTML for presentation. Visual cues are associated with error and warning messages.

The viewer is a java program, which requires JVM 1.2.2 or better, and comes with an InstallShield Wizard to aid in installation.

Packaging

This product includes software developed by the Apache Software Foundation (http://www.apache.org/).

Install Instructions

The viewer and InstallShield Wizard are provided in setup.jar. It requires a JVM version 1.2.2 or better.

To invoke the interactive install use the command:

java -cp setup.jar run

To invoke the console install, Use the command:

java -cp setup.jar run -console

To invoke the silent install, Use the command:

java -cp setup.jar run -silent -P bean5.installLocation=<location>

where <location> is replaced with a directory.

Add the location of the viewer installation and java executable to your PATH variable. For UNIX systems, give the viewer.sh execute permissions with the command in the directory where the viewer is installed:

chmod +x viewer.sh

Uninstall Instructions

To remove the viewer, invoke the uninstall program. The uninstall program is provided in uninstall.jar, which is located in the _uninst directory, an subdirectory of the install location. It requires a JVM version 1.2.2 or better. To invoke the interactive uninstall use the command:

java -cp uninstall.jar run

Usage

The viewer may be invoked by using the provided wrapper script (recommended) or by calling java directly.

Wrapper Script

The command assumes the viewer.bat (DOS), or viewer (shell) is in your PATH environment variable. The script will determine its location, and use that to set the CLASSPATH and VIEWER_HOME. If you are using a UNIX system, replace "viewer" below with "viewer.sh".

viewer [(-q Query_String) | (-f filename)]
        [-s (text | html)]
        [-h]
        <input.xml> [<input.xml>*]
where
-q is a parameter to specify a query string.
   See below for description of the query string syntax.
   Only one of -q or -f can be specified.
-f is a parameter to specify a file which contains a query string.
-s allows either text or html output (default html).  The html output
will be in UTF-8 encoding.  The text format will be in the default
encoding of the console where the command is issued.
-h prints the usage statement.
All other arguments are interpreted as log xml input files. 
When multiple input files are given, the log and trace records
will be merged based on the timestamp.

Direct JVM Usage

The command assumes the CLASSPATH environment variable includes jlog.jar, viewer.jar, regex4j.jar, and xerces.jar, and that java is in your PATH environment variable.

java -DVIEWER_HOME=
	[-DTRACE=DEBUG_MIN] 
	[-DSHOWTITLE=TRUE]
        -cp "viewer.jar:jlog.jar:xercesImpl.jar:xmlparserAPIs.jar:regex4j.jar"
        com.tivoli.log.viewer.Cli
        [(-q Query_String) | (-f filename)]
        [-s (text | html)]
        [-h]
        <input.xml> [<input.xml>*] 
where
-DVIEWER_HOME is a system property that defines the location of the
   stylesheet (.css) files. These stylesheets will be embedded in 
   the HTML file.
-DTRACE is a system property that defines the level of tracing.
   The default is DEBUG_MIN, but DEBUG_MID and DEBUG_MAX
   are also valid settings.
-DSHOWTITLE is a system property that directs the HTML formatter
   to either include or omit the title.  The default is to include 
   the title.  The title consists of a comma separated list
   of input filenames.
-cp "viewer.jar:jlog.jar:xercesImpl.jar:xmlparserAPIs.jar:regex4j.jar"
   indicates to the JVM which jar files must be availble for the viewer
   to function.  This example shows the use of a UNIX separator ':'.  In
   DOS, this would be ';'.  If these jar files are not in the current 
   directory, it is the responsibility of the user to give the full path 
   to each jar file, rather than just the name of the files as shown.
-q is a parameter to specify a query string.
   See below for description of the query string syntax.
   Only one of -q or -f can be specified.
-f is a parameter to specify a file which contains a query string.
-s allows either text or html output (default html).  The html output
will be in UTF-8 encoding.  The text format will be in the default
encoding of the console where the command is issued.
-h prints the usage statement.
All other arguments are interpreted as log xml input files. 
When multiple input files are given, the log and trace records
will be merged based on the timestamp.

Terminology

Query String

The query string will have the following format:

select column [,column] where Filter_Predicate

Following the reserved word "select" is one or more column headers. These are the elements of the log or trace records that will be apparent in the output. A timestamp is always displayed in the output for each record. After the reserved word "where" is a filter predicate. The filter predicate determines which records will be present in the output. The default query string is "select default where true".

These are the column names(not case sensitive):

Filter Predicate

A filter predicate can be an expression, or the reserved word true.

Conditional operators used in Filter Predicate clause:

  =       Equal
  >       Greater than
  <       Less than
  >=      Greater than or equal to
  <=      Less than or equal to
  <>      Not equal to
  MATCH   *See note below

* The MATCH pattern matching operator can also be used in the conditional selection of the where clause. Match is a very powerful operator that allows you to select log or trace records using regular expression syntax. This is implemented using the regex4j regular expression engine from alphaWorks Strings with special characters used in the regular expression must be in single quotes. Strings with spaces must be in single quotes.

Boolean Operators

  OR
  AND

Boolean operators can be used to conjoin two expressions. They must be of the form (expression) AND (expression). The parenthesis are required around each expression.

The Keyword true

The keyword true is a complete filter expression, which indicates that filtering is disabled, and that every log and trace record should be present in the output.

Examples

The following query will show the default field list of all message and trace records in html, to sample.html.

The following query selects for display all fields with a correlation id of 12. The output is sent to stdout.

The following example displays all fields with a timestamp less than 1007067881373. Timestamp is the only column name that takes a numeric argument instead of a string. Output is in text format, written to stdout.

The following example will display only the server and product id, where the boolean expression is met. Since boolean operators are present, parenthesis have been used to indicate order of operator evaluation. Input is merged from the three files "sample1.xml" "sample2.xml" and "sample3.xml".

This example illustrates filtering on a Log Attribute. The output will contain log records which have a Log Attribute with the name FNG and value 123.

Error Handling

The query string will be verified for correctness, and processing will halt if the query string is malformed. Validation of the column labels will be done. Validation of each command line argument is done, and if an invalid argument value is specified, processing will halt. If one of the input Log XML files is malformed, there wil be no further attempt to read input from that file, however any other input files will be processed. Input files will not be checked against the PDLog.dtd, so if a file has an entry that is not specified in PDLog.dtd, the entry will be ignored. The opening and closing <PDLog> tags are not required in the input file, as the viewer inserts these into the input files.

Troubleshooting

Boolean operators require parenthesis

The following example demonstrates the strictness of the boolean expressions.

This results in the following error:

The solution is to ensure that each boolean expression has the form: (expression) AND (expression). So in this case, we could change the example to:

Using quotes in the Query String

The following example attempts to make a query using the match operator. The query string is not delimited by double quotes.

This results in the following error:

When a query is incomplete, the viewer issues an error to indicate which component of the query sting was found to be missing. In this example It was expecting to find a column label, when the string ended. Without double quotes around the query string, this shell will provide each word of the query in a different argument, resulting in the string appearing as "select". We can correct the situation by adding double quotes around the query string like so:

Upon running the new query, we get the following error:

The query syntax allows values to be enclosed in single quotes. This signals to the viewer that what is inside the single quote, is a value which does not need to be parsed. We must use the single quote in this case, or the viewer will report an error.

Another case where single quotes around the term is needed, is if the term contains spaces.

Filenames with spaces

Occasionally, directory names and file names have spaces. Since the viewer accepts space separated file names, this creates ambiguity.

For example:

viewer a b/c

For example:

viewer "a b/c"

viewer a b/c

Enabling Viewer Tracing

Tracing is enabled for the viewer using the java System property "trace". This needs to be passed on the java command line before the classname is given. To enable tracing for the viewer, you will either edit the viewer script (viewer.bat or viewer.sh), or run the command without the use of the script. For example (assuming the CLASSPATH has each of xerces.jar regex4j.jar viewer.jar jlog.jar):

A file will be created in the current directory with the name: logViewerTrace.log. If you would like to view this file with the viewer, rename the file first, or the viewer will go into a loop!