The following sections describe how to use Oracle Communications Converged Application Server message logging features on a development system:
Message logging records SIP and Diameter messages (both requests and responses) received by Oracle Communications Converged Application Server. 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.
WARNING: | 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 the Operations Guide. |
When you enable message logging, Oracle Communications 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. Oracle Communications Converged Application Server provides two different methods of configuring the information that is logged:
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 Configuration->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.
Listing 11-1 shows a configuration entry that specifies the full
logging level.
<message-debug>
<level>full</level>
</message-debug>
Oracle Communications 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: | If you specify a format element with a <level>full</level> element (or with the level element undefined) in message-debug , Oracle Communications Converged Application Server uses “full” message debugging and ignores the format entry. The format entry can be used in combination with either the “terse” or “basic” message-debug levels. |
Table 11-1 describes the nested elements used in the format
element.
A string token that identifies a portion of the SIP message to include in a log record.
Table 11-2 provides a list of available string tokens. You can define multiple token elements as needed to customize your log records.
|
Table 11-2 describes the string token
values used to specify information in a message log record:
See Example Message Log Configuration and Output for an example sipserver.xml
file that defines a custom log record using two tokens.
By default Oracle Communications 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, Oracle Communications 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, Oracle Communications 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, Oracle Communications 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. |
Listing 11-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.
<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>
Listing 11-3 shows a sample message log configuration in sipserver.xml
.
Listing 11-4, Sample Message Log Output, on page 11-7 shows sample output from the Managed Server log file.
<message-debug>
<format>
<pattern>{0} {1}</pattern>
<token>%headers</token>
<token>%content</token>
</format>
</message-debug>
####<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 Oracle Communications 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 Oracle Communications 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 11-3 describes each element. Note that a server restart is necessary in order to initiate independent logging and log rotation.
Listing 11-5 shows a sample message-debug
configuration using log rotation.
<?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>