Pages/LoggingMarketDataAndEvents.md

Go to the documentation of this file.

\addtogroup logging-options

\brief Describes Logger concept and logging services. 

\section logger-abstraction Logger Abstraction

The logging services have been advanced in the SDK starting with 
this major release. Now it exposes abstraction of logging services 
defining the way for users to bring custom solutions more suitable 
for their purposes.

Logger abstraction is based on two primary classes:

- The OnixS::CME::MDH::Logger which serves as a primary logging instrument, and
- The OnixS::CME::MDH::LogEntry which represents an abstraction of a logged entry.

The OnixS::CME::MDH::Logger defines an interface for adding entries 
to the logger. The OnixS::CME::MDH::LogEntry in its turn defines an 
interface of the entry being added to a log.

The SDK contains a few utility classes like OnixS::CME::MDH::LogEvent 
and its descendants to improve the experience with using logging services.

A typical use-case for the logger inside the Handler looks like following:

~~~{.cpp}

using namespace OnixS::CME::MDH;

if (LogEntry* entry =
    logger.addEntry(LogSeverity::Important))
{
    LogWarning warning(*entry, warningSource);

    static_cast<LogEvent&>(warning) << warningDescription;
}

~~~

Adding a new entry into a log is done by the 
OnixS::CME::MD3::Logger::addEntry member. It returns 
instance of OnixS::CME::MDH::Entry which should be 
used to put information to be logged.

An important aspect of Logger abstraction is the fact Logger may 
return NULL instance of OnixS::CME::MDH::LogEntry. That may happen 
if the information, which is added to a log, has lower severity than 
a logger configured with it. For example, an implementation may log 
only important events and thus regular and debug information is ignored. 
Therefore, when a caller of the OnixS::CME::MDH::Logger::addEntry supplies 
a lower severity level, the member returns a NULL instance.

A valid (non-NULL) instance of the OnixS::CME::MDH::LogEntry class it can be 
filled with any information. Once the entry is set up, information in it must be 
committed to the log by invoking the OnixS::CME::MDH::LogEntry::commit member.

\note An instance of OnixS::CME::MDH::Logger successor can be bound 
to multiple instances of OnixS:CME::MDH::Handler. Therefore, successors
of the Logger abstraction must take into consideration the fact the
OnixS::CME::MDH::Logger::addEntry member can be invoked simultaneously.

\warning It's up to the implementation to allow allocation of the new entries 
while another entry is in the process of fulfilling with data to be logged. 
However, the common rule while using a logger is to avoid adding multiple 
entries at the same time as other implementations may not allow that.

\warning Logging issues should not affect market data processing and thus 
should be exposed through own way. For example, the OnixS::CME::MDH::FileLogger 
can be associated with an instance of the OnixS::CME::MDH::FileLoggerListener 
class upon the instance construction. In case of failure like the inability 
to log an event into a file, an issue is raised and delivered through the 
OnixS::CME::MDH::FileLoggerListener::onFileLoggerIssue member. 

\section logger-implementations Ready-to-use Logger Implementations

The SDK comes with a few ready-to-use implementations of the Logger 
abstractions allowing the users to build their solutions quickly:

Logger Implementation      | Description
---------------------------|-------------------------------------------------------------
OnixS::CME:MDH::FileLogger | Implements logging services over text-based files. Logged data is stored into files which may be limited by size. Once volume reaches its limit, Logger detaches logged data, backs it up and starts a new volume.
OnixS::CME:MDH::NullLogger | Logs nothings. The Handler suppresses logging at all, if the instance of given class is bound to it. 

\section bind-logger-to-handler Binding Logger to the Handler

The Handler logs important aspects of its execution with the help
of Logger abstraction explained above. Logging includes network data
received and processed by the Handler, states of books and, of course,
errors occurred at execution time.

The following example demonstrates how to configure
and bind file-based logger to the Handler:

~~~{.cpp}

using namespace OnixS::CME::MDH;

// Implementing logger listener to get notified on 
// issues which are not raised through other ways. 

struct FileLoggerIssueTracer
: FileLoggerListener
{
    // Member is invoked when file logger experience 
   // issue solely beloning to logging subsystem. 
    void
    onFileLoggerIssue(
        const FileLogger& logger,
        const Char* issue)
    {
       std::cout
            << "ALERT!!! "
               "Issue occurred while logging data. " 
            << issue
            << std::endl;
    }
};

// Later, in code..

HandlerSettings handlerSettings;

handlerSettings.channel(310);
handlerSettings.feeds().connectivityConfigurationFile("config.xml");

handlerSettings.debugLogging().traceMessages(MessageTracing::SbeFormat);

Handler handler(handlerSettings);

FileLoggerSettings loggerSettings;

loggerSettings.filename(makeLogFilename(handlerSettings.channel()));
loggerSettings.severityLevel(LogSeverity::Debug);

FileLoggerIssueTracer loggerTracer;

FileLogger logger(loggerSettings, &loggerTracer);

handler.bindLogger(logger);

~~~