Skip Headers

Oracle® Communication and Mobility Server Developer's Guide Release 10.1.3 Part Number E10293-02 |
Home | Contents | Index | Contact Us

Previous | Next
| View PDF

# 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