Event Logging Module

Introduction

The Event Logging Module allows you to log information about events fired in MOTECH. It is possible to filter which events get logged using EventLoggers. The module uses logging services to store information about these events. Each service must be registered using the EventLoggingServiceManager which will generate the appropriate listeners for the specified subjects. After registering these services, events with the matching subjects will be processed (logged) by them. The Event Logging Module provides two implementations of the logging service, DbEventLoggingService and FileEventLoggingService, but it is also possible to provide your own implementation.

LoggableEvent and EventLogger

The logging services use EventLogger implementations to log events. Each EventLogger contains data about events to log in the form of LoggableEvent. EventLogger contains followings methods:

  • void addLoggableEvents(List<LoggableEvent> loggableEvents) - Adds data about events to log.
  • void removeLoggableEvents(List<LoggableEvent> - Removes data about events to log.
  • List<LoggableEvent> getLoggableEvents() - Returns data about events to log.
  • void clearLoggableEvents() - Removes all data about events to log.
  • abstract void log(MotechEvent eventToLog) - Abstract method used to store data about events.

LoggableEvent class should be used to check whether the event should be stored by EventLogger. LoggableEvent contains method to check events(boolean isLoggableEvent(MotechEvent eventToLog)). This method checks event subject and compare event parameters with flags.

Field Description Type
eventSubjects List of event subjects which will be logged by EventLogger. Wildcards are allowed. List<String>
flags List of special flags. They are used to filter events on the basis of the parameters. List<? extends EventFlag>

The EventLoggingService provides a method that allows you to retrieve set of all event subjects for which this service is listening.

-Set<String> getLoggedEventSubjects()

EventLoggingServiceManager

EventLoggingServiceManager is an OSGI service through which you can register or update your logging service. Its main function is to manage logging services. The manager keeps a list of all registered logging services.

  • void registerEventLoggingService(EventLoggingService eventLoggingService) - registers MOTECH Listener in MOTECH Platform Event module for events with subjects concluded in EventLogger objects of given logging service.
  • void updateEventLoggingService(EventLoggingService eventLoggingService) - updates MOTECH Listener for events with subjects concluded in EventLogger objects of given logging service(Method not implemented yet).

We can create and register a new logging service as follows:

EventLoggingService newLoggingService = new EventLoggingServiceImplementation();
eventLoggingServiceManager.registerEventLoggingService(newLoggingService);

Database logging

Description

The Event Logging Module automatically creates one DbEventLoggingService. By default, this service logs all events fired in MOTECH. Information about events is stored in the database.

DB Event Converter and Log Mapping

Description

The DB loggers(DbEventLogger) uses a DefaultDbToLogConverter class to build records from events. The main objective of this component is to map the event parameters. This mapping process can remove, add or replace event parameters.

DefaultDbToLogConverter

DbEventLoggingService to convert events is using a DefaultDbToLogConverter. The conversion involves the removal of unwanted event parameters or their replacement to others. The conversion is made on the basis of the information contained in db loggers. This information is represented by LogMappings class which contains following fields.

Field Description Type
mappings List of KeyValue, which contains informations about replacing event params. List<KeyValue>
excludes If events contains a parameter key which is included in this list then this param will be excluded from database log. List<String>
includes If events contains a parameter key which is included in this list then this param will be included in database log. By default all parameters are included so you don’t need to specify keys. You can use this param for example for include a parameter which was replaced by mappings content. List<String>

KeyValue class contains following fields:

  • startKey(String)
  • startValue (Object)
  • endKey (String)
  • endValue (Object)

If we specify mappings section in LogMappings then Db log converter will map event parameters as follows. When an event contains parameter with key equals to startKey and this parameter has value equal to startValue then this parameter is replaced by parameter with key endKey and with value from endValue. So we can replace some parameters before logging an event.

DbEventLoggingService configuration

The Event Logging Module to configure default database logging uses a event-mappings.json configuration file.

Below find an example of the event-mappings.json configuration file:

[
    {
        "subjects": [
            "org.sms",
            "org.ivr"
        ],
        "mappings": [
            {
                "status": "ok",
                "result": "success"
            },
            {
                "status": "error",
                "result": "failure"
            }
        ],
        "excludes": [
            "exclude1",
            "exclude2"
        ],
        "includes": [
            "include1",
            "include2"
        ],
        "flags": [
            {
                "keyValuePairsPresent": {
                    "requiredParameter1": "value1",
                    "requiredParameter2": "value2"
                }
            },
            {
                "keyValuePairsPresent": {
                    "requiredParameter3": "value3"
                }
            }
        ]
    }
]

Below find a default configuration file:

[
    {
        "subjects": [
            "*"
        ]
    }
]

This configuration file is represented by MappingsJson class:

Field Description Type
subject List of event subjects which will be log. List<String>
mappings List of maps used for creating KeyValue list in LogMappings class. List<Map<String, String>>
excludes List of parameter keys which will be excluded from log. List<String>
includes List of parameter keys which will be included in log. List<String>
flags List of ParametersPresentEventFlag. List<ParametersPresentEventFlag>

EventLog

Represents a single, logged event record, that is persisted in the database. Each EventLog contains following fields:

Field Description Type
subject Subject of logged event. String
parameters The parameters(key value pairs) of the logged event. Map<String, Object>
timeStamp Timestamp of logged event. org.joda.time.DateTime

Browsing Logs

You can retrieving event logs using the MDS user interface, or using the DbEventQueryService which is an OSGI service and allows to query for log records, given certain criteria.

  • getAllEventsBySubject(String subject) - Retrieves all events that match a given subject.
  • getAllEventsByParameter(String parameter, String value) - Retrieves all events that match a given parameter and key-value pair.
  • getAllEventsBySubjectAndParameter(String subject, String parameter, String value) - Retrieves all events that match a given subject and parameter key-value pair.

File logging

Description

The Event Logging Module provides possibility to store logs in files. To do this you must use FileEventLoggingService. By default, no FileEventLoggingService instance is created.

FileEventLoggingService

FileEventLoggingService is using FileEventLogger instances to log events. When event arrives each logger added to FileEventLoggingService process it. Each FileEventLogger contains list of File objects. This list is used to create files if they not exist and for storing information about fired events. FileEventLogger for converting events use DefaultFileToLogConverter. Which stores all event parameters to file.

To enable file logging you must add @Service annotation to the FileEventLoggingService and implement @PostConstruct method. In this method you should configure file logger. You can also implement constructor which will configure service. Last step is to register service instance by EventLoggingServiceManager.

@PostConstruct
public void configureFileLoggingService() {
    List<File> loggingFiles = new ArrayList<>();
    //Here we must add some files in which logs will be saved

    List<LoggableEvent> loggableEvents = new ArrayList<>();
    //Here we must specify some loggable events

    //creating and adding new logger
    FileEventLogger logger = new FileEventLogger(loggableEvents, loggingFiles, eventConverter);
    fileEventLoggers.add(logger);
}

Below you can see a sample file content.

EVENT: eventSubject1 at TIME: 2015-04-17T14:20:45.713+02:00 with PARAMETERS: param1/1 param2/5 param3/moduleName1
EVENT: eventSubject2 at TIME: 2015-04-17T14:21:45.713+02:00 with PARAMETERS: param1/3 param2/value param3/moduleName2
EVENT: eventSubject3 at TIME: 2015-04-17T14:22:45.713+02:00 with PARAMETERS: param1/4 param2/value param3/moduleName3

Parameters Flags

ParametersPresentEventFlag

This class is used by LoggableEvent class for filter events by parameters.

Field Description Type
keyValuePairsPresent Key-value pairs representing parameters and their values which are required in the event to log. Map<String, String>

RegexEventFlag

Not implemented yet.