Event Logging Module¶
Contents
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 inEventLogger
objects of given logging service.void updateEventLoggingService(EventLoggingService eventLoggingService)
- updates MOTECH Listener for events with subjects concluded inEventLogger
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.