Logging SIP Requests and Responses
This chapter describes how to configure and manage logging for SIP requests and responses that Oracle Communications Converged Application Server processes.
Overview of SIP Logging
Converged Application 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 Converged Application Server, or in the log files for individual Managed Server instances. Because SIP messages share the same log files as Converged Application 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 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.
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.
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 definition for a sample msgTraceLogger is shown below.
Example 3-5 Sample Logging Servlet
<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>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 3-15 lists the parameters and parameter values that you can specify as init-param entries. Example 3-5 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 Converged Application Server uses for selecting SIP requests and responses to place in the log file.
As SIP requests are processed or SIP responses generated, the logging Servlet compares the message with the defined filtering patterns. 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.
Note:
By default Converged Application Server logs both requests and responses. If you define a request-pattern.xml file, the response within the SIP session will be logged automatically.
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
Example 3-6 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, require a variable
(var element) that identifies the portion of the SIP message to evaluate.
The table below lists some common variables and sample values. For additional variable names
and examples, see Section 16: Mapping Requests to Servlets in the SIP Servlet API 1.1
specification (http://jcp.org/en/jsr/detail?id=289); Converged
Application Server enables mapping of both request and response variables to logging
Servlets.
Table 3-15 Pattern-matching Variables and Sample Values
| Variable | Sample Values |
|---|---|
|
request.method, response.method |
MESSAGE, INVITE, ACK, BYE, CANCEL |
|
request.uri.user, response.uri.user |
guest, admin, joe |
|
request.to.host, response.to.host |
server.example.com |
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. The example below 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.
Example 3-7 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>Specifying Content Types for Unencrypted Logging
By default Converged Application 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, Converged Application 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, Converged Application 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, Converged Application 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.The example below shows a sample message-debug configuration that logs String content for three additional Content-Type values, in addition to text/* and application/sdp content.
Example 3-8 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>Enabling Log Rotation and Viewing Log Files
The Converged Application 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.
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.
Example 3-9 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 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 Converged Application 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.
Example 3-10 Using the TraceMessageListenerFactory
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);
}
}