Log and Trace extensions

Log and Trace extensions

The High Performance Extensible Logging (HPEL) capability in the application server provides a way for developers to add extension fields to log and trace records, and a corresponding way for you to filter log and trace records by extension value.

Log and trace records contain fields for information such as the time the record was created and the content of the message that is logged. These fields are core fields present in every log and trace record. In contrast, extension fields are fields which application developers can add to log and trace records, which we can use as filter criteria when you search for specific log and trace content. These log and trace extensions are visible in the HPEL Text Log when we configure the text output format to use the Advanced format, or they are visible when using the logViewer command in the advanced format.

Administrators

The application server automatically creates a number of extensions we can use to filter log and trace records. We can also filter log and trace records using any extensions that are added by the application developers. Use the logViewer command-line tool to filter records based on the content of log and trace record extensions.

For example, to see all records that were created by the thread, WebContainer : 6, we can use the following logViewer command:(iSeries)
logViewer -includeExtensions thread="WebContainer : 6" -format advanced
(UNIX) (Linux)
logViewer.sh -includeExtensions thread="WebContainer : 6" -format advanced
(Windows)
logViewer.bat -includeExtensions thread="WebContainer : 6" -format advanced
(ZOS)
logViewer.sh -instance instance_id -includeExtensions thread="WebContainer : 6" -format advanced

Developers

Developers can use HPEL to add custom extensions to log and trace records through the log record context API, com.ibm.websphere.logging.hpel.LogRecordContext. When HPEL stores log and trace records, it includes any extensions present in the log record context on the same thread. For example, we can write a servlet filter to add important HTTP request parameters to the log record context. While that servlet runs, HPEL adds those extensions to any log and trace records created on the same thread.

As with other log and trace record fields, developers can access the record extensions using the HPEL API. This API is useful when you write tools to read from log and trace repositories. Developers can also use the log record context API to access extensions in custom log handlers, filters, and formatters at run time.

The following table describes the log and trace extensions, including the identifier we can use to filter various aspects of the trace.

Extension Description
appName
Name of the Java EE application that the log or trace record relates to, if any.

requestID
Unique ID of the request that each log or trace record relates to, if any. For the application server to add the requestID extension to log and trace records, enable Cross Component Trace (XCT), also referred to in the administrative console as log and trace correlation. Request IDs are only added for certain types of requests, such as HTTP or JMS requests.

SIPCallId
The SIP call identifier being used processed by the SIP proxy server or SIP container. This information is common across SIP proxy servers and SIP containers. Use this extension to track the SIP call flow across the various components. The SIP proxy server and SIP container automatically adds this identifier to each log and trace record when HPEL logging is enabled.

SIPASId
The SIP application session ID being used processed by the SIP container. This information is common across SIP containers. Use this extension to track the SIP call flow. The SIP container automatically adds this identifier to each log and trace record when HPEL logging is enabled.

SIPSessionId
The SIP session ID being used processed by the SIP container. This information is common across SIP containers. Use this extension to track the SIP call flow. The SIP container automatically adds this identifier to each log and trace record when HPEL logging is enabled.

SIPCallId2
Second SIP call ID associated with the same SIP application session and is being processed by the SIP container. This information is common across SIP containers. Use this extension to track the SIP call flow. The SIP container automatically adds this identifier to each log and trace record when HPEL logging is enabled.

If more than two SIP call IDs are associated with a single SIP application session, only the first two IDs are recorded. The additional IDs are not recorded.

SIPSessionId2
Second SIP session ID associated with the same SIP application session and is being processed by the SIP container. This information is common across SIP containers. Use this extension to track the SIP call flow. The SIP container automatically adds this identifier to each log and trace record when HPEL logging is enabled.

If more than two SIP session IDs are associated with a single SIP application session, only the first two IDs are recorded. The additional IDs are not recorded.

thread
Thread name of the request that each log or trace record relates to.

Related:

High Performance Extensible Logging (HPEL)
Use High Performance Extensible Logging to troubleshoot applications
Troubleshoot SIP call flows
logViewer command-line tool

Extension	Description
appName	Name of the Java EE application that the log or trace record relates to, if any.
requestID	Unique ID of the request that each log or trace record relates to, if any. For the application server to add the requestID extension to log and trace records, enable Cross Component Trace (XCT), also referred to in the administrative console as log and trace correlation. Request IDs are only added for certain types of requests, such as HTTP or JMS requests.
SIPCallId	The SIP call identifier being used processed by the SIP proxy server or SIP container. This information is common across SIP proxy servers and SIP containers. Use this extension to track the SIP call flow across the various components. The SIP proxy server and SIP container automatically adds this identifier to each log and trace record when HPEL logging is enabled.
SIPASId	The SIP application session ID being used processed by the SIP container. This information is common across SIP containers. Use this extension to track the SIP call flow. The SIP container automatically adds this identifier to each log and trace record when HPEL logging is enabled.
SIPSessionId	The SIP session ID being used processed by the SIP container. This information is common across SIP containers. Use this extension to track the SIP call flow. The SIP container automatically adds this identifier to each log and trace record when HPEL logging is enabled.
SIPCallId2	Second SIP call ID associated with the same SIP application session and is being processed by the SIP container. This information is common across SIP containers. Use this extension to track the SIP call flow. The SIP container automatically adds this identifier to each log and trace record when HPEL logging is enabled. If more than two SIP call IDs are associated with a single SIP application session, only the first two IDs are recorded. The additional IDs are not recorded.
SIPSessionId2	Second SIP session ID associated with the same SIP application session and is being processed by the SIP container. This information is common across SIP containers. Use this extension to track the SIP call flow. The SIP container automatically adds this identifier to each log and trace record when HPEL logging is enabled. If more than two SIP session IDs are associated with a single SIP application session, only the first two IDs are recorded. The additional IDs are not recorded.
thread	Thread name of the request that each log or trace record relates to.