Configuring and Managing WebLogic SIP Server

Logging SIP Requests and Responses

The following sections describe how to configure and manage logging for SIP requests and responses:

Overview of SIP Logging

WebLogic SIP Server enables you to perform Protocol Data Unit (PDU) logging for the SIP requests and responses it processes. Logged SIP messages are placed either in the domain-wide log file for WebLogic SIP Server, or in the log files for individual Managed Server instances. Because SIP messages share the same log files as WebLogic SIP Server instances, you can use advanced server logging features such as log rotation, domain log filtering, and maximum log size configuration when managing logged SIP messages.

Administrators configure SIP PDU logging by defining one or more SIP Servlets using the com.bea.wcp.sip.engine.tracing.listener.TraceMessageListenerImpl class that is available in the template sipserver-tracing.war application. Logging criteria are then configured either as parameters to the defined servlet, or in separate XML files packaged with the application.

As SIP requests are processed or SIP responses generated, the logging Servlet compares the message with the filtering patterns defined in a standalone XML configuration file or Servlet parameter. SIP requests and responses that match the specified pattern are written to the log file along with the name of the logging servlet, the configured logging level, and other details. To avoid unnecessary pattern matching, the Servlet marks new SIP Sessions when an initial pattern is matched and then logs subsequent requests and responses for that session automatically.

WebLogic SIP Server includes a template Web Application, sipserver-tracing.war, that defines several SIP logging Servlets. You can use the Servlets that are predefined in this application, or you can copy the Servlet implementation class into your own applications and define logging Servlets as needed. See Using the Template Logging Servlet. Logging criteria are defined either directly in sip.xml as parameters to a logging Servlet, or in external XML configuration files. See Specifying the Criteria for Logging Messages.

Using the Template Logging Servlet

The template logging application, sipserver-tracing.war, contains a logging Servlet implementation that you can customize to perform logging in a WebLogic SIP Server domain. You can either use sipserver-tracing.war as a standalone application that you configure and deploy along with other applications on your system, or you can incorporate the Servlet implementation class from sipserver-tracing.war directly into other applications to provide tracing functionality. The following sections describe each approach.

Deploying the Template Logging Application

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

Using the Logging Servlet Implementation in Other Applications

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

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 10-1.

<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 10-1 lists the parameters and parameter values that you can specify as init-param entries. Listing 10-1, Template Logging Servlets, on page 10-4 shows the sample init-param entries for a Servlet that logs full SIP message information to the domain log file.

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.

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

<?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 10-2, require a variable (var element) that identifies the portion of the SIP message to evaluate. Table 10-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.

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 10-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.

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

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.

Listing 10-4 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>

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:

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.

<!--

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 instance 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.

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

public final class TraceMessageListenerImpl extends SipServlet implements MessageListener {

  private MessageListener delegate;

  public void init() throws ServletException {

    ServletContext sc = (ServletContext) getServletContext();

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

    delegate = factory.createTraceMessageListener(getServletConfig());

  }

  public final void onRequest(SipServletRequest req, boolean incoming) {

    delegate.onRequest(req,incoming);

  }

  public final void onResponse(SipServletResponse resp, boolean incoming) {

    delegate.onResponse(resp,incoming);

  }

}

Order of Startup for Listeners and Logging Servlets

If you deploy both listeners and logging servlets, the listener classes are loaded first, followed by the Servlets. Logging Servlets are deployed in order according to the load order specified in their Web Application deployment descriptor.