Session Initiation Protocol (SIP) binary log and trace extensions on Liberty
Binary logging 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 that are present in every log and trace record. In contrast, extension fields are fields which application developers can add to log and trace records, which you can use as filter criteria when you search for specific log and trace content. These log and trace extensions are visible in the binary log when you configure the text output format to use the advanced format, or they are visible when you use the binaryLog command in the advanced format.
- Administrators
-
The application server automatically creates a number of extensions that you can use to filter log and trace records. You can also filter log and trace records by using any extensions that are added by your application developers. You can use the binaryLog command-line tool to filter records based on the content of log and trace record extensions. For more information, see BinaryLog command options.
For example, to see all SIP application sessions that the SIP container processed, you can use the following binaryLog command:binaryLog view binaryFile --includeExtension=SIPASId=* --format=advanced
- Developers
-
Developers can use binary logging to add custom extensions to log and trace records through the log record context API, com.ibm.websphere.logging.hpel.LogRecordContext. When binary logging stores log and trace records, it includes any extensions that are present in the log record context on the same thread. For example, you can write a servlet filter to add important HTTP request parameters to the log record context. While that servlet runs, the HPEL API adds those extensions to any log and trace records that are created on the same thread.
As with other log and trace record fields, developers can access the record extensions by 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 that you can use to filter various aspects of the trace.
| Extension | Description |
|---|---|
| appName |
Specifies the name of the Java™ Platform, Enterprise Edition (Java EE) application that the log or trace record relates to, if any. |
| requestID |
Specifies the 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, you must 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 |
Specifies the SIP call identifier that is being processed by the SIP proxy server or SIP container. This information is common across SIP proxy servers and SIP containers. You can 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 |
Specifies the SIP application session ID that is being processed by the SIP container. This information is common across SIP containers. You can 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 |
Specifies the SIP session ID that is being processed by the SIP container. This information is common across SIP containers. You can 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 |
Specifies the second SIP call ID that is associated with the same SIP application session and is being processed by the SIP container. This information is common across SIP containers. You can 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 |
Specifies the second SIP session ID that is associated with the same SIP application session and is being processed by the SIP container. This information is common across SIP containers. You can 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 |
Specifies the thread name of the request that each log or trace record relates to. |