> Developing Applications with WebLogic SIP Server > Enabling Message Logging

Developing Applications with WebLogic SIP Server

     Previous  Next    Open TOC in new window    View as PDF - New Window  Get Adobe Reader - New Window
Content starts here

Enabling Message Logging

The following sections describe how to use WebLogic SIP Server message logging features on a development system:

 

Overview

Message logging records SIP and Diameter messages (both requests and responses) received by WebLogic SIP 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, WebLogic SIP 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.

 

Enabling Message Logging

You enable and configure message logging by adding a message-debug element to the sipserver.xml configuration file. WebLogic SIP 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 SIP Server 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:

Listing 14-1 shows a configuration entry that specifies the full logging level.

Listing 14-1 Sample Message Logging Level Configuration in sipserver.xml 
<message-debug>
   <level>full</level>
</message-debug>

Customizing Log Records

WebLogic SIP 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: If you specify a format element with a <level>full</level> element (or with the level element undefined) in message-debug, WebLogic SIP 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 14-1 describes the nested elements used in the format element.

Table 14-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 14-2 provides a list of available string tokens. You can define multiple token elements as needed to customize your log records.

Table 14-2 describes the string token values used to specify information in a message log record:

Table 14-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
%exception
The class name of the exception occurred when calling the AP. Detailed information is recorded to the run-time log.
NullPointerException
%from
The From header (all). It is blank when forwarding.
sip:foo@bea.com;tag=438943
%from_addr
The address portion of the From header.
foo@bea.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@bea.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@bea.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@bea.com;tag=438943
%to_addr
The address portion of the To header.
foo@bea.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@bea.com

See Example Message Log Configuration and Output for an example sipserver.xml file that defines a custom log record using two tokens.

 

Specifying Content Types for Unencrypted Logging

By default WebLogic SIP 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, WebLogic SIP 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, WebLogic SIP 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, WebLogic SIP 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 14-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.

Listing 14-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 Message Log Configuration and Output

Listing 14-3 shows a sample message log configuration in sipserver.xml. Listing 14-4, Sample Message Log Output, on page 14-6 shows sample output from the Managed Server log file.

Listing 14-3 Sample Message Log Configuration in sipserver.xml 
<message-debug>
   <format>
      <pattern>{0} {1}</pattern>
      <token>%headers</token>
      <token>%content</token>
   </format>
</message-debug>
Listing 14-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: BEA WebLogic SIP Server 3.1.0.0
 >

 

Configuring Log File Rotation

Message log entries for SIP and Diameter messages are stored in the main WebLogic SIP 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 WebLogic SIP 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 14-3 describes each element. Note that a server restart is necessary in order to initiate independent logging and log rotation.

Table 14-3 XML Elements for Configuring Log Rotation
Element
Description
logging-enabled
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 WebLogic SIP Server log file.
file-min-size
Configures the minimum size, in kilobytes, after which the server automatically rotate log messages into another file. This value is used when the rotation-type element is set to bySize.
log-filename
Defines the name of the log file for storing messages. By default, the log files are stored under domain_home/servers/server_name/logs.
rotation-type
Configures the criterion for moving older log messages to a different file. This element may have one of the following values:
  • bySize—This default setting rotates log messages based on the specified file-min-size.
  • byTime—This setting rotates log messages based on the specified rotation-time.
  • none—Disables log rotation.
number-of-files-limited
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.
file-count
Configures the maximum number of log files to keep when number-of-files-limited is set to true.
rotate-log-on-startup
Determines whether the server should rotate the log file at server startup time.
log-file-rotation-dir
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.
rotation-time
Configures a start time for log rotation when using the byTime log rotation criterion.
file-time-span
Specifies the interval, in hours, after which the log file is rotated. This value is used when the rotation-type element is set to byTime.
date-format-pattern
Specifies the pattern to use for rending dates in log file entries. The value of this element must conform to the java.text.SimpleDateFormat class.

Listing 14-5 shows a sample message-debug configuration using log rotation.

Listing 14-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>

  Back to Top       Previous  Next