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, disabling 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

  1. 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.
    [Version 8.6 and later] hpelEnable
    Specifies if High Performance Extensible Logging (HPEL) is enabled. HPEL logging is enabled when the property is set to true.

    Default: false

    [Version 8.6 and later] hpelRepositoryPath
    Specifies the HPEL logging repository location.

    Default: "." (the runtime location)

    [Version 8.6 and later] hpelEnablePurgeBySize
    Indicates if the HPEL purges log files by size. You can set the size of the files with the hpelMaxRepositorySize property.

    Default: true (enabled)

    [Version 8.6 and later] hpelEnablePurgeByTime
    Indicates if the HPEL purges log files by time. Set the amount of time with the hpelMaxRetentionTime property.

    Default: true (enabled)

    [Version 8.6 and later] hpelEnableFileSwitch
    Indicates if 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)

    [Version 8.6 and later] hpelEnableBuffering
    Indicates if the HPEL buffering is enabled.

    Default: false (disabled)

    [Version 8.6 and later] hpelIncludeTrace
    Indicates if the HPEL text files include tracing.

    Default: false (disabled)

    [Version 8.6 and later] hpelOutOfSpaceAction
    Indicates the action to be performed when the disk space has been exceeded.

    Default: PurgeOld

    Possible values: PurgeOld, StopServer, StopLogging

    [Version 8.6 and later] hpelOutputFormat
    Indicates the format of the log files to be generated.

    Default: Basic

    Possible values: Basic, Advanced, CBE-1.0.1

    [Version 8.6 and later] hpelMaxRepositorySize
    Indicates the maximum size of files, in megabytes. This value is used when you able the hpelEnablePurgeBySize property.

    Default: 50

    [Version 8.6 and later] hpelMaxRetentionTime
    Indicates the maximum retention time to hold files, in hours.

    Default: 48

    [Version 8.6 and later] hpelFileSwitchHour
    Indicates the hour at which to create a new file. This value is used when the hpelEnableFileSwitch property is enabled.

    Default: 0

  2. 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.
  3. 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. [Windows]
      C:\Program Files\IBM\WebSphere\eXtremeScale\ObjectGrid\bin
      [Linux][Unix]
      /opt/IBM/WebSphere/eXtremeScale/ObjectGrid/bin
    2. Run the following command to get help with the log viewer: [Windows]
      logViewer -help
      [Linux][Unix]
      ./logViewer.sh -help
  4. 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:
      [Windows]
      logViewer -outLog ..\logs\legacyFormat.log -minLevel INFO -maxLevel SEVERE

      [Linux][Unix]
      ./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:
      [Windows]
      logViewer -thread 0

      [Linux][Unix]
      ./logViewer.sh -thread 0
    • Run the following command to view only WARNING messages:
      [Windows]
      logViewer -level WARNING

      [Linux][Unix]
      ./logViewer.sh -level WARNING
    • Run the following command to retrieve all log records NOT from loggers that begin with com.ibm:
      [Windows]
      logViewer -excludeLoggers com.ibm.*

      [Linux][Unix]
      ./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:
      [Windows]
      logViewer -minLevel WARNING -maxLevel SEVERE -extractToNewRepository ..\logs\newHPELRepository

      [Linux][Unix]
       ./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:
      [Windows]
      logViewer -repositoryDir ..\logs\newHPELRepository -outLog ..\logs\newFormat.log

      [Linux][Unix]
       ./logViewer.sh -repositoryDir ../logs/newHPELRepository -outLog ../logs/newFormat.log
      Use a text editor to view the resulting log file.