jordansissel/eventmachine-tail

h1. eventmachine-tail

This project contains two "EventMachine":http://wiki.github.com/eventmachine/eventmachine/ extensions.

First, it adds an event-driven file-following similar to the unix 'tail -f' command. For example, you could use it to follow /var/log/messages the same way tail -f would.

Second, it adds event-driven file patterns allowing you to watch a given file pattern for new or removed files. For example, you could watch /var/log/*.log for new/deleted files.

h2. Why?

For "logstash":http://code.google.com/p/logstash/, the log agents were event-driven using EventMachine. The log agents mainly get their data from logfiles. To that end, we needed a way to treat log files as a stream.

There's a ruby gem 'file-tail' that implements tailing, but not in an event-driven way. This makes it hard to use in EventMachine programs like logstash.

Thus, eventmachine-tail was born.

Further, the usage patterns for logstash required the ability to watch a directory (or a file pattern) for new log files.

h2. Get eventmachine-tail

To install eventmachine-tail, you only need to use gem:

bc. gem install eventmachine-tail

This will also install the rtail tool described below.

h2. Implementation Thoughts

h3. "Don't block the reactor"

EventMachine::FileTail will only read one chunk (64K by default) from any file for each tick of the reactor. This helps ensure we don't spend too much time reading from the file.

A consequence of not reading the file "as fast as possible until eof" can cause longer data sets to take longer to read since there will be a small delay between each read since the reactor only runs about once every 50ms (depending on the polling features used).

h3. EOF Handling

When we are at the end of file, we rely on EventMachine::FileWatch to notify us when the file changes. On Linux this uses inotify and on OS X and FreeBSD will use kqueue to get event-driven notifications of file changes.

h3. File truncation

If the file length ever shortens, we assume this means the file was truncated. When this happens, we seek to the beginning of the file and continue reading.

h3. File rotation

If we notice that the inode (or underlying device) has changed, we will reopen the file by pathname. This change is generally an indication that our file has been rotated as part of some periodic log rotation.

h3. Globs

You can also use file "glob patterns":http://en.wikipedia.org/wiki/Glob_(programming) to select files to tail. This pattern is checked periodically to see if new files are found.

For example, if your java app writes to logfiles with generated filenames that are hard to predict, you should use EventMachine::FileGlobWatch to match any generated files as they are generated.

Globs are implemented in a polling manner because of the "non-obviousness" of implementing a glob notifier with file watches. It is on my todo list to implement in this way, however.

h2. Example code

For a simple file tailing example, look at "tail.rb":http://github.com/jordansissel/eventmachine-tail/blob/master/samples/tail.rb

For an example of using glob watching file patterns, look at "globwatch.rb":http://github.com/jordansissel/eventmachine-tail/blob/master/samples/globwatch.rb

For an example of using both glob watching and file tailing, check out "glob-tail.rb":http://github.com/jordansissel/eventmachine-tail/blob/master/samples/glob-tail.rb - this project provides a glue class that helps you easily tail globs.

h2. rtail tool

A script comes with eventmachine-tail called 'rtail'

This script allows you to tail files similar to tail(1) but allows you to use the glob watching feature of eventmachine-tail to watch file path patterns (globs) in a tail-ey way.

For example, if you want to 'tail -f' all files, recursively, in /var/log except ones matching '*.gz', you would use:

bc. rtail -x ".gz" "/var/log/**/"

This will follow any existing files and follow newly-created ones that match the glob given as they are created.

By default, rtail checks the glob pattern every 5 seconds. You can change this value with the '-i' flag.

You can also tell rtail to not prefix each line with the filename by giving the '-n' flag.