Developing SIP Servlets with WebLogic SIP Server

Enabling Access Logging

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

Overview

Access logging records all SIP messages (both requests and responses) received by WebLogic SIP Server. You can use the access 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 access log, you can also check SIP invocations from HTTP servlets and so forth.

Warning: The access 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 Configuring and Managing WebLogic SIP Server.

When you enable access logging, WebLogic SIP Server records access log records in the Managed Server log file associated with each engine tier server instance.

Enabling Access Logging

You enable and configure access 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:

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 access logging functionality. See also the Engine Tier Configuration Reference (sipserver.xml) in Configuring and Managing WebLogic SIP Server for a full reference to the sipserver.xml file contents.

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.

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

Listing 6-1 Sample Accessing 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 access log record. To configure a custom log record, you must omit the level element described in Specifying a Predefined Logging Level and instead provide a format element that defines a log record pattern and one or more tokens to log in each record.

Note: If you specify both a level element and a format element in message-debug, WebLogic SIP Server uses the specified level and ignores the format entry.

Table 6-1 describes the nested elements used in the format element.

Table 6-1 Nested format Elements

param-name	param-value Description
`pattern`	Specifies the pattern used to format an access 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 6-2 provides a list of available string tokens. You can define multiple `token` elements as needed to customize your log records.

Table 6-2 describes the string token values used to specify information in an access log record:

Table 6-2 Available Tokens for Access 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 Access Log Configuration and Output for an example sipserver.xml file that defines a custom log record using two tokens.

Example Access Log Configuration and Output

Listing 6-2 shows a sample access log configuration in sipserver.xml. Listing 6-3 shows sample output from the Managed Server log file.

Listing 6-2 Sample Access Log Configuration in sipserver.xml

<message-debug>

   <format>

      <pattern>{0} {1}</pattern>

      <token>%headers</token>

      <token>%content</token>

   </format>

</message-debug>

Listing 6-3 Sample Access 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: sip:sipp@10.32.5.230:5061

CSeq: 1 INVITE

Call-ID: 59.3170.10.32.5.230@sipp.call.id

From: sipp <sip:sipp@10.32.5.230:5061> <mailto:sip:sipp@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@sipp.call.id

Via: SIP/2.0/UDP 10.32.5.230:5061

From: sipp <sip:sipp@10.32.5.230:5061> <mailto:sip:sipp@10.32.5.230:5061> ;tag=59

Server: BEA WebLogic SIP Server 2.1.0.0