Oracle® Communication and Mobility Server Developer's Guide Release 10.1.3 Part Number E10293-02 |
|
|
View PDF |
This appendix describes the OCMS Accounting Event API, in the following sections:
logEvent(SipServletRequest req, Map<Object, Object> additional) Method
logEvent(SipServletResponse resp, Map<Object, Object> additional) Method
logEvent(Map <Object, Object> event, String category) Method
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); }
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). |
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). |
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); } } }
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
.
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