Viewing log file data

IBM Verify Identity Governance provides a viewer for formatting and viewing logs. The logs are formatted in XML, but the viewer displays the files in HTML or plain text. The viewer can filter message and trace records for various fields in the records. For example, you can filter for timestamp, severity, thread identifier, and component ID. You can combine different types of logs and view them together.

To create a single file for presentation, run the viewer command from a command-line window. The filepath of the viewer command depends on the operating system.

Microsoft Windows systems: ISIM_HOME\bin\logviewer\viewer.bat

UNIX and Linux® systems: ISIM_HOME/bin/logviewer/viewer.sh

The viewer command uses the following syntax and parameters:

viewer [{-qstring | -ffilename}] [-soutput_type] [-h] input_data

-qstring: Defines a string that determines the content and format of the output. You can define this string on the command line or in a file. For more information, see Query strings.

-ffilename: Defines a file that contains a string and determines the content and format of the output. You can define this string on the command line or in a file. For more information, see Query strings.

soutput_type: Specifies that the output format of the data is in plain text or HTML. The default value is HTML. The HTML output is in UTF-8 encoding. The text format is in the default encoding of the console where the command is issued. Specify text or HTML. Use the standard redirection symbol (>) to direct the output to a file instead of stdout. See Generating the contents of the access.log in HTML format.

-h: Prints the usage statement, which is the command syntax.

input_data: Specifies one or more input files to be viewed. If you specify multiple input files, the log and trace records are merged based on the timestamp of each record.

Query strings

The query string has the following format. If you do not specify a query string, the default query string is "select default where true". This section describes these values.

"select column_name [,column_name]
where filter_predicate"

column_name

Specify one or more column headers for the trace output. A timestamp is displayed in the output for each record.

all: Includes all columns.

default: Specifies to include the default columns. The default columns are Time, Severity, MessageId, LogText, Server, ProductID, Component, and ProductInstance.

Names of columns: Table 1 lists the valid column names. The column names are not case-sensitive. Some column names might not apply to a particular log. If a description or example is not listed, review the actual log to determine whether the column applies to the troubleshooting task.

Table 1. Column names for query strings
Column name	Column type	Description or example
Client	String	Client identifier
Component	String	Component identifier
CorrelationId	String	Correlation identifier
Element	String	Message or trace
Exception	String	Error identifier
LogAttribs	Key value pairs (keyword=`value`), separated by spaces	The attributes of a log
LogText	String	The description of the log attribute
MessageId	String	Unique identifier of the message
Millis	Long integer	Time in milliseconds
Principal	String	An ID that has the necessary permissions. For example, server1.
Process	String	The process number.
ProductId	String	The three-letter identifier
ProductInstance	String	The installed server instance name
Server	String	Name or IP address
ServerFormat	String	For example, TCP/IP
Severity	String	Severity level of the log record
SourceFile	String	Name of the source file where the event was generated
SourceLine	String	Line number where the event was generated
SourceMethod	String	Name of the method that generated the event
Thread	String	The thread number. For example, 3928.
Time	String	Localized time.
TraceLevel	String	Trace level of the log file. For example, MIN.

filter_predicate

Determines which records are in the output. The filter_predicate value can contain conditional operators, pattern operators, Boolean operators, or the true keyword.

The true keyword indicates that filtering is disabled and all log records are included in the output.

Conditional operators include:

= (equal)
> (greater than)
_< (less than)
>= (greater than or equal to)
<= (less than or equal to)
<> (not equal to)

You can also use the MATCH pattern operator in the conditional selection of the where clause. Use MATCH to select log or trace records with regular expression syntax. Put strings with special characters in the regular expression in quotation marks.

Boolean operators include the following operators in the format of

(expression) operator
(expression)

Displaying only the server and productID columns of the log records includes a Boolean expression with the MATCH pattern operator and the AND and OR Boolean operators.

Log viewer syntax examples

The examples show various uses of the viewer command:

Generating the contents of the access.log in HTML format

It uses the default columns. It redirects the output to the logout.html file in the local directory.

Microsoft Windows systems: viewer -shtml "C:\Program Files\IBM\tivo..\..\common\CTGIM\logs\access.log" > logout.html

UNIX and Linux systems: ./viewer.sh -shtml "/opt/IBM/tivo../../common/CTGIM/logs/access.log" > logout.html

Displaying the filtered contents of the trace.log file in text format

It displays all fields with a correlation identifier of 12. The output goes to stdout.

Microsoft Windows systems: viewer -q"select all where CorrelationId = 12" -stext "C:\Program Files\IBM\tivo..\..\common\CTGIM\logs\trace.log"

UNIX and Linux systems: ./viewer.sh -q"select all where CorrelationId = 12" -stext "/opt/IBM/tivo../../common/CTGIM/logs/trace.log"

Displaying the filtered contents of the trace.log file in text format

It displays all records with a timestamp less than 1007067881373. The output goes to stdout.

Microsoft Windows systems: viewer -q"select all where Millis < 1007067881373" -stext "C:\Program Files\IBM\tivo../../common\CTGIM\logs\trace.log"

UNIX and Linux systems: ./viewer.sh -q"select all where Millis < 1007067881373" -stext "/opt/IBM/tivo../../common/CTGIM/logs/trace.log"

Displaying only the server and productID columns of the log records

Records are displayed only if the Boolean expression evaluates to TRUE. The output is sent to stdout. You must use parentheses with Boolean operators to indicate the order of operator evaluation. Input is merged from the specified files: msg1.log, msg2.log, and msg3.log.

Note: Parentheses determine how the Boolean expression is evaluated. The Boolean expression evaluates to TRUE only if both of these statements are true:

The text in the messageid column contains message IDs in the range CTGIMA010 to CTGIMA045
The Server column contains the string test1, or the severity column contains the string ERROR.

Microsoft Windows systems

viewer -q"select server,ProductId where 
(messageid MATCH 'CTGIMA0[10-45]') 
AND ((server = 'test1') 
OR (severity = 'ERROR'))" 
"C:\Program Files\IBM\tivo..\..\common\CTGIM\logs\msg1.log 
C:\Program Files\IBM\tivo..\..\common\CTGIM\logs\msg2.log 
C:\Program Files\IBM\tivo../../common\CTGIM\logs\msg3.log"

UNIX and Linux systems

./viewer.sh -q"select server,ProductId where 
(messageid MATCH 'CTGIMA0[10-45]') 
AND ((server = 'test1') 
OR (severity = 'ERROR'))" 
"/opt/IBM/tivo../../common/CTGIM/logs/msg1.log 
/opt/IBM/tivo../../common/CTGIM/logs/msg2.log 
/opt/IBM/tivo../../common/CTGIM/logs/msg3.log"

Filtering with a log attribute

You can filter with a log attribute that has the name FNG and a value of 123. The output is sent to stdout.

Microsoft Windows systems: viewer -q"select default where LogAttribs MATCH 'FNG=123'" "C:\Program Files\IBM\tivo..\..\common\CTGIM\logs\trace.log"

UNIX and Linux systems: ./viewer.sh -q"select default where LogAttribs MATCH 'FNG=123'" "/opt/IBM/tivo../../common/CTGIM/logs/trace.log"