|
|
The following sections describe how to configure and manage logging for SIP requests and responses:
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. Logging criteria are 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.
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.
| Note: | Engineers can implement PDU logging functionality in their Servlets either by creating a delegate with the TraceMessageListenerFactory in the Servlet's init() method, or by using the tracing class in deployed Java applications. Using the delegate enables you to perform custom logging or manipulate incoming SIP messages using the default trace message listener implementation. See Adding Tracing Functionality to SIP Servlet Code for an example of using the factory in a Servlet's init() method. |
Logging Servlets for SIP messages are created by defining Servlets having the implementation class com.bea.wcp.sip.engine.tracing.listener.TraceMessageListenerImpl. The definition for a sample msgTraceLogger is shown in Listing 3-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>
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 3-1 lists the parameters and parameter values that you can specify as init-param entries.
Listing 3-1, Sample Logging Servlet, on page 3-2 shows the sample init-param entries for a Servlet that logs full SIP message information to the domain log file.
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.
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
<?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 3-2, require a variable (var element) that identifies the portion of the SIP message to evaluate. Table 3-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.
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 3-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>
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 3-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>
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:
sip.tracing.local or sip.tracing.domain to configure the queue.
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 Rotate log file in the WebLogic Server 9.2 documentation for more information about basic log management.
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>
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.
| 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 a delegate in the Servlet's init() method as shown in Listing 3-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);
}
}
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.
|