Enabling Message Logging

You enable and configure message logging by adding a message-debug element to the sipserver.xml configuration file. Within the message-debug element, message logging is enabled by setting debug-enabled to true. If debug-enabled is missing, the Converged Application Server treats the message-debug element as if debug-enabled were set to false.

An sample message-debug element

<message-debug>
    <debug-enabled>true</debug-enabled>
    <level>full</level>
    <logging-enabled>true</logging-enabled>
    <local-logging-enabled>true</local-logging-enabled>
    <file-min-size>500</file-min-size>    
    <log-filename>sip-messages.log</log-filename>
    <rotation-type>bySize</rotation-type>
    <number-of-files-limited>false</number-of-files-limited>    
    <file-count>7</file-count>
    <rotate-log-on-startup>true</rotate-log-on-startup>
    <rotation-time>00:00</rotation-time>    
    <file-time-span>24</file-time-span>
    <date-format-pattern>d MMM, yyyy h:mm:ss,SSS a z</date-format-pattern>
</message-debug>

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.

Specifying a Predefined Logging Level

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.

Example 15-1 Sample Message Logging Level Configuration in sipserver.xml

<message-debug>
   <level>full</level>
</message-debug>

Customizing Log Records

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 tokens to log in each record.

Note:

When level 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
`pattern`	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 `token` defined later in the `format` definition.
`token`	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 `token` elements as needed to customize your log records.

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 up to 327675 characters
%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.