Dispatchers and receivers

The concept

Receivers

We use 'receiver' term for back-end byte receivers, like log files, network channels, etc.

Dispatchers

We use 'dispatcher' term for intermediate elements which send messages to multiple underlying receivers/dispatchers.

Example

We will visualize these two concepts with an example. Here the dispatchers are green and receivers are white. Note the 'filter' dispatcher: it sends only 'critical' messages to its underlying elements.

Example of dispatchers and receivers

The main goal of making such configurations is to create different groups with common format options or allowed log levels. For example, let's create an example config for the diagram above:

<seelog>
    <outputs>
        <splitter formatid="common">
            <console/>
            <file path="file.log"/>
            <network address="192.168.0.2" port="8123"/>
        </splitter>
        <filter levels="critical">
            <file path="critical.log" formatid="critical"/>
            <smtp formatid="criticalemail" senderaddress="noreply-notification-service@none.org" sendername="Automatic notification service" hostname="mail.none.org" hostport="587" username="nns" password="123">
                <recipient address="john-smith@none.com"/>
                <recipient address="hans-meier@none.com"/>
            </smtp>
        </filter>
    </outputs>
    <formats>
        <format id="common" format="[%LEV] %Msg"/>
        <format id="critical" format="%Time %Date %RelFile %Func %Msg"/>
        <format id="criticalemail" format="Critical error on our server!\n    %Time %Date %RelFile %Func %Msg \nSent by Seelog"/>
    </formats>
</seelog>

So, here we use a 'splitter' element to group three receivers by format ('common') and other two receivers are grouped by allowed log level using a 'filter'. Note, the top element 'outputs' is a splitter itself, so we could simplify the config:

<seelog>
    <outputs formatid="common">
        <console/>
        <file path="file.log"/>
        <network address="192.168.0.2" port="8123"/>
        <filter levels="critical">
            <file path="critical.log" formatid="critical"/>
            <smtp formatid="criticalemail" senderaddress="noreply-notification-service@none.org" sendername="Automatic notification service" hostname="mail.none.org" hostport="587" username="nns" password="123">
                <recipient address="john-smith@none.com"/>
                <recipient address="hans-meier@none.com"/>
            </smtp>
        </filter>
    </outputs>
    <formats>
        <format id="common" format="[%LEV] %Msg"/>
        <format id="critical" format="%Time %Date %RelFile %Func %Msg"/>
        <format id="criticalemail" format="Critical error on our server!\n    %Time %Date %RelFile %Func %Msg \nSent by Seelog"/>
    </formats>
</seelog>

This config would practically do the same as the previous but it is more efficient. Dispatcher diagram for this config looks like:

Dispatcher example 2

Formatting

Formats are applied only when writing to a byte-receiver. Dispatchers inherit format identifiers if 'formatid' is not set. Dispatchers and byte-receivers override any inherited formats if 'format id' is set.

Let's use the config from example above:

<seelog>
    <outputs formatid="common">
        <console/>
        <file path="file.log"/>
        <network address="192.168.0.2" port="8123"/>
        <filter levels="critical">
            <file path="critical.log" formatid="critical"/>
            <smtp formatid="criticalemail" senderaddress="noreply-notification-service@none.org" sendername="Automatic notification service" hostname="mail.none.org" hostport="587" username="nns" password="123">
                <recipient address="john-smith@none.com"/>
                <recipient address="hans-meier@none.com"/>
            </smtp>
        </filter>
    </outputs>
    <formats>
        <format id="common" format="[%LEV] %Msg"/>
        <format id="critical" format="%Time %Date %RelFile %Func %Msg"/>
        <format id="criticalemail" format="Critical error on our server!\n    %Time %Date %RelFile %Func %Msg \nSent by Seelog"/>
    </formats>
</seelog>

It demonstrates the inheritance/overriding features. The topmost splitter has 'common' formatid, so all of its children inherit it: console, file, network, and filter. File and smtp receivers that are inside a filter do not inherit it because they override it with their own formatids. If smtp has not had a 'formatid' attribute set, then it would inherit the 'common' formatid from its parent - 'filter' dispatcher.

Demonstration

A working demo of dispatcher/receiver functionality can be found here: outputs

List of dispatchers

Check the Reference

List of receivers