This chapter describes how to use Oracle Communications Converged Application Server message logging features on a development system.
Message logging records Session Initiation Protocol (SIP) and Diameter messages (both requests and responses) received by Converged Application Server. This requires that the logging level be set to at least the INFO level. You can use the message log in a development environment to check how external SIP requests and SIP responses are received. By outputting the distinguishable information of SIP dialogs such as Call-IDs from the application log, and extracting relevant SIP messages from the message log, you can also check SIP invocations from HTTP servlets and so forth.
Note:
The message logging functionality logs all SIP requests and responses; do not enable this feature in a production system. In a production system, you can instead configure one or more logging Servlets, which enable you to specify additional criteria for determining which messages to log. See ”Logging SIP Requests and Responses” in Converged Application Server Administrator's Guide.When you enable message logging, Converged Application Server records log records in the Managed Server log file associated with each engine tier server instance by default. You can optionally log the messages in a separate, dedicated log file, as described in "Configuring Log File Rotation".
You enable and configure message logging by adding a message-debug
element to the sipserver.xml configuration file. Converged Application Server provides two different methods of configuring the information that is logged:
Specify a predefined logging level (terse, basic, or full), or
Identify the exact portions of the SIP message that you want to include in a log record, in a specified order
The sections that follow describe each method of configuring message logging functionality using elements in the sipserver.xml file. Note that you can also set these elements using the Administration Console. In the left pane of the Administration Console, select Configuration, then select the Message Debug tab of the SipServer console extension node.
The optional level
element in message-debug
specifies a predefined collection of information to log for each SIP request and response. The following levels are supported:
terse
: Logs only the domain
setting, logging Servlet name, logging level
, and whether or not the message is an incoming message.
basic
: Logs the terse
items plus the SIP message status, reason phrase, the type of response or request, the SIP method, the From header, and the To header.
full
: Logs the basic
items plus all SIP message headers plus the timestamp, protocol, request URI, request type, response type, content type, and raw content.
Example 15-1 shows a configuration entry that specifies the full
logging level.
Converged Application Server also enables you to customize the exact content and order of each message log record. To configure a custom log record, you provide a format
element that defines a log record pattern
and one or more token
s to log in each record.
Note:
Whenlevel
is set to full
, format
is overridden.Table 15-1 describes the nested elements used in the format
element.
Table 15-1 Nested format Elements
param-name | param-value Description |
---|---|
|
Specifies the pattern used to format a message log entry. The format is defined by specifying one or more integers, bracketed by ”{” and ”}”. Each integer represents a |
|
A string token that identifies a portion of the SIP message to include in a log record. Table 15-2 provides a list of available string tokens. You can define multiple |
Table 15-2 describes the string token
values used to specify information in a message log record:
Table 15-2 Available Tokens for Message Log Records
Token | Description | Example or Type |
---|---|---|
%call_id |
The Call-ID header. It is blank when forwarding. |
43543543 |
%content |
The raw content. |
Byte array |
%content_length |
The content length. |
String value |
%content_type |
The content type. |
String value |
%cseq |
The CSeq header. It is blank when forwarding. |
INVITE 1 |
%date |
The date when the message was received. (”yyyy/MM/dd” format) |
2004/05/16 |
%from |
The From header (all). It is blank when forwarding. |
sip:foo@oracle.com;tag=438943 |
%from_addr |
The address portion of the From header. |
foo@oracle.com |
%from_port |
The port number portion of the From header. |
7002 |
%from_tag |
The tag parameter of the From header. It is blank when forwarding. |
12345 |
%from_uri |
The SIP URI part of the From header. It is blank when forwarding. |
sip:foo@oracle.com |
%headers |
A List of message headers stored in a 2-element array. The first element is the name of the header, while the second is a list of all values for the header. |
List of headers |
%io |
Whether the message is incoming or not. |
TRUE |
%method |
The name of the SIP method. It records the method name to invoke when forwarding. |
INVITE |
%msg |
Summary Call ID |
String value |
%mtype |
The type of receiving. |
SIPREQ |
%protocol |
The protocol used. |
UDP |
%reason |
The response reason. |
OK |
%req_uri |
The request URI. This token is only available for the SIP request. |
sip:foo@oracle.com |
%status |
The response status. |
200 |
%time |
The time when the message was received. (”HH:mm:ss” format) |
18:05:27 |
%timestampmillis |
Time stamp in milliseconds. |
9295968296 |
%to |
The To header (all). It is blank when forwarding. |
sip:foo@oracle.com;tag=438943 |
%to_addr |
The address portion of the To header. |
foo@oracle.com |
%to_port |
The port number portion of the To header. |
7002 |
%to_tag |
The tag parameter of the To header. It is blank when forwarding. |
12345 |
%to_uri |
The SIP URI part of the To header. It is blank when forwarding. |
sip:foo@oracle.com |
See "Example Message Log Configuration and Output" for an example sipserver.xml file that defines a custom log record using two tokens.
By default Converged Application Server uses String format (UTF-8 encoding) to log the content of SIP messages having a text or application/sdp Content-Type value. For all other Content-Type values, Converged Application Server attempts to log the message content using the character set specified in the charset
parameter of the message, if one is specified. If no charset
parameter is specified, or if the charset
value is invalid or unsupported, Converged Application Server uses Base-64 encoding to encrypt the message content before logging the message.
If you want to avoid encrypting the content of messages under these circumstances, specify a list of String-representable Content-Type values using the string-rep
element in sipserver.xml. The string-rep
element can contain one or more content-type
elements to match. If a logged message matches one of the configured content-type
elements, Converged Application Server logs the content in String format using UTF-8 encoding, regardless of whether or not a charset
parameter is included.
Note:
You do not need to specify text/* or application/sdp content types as these are logged in String format by default.Example 15-2 shows a sample message-debug
configuration that logs String content for three additional Content-Type values, in addition to text/* and application/sdp content.
Example 15-2 Logging String Content for Additional Content Types
<message-debug> <level>full</level> <string-rep> <content-type>application/msml+xml</content-type> <content-type>application/media_control+xml</content-type> <content-type>application/media_control</content-type> </string-rep> </message-debug>
Example 15-3 shows a sample message log configuration in sipserver.xml. Example 15-4, "Sample Message Log Output" shows sample output from the Managed Server log file.
Example 15-3 Sample Message Log Configuration in sipserver.xml
<message-debug> <format> <pattern>{0} {1}</pattern> <token>%headers</token> <token>%content</token> </format> </message-debug>
Example 15-4 Sample Message Log Output
####<Aug 10, 2005 7:12:08 PM PDT> <Info> <WLSS.Trace> <jiri.bea.com> <myserver> <ExecuteThread: '11' for queue: 'sip.transport.Default'> <<WLS Kernel>> <> <BEA- 331802> <SIP Tracer: logger Message: To: sut <sip:invite@10.32.5.230:5060> <mailto:sip:invite@10.32.5.230:5060> Content-Length: 136 Contact: user:user@10.32.5.230:5061 CSeq: 1 INVITE Call-ID: 59.3170.10.32.5.230@user.call.id From: user <sip:user@10.32.5.230:5061> <mailto:sip:user@10.32.5.230:5061> ;tag=59 Via: SIP/2.0/UDP 10.32.5.230:5061 Content-Type: application/sdp Subject: Performance Test Max-Forwards: 70 v=0 o=user1 53655765 2353687637 IN IP4 127.0.0.1 s=- c=IN IP4 127.0.0.1 t=0 0 m=audio 10000 RTP/AVP 0 a=rtpmap:0 PCMU/8000 > ####<Aug 10, 2005 7:12:08 PM PDT> <Info> <WLSS.Trace> <jiri.bea.com> <myserver> <ExecuteThread: '11' for queue: 'sip.transport.Default'> <<WLS Kernel>> <> <BEA- 331802> <SIP Tracer: logger Message: To: sut <sip:invite@10.32.5.230:5060> <mailto:sip:invite@10.32.5.230:5060> Content-Length: 0 CSeq: 1 INVITE Call-ID: 59.3170.10.32.5.230@user.call.id Via: SIP/2.0/UDP 10.32.5.230:5061 From: user <sip:user@10.32.5.230:5061> <mailto:sip:user@10.32.5.230:5061> ;tag=59 Server: Oracle WebLogic Communications Server 10.3.1.0 >
Message log entries for SIP and Diameter messages are stored in the main Converged Application Server log file by default. You can optionally store the messages in a dedicated log file. Using a separate file makes it easier to locate message logs, and also enables you to use Converged Application Server's log rotation features to better manage logged data.
Log rotation is configured using several elements nested within the main message-debug
element in sipserver.xml. As with the other XML elements described in this section, you can also configure values using the Configuration->Message Debug tab of the SIP Server Administration Console extension.
Table 15-3 describes each element. Note that a server restart is necessary in order to initiate independent logging and log rotation.
Table 15-3 XML Elements for Configuring Log Rotation
Element | Description |
---|---|
|
Determines whether a separate log file is used to store message debug log messages. By default, this element is set to false and messages are logged in the general log file. |
|
Configures the minimum size, in kilobytes, after which the server automatically rotate log messages into another file. This value is used when the |
|
Defines the name of the log file for storing messages. By default, the log files are stored under |
|
Configures the criterion for moving older log messages to a different file. This element may have one of the following values:
|
|
Specifies whether or not the server places a limit on the total number of log files stored after a log rotation. By default, this element is set to false. |
|
Configures the maximum number of log files to keep when |
|
Determines whether the server must rotate the log file at server startup time. |
|
Configures a directory in which to store rotated log files. By default, rotated log files are stored in the same directory as the active log file. |
|
Configures a start time for log rotation when using the |
|
Specifies the interval, in hours, after which the log file is rotated. This value is used when the |
|
Specifies the pattern to use for rending dates in log file entries. The value of this element must conform to the |
Example 15-5 shows a sample message-debug
configuration using log rotation.
Example 15-5 Sample Log Rotation Configuration
<?xml version='1.0' encoding='UTF-8'?> <sip-server xmlns="http://www.bea.com/ns/wlcp/wlss/300" xmlns:sec="http://www.bea.com/ns/weblogic/90/security" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:wls="http://www.bea.com/ns/weblogic/90/security/wls"> <message-debug> <logging-enabled>true</logging-enabled> <file-min-size>500</file-min-size> <log-filename>sip-messages.log</log-filename> <rotation-type>byTime</rotation-type> <number-of-files-limited>true</number-of-files-limited> <file-count>5</file-count> <rotate-log-on-startup>false</rotate-log-on-startup> <log-file-rotation-dir>old_logs</log-file-rotation-dir> <rotation-time>00:00</rotation-time> <file-time-span>20</file-time-span> <date-format-pattern>MMM d, yyyy h:mm a z</date-format-pattern> </message-debug> </sip-server>