senf::log::Target Class Reference

Logging target base class. More...

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

Inheritance diagram for senf::log::Target:

[legend]

List of all members.

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 ACCEPT or 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

(optional) stream. If specified, the entry will match only messages directed at that stream
(optional) area. If the area is specified, only messages directed at that area are matched, otherwise any area will be allowed
(optional) 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 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 v_write call must 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 also:: Targets

Definition at line 142 of file Target.hh.


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.
typedef RIB::size_type	size_type
Public Member Functions
iterator	begin () const
	Iterator to beginning of routing table.
iterator	end () const
	Iterator past the end of routing table.
RoutingEntry const &	operator[] (size_type i) const
	Access routing entry.
size_type	size () const
	Number of routing table entries.
bool	empty () const
	`true`, if routing table empty, `false` otherwise
void	flush ()
	Clear routing table.
senf::console::ScopedDirectory &	consoleDir ()
	Get console/config directory.
Related Functions
(Note that these are not member functions.)
std::ostream &	operator<< (std::ostream &os, Target::action_t const &action)
	Write route action.
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).
void	route (std::string const &stream, std::string const &area="", unsigned level=NONE::value, action_t action=ACCEPT, int index=-1)
	Add route (dynamic).
template<class Stream , class Area , class Level >
void	unroute (action_t action=ACCEPT)
	Remove route (static).
void	unroute (std::string const &stream, std::string const &area="", unsigned level=NONE::value, action_t action=ACCEPT)
	Remove route (dynamic).
void	unroute (int index=-1)
	Remove route (indexed).
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.

Member Typedef Documentation

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

Routing table iterator.

Definition at line 195 of file Target.hh.

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

Definition at line 196 of file Target.hh.

Member Enumeration Documentation

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 153 of file Target.hh.

Constructor & Destructor Documentation

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

Definition at line 54 of file Target.cc.

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

Definition at line 131 of file Target.cc.

Member Function Documentation

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

Iterator to beginning of routing table.

Definition at line 47 of file Target.cci.

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

Get console/config directory.

Definition at line 221 of file Target.cc.

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

true, if routing table empty, false otherwise

Definition at line 71 of file Target.cci.

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

Iterator past the end of routing table.

Definition at line 53 of file Target.cci.

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

Clear routing table.

Definition at line 207 of file Target.cc.

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

Access routing entry.

Definition at line 59 of file Target.cci.

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 142 of file Target.cc.

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 action and index parameters

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
`[in]`	index	position of new route in the routing table

Definition at line 37 of file Target.cci.

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

Number of routing table entries.

Definition at line 65 of file Target.cci.

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 178 of file Target.cc.

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 160 of file Target.cc.

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

Definition at line 42 of file Target.cci.

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

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

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

Write route action.

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

SENF Extensible Network Framework

senf::log::Target Class Reference

Detailed Description

Routing

Ordering routing entries and route processing

Implementing new targets

Classes

Public Types

Public Member Functions

Related Functions

Structors and default members

Routing

Protected Member Functions

Member Typedef Documentation

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation