Troubleshooting with High Performance Extensible Logging (HPEL)

[Version 8.6 and later] HPEL is a log and trace facility that you can use in stand-alone and WebSphere® Application Server environments. You can use HPEL to store and access log, trace, System.err, and System.out information produced by the application server or applications. HPEL is an alternative to the basic log and trace facility, which provides the Java™ virtual machine (JVM) logs, diagnostic trace, and service log files. These files are commonly named SystemOut.log/SystemErr.log, trace.log and activity.log. HPEL provides a log data repository, a trace data repository, and a text log file.

About this task

Instead of the existing logging facility, you can use HPEL, which is disabled by default. In HPEL mode, the log and trace contents are written to a log data or trace data repository in a proprietary binary format. Therefore, enabling HPEL can improve server performance by providing faster log and trace handling capabilities. Enable HPEL with the server properties files for your container servers and catalog servers. After you enable HPEL, all WebSphere eXtreme Scale logging and the resulting log files are placed in the specified HPEL repository location.

Procedure

Set properties to enable HPEL logging.
Edit the Server properties file for each container and catalog server with the properties that you want to use.

hpelEnable

Specifies whether High Performance Extensible Logging (HPEL) is enabled. HPEL logging is enabled when the property is set to true.
Default: false

hpelRepositoryPath

Specifies the HPEL logging repository location.
Default: "." (the runtime location)

hpelEnablePurgeBySize

Indicates whether the HPEL purges log files by size. You can set the size of the files with the hpelMaxRepositorySize property.
Default: true (enabled)

hpelEnablePurgeByTime

Indicates whether the HPEL purges log files by time. Set the amount of time with the hpelMaxRetentionTime property.
Default: true (enabled)

hpelEnableFileSwitch

Indicates whether the HPEL file is enabled to create a new file at a specified hour. Use the hpelFileSwitchHour property to specify the hour at which to create a new file.
Default: false (disabled)

hpelEnableBuffering

Indicates whether the HPEL buffering is enabled.
Default: false (disabled)

hpelIncludeTrace

Indicates whether the HPEL text files include tracing.
Default: false (disabled)

hpelOutOfSpaceAction

Indicates the action to take when the disk space is exceeded.
Default: PurgeOld

Possible values: PurgeOld, StopServer, StopLogging

hpelOutputFormat

Indicates the format of the log files to be generated.
Default: Basic

Possible values: Basic, Advanced, CBE-1.0.1

hpelMaxRepositorySize

Indicates the maximum size of files, in megabytes. This value is used when you able the hpelEnablePurgeBySize property.
Default: 50

hpelMaxRetentionTime

Indicates the maximum retention time to hold files, in hours.
Default: 48

hpelFileSwitchHour

Indicates the hour at which to create a new file. This value is used when the hpelEnableFileSwitch property is enabled.
Default: 0
Restart the servers on which you modified the server properties file to set HPEL properties. After HPEL is enabled and the server restarted, the previous WebSphere eXtreme Scale logging information is no longer available. The previous logging information is replaced by equivalent HPEL information.
For more information, see Starting and stopping stand-alone servers and Starting and stopping servers in a WebSphere Application Server environment.
Use the HPEL command-line log viewer to view your log files.
The command-line log viewer is a powerful, yet simple solution for viewing logging information. For a detailed reference of the command-line viewer options, see WebSphere Application Server Information Center: LogViewer command-line tool.
1. From a command prompt, go to the bin directory.
```
C:\Program Files\IBM\WebSphere\eXtremeScale\ObjectGrid\bin
```
```
/opt/IBM/WebSphere/eXtremeScale/ObjectGrid/bin
```
2. Run the following command to get help with the log viewer:
```
logViewer -help
```
```
./logViewer.sh -help
```
Some common commands that you can use with the log viewer follow:
- Run the following command to create a legacy format log file, legacyFormat.log, that contains only log records INFO, WARNING, and SEVERE:
```
logViewer -outLog ..\logs\legacyFormat.log -minLevel INFO -maxLevel SEVERE
```
```
./logViewer.sh -outLog ../logs/legacyFormat.log -minLevel INFO -maxLevel SEVERE
```
  Use a text editor to view the legacy format log file that you created.
- Run the following command to view only the log records for thread 0:
```
logViewer -thread 0
```
```
./logViewer.sh -thread 0
```
- Run the following command to view only WARNING messages:
```
logViewer -level WARNING
```
```
./logViewer.sh -level WARNING
```
- Run the following command to retrieve all log records NOT from loggers that begin with com.ibm:
```
logViewer -excludeLoggers com.ibm.*
```
```
./logViewer.sh -excludeLoggers com.ibm.*
```
- Run the following command to extract a repository of just WARNING and SEVERE messages and save the resulting file in a new directory:
```
logViewer -minLevel WARNING -maxLevel SEVERE -extractToNewRepository ..\logs\newHPELRepository
```
```
 ./logViewer.sh -minLevel WARNING -maxLevel SEVERE -extractToNewRepository ../logs/newHPELRepository
```
- Run the following command to export the contents of the resulting repository to a text format log file:
```
logViewer -repositoryDir ..\logs\newHPELRepository -outLog ..\logs\newFormat.log
```
```
 ./logViewer.sh -repositoryDir ../logs/newHPELRepository -outLog ../logs/newFormat.log
```
  Use a text editor to view the resulting log file.