12 Logging SIP Requests and Responses and EDRs

This chapter describes how to configure and manage logging for SIP requests and responses that Oracle Communications WebRTC Session Controller processes.

Overview of SIP Logging

WebRTC Session Controller 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 WebRTC Session Controller, or in the log files for individual Managed Server instances. Because SIP messages share the same log files as WebRTC Session Controller 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. WebRTC Session Controller writes SIP requests and responses that match the specified pattern 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.

In addition, for each engine you can enable logging of event detail records to the oracle.wsc.core.edr file. See "Accessing Event Detail Records" for more information.

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, "Pattern-matching Variables and Sample Values" lists the parameters and parameter values that you can specify as init-param entries.

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 WebRTC Session Controller uses for selecting SIP requests and responses to place in the log file.

Note:

By default WebRTC Session Controller 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 Example 12-1.

Example 12-1 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>

See "trace-pattern.dtd Reference" for descriptions of additional operators and conditions used for matching SIP messages. Most conditions, such as the equal condition shown in Example 12-1, require a variable (var element) that identifies the portion of the SIP message to evaluate. Table 12-1 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; WebRTC Session Controller enables mapping of both request and response variables to logging servlets.

Table 12-1 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.mydomain.com

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

Specifying Content Types for Unencrypted Logging

By default WebRTC Session Controller 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, WebRTC Session Controller 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, WebRTC Session Controller uses Base-64 encoding to encrypt the message content before logging the message.

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, WebRTC Session Controller logs the content in String format using UTF-8 encoding, regardless of whether 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.

Example 12-2 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 12-2 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 WebRTC Session Controller 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 and the values for the request-pattern-string and response-pattern-string servlet init-param variables.

Example 12-3 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 WebRTC Session Controller 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 Example 12-4.

Example 12-4 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);
  }
}

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.

Accessing Event Detail Records

The Signalling Engine collects data in an event detail record (EDR) for each event that occurs in a subsession for the Call, Chat, and File Transfer packages. Each engine creates event detail records and writes them to a file, oracle.wsc.core.edr, for the sessions that it owns.

An event detail record consists of a number of attributes whose values are written to the file, separated by commas. The following example shows the format of a call event detail record:

"call", "Event Data Record for call", "guest", "wlss-ffc87c6f-03a1b947a75bee7641d1e6caa71af17e@127.0.0.1", "alice@example.com", "bob@example.com", "guest481739666754963347", "0", "Mon Aug 04 22:25:44 IST 2014", "603"

Table 12-2 shows the supported list of attributes in the order in which they appear in an EDR:

Table 12-2 EDR Attributes

Attribute	Value Description	Data Type	Example
EVENT_NAME	call/chat/file_transfer	String	"call"
DESCRIPTION	Description	String	"Event Data Record for call"
APPLICATION	Application for which EDR is generated	String	"guest"
SESSION_ID	Unique subsession ID (call-id)	String	"wlss-ffc87c6f-03a1b947a75bee7641d1e6caa71af17e@127.0.0.1"
INITIATOR	Initiator of subsession	String	"alice@example.com"
TARGET	Target of the subsession	String	"bob@example.com"
USER_ID	Web user ID	String	"alice@web.net"
SESSION_DURATION	Duration of the subsession in seconds	long	61
START_TIME	Start time for the subsession	Date	Mon Aug 04 22:25:44 IST 2014
FAILURE_REASON	Reason for the failure.	Int	603

Note:

The actual start time of the call might be perceived differently by the user. The Signalling Engine cannot identify the time that the media packets are sent between two users because RTP packets are not routed through it. With WebRTC, packets can go directly between the browsers. Consequently, the session duration time is based on the Signaling Engine's perception of the session, not the exact duration of the media packet flow.

You enable EDR logging in the administration console.

You can specify additional configuration options in the edr-log4j2-conf.xml file. In this file is missing, EDRs are logged to the WSC.log file by default.

Table 12-2 lists the contents of a sample edr-log4j2-conf.xml file:

Example 12-5 EDR Logging Configuration Options in the edr-log4j2-conf.xml File

<?xml version="1.0" encoding="UTF-8"?>
<Configuration status="WARN">
       <Appenders>
               <RollingFile  name="file" fileName="servers/${sys:weblogic.Name}/logs/wsc.log" filePattern="servers/${sys:weblogic.Name}/logs/wsc-%d{yyyyMM}-%i.log">
                 <PatternLayout pattern="%5p %d [%-15.15t] (%-25.25c:%4L) - %m%n" />
                 <Policies>
                       <TimeBasedTriggeringPolicy />
                       <SizeBasedTriggeringPolicy size="100 MB"/>
                </Policies>
               </RollingFile>
              
               <RollingFile  name="edr.file" fileName="servers/${sys:weblogic.Name}/logs/edr.log" filePattern="servers/${sys:weblogic.Name}/logs/edr-%d{yyyyMM}-%i.log">
                 <PatternLayout pattern="%m%n" />
                 <Policies>
                       <TimeBasedTriggeringPolicy />
                       <SizeBasedTriggeringPolicy size="100 MB"/>
                 </Policies>
               </RollingFile>
       </Appenders>
              
       <Loggers>
               <Logger name="oracle.wsc.core.edr.EventDataRecorder" level="debug" additivity="false">
                       <AppenderRef ref="edr.file"/>
               </Logger>
               <Root level="info">
                 <AppenderRef ref="file" />
               </Root>
       </Loggers>
      
</Configuration>

You provide the name of the log4j file as part of configuration. For information on log4j configuration, see http://logging.apache.org/log4j/2.x/faq.html#config_location.

For information about the log4j file, see http://logging.apache.org/log4j/2.x/manual/configuration.html.