blackdog 0.0.2

data/README.md

@@ -0,0 +1,105 @@
+# blackdog
+
+A Ruby program that watches lines added to log files (or any text file) for
+patterns and invokes specific actions when these patterns match.
+
+## Install
+
+To install, change directory to where you have extracted the blackdog source
+files and issue:
+
+    gem build blackdog.gemspec
+    gem install blackdog-*.gem
+
+Alternatively, you can download the gem remotely from [RubyGems.org][]:
+
+    gem install -r blackdog
+
+[RubyGems.org]: http://rubygems.org/
+
+## Use
+
+blackdog comes with a binary of the same name that you use to run configuration
+files.
+
+A blackdog configuration file is a pure Ruby script that contains a simple and
+pretty intuitive [DSL][] for specifying which files you want to watch, for which
+patterns and the actions to take when each of these patterns matches.
+
+[DSL]: http://en.wikipedia.org/wiki/Domain-specific_language
+
+A typical example of what you'd do to watch the access log file of a
+[lighttpd][] instance follows:
+
+[lighttpd]: http://www.lighttpd.net/
+
+    file '/var/log/lighttpd/access.log' do |f|
+      f.watch {|w|
+        w.for /^([^ ]+)/
+
+        w.limit 1, :every => MINUTE
+
+        w.do {|line, matches|
+          from = 'blackdog@localhost'
+          to = 'user@example.com'
+          subject = "#{f.path}: remote connection from #{matches[1]}"
+          body = line
+          mail(from, to, subject, body)
+        }
+      }
+    end
+
+The above example reads:
+
+* Watch file _/var/log/lighttpd/access.log_
+* For any line, capturing the first word (text until the first space character)
+* Limit the number of matches to one per minute
+* Send an email whenever there's a match
+
+Some things to note:
+
+* [Capturing groups][groups] in the pattern are available in the actions block
+  along with the matching line through the `matches` and `line` variables
+  respectively.
+* It's possible to throttle the number of matches in a watch (M matches in N
+  seconds). Time constants for seconds, minutes, hours and days (both singular
+  and plural) are defined for this purpose. In the above example, `MINUTE` could
+  also have been written as `1 * MINUTE`, `1 * MINUTES`, `60 * SECONDS`,
+  `60 * SECOND` or simply `60`.
+* The following additional data is available inside the actions block:
+  * `f.path` -- path of file being watched
+  * `w.pattern` -- matching pattern
+  * `w.throttle` -- throttling parameters (optional)
+* What you do inside the actions block is up to you (e.g. send an email message,
+  post to a private [Twitter][] account, etc.)
+
+[groups]: http://www.regular-expressions.info/brackets.html
+[Twitter]: http://twitter.com/
+
+## License
+
+(The MIT License)
+
+Copyright (c) 2010 Aggelos Orfanakos
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+## Author
+
+[Aggelos Orfanakos](http://agorf.gr/), with suggestions and help from [Christos
+Trochalakis](http://ctrochalakis.org/).

data/bin/blackdog

@@ -0,0 +1,27 @@
+#!/usr/bin/env ruby
+
+require 'rubygems'
+require 'eventmachine'
+require 'blackdog/blackdog'
+
+if ARGV.size != 1
+  $stderr.puts "usage: #$0 <config_file>"
+  exit 1
+end
+
+conf = ARGV[0]
+
+if not File.exist?(conf)
+  $stderr.puts "#{conf}: file does not exist"
+  exit 2
+end
+
+begin
+  EM.run do
+    conf_data = open(conf).read
+    BlackDog.module_eval(conf_data)
+  end
+rescue Interrupt
+  puts
+  puts 'Bye!'
+end

data/lib/blackdog/blackdog.rb

@@ -0,0 +1,121 @@
+require 'logger'
+require 'eventmachine-tail'
+
+module BlackDog
+  extend self
+
+  SECOND = SECONDS = 1
+  MINUTE = MINUTES = 60 * SECONDS
+  HOUR   = HOURS   = 60 * MINUTES
+  DAY    = DAYS    = 24 * HOURS
+
+  LOGGER = Logger.new(STDERR)
+  LOGGER.level = Logger::DEBUG
+
+  def self.log; LOGGER end
+
+  class Watch
+    attr_reader :pattern, :throttle, :actions
+
+    def initialize
+      @pattern  = nil
+      @throttle = nil
+      @actions  = nil
+      @window   = []
+    end
+
+    def for(pattern)
+      @pattern = pattern
+    end
+
+    def limit(times, opts)
+      every = opts[:every]
+
+      if times.is_a?(Integer) and times > 0 &&
+          every.is_a?(Integer) and every > 0
+        @throttle = {:times => times, :every => every}
+      else
+        @throttle = false
+      end
+    end
+
+    def do(&block)
+      @actions = block
+    end
+
+    def throttled?
+      return false if @throttle.nil?
+
+      now = Time.new
+
+      if @window.size == @throttle[:times]
+        if now - @window[0] <= @throttle[:every]
+          return true
+        end
+
+        @window.shift
+      end
+
+      @window << now
+
+      return false
+    end
+
+    def match(line)
+      @pattern && line.match(@pattern)
+    end
+  end
+
+  class LogFile
+    attr_reader :path, :watches
+
+    def initialize(path)
+      @path = path
+      @watches = []
+    end
+
+    def watch
+      yield w = Watch.new
+      @watches << w
+
+      # {{{ logging
+      if w.throttle
+        BlackDog.log.debug(@path) {
+          "watching for #{w.pattern.inspect} with throttle \
+#{w.throttle[:times]}/#{w.throttle[:every]} secs"
+        }
+      else
+        BlackDog.log.debug(@path) { "watching for #{w.pattern.inspect}" }
+
+        if w.throttle == false
+          BlackDog.log.warn(@path) {
+            "ignoring invalid throttle for watch #{w.pattern.inspect}"
+          }
+        end
+      end
+      # }}}
+    end
+
+    def each_watch
+      @watches.each {|w| yield w }
+    end
+  end
+
+  def self.file(path)
+    yield f = LogFile.new(path)
+
+    EventMachine.file_tail(path) {|ft, line|
+      f.each_watch {|w|
+        if matches = w.match(line) and not w.throttled?
+          # {{{ logging
+          BlackDog.log.debug(f.path) {
+            "#{w.pattern.inspect} matched #{line.inspect} \
+with matches #{matches.to_a.inspect}"
+          }
+          # }}}
+          w.actions.call(line, matches) if not w.actions.nil?
+        end
+      }
+    }
+  end
+end

data/lib/blackdog/version.rb

@@ -0,0 +1,3 @@
+module BlackDog
+  VERSION = '0.0.2'
+end

metadata

@@ -0,0 +1,97 @@
+--- !ruby/object:Gem::Specification 
+name: blackdog
+version: !ruby/object:Gem::Version 
+  hash: 27
+  prerelease: false
+  segments: 
+  - 0
+  - 0
+  - 2
+  version: 0.0.2
+platform: ruby
+authors: 
+- Aggelos Orfanakos
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-09-20 00:00:00 +03:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: eventmachine
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :runtime
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: eventmachine-tail
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :runtime
+  version_requirements: *id002
+description: Watch log files for patterns and react
+email: agorf@agorf.gr
+executables: 
+- blackdog
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- README.md
+- bin/blackdog
+- lib/blackdog/blackdog.rb
+- lib/blackdog/version.rb
+has_rdoc: true
+homepage: http://github.com/agorf/blackdog
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.7
+signing_key: 
+specification_version: 3
+summary: Watch log files for patterns and react
+test_files: []
+