Overview

ELAPI – stands for Event Logging API. There are many ways the applications generate and submit the logging information. Historically the applications usually write their log information to files, databases or syslog. The need to collect and process these logs in one central place for compliance and forensic reasons requires a new approach to the logging of the information. The syslog is not good for processing due to lack of specific format for the messages, there is no filtering at the collection point and it is hard to filter unstructured data; the files are hard to remote and merge in one central location; files also usually do not have a well defined structured format.

The idea behind the ELAPI is to give the applications a mean to solve several problems at the same time.

Applications usually lock on some logging interface like syslog, file and changing them to log into alternative more advanced log destination (log facility) becomes a challenge. The ELAPI solves this problem by creating a logging interface that would abstract the application from the actual destination of the log, it being a local file, syslog, database or something else. The log facilities (or sinks) can be plugged into the the ELAPI without any changes to the application.

The data that needs to be logged into the audit logs usually is complex and significantly varies from one situation the application deals with to another. It is very hard and some times impractical to create a fixed structure of the log messages (like in database cases) this usually ends up in situations when half of the fields is not used while the information has to be jammed into some fields since there is not clear definition of where it belongs to. The ELAPI solves this issue by providing the application a way to pass arbitrarily complex data to the logging facility. The data is represented by the collection of the key-value pairs. The collections can be easily constructed, modified or nested allowing reuse of the data in different events (for example the information about the peer host, or socket properties).

The information in the log should be complete but also human readable. In the ELAPI case this is achieved by separating the data of the event from the actual presentation (formatting) of the message. Thus the event can contain much more data than the message in a human readable form. The log facilities that work with human readable messages (syslog, file) will receive the event in the formatted, user readable form. The more advanced facilities like the one being built for IPA will receive the data and formatting information separately. Such approach allows much easier processing and filtering of the events based on raw data but leaves a possibility to convert the event into the human readable form at any moment when user wants to inspect the event.

Usually applications use different interfaces for logging, debugging and audit trails. This means that application developer needs to deal with three different way of emmiting information from the application. ELAPI comes to help providing one interface that can be configured to send events into different destinations. The event is a collection of key-value pairs. One of the keys is so called "target". The configuration can define different logical targets. By default ELAPI operates with three predefined targets "debug", "log" and "audit" but application developers can add other targets if they see a need to have more. Each target is represented by a number (for faster comparison) and mapped to a configuration in the ELAPI configuration file. If the event's value of the target attribute matches the number associated with the target in the configuration file (see specific details later), the event will be sent into this target.

The reliability of the target facilities is also very important. The audit information on one hand should not be lost but on the other logging should not be intrusive and prevent the application from doing what it is supposed to do. For that purpose the ELAPI allows defining several sinks (actual physical event destinations) per target. The sinks are listed in fail over order. If the active sink returns error and there is a fail over sink the ELAPI will automatically fail over without returning error. If there are no available sinks (all sinks returned error) and error will be returned to application and it is responsibility of the application to take a corresponding action.

As we started to implement ELAPI it turned out that it can also be used as a simple reporting tool. Any data that is read as key value pairs (database record for example) can be sent to the output destination (specifically file) in different formats (CSV, HTML etc.). Thus ELAPI can be used to create simple conversion tools that get data in one format and output using other. Though there are many other tools that do that it is useful to know that ELAPI is also an option.