Message Delivery Status

Throughout their lifetime, messages will transition between different states.

INCOMING

When a line is first read from the watched file, it is converted into a Message. And since each message can span multiple lines, we cannot decide whether a particular line is the last line of the message. Therefore, before we receive the first line of a new message, the current one will be in the INCOMING state.

ACCEPTED

When we have received first line of the new message, the previous one is now finally over and it can transition into ACCEPTED or REJECTED state. The message will only become REJECTED if the LogWatch is configured to reject it through LogWatchBuilder. Otherwise, it will be ACCEPTED and stored for future retrieval.

UNDELIVERED

This state is special. The transition from INCOMING to UNDELIVERED will only happen when a Follower is terminated that is currently processing an INCOMING message. Only this one Follower will receive this message with this state.

This has some noteworthy consequences:

• Messages that are REJECTED, INCOMING or UNDELIVERED will not be stored. All message consumers will, however, be notified of them.
• Followers, as well as their expectations and metrics, will be notified of every messages in any state. However, their write() and getMessages() methods will only ever work with messages that have been stored.
• Unless a line appears in the log that starts a new Message, the previous one will never reach ACCEPTED state. The latest Message in the log will therefore always be INCOMING. This is an unfortunate consequence of Splitlog not being able to predict the future.
• More on this can be found in the chapter about splitting.

Consumers and producers

Message producer has the capability of notifying a message consumer of Messages. Producers and consumers form a tree, where a consumer of one producer may itself be a producer for other consumers. Users are allowed to register their own custom consumers.

LogWatch is the ultimate producer, the root of the tree. Follower serves as its consumer and as a producer for its metrics or merged followers. Merged follower consumes a Follower and may pass Messages to its own metrics. However, metrics and expectations are the leaves of this tree.

Consumers can be stopped, after which they will refuse any new message from their producers and they will not pass them on to consumers of their own. In practice, when you stop a Follower, no more expectations will ever return and no metrics will ever trigger.

Whether or not a producer notifies its consumers of the Messages that it has been notified of, that is left to the discretion of the producer. By default, however, no producer provided by the Splitlog package will ever swallow a message.

Gating

Before a Message enters Splitlog, it needs to “pass through the gate.” Messages that don’t pass will not be stored, will never be assigned any of the states, and no consumer will ever be notified of their arrival. It would be as if they never existed.

Gating can be configured on the LogWatchBuilder and is the very first thing that happens when a line is read from the watched log.