C Accounting Event API

This appendix describes the OCMS Accounting Event API, in the following sections:

Introduction
logEvent(SipServletRequest req, Map<Object, Object> additional) Method
logEvent(SipServletResponse resp, Map<Object, Object> additional) Method
logEvent(Map <Object, Object> event, String category) Method
Event Processing in Log4j

Introduction

OCMS provides the Accounting Event API, an interface to create SIP event data that can be used for accounting and charging. The event output data can be post-processed to create CDRs.

The Accounting Event API consists of the following two interfaces:

oracle.sdp.sipservletframework.eventlogger.EventLoggerFactory
oracle.sdp.sipservletframework.eventlogger.EventLogger

The container creates an EventLoggerFactory instance available trough a ServletContext attribute with the name, oracle.sdp.sipservlet.EventLoggerFactory.EVENT_LOGGER_FACTORY. The string cannot be used by itself, but must be specified as follows:

EventLoggerFactory elf =
getServletContext().getAttribute(oracle.sdp.sipservletframework.eventlogger.
EventLoggerFactory.EVENT_LOGGER_FACTORY

The EventLogger interface is implemented by the loggers created by the EventLoggerFactory.getLogger(String loggerName) method. The EventLogger instances use Apache Log4j internally for the actual logging. Log4j allows flexible logging for instance to a file or to a centralized log server using syslog.

The EventLogger interface has three methods for logging events (illustrated in Example C-1):

logEvent(SipServletRequest req, Map<Object, Object> additional)
logEvent(SipServletResponse resp, Map<Object, Object> additional)
logEvent(Map<Object, Object> event, String category)

Example C-1 Logging Events in the EventLogger Interface

public interface EventLogger 
{
  public void logEvent(SipServletRequest req, Map<Object, Object> additional);

  public void logEvent(SipServletResponse resp, Map<Object, Object> additional);

  public void logEvent(Map<Object, Object> event, String category);

  public boolean isEnabled(SipServletRequest req);
  public boolean isEnabled(SipServletResponse resp);
  public boolean isEnabled(String category);
}

logEvent(SipServletRequest req, Map<Object, Object> additional) Method

The logEvent(SipServletResponse resp, Map<Object, Object> additional) method logs an event with the characteristic request attributes listed in together with any additional event attributes provided. Table C-1 describes the request attributes of the logEvent Method. The event is logged to the following Log4j category name:

"eventlogger." + loggerName + ".REQUEST." + method.

Table C-1 Request Attributes of the logEvent(SipServletRequest req, Map<Object, Object> additional) Method

Attribute	Description
RequestUri	The Request-URI value.
Method	The method value.
To	The To header value.
From	The From header value.
Call-ID	The Call-ID header value.
CSeq	The CSeq header value.
Via	A string of all Via header values, separated by semicolons (;).
Content-Type	The Content-Type header value, or "".
Content-Length	The Content-Length header value, or "".
MEDIA	A string of all SDP media line values (that is, the portion following m=), which are separated by semicolons(;). Only include this attribute for INVITE requests when SDP content is not present.
Service	The name of the service generating the event (that is, the full Log4j category name).

logEvent(SipServletResponse resp, Map<Object, Object> additional) Method

The public void logEvent(SipServletResponse resp, Map<Object, Object> additional) method logs an event with the characteristic response attributes listed in Table C-2 with any additional event attributes provided. The event will be logged to the following full Log4j category name:

"eventlogger." + loggerName + ".RESPONSE." + method + "." + statuscode.

Table C-2 describes the attributes for public void logEvent(SipServletResponse resp, Map<Object, Object> additional).

Table C-2 Response Attributes for the logEvent(SipServletResponse resp, Map<Object, Object> additional) Method

Attribute	Description
StatusCode	The response status code.
Method	The method value.
To	The To header value.
From	The From header value.
Call-ID	The Call-ID header value.
CSeq	The CSeq header value.
Via	A string of all Via header values, separated by semicolons (;).
Content-Type	The Content-Type header value, or "".
Content-Length	The Content-Length header value, or "".
MEDIA	A string of all SDP media line values (that is, the portion following m=), which are separated by semicolons(;). Only include this attribute for INVITE requests when SDP content is not present.
Service	The name of the service generating the event (that is, the full Log4j category name).

logEvent(Map <Object, Object> event, String category) Method

The public void logEvent(Map <Object, Object> event, String category) method is a generic method that can be used to log any kind of event in the form of an attribute map. The Service attribute listed in Table C-3 is also added to the attribute map. The event will be logged to the full Log4j category name, which can take either of the following two forms:

"eventlogger." + loggerName
"eventlogger." + loggerName + "." + category if a non-null category is provided.

Table C-3 lists the attributes for this method.

Table C-3 Attributes of the logEvent(Map <Object, Object> event, String category) Method

Attribute Key	Description of attribute value
Service	The name of the service generating the event (that is, the full Log4j category name).

The isEnabled method returns true only if the Log4j filter is configured so that a call to logEvent method with the same argument is logged. Example C-2 illustrates how a servlet uses the Accounting Event API to log events for all of its requests and responses.

Example C-2 Logging Events with the Accounting API

public class EventTestServlet extends SipServlet 
{

  private EventLogger eventLogger;

  public void init() {

     ServletContext sc = getServletContext();
     EventLoggerFactory factory = (EventLoggerFactory) sc
        .getAttribute("oracle.sdp.sipservlet.EventLoggerFactory");
     eventLogger = factory.getLogger(EventTestServlet.class);
   }
   public void doRequest(SipServletRequest req) {
      if (eventLogger.isEnabled(req)) {
      eventLogger.logEvent(req, null);
   }
      URI requestURI = req.getRequestURI();
      req.getProxy().proxyTo(requestURI);
   }
   public void doResponse(SipServletResponse resp) {
      if (eventLogger.isEnabled(resp)) {
         Map additional = new HashMap();
         additional.put("foo", "bar")
         eventLogger.logEvent(resp, additional);
      }
   }
}

Event Processing in Log4j

Log4j is executes the following tasks:

Event filtering
Event formatting
Deciding the destination for events

These configurations can be changed in runtime by editing the Log4j configuration file (log4j.xml).

For more information about Log4j, see http://logging.apache.org/log4j.

Event Filtering

By uncommenting or commenting categories in the Log4j configuration file (log4j.xml), events can be enabled or disabled as illustrated in Example C-3. The Log4j configuration determines which events generated from the servlets are logged to the event.log file.

Example C-3 illustrates a Log4j configuration for displaying 200 (OK) responses to INVITE and BYE requests from the EventTestServlet. These responses are logged to the event.log file.

Example C-3 Log4j Configuration for Displaying BYE Requests and 200 (OK) Responses to INVITE Requests

<category
  name="eventlogger.com.example.EventTestServlet.RESPONSE.INVITE.200"
  additivity="false">
  <priority value="ALL"/>
  <appender-ref ref="EVENTLOGGER"/>
  <appender-ref ref="EVENTLOGGER_LOCAL" />
</category>
<category name="eventlogger.com.example.EventTestServlet.REQUEST.BYE"
  additivity="false">
  <priority value="ALL"/>
  <appender-ref ref="EVENTLOGGER"/>
  <appender-ref ref="EVENTLOGGER_LOCAL" />
</category>

Note the notation with class name and type of RESPONSE/REQUEST.

Event Formatting and Destination

The format of the events in the event.log is determined by the layout class in Log4j. The default layout class used for SipServlet event logging is oracle.sdp.eventlogger.BasicLayout, and it logs each event as a single row with comma-separated attributes. The method toString() is then called on the attribute keys and values, which are concatenated with an equals sign (= ). The BasicLayout class also adds the attributes described in Table C-4. If needed, you can create a new layout class.

Table C-4 Event Logging Attributes

Attribute Key	Description of Attribute Value
Creation Time	The event creation time in format: yyyy-MM-dd'T'HH:mm:ss.SSS'Z'
TimeZoneOffset	The offset, in minutes from GMT

The configuration also determines where events will be sent, for example to console, file, syslog, remote socket, or JMS. In Example C-4 the events are logged to a file, by using syslog to the localhost (127.0.0.1).For more information about Log4j, see http://logging.apache.org/log4j.

Example C-4 Logging Events to a File

<appender name="EVENTLOGGER_LOCAL"
  class="org.oracle.logging.appender.RollingFileAppender">
  <param name="File" value="/var/log/sdp/events.log"/>
  <param name="Append" value="true"/>
  <param name="MaxFileSize" value="100000KB"/>
  <param name="MaxBackupIndex" value="10"/>
  <layout class="oracle.sdp.eventlogger.BasicLayout">
  </layout>
</appender>

Example of BasicLayout Output

Each attribute is displayed in a separate row with the key in bold text.

REQUEST.INVITE:

CreationTime=2005-04-15T07:50:51.767Z,
To=<sip:08505@example.com>;tag=0f54d930-f916-4702-8293-d8b014810a29,
TimeZoneOffset=120,
Method=INVITE,
Content-Type=application/sdp,
Service=eventlogger.com.example.EventTestServlet.REQUEST.INVITE,
Call-ID=8e02578d-2021-4d06-b98d-bf9827c93003@192.0.2.0,
RequestUri=sip:08505@example.com;transport=TCP,
MEDIA=audio 8502 RTP/AVP 97 103 100 101 0 8 102 18 107,
CSeq=2 INVITE,
Content-Length=418,
Via=SIP/2.0/TCP 192.0.2.0:5060;branch=z9hG4bKc549d2be44c901ac050be55ff622e1c8;
rport; SIP/2.0/TCP
192.0.2.0:2051;received=192.0.2.0;branch=z9hG4bK-b20b96e2-
1fac-4500-8030-580da1d81051.1;rport=2051,
From=Alice <sip:alice@example.com>;tag=35ec862a-1d03-4f78-904c-
1accf44d15fe

RESPONSE.INVITE.200

CreationTime=2005-04-15T07:50:51.830Z,To=<sip:08505@example.com>;tag=0f54d930-f916-4702-8293-d8b014810a29,
TimeZoneOffset=120,
Method=INVITE,
Content-Type=application/sdp,
Service=eventlogger.com.example.EventTestServlet.RESPONSE.INVITE.200,
Call-ID=8e02578d-2021-4d06-b98d-bf9827c93003@192.0.2.0,
StatusCode=200,
MEDIA=audio 8502 RTP/AVP 0 8,
CSeq=2 INVITE,
Content-Length=392,
Via=SIP/2.0/TCP 192.0.2.0:5060;branch=z9hG4bKc549d2be44c901ac050be55ff622e1c8;
rport; SIP/2.0/TCP
192.0.2.0:2051;received=192.0.2.0;branch=z9hG4bK-b20b96e2-
1fac-4500-8030-580da1d81051.1;rport=2051,
From=Alice <sip:alice@example.com>;tag=35ec862a-1d03-4f78-904c-
1accf44d15fe