High Performance Extensible Logging (HPEL) is a log and trace facility that is provided as a part of WebSphere® Application Server.
HPEL log and trace storage
HPEL provides a log data repository, a trace data repository, and a text log file. See the following figure to understand how applications and the application server store log and trace information.
HPEL log data repository
The log data repository is a storage facility for log records. Log data is typically intended to be reviewed by administrators. This includes any information applications or the server write to System.out, System.err, or java.util.logging at level Detail or higher (including Detail, Config, Info, Audit, Warning, Severe, Fatal, and any custom levels at level Detail or higher).
HPEL trace data repository
The trace data repository is a storage facility for trace records. Trace data is typically intended for use by application programmers or by the WebSphere Application Server support team. This includes any information applications or the server write to java.util.logging at levels below level Detail (including Fine, Finer, Finest, and any custom levels below level Detail).
HPEL text log
The text log file is a plain text file for log and trace records. The text log file is provided for convenience, primarily so that log content can be read without having to run the LogViewer command-line tool to convert the log data repository content to plain text.
The text log file does not contain any content that is not also stored in either the log data repository or trace data repository. You can disable the text log to enhance server performance. The text log can be configured to record trace content for debugging convenience.
The text log file only contains log entries that are generated by the controller process and not those from servant or adjunct processes. As such, application log records are not written to the text log on z/OS. To view log or trace data for all application server processes, use the LogViewer command-line tool or the HPEL log viewing tool in the administrative console.
Log and trace events are each stored in only one place
Log events, System.out, and System.err are stored in the log data repository. Trace events are stored in the trace data repository. If the text log file is disabled, HPEL might only write log and trace content to these repositories. Storing each type of event in one place ensures that performance is not wasted on redundant data storage.
Log events, and optionally trace events, are written to the text log file when it is enabled. Since this data is always also stored in the log data and trace data repositories, the text log file content is redundant. The text log is convenient for users who do not want to run the LogViewer command-line tool to see their logs and trace; but you can disable the text log if this convenience is not needed.
Log and trace repositories are not shared across processes
Synchronizing activities between processes causes a degradation in performance to all processes involved. With HPEL, each server process has its own log data repository, trace data repository, and text log file. Since these files are not shared across processes, the server runtime environment does not need to synchronize with other processes when writing to these destinations.
Data is not formatted unless it is needed
Formatting data for an user to read uses processor time. Rather than format log event and trace event data at run time, HPEL log and trace data is stored more rapidly in a proprietary binary representation. This improves the performance of the log and trace facility. By deferring log and trace formatting until the LogViewer is run, sections of the log or trace that are never viewed are never formatted.
You can enable the text log file, which stores the log data and trace data in an already readable text format.
Log and trace data is buffered before being written to disk
Writing large blocks of data to a disk is more efficient than writing the same amount of data in small blocks. HPEL provides buffer log and trace data before writing it to disk. By default, log and trace data is stored in an 8 KB buffer before being written to disk. If the buffer is filled within 10 seconds, the buffer is written to disk. If the buffer is not filled within that time it is automatically written to disk to ensure that the logs have the most current information.
Reading from the log data and trace data repositories
The log data and trace data repositories are stored in a WebSphere Application Server proprietary format and cannot be read using text file editors such as Notepad or VI. You can copy the log data and trace data repositories in to a plain text format using the LogViewer command.
HPEL LogViewer command
The HPEL LogViewer is an easy-to-use, command-line tool provided for HPEL users to work with the log data and trace data repositories. The LogViewer provides filtering and formatting options that make finding important content in the log data and trace data repositories easy. For example, a user might filter any errors or warnings, then filter all log and trace entries that occurred within 10 seconds of a key error message on the same thread.
HPEL in the administrative console
The administrative console contains panels that enable HPEL administrators to:
To use these capabilities, in the administrative console, click
link.Scripts and Java programs read from the log data and trace data repositories
HPEL-related JMX MBeans
A MBean interface has been provided to make it easy to access HPEL repository content remotely. For example, a developer might write a JMX client program to read log content from across their WebSphere Application Server cell. This interface is part of the HPELControlService MBean. Refer to the MBean interface documentation for details on the HPEL remote log reading interface.
JMX MBean | Description |
---|---|
HPELControlService | Provides operations related to configuring the log or trace detail level of the server, viewing the log component registry, and querying the log and trace repositories |
HPELLogDataService | Provides operations related to configuring the log data repository of the server |
HPELTraceDataService | Provides operations related to configuring the trace data repository of the server |
HPELTextLogService | Provides operations related to configuring the text log file of the server |
RasLoggingService | Only used for JMX Notification of log events |
When using HPEL for log and trace rather than basic logging, the log and trace JMX MBean, TraceService, is not used.
HPEL API
An API has been provided to make it easy for developers to develop tools to consume content from the HPEL log and trace repositories. For example, a developer might write a Java program to search the log and trace content to find any messages with message IDs that match a known list of important message IDs. This API is in the com.ibm.websphere.logging.hpel package. Refer to the API documentation for details on the HPEL log reading API.