logViewer command-line tool

Use the logViewer command to query the contents of the High Performance Extensible Logging (HPEL) log and trace repositories. We can also use the logViewer command to view new log and trace repository entries as the server writes content to them.

The High Performance Extensible Logging (HPEL) facility writes to the log and trace repositories in a binary format. We can view, query and filter the repository using the logViewer command. The logViewer command provides options for converting HPEL logs into a text file in various formats, including basic, advanced, and Common Base Event format. We can filter what log records we want by level, logger name, or date and time.

To view the full contents of our log and trace repositories:

logViewer.sh

Optional parameters

[Liberty] servername

Name of the server whose log and trace data repositories we want the logViewer command to use. This parameter is not needed in cases where there is only one Liberty server created nor in cases where we specify the path to the log and trace data repository root using the -repositoryDir parameter.

-repositoryDir directory_name

Path to the repository directory. In the case where we want to query both the log and trace data together, provide the path to the parent directory, which contains both the log data and tracedata directories. If we use the default repository location, profile_root/logs/application_server/, and run this tool from the profile bin directory, then this argument is optional. The tool checks the default location if one is not provided. If multiple application servers exist in this profile with HPEL repositories, we are prompted to select which server log and trace repository we want to view.

-outLog file_name

File name we want the text output written to. If we do not provide this information, the text output is displayed on the console.

-format basic | advanced | cbe-1.0.1

Output format. Supported formats include basic, advanced, and the CBE-1.0.1 format. If we do not provide this information, the output is in basic format.

-monitor [integer]

Continuously monitor the repository and output new log record entries as they are created. We can provide an optional integer argument after this parameter to specify how often we want the logViewer tool to query the repository for new records. By default the logViewer queries the repository for new records every 5 seconds. When used with other filtering options, only those new records that match the filter criteria are displayed.

-help

List the full set of options that are available.

-startDatedate_time

Filter results displayed from the repository by date and time. Use the startDate parameter to filter out log entries that occurred after the date or date time provided as an argument. Provide either a date or date and time, entered in the MM/dd/yy format or the MM/dd/yy H:m:s:S z format. With z referring to the timezone.

-stopDate date_time

Filter out log entries that occurred before the specified date or date time. Provide the argument in the same format as the -startDate option.

-level level_name

Only display those log events which match the level name you provide as an argument. Valid values for the level name are FINEST, FINER, FINE, DETAIL, CONFIG, INFO, AUDIT, WARNING, SEVERE, FATAL.

-minLevel level_name

Only display records which are at or higher than the specified level. Valid values for the level name are FINEST, FINER, FINE, DETAIL, CONFIG, INFO, AUDIT, WARNING, SEVERE, FATAL.

-maxLevel level_name

Only display records that are at or below the specified level. Valid values for the level name are FINEST, FINER, FINE, DETAIL, CONFIG, INFO, AUDIT, WARNING, SEVERE, FATAL.

-includeLoggers logger_name

Only log events from the specified loggers are included in the logViewer output. Separate multiple entries with a comma. The * symbol can be used as a wild card to include all loggers below a parent logger. When used in combination with the -excludedLoggers option, the more specific match determines if the log event is included or excluded.

-excludeLoggers logger_name

Exclude log events from the specified loggers in the logViewer output. Separate multiple entries with a comma. The * symbol can be used as a wildcard to include all loggers below a parent logger. When used in combination with the -includeLoggers option, the more specific match determines if the log event is included or excluded.

-thread thread_id

Restrict output to only those log events from a specific thread. Any log messages that were not created by the thread ID provided as an argument to this option are not displayed. Specify the thread ID in hex format.

-extractToNewRepository directory_name

Redirect log and trace records from a binary repository to a new binary repository at the location specified. Use this option with other filtering options to get a subset of log and trace records into the new repository. This option uses the directory path where the new repository must be written as an argument. Therefore, the directory must be empty. If the directory does not exist, the directory is created. However, errors that occur during the directory creation might create extraneous directories.

-listInstances

List the IDs of available server process instances available to use with the -instance option. After running logViewer with the -listInstances option, we can then use the -instance option to invoke logViewer with one of the server process instance IDs as an argument. Since this option does not process any log or trace records, all other options are ignored when we specify this option.

-instance instance_id

Retrieve the log and trace data for a given server process instance by providing the server instance ID. Run logViewer, along with the -listInstances option, before we use this option to obtain a valid instance ID. This option is required when viewing logs and trace from an environment containing subprocesses, such as the z/OS operating system.

If this option is combined with -latestInstance, -instance is ignored.

-latestInstance

Retrieve the log and trace data from the most recent server instance. If this option is used with the -instance option, the -instance option is ignored.

-message match_string

Retrieve only log or trace data with a message field that matches the requested text.

-includeExtensionsname[=value][,name[=value]]*

Retrieve the log and trace data with an extension name that matches the requested name, and an extension value that matches the requested value. We can also use this option to retrieve the log and trace data with an extension name that matches the requested name, and an extension value that matches any value, if you omit the =value part of the option.

Any extension name shown in the advanced format can be used. Note that 'source', 'class', and 'method' are not stored in the log/trace repositories as extensions, and so cannot be filtered on with this option.

Separate multiple name=value arguments with a comma. Specify '==' (two equals signs) in place of '=' (one equals sign) in cases where the name or value must contain an equal sign. Specify ',,' (two commas) in place of ',' (one comma) in cases where the name or value must contain a comma.

-encoding character_set

Character set that the logViewer command will use for text output.

Filtering considerations

Be aware of logViewer filtering optimizations. The logViewer tool is able to filter log and trace data most efficiently when used with the following filter options:

• startDate
• stopDate
• thread
• level
• minLevel
• maxLevel

Example usage

• Write all records in the default repository between July 19th, 2009 and August 2nd, 2009 to a file called /tmp/promo.logs.
  logViewer.sh -outLog /tmp/promo.logs -startDate 07/19/2009 -stopDate 08/02/2009

• Display new records whose specified level is WARNING or higher using the advanced format as the server writes them to the log repository.
  logViewer.sh -monitor -minLevel WARNING -format advanced

• Write only those log messages that were written to the error stream of a specific repository to a file called logged_errors.txt.
  logViewer.sh -repositoryDir /apps/server1/logs -includeLoggers SystemErr -outLog logged_errors.txt

• View events from the default repository that occurred before September 14th, 2009 4:28 PM eastern daylight time.
  logViewer.sh -stopDate "09/14/2009 16:28:00:000 EDT"

• Write events from the default repository that contain a thread extension with value WebContainer : 6
  logViewer.sh -includeExtensions thread="WebContainer : 6" -format advanced

• Write events from the default repository that were a part of the request with requestID a856cb2c-79ed-4d62-a3cf-a9908b2db07b.
  logViewer.sh -includeExtensions requestID=a856cb2c-79ed-4d62-a3cf-a9908b2db07b

• Write events from the default repository that were created on a thread servicing the PlantsByWebSphere application.
  logViewer.sh -includeExtensions appName=PlantsByWebSphere

(ZOS) On z/OS operating systems where multiple processes exist, we must provide the instance ID to identify which process we want to view logs and trace from. The instance ID of a controller is represented by a numeric value while the instance ID of a servant is represented by a combination of a numeric value, job name, job ID, and process ID. To obtain a list of valid instance IDs, run logViewer with the -listInstances option.

• Invoke logViewer with the -listInstances option; for example:
  logViewer.sh -listInstances

  The following example is a list of instance IDs from one controller and three servants:

  Instance ID 					      Start Date
   1280334046 					5/10/10 18:53:12:770 GMT
   1280334046/000001BC00000002_BBOS1S_STC003119 	5/10/10 18:53:39:220 GMT
   1280334046/000001B400000002_BBOS1S_STC003120 	5/10/10 18:54:44:339 GMT
   1280334046/000001C000000001_BBOS1S_STC003121 	5/10/10 18:55:43:520 GMT
  

• Invoke logViewer with the -instance option using one of the instance IDs from the previous example. The ID type is a controller; for example:
  logViewer.sh -instance 1280334046

• Invoke logViewer with -instance option for a servant instance; for example:
  logViewer.sh -instance 1280334046/000001BC00000002_BBOS1S_STC003119