Logging target base class. More...

#include <senf/Utils/Logger/Target.hh>

Inheritance diagram for senf::log::Target:

[legend]

Classes
struct	InvalidAreaException
	Exception: Invalid area. More...

struct	InvalidStreamException
	Exception: Invalid stream. More...

struct	RoutingEntry
	Target routing entry. More...

Public Types
enum	action_t { ACCEPT, REJECT }
	Routing action. More...

typedef RIB::const_iterator	iterator
	Routing table iterator. More...

typedef RIB::size_type	size_type

Public Member Functions
iterator	begin () const
	Iterator to beginning of routing table. More...

iterator	end () const
	Iterator past the end of routing table. More...

RoutingEntry const &	operator[] (size_type i) const
	Access routing entry. More...

size_type	size () const
	Number of routing table entries. More...

bool	empty () const
	`true`, if routing table empty, `false` otherwise More...

void	flush ()
	Clear routing table. More...

senf::console::ScopedDirectory &	consoleDir ()
	Get console/config directory. More...

Protected Member Functions
virtual void	v_write (time_type timestamp, std::string const &stream, std::string const &area, unsigned level, std::string const &message)=0
	Called to write out the routing message. More...

Related Functions
(Note that these are not member functions.)
std::ostream &	operator<< (std::ostream &os, Target::action_t const &action)
	Write route action. More...

Structors and default members
	Target (std::string const &name)

virtual	~Target ()

Routing
template<class Stream , class Area , class Level >
void	route (action_t action=ACCEPT, int index=-1)
	Add route (static) More...

void	route (std::string const &stream, std::string const &area="", unsigned level=NONE::value, action_t action=ACCEPT, int index=-1)
	Add route (dynamic) More...

template<class Stream , class Area , class Level >
void	unroute (action_t action=ACCEPT)
	Remove route (static) More...

void	unroute (std::string const &stream, std::string const &area="", unsigned level=NONE::value, action_t action=ACCEPT)
	Remove route (dynamic) More...

void	unroute (int index=-1)
	Remove route (indexed) More...

Detailed Description

Logging target base class.

Targets are the final destination of log messages. Every message is eventually routed to one or several targets.

Routing

    Each target manages a routing table. The message meta-data (stream, area and level) is
    matched against this table. If an entry matches, the action associated with this entry is
    taken (either \c ACCEPT or \c REJECT).

    Every target manages it's own routing table. Conceptually, every message will be routed to
    every target where it will then be matched against each targets routing table (the
    implementation is more efficient and utilizes a routing cache).

    Each routing entry consists of the following parameters
    \li (optional) \e stream. If specified, the entry will match only messages directed at that
        stream
    \li (optional) \e area. If the area is specified, only messages directed at that area are
        matched, otherwise any area will be allowed
    \li (optional) \e level. If the %log level is specified, messages will be accepted if their
        level is at least that value. If the value is not specified, the limit will be taken
        from the stream's default value.

    Each parameter (stream, area and level) has two representations: A static (compile time
    constant) representation, which is the representation also used in the %log statements, and a
    dynamic (runtime) representation.

    The static representation is used, when passing routing parameters via template arguments:

target.route<foo::SomeStream, senf::log::NOTICE>(senf::log::Target::REJECT);
target.route<foo::SomeStream>();
target.route();

The identical routing statements may be expressed using dynamic routing via:

target.route("foo::SomeStream", "", senf::log::NOTICE::value, senf::log::Target::REJECT);
target.route("foo::SomeStream");
target.route();

The static representation has the benefit of being compile-time type checked: Invalid routing parameters will be caught while compiling the code. The dynamic representation is more flexible as it allows to adjust routing from user input (e.g. configuration files).

The different object representations are:

The streams is statically represented by it's name, which is the name of a class defined with SENF_LOG_DEFINE_STREAM. The dynamic representation is a string representation of this name.
The area is statically represented by it's name, which again is the name of a class defined with SENF_LOG_DEFINE_STREAM. The dynamic representation again is a string representation of this class's name. The dynamic representation represents an absent area with the empty string.
The level is statically represented by a level class from Log levels. Dynamically, it is represented by an unsigned integer number, the value member of that class.

Ordering routing entries and route processing

    The routing table is processed from first route to last route, the first matching entry
    determines the fate of a log messages. Therefore, the ordering of routing entries is
    important.

    If no position is explicitly specified, new routing entries are added to the end of the
    routing table. All routing statements however take an index as optional argument to
    explicitly specify the position of the new routing entry.

    The index value starts from 0 for the first route. The value gives the position the new
    routing entry will have after it has been added. An index of 0 will thus insert the new
    routing entry at the beginning of the table. Negative values count from the back, -1 being
    the last entry.

Implementing new targets

    To implement a new target type, you need to derive from senf::log::Target and implement the
    single \c v_write member. This member will be called whenever a message should be output.

    The target may process the message in any arbitrary way: reformat it, write it into an SQL
    DB, whatever can be envisioned. However, there is one important limitation: The \c v_write
    call must \e not block. So for more complex scenarios, additional measures must be taken
    (e.g. writing a %log backend daemon which receives the messages via UDP and processes
    them). Of course, in rare cases messages might be lost but this cannot be avoided.

    \see \ref targets

Definition at line 133 of file Target.hh.

Member Typedef Documentation

◆ iterator

typedef RIB::const_iterator senf::log::Target::iterator

Routing table iterator.

Definition at line 186 of file Target.hh.

◆ size_type

typedef RIB::size_type senf::log::Target::size_type

Definition at line 187 of file Target.hh.

Member Enumeration Documentation

◆ action_t

enum senf::log::Target::action_t

Routing action.

Every routing entry is associated with a routing action. This action is final (for this target. Each target is processed independently).

Enumerator
ACCEPT	Output message
REJECT	Suppress message output

Definition at line 144 of file Target.hh.

Constructor & Destructor Documentation

◆ Target()

senf::log::Target::Target ( std::string const & name )

explicit

Definition at line 45 of file Target.cc.

◆ ~Target()

senf::log::Target::~Target ( )

virtual

Definition at line 122 of file Target.cc.

Member Function Documentation

◆ begin()

iterator senf::log::Target::begin ( ) const

Iterator to beginning of routing table.

◆ consoleDir()

senf::console::ScopedDirectory & senf::log::Target::consoleDir ( )

Get console/config directory.

Definition at line 212 of file Target.cc.

◆ empty()

bool senf::log::Target::empty ( ) const

true, if routing table empty, false otherwise

◆ end()

iterator senf::log::Target::end ( ) const

Iterator past the end of routing table.

◆ flush()

void senf::log::Target::flush ( )

Clear routing table.

Definition at line 198 of file Target.cc.

◆ operator[]()

RoutingEntry const& senf::log::Target::operator[] ( size_type i ) const

Access routing entry.

◆ route() [1/2]

template<class Stream , class Area , class Level >

void senf::log::Target::route	(	action_t	action = `ACCEPT`,
		int	index = `-1`
	)

Add route (static)

Add a route for the given combination of Stream, Area and Level. All parameters (Stream, Area and Level) are optional (the template signature is shown simplified here). So possible commands are:

target.route();
target.route<SomeStream>();
target.route<SomeArea>();
target.route<SomeLevel>();
target.route<SomeStream, SomeArea>();
target.route<SomeStream, SomeLevel>();
target.route<SomeArea, SomeLevel>();
target.route<SomeStream, SomeArea, SomeLevel>();

                                         See the class description for information on the \a
                                         action and \a index parameters

                                         \tparam Stream stream to match
                                         \tparam Area area to match
                                         \tparam Level level, matches messages with
                                             at least the given level.
                                         \param[in] action routing action to take
                                         \param[in] index position of new route in the routing
                                             table

◆ route() [2/2]

void senf::log::Target::route	(	std::string const &	stream,
		std::string const &	area = `""`,
		unsigned	level = `NONE::value`,
		action_t	action = `ACCEPT`,
		int	index = `-1`
	)

Add route (dynamic)

Add a route for the given combination of stream, area and level. All parameters (Stream, Area and Level) are optional and may be omitted by setting them to the empty string or the senf::log::NONE::value respectively.

See the class description for information on the action and index parameters

Exceptions

InvalidStreamException	if the given stream is not found in the StreamRegistry
InvalidAreaException	if the given area is not found in the AreaRegistry

Parameters

[in]	stream	stream to match
[in]	area	area to match
[in]	level	level, matches messages with at least the given level.
[in]	action	routing action to take
[in]	index	position of new route in the routing table

Definition at line 133 of file Target.cc.

◆ size()

size_type senf::log::Target::size ( ) const

Number of routing table entries.

◆ unroute() [1/3]

template<class Stream , class Area , class Level >

void senf::log::Target::unroute ( action_t action = ACCEPT )

Remove route (static)

This member removes an arbitrary routing entry. The template parameters are the same as for the corresponding route() call.

The routing table is searched for a route exactly matching the given specification. If such a route is found, it will be removed, otherwise the call will be ignored

Template Parameters

Stream	stream to match
Area	area to match
Level	level, matches messages with at least the given level.

Parameters

[in] action routing action to take

◆ unroute() [2/3]

void senf::log::Target::unroute	(	std::string const &	stream,
		std::string const &	area = `""`,
		unsigned	level = `NONE::value`,
		action_t	action = `ACCEPT`
	)

Remove route (dynamic)

This member removes an arbitrary routing entry. The stream parameter is mandatory while either area or level may be left unspecified by setting them to the empty string or senf::log::NONE::value respectively.

The routing table is searched for a route exactly matching the given specification. If such a route is found, it will be removed, otherwise the call will be ignored

Parameters

[in]	stream	stream to match
[in]	area	area to match
[in]	level	level, matches messages with at least the given level.
[in]	action	routing action to take

Definition at line 151 of file Target.cc.

◆ unroute() [3/3]

void senf::log::Target::unroute ( int index = -1 )

Remove route (indexed)

This call will remove the route with the given index.

See the class documentation for more information on indexing.

Parameters

[in] index index of routing entry to remove

Definition at line 169 of file Target.cc.

◆ v_write()

virtual void senf::log::Target::v_write	(	time_type	timestamp,
		std::string const &	stream,
		std::string const &	area,
		unsigned	level,
		std::string const &	message
	)

protectedpure virtual

Called to write out the routing message.

This member must be defined in the derived class to somehow format and write the log message.

Every log message always possesses a complete set of meta information (stream, area and level).

Note: This member must not block since it may be called from any unknown context. This prohibits simple logging over NFS or many other network protocols.

Parameters

[in]	timestamp	log message timing information
[in]	stream	message stream
[in]	area	message area
[in]	level	message level
[in]	message	the message string

Implemented in senf::log::IOStreamTarget.

Friends And Related Function Documentation

◆ operator<<()

std::ostream & operator<<	(	std::ostream &	os,
		Target::action_t const &	action
	)

The documentation for this class was generated from the following files:

SENF Extensible Network Framework

Classes

Public Types

Public Member Functions

Protected Member Functions

Related Functions

Structors and default members

Routing

Detailed Description

Routing

Ordering routing entries and route processing

Implementing new targets

Member Typedef Documentation

◆ iterator

◆ size_type

Member Enumeration Documentation

◆ action_t

Constructor & Destructor Documentation

◆ Target()

◆ ~Target()

Member Function Documentation

◆ begin()

◆ consoleDir()

◆ empty()

◆ end()

◆ flush()

◆ operator[]()

◆ route() [1/2]

◆ route() [2/2]

◆ size()

◆ unroute() [1/3]

◆ unroute() [2/3]

◆ unroute() [3/3]

◆ v_write()

Friends And Related Function Documentation

◆ operator<<()