If you want to create and deploy logging Servlets in your own applications (instead of using the template Web Application described below), you must package the sipserver-tracing.jar library from the template in your Web Application. The library is not deployed by default with the sipserver implementation application.

The default SIP Logging Servlets are included in a Web Application, WL_HOME/telco/lib/sipserver-tracing.war. To deploy this application:

Create a new directory from which to deploy the logging application. For example:

cd c:\bea\user_projects\domains\mydomain

mkdir sipserver-tracing

Change to the newly-created application directory:

cd sipserver-tracing

Extract the logging application into the new application directory:

jar xvf c:\bea\wlss210\telco\lib\sipserver-tracing.war

The logging Servlets are activated by deploying the sipserver-tracing application. Deploy the new application using either the Administration Console or the weblogic.Deployer utility. For example:

java weblogic.Deployer -adminurl t3://localhost:7001 -user weblogic -password weblogic deploy -nostage -source c:\bea\user_projects\domains\mydomain\sipserver-tracing

Deploying the unmodified application enables the template logging Servlets with default pattern matching configuration. See Defining Logging Servlets in sip.xml and Specifying the Criteria for Logging Messages for information about customizing the template application to perform logging for your system.

Using the Logging Servlet Implementation in Other Applications

Follow these steps to add logging capabilities to an existing application:

Create a temporary directory into which you will extract the template logging application:

mkdir c:\tracing-tmp

Change to the newly-created application directory:

cd c:\tracing-tmp

Extract the template logging application into the new application directory:

jar xvf c:\bea\wlss210\telco\lib\sipserver-tracing.war

Copy the sipserver-tracing.jar library from the temporary directory into the WEB-INF/lib directory of your own application. For example:

cp WEB-INF\lib\sipserver-tracing.jar c:\bea\user_projects\mydomain\myapplication\WEB-INF\lib

See Defining Logging Servlets in sip.xml to define a new logging Servlet in your existing application. Then read Specifying the Criteria for Logging Messages to customizing the logging performed by the Servlet.

Defining Logging Servlets in sip.xml

Logging Servlets for SIP messages are created by defining Servlets having the implementation class com.bea.wcp.sip.engine.tracing.listener.TraceMessageListenerImpl. The sipserver-tracing template application defines two logging servlets in its sip.xml deployment descriptor, msgTraceLogger and invTraceLogger. The definition for msgTraceLogger is shown in Listing 12-1.

Listing 12-1 Template Logging Servlets

<servlet>

    <servlet-name>msgTraceLogger</servlet-name>

    <servlet-class>com.bea.wcp.sip.engine.tracing.listener.TraceMessageListenerImpl</servlet-class>

    <init-param>

      <param-name>domain</param-name>

      <param-value>true</param-value>

    </init-param>

    <init-param>

      <param-name>level</param-name>

      <param-value>full</param-value>

    </init-param>

    <load-on-startup/>

  </servlet>

You can either maintain all of your logging Servlets within the template application, or you can add logging Servlets to your own SIP applications by defining Servlets that use the com.bea.wcp.sip.engine.tracing.listener.TraceMessageListenerImpl implementation class. See Using the Template Logging Servlet.

Configuring the Logging Level and Destination

Logging attributes such as the level of logging detail and the destination log file for SIP messages are passed as initialization parameters to the logging Servlet. Table 12-1 lists the parameters and parameter values that you can specify as init-param entries. Listing 12-1 shows the sample init-param entries for a Servlet that logs full SIP message information to the domain log file.

Table 12-1 Logging Level and Destination Parameters

Specifying the Criteria for Logging Messages

The criteria for selecting SIP messages to log can be defined either in XML files that are packaged with the logging Servlet's application, or as initialization parameters in the Servlet's sip.xml deployment descriptor. The sections that follow describe each method.

Using XML Documents to Specify Logging Criteria

If you do not specify logging criteria as an initialization parameter to the logging Servlet, the Servlet looks for logging criteria in a pair of XML descriptor files in the top level of the logging application. These descriptor files, named request-pattern.xml and response-pattern.xml, define patterns that WebLogic SIP Server uses for selecting SIP requests and responses to place in the log file.

Note: By default WebLogic SIP Server logs both requests and responses. If you do not want to log responses, you must define a response-pattern.xml file with empty matching criteria.

A typical pattern definition defines a condition for matching a particular value in a SIP message header. For example, the sample response-pattern.xml used by the msgTraceLogger Servlet matches all MESSAGE requests. The contents of this descriptor are shown in

Listing 12-2 Sample response-pattern.xml for msgTraceLogger Servlet

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE pattern

   PUBLIC "Registration//Organization//Type Label//Definition Language"

   "trace-pattern.dtd">

<pattern>

  <equal>

    <var>response.method</var>

    <value>MESSAGE</value>

  </equal>

</pattern>

Additional operators and conditions for matching SIP messages are described in trace-pattern.dtd Reference. Most conditions, such as the equal condition shown in Listing 12-2, require a variable (var element) that identifies the portion of the SIP message to evaluate. Table 12-2 lists some common variables and sample values. For additional variable names and examples, see Chapter 11: Mapping Requests to Servlets in the SIP Servlet API 1.0 specification; WebLogic SIP Server enables mapping of both request and response variables to logging Servlets.

Table 12-2 Pattern-matching Variables and Sample Values

Both request-pattern.xml and response-pattern.xml use the same Document Type Definition (DTD). See trace-pattern.dtd Reference for more information.

Using Servlet Parameters to Specify Logging Criteria

Pattern-matching criteria can also be specified as initialization parameters to the logging Servlet, rather than as separate XML documents. The parameter names used to specify matching criteria are request-pattern-string and response-pattern-string. They are defined along with the logging level and destination as described in Configuring the Logging Level and Destination.

The value of each pattern-matching parameter must consist of a valid XML document that adheres to the DTD for standalone pattern definition documents (see Using XML Documents to Specify Logging Criteria). Because the XML documents that define the patterns and values must not be parsed as part of the sip.xml descriptor, you must enclose the contents within the CDATA tag. Listing 12-3 shows the full sip.xml entry for the sample logging Servlet, invTraceLogger. The final two init-param elements specify that the Servlet log only INVITE request methods and OPTIONS response methods.

Listing 12-3 Logging Criteria Specified as init-param Elements

<servlet>

      <servlet-name>invTraceLogger</servlet-name>

      <servlet-class>com.bea.wcp.sip.engine.tracing.listener.TraceMessageListenerImpl</servlet-class>

      <init-param>

        <param-name>domain</param-name>

        <param-value>true</param-value>

      </init-param>

      <init-param>

        <param-name>level</param-name>

        <param-value>full</param-value>

      </init-param>

      <init-param>

        <param-name>request-pattern-string</param-name>

        <param-value>

            <![CDATA[

                <?xml version="1.0" encoding="UTF-8"?>

                <!DOCTYPE pattern

                   PUBLIC "Registration//Organization//Type Label//Definition Language"

                   "trace-pattern.dtd">

                <pattern>

                  <equal>

                    <var>request.method</var>

                    <value>INVITE</value>

                  </equal>

                </pattern>

            ]]>

        </param-value>

      </init-param>

      <init-param>

        <param-name>response-pattern-string</param-name>

        <param-value>

            <![CDATA[

                <?xml version="1.0" encoding="UTF-8"?>

                <!DOCTYPE pattern

                   PUBLIC "Registration//Organization//Type Label//Definition Language"

                   "trace-pattern.dtd">

                <pattern>

                  <equal>

                    <var>response.method</var>

                    <value>OPTIONS</value>

                  </equal>

                </pattern>

            ]]>

        </param-value>

      </init-param>

      <load-on-startup/>

  </servlet>

Managing Logging Performance

The SIP message logging implementation uses the threads in two execute queues, sip.tracing.local and sip.tracing.domain, to write log messages to the server and domain log files, respectively. By default each queue is configured with only a single thread. If the volume of log messages exceeds the capacity of either of these queues, log messages are dropped and a notification of drop messages is written to the file. Normal logging continues when the volume of logged messages can be handled by the available threads.

If the number of dropped message notifications is unacceptable, follow these instructions to increase the number of threads available in the queue:

Access the Administration Console for the WebLogic SIP Server domain.
Expand the Servers node in the left pane of the Administration Console.
Right-click the name of the server that contains the execute queue you want to configure, and select View Execute Queues. (If you want to configure the queue used for writing to the domain log file, right-click any available server.)
In the right pane of the console, click either sip.tracing.local or sip.tracing.domain to configure the queue.
Edit the Thread Count value to change the number of threads allocated to the pool, or change any other Execute Queue properties to improve performance as needed.
Click Apply to apply your changes.
Reboot the WebLogic SIP Server instance to realize the change.

Enabling Log Rotation and Viewing Log Files

The WebLogic SIP Server logging infrastructure enables you to automatically write to a new log file when the existing log file reaches a specified size. You can also view log contents using the Administration Console or configure additional server-level events that are written to the log. See Server Log in the WebLogic Server 8.1 documentation for more information about basic log management.

trace-pattern.dtd Reference

trace-pattern.dtd defines the required contents of the request-pattern.xml and response-pattern.xml, documents, as well as the values for the request-pattern-string and response-pattern-string Servlet init-param variables.

Listing 12-4 trace-pattern.dtd

<!--

The different types of conditions supported.

-->

<!ENTITY % condition "and | or | not |

                      equal | contains | exists | subdomain-of">

<!--

A pattern is a condition: a predicate over the set of SIP requests.

-->

<!ELEMENT pattern (%condition;)>

<!--

An "and" condition is true if and only if all its constituent conditions

are true.

-->

<!ELEMENT and (%condition;)+>

<!--

An "or" condition is true if at least one of its constituent conditions

is true.

-->

<!ELEMENT or (%condition;)+>

<!--

Negates the value of the contained condition.

-->

<!ELEMENT not (%condition;)>

<!--

True if the value of the variable equals the specified literal value.

-->

<!ELEMENT equal (var, value)>

<!--

True if the value of the variable contains the specified literal value.

-->

<!ELEMENT contains (var, value)>

<!--

True if the specified variable exists.

-->

<!ELEMENT exists (var)>

<!--

-->

<!ELEMENT subdomain-of (var, value)>

<!--

Specifies a variable. Example:

  <var>request.uri.user</var>

-->

<!ELEMENT var (#PCDATA)>

<!--

Specifies a literal string value that is used to specify rules.

-->

<!ELEMENT value (#PCDATA)>

<!--

Specifies whether the "equal" test is case sensitive or not.

-->

<!ATTLIST equal ignore-case (true|false) "false">

<!--

Specifies whether the "contains" test is case sensitive or not.

-->

<!ATTLIST contains ignore-case (true|false) "false">

<!--

The ID mechanism is to allow tools to easily make tool-specific

references to the elements of the deployment descriptor. This allows

tools that produce additional deployment information (i.e information

beyond the standard deployment descriptor information) to store the

non-standard information in a separate file, and easily refer from

these tools-specific files to the information in the standard sip-app

deployment descriptor.

-->

<!ATTLIST pattern id ID #IMPLIED>

<!ATTLIST and id ID #IMPLIED>

<!ATTLIST or id ID #IMPLIED>

<!ATTLIST not id ID #IMPLIED>

<!ATTLIST equal id ID #IMPLIED>

<!ATTLIST contains id ID #IMPLIED>

<!ATTLIST exists id ID #IMPLIED>

<!ATTLIST subdomain-of id ID #IMPLIED>

<!ATTLIST var id ID #IMPLIED>

<!ATTLIST value id ID #IMPLIED>

Adding Tracing Functionality to SIP Servlet Code

Tracing functionality can be added to your own Servlets or to Java code by using the TraceMessageListenerFactory. TraceMessageListenerFactory enables clients to reuse the default trace message listener implementation behaviors by creating an instances and then delegating to it. The factory implementation instance can be found in the servlet context for SIP Servlets by looking up the value of the TraceMessageListenerFactory.TRACE_MESSAGE_LISTENER_FACTORY attribute.

Note: Instances created by the factory are not registered with WebLogic SIP Server to receive callbacks upon SIP message arrival and departure.

To implement tracing in a Servlet, you use the factory class to create delegate in the Servlet's init() method as shown in Listing 12-5.

Listing 12-5 Using the TraceMessageListenerFactory

public void init() throws ServletException {

   ServletContext sc = (ServletContext) getServletContext();

   TraceMessageListenerFactory factory = (TraceMessageListenerFactory) sc.getAttribute(TraceMessageListenerFactory.TRACE_MESSAGE_LISTENER_FACTORY);

   delegate = factory.createTraceMessageListener(getServletConfig());

}