:description: Ada Logging Framework
:sectanchors:
:source-highlighter: pygments
:stylesdir: css
:stylesheet: styles.css

Alog
====

Alog is a stackable logging framework for the Ada programming language. It aims
to be straight forward to use and is easily extendable. It provides support for
various logger types, log facilities, loglevel policies and message
transformations.

image::alog-arch.svg[Framework Architecture, align="center", width=90%]

include::README[]


Usage
-----

Logger
~~~~~~
Logger instances are used to manage an arbitrary number of log facilities and
message transformations. Various logger types exist which are suitable for
different scenarios:

Logger::
  This is the basic Alog logger type. This logger is easy to use and good enough
  for most situations. However, it does not provide thread safety.

Tasked Logger::
  The Alog tasked logger encapsulates a basic logger instance inside a server
  task to provide safe concurrent logging. Since calls to this logger are
  potentially blocking operations, it cannot be used from within a protected
  action.

Active Logger::
  The Alog active logger provides task safe concurrent logging from any context.

Facility
~~~~~~~~
Another basic entity in the Alog framework is called a Facility. Facilities
are log destinations and used to log messages to different backends, e.g. a
file or a database. Currently, the framework provides the following log
facilities:

File_Descriptor::
  Writes log messages to file or console.

Syslog::
  Writes log messages to syslog.

Transformation
~~~~~~~~~~~~~~
Transformations are used to modify a log message before it is passed on to a
facility. The following message transformations are available:

Casing (toUpper / toLower)::
  Convert a log message to upper/lower case.

Policy
~~~~~~
Alog supports destination and if needed source filtering by means of loglevel
policies. Refer to the example section for information on how to setup an use
these policy mechanism.

Examples
--------
The examples presented in this section will give an introduction on how to use
the Alog framework in your own project.

Logger
~~~~~~
The following example uses a basic logger instance to log messages to standard
output. Furthermore, a file based facility is attached which writes log messages
to a file.

[source,ada]
---------------------------------------------------------------------
include::../examples/logger_example1.adb[]
---------------------------------------------------------------------

The logger will take care about cleaning up all the attached facilities when
it goes out of scope. However, you can do this explicitly by calling
`Logger.Clear` as well.

Facility
~~~~~~~~
The following code sets up a file descriptor based facility to log messages to
a file. If the file already exists, it will be overwritten.

[source,ada]
---------------------------------------------------------------------
include::../examples/facility_example1.adb[]
---------------------------------------------------------------------

Policy
~~~~~~
The first policy example illustrates how destination filtering works. Only log
messages with loglevel `Error` or higher are written to the application error
logfile. It shows how logging policies can be used to filter log messages
depending on the destination (facility name). Furthermore it illustrates how
the default level can be used to filter out messages with lower loglevels.

[source,ada]
---------------------------------------------------------------------
include::../examples/policy_example1.adb[]
---------------------------------------------------------------------

The second policy example demonstrates how the protected policy database type
of Alog can be used to implement source filtering in an application. It shows
how logging policies can be constructed by specifying source specific loglevels
and how this leads to log messages being filtered depending on their source.

[source,ada]
---------------------------------------------------------------------
include::../examples/policy_example2.adb[]
---------------------------------------------------------------------
