File::Tail for Ruby
Description
This is a small ruby library that allows it to “tail” files in Ruby, including following a file, that still is growing like the unix command ‘tail -f’ can.
Documentation
Complete API documentation is available at: GitHub.io
Architecture Overview
File::Tail follows a well-defined architectural pattern with clear separation of concerns between several key components:
Core Components
File::Tail Module - The central hub extending File objects with tailing capabilities 🔄 - Provides core methods for forward/backward traversal and tailing 📊 - Handles file system events like rotation, truncation, and deletion 🔁
File::Tail::Logfile - A convenience class that simplifies opening and tailing files with options 🚀 - Includes File::Tail module for direct file access 🧠 - Supports various initialization patterns for flexible usage 🔄
File::Tail::Group - Manages multiple files to be tailed together 🔄 - Uses ThreadGroup to coordinate multiple tailing threads ⏳ - Provides batch operations for concurrent file monitoring 📊
File::Tail::Tailer - A Thread subclass that supervises a single file’s tailing 🧠 - Uses queues for line buffering and thread-safe communication 📦 - Implements method_missing for thread-local variable access ⚡
Component Interactions
mermaid
graph LR
A[File::Tail] --> B[File::Tail::Logfile]
A --> C[File::Tail::Group]
C --> D[File::Tail::Tailer]
D --> E[Thread]
A --> F[File::Tail::LineExtension]
F --> G[Lines from tailers]
The File::Tail module acts as the foundation, providing core functionality that is extended by Logfile and Group classes. The Group class coordinates multiple Tailer threads, each managing a single file’s tailing process.
Loading Mechanism
File::Tail supports two primary access patterns:
-
Direct File Extension - Extending File objects directly with File::Tail:
ruby File.open(filename) do |log| log.extend(File::Tail) log.backward(10) log.tail { |line| puts line } end -
Logfile Convenience Class - Using the Logfile wrapper for simpler usage:
ruby File::Tail::Logfile.tail('app.log', :backward => 10) do |line| puts line end
Installation
To install file-tail via its gem type:
bash
gem install file-tail
You can also put this line into your Gemfile:
ruby
gem 'file-tail'
and bundle. This will make the File::Tail module available for extending File objects.
Usage
File::Tail is a module in the File class. A lightweight class interface for logfiles can be seen under File::Tail::Logfile.
Direct Extension of File Objects
ruby
File.open(filename) do |log|
log.extend(File::Tail)
log.interval # 10
log.backward(10)
log.tail { |line| puts line }
end
It’s also possible to mix File::Tail in your own File classes (see also File::Tail::Logfile):
ruby
class MyFile < File
include File::Tail
end
log = MyFile.new("myfile")
log.interval # 10
log.backward(10)
log.tail { |line| print line }
The forward/backward method returns self, so it’s possible to chain methods together like that:
ruby
log.backward(10).tail { |line| puts line }
Multiple File Tailing with Group
ruby
group = File::Tail::Group.new
group.add_filename('app.log')
group.add_filename('error.log')
group.tail { |line| puts line }
Advanced Usage with Callbacks
ruby
log = File::Tail::Logfile.open('app.log')
log.after_reopen { |file| puts "File reopened: #{file.path}" }
log.tail { |line| puts line }
Backward Traversal
```ruby # Tail last 10 lines of file File::Tail::Logfile.open(‘app.log’, :backward => 10) do |log| log.tail { |line| puts line } end
Skip first 5 lines and tail
File::Tail::Logfile.open(‘app.log’, :forward => 5) do |log| log.tail { |line| puts line } end ```
Documentation
To create the documentation of this module, type
bash
$ rake doc
and the API documentation is generated.
In the examples directory is a small example of tail and pager program that use this module. You also may want look at the end of examples/tail.rb for a little example.
Debugging and Troubleshooting
File::Tail provides built-in debugging capabilities through environment variables:
Enabling Debug Output
Set the FILE_TAIL_DEBUG environment variable to enable detailed debugging information:
bash
export FILE_TAIL_DEBUG=1
ruby your_tail_script.rb
This will output information about: - File paths being tailed - Line counts and intervals - Reopening events - Sleep intervals and timing
Exception Handling
File::Tail defines several specific exceptions for different failure scenarios:
ruby
begin
log.tail { |line| puts line }
rescue File::Tail::DeletedException
# Handle file deletion
rescue File::Tail::ReopenException
# Handle file rotation/reopening
rescue File::Tail::BreakException
# Handle end-of-file with break_if_eof set
rescue File::Tail::ReturnException
# Internal exception for controlling tailing behavior
end
Configuration
Key Attributes
File::Tail provides several configurable attributes for fine-tuning behavior:
ruby
log = File::Tail::Logfile.open('app.log')
log.interval = 1.0 # Initial sleep interval (default: 10)
log.max_interval = 5.0 # Maximum sleep interval (default: 10)
log.reopen_deleted = true # Reopen deleted files (default: true)
log.reopen_suspicious = true # Reopen on suspicious events (default: true)
log.suspicious_interval = 60 # Interval before suspicious event detection (default: 60)
log.break_if_eof = false # Break on EOF (default: false)
log.return_if_eof = false # Return on EOF (default: false)
Advanced Configuration
```ruby # Configure for high-traffic logs log.interval = 0.1 log.max_interval = 1.0 log.suspicious_interval = 30
Configure for low-traffic logs
log.interval = 5.0 log.max_interval = 30.0 log.suspicious_interval = 120 ```
Performance Considerations
Thread Safety
File::Tail uses thread-safe mechanisms for concurrent file monitoring: - ThreadGroup for managing tailer threads - Mutex and ConditionVariable for synchronization - Queue-based line buffering for thread communication
Memory Management
The library implements efficient memory usage: - Lines are buffered in queues per tailer - Exponential backoff reduces CPU usage when files are quiet - Proper thread lifecycle management prevents resource leaks
File System Event Handling
File::Tail gracefully handles various file system events: - File rotation (log rotation) - File truncation - File deletion - File reopening after deletion
Error Handling
File::Tail provides comprehensive error handling for common file system scenarios:
File::Tail Exception Hierarchy
```mermaid classDiagram class TailException { «abstract» +message }
class DeletedException
class ReturnException
class BreakException
class ReopenException
TailException <|-- DeletedException
TailException <|-- ReturnException
TailException <|-- BreakException
TailException <|-- ReopenException ```
Safe Usage Pattern
ruby
def safe_tail(filename)
File::Tail::Logfile.open(filename) do |log|
log.tail { |line| puts line }
rescue File::Tail::DeletedException
puts "File was deleted, stopping tailing"
rescue File::Tail::ReopenException
puts "File reopened, continuing tailing"
end
end
Download
The latest version of File::Tail (file-tail) can be found at
https://github.com/flori/file-tail
Author
Florian Frank mailto:flori@ping.de
License
This software is licensed under the Apache 2.0 license.