log4r-xmpp 0.1.0

data/README.rdoc

@@ -0,0 +1,107 @@
+= Log4r-XMPP
+
+== Description
+
+Log4r-XMPP adds a XMPP/Jabber outputter to Log4r.
+
+== Installation
+
+    $ gem install log4r-xmpp
+
+== Requirements
+
+The following gems are required to use Log4r-XMPP:
+
+* log4r
+* xmpp4r (http://home.gna.org/xmpp4r)
+
+== Caveats
+
+* Do NOT include Log4r into your namespace! XMPP4r uses the generic Logger
+  library and would become present in your namespace.
+
+== Using Log4r-XMPP
+
+Requiring 'log4r-xmpp' will add an XMPPOutputter to Log4r. It is as simple as
+using any other Log4r::Outputter and can use most formatters in addition to the
+default.
+
+===Options:
+
+ :buffsize   => The number of logging events to buffer before sending (default 1)
+ :username   => Sending user's XMPP/Jabber account username
+ :password   => Sending user's XMPP/Jabber account password
+ :resource   => Optional sending user's XMPP/Jabber resource (default 'Log4r')
+ :recipients => An array of accounts to send Log4r log statements to
+
+===Example:
+
+    require 'log4r-xmpp'
+
+    options = { :buffsize   => 10,
+                :username   => 'log4r@example.com',
+                :password   => 'secret',
+                :resource   => 'Log4r',
+                :recipients => ['recipient1@example.com', 'recipient2@example.com']
+              }
+
+    outputter = Log4r::XMPPOutputter.new('xmpp', options)
+
+    mylog = Log4r::Logger.new 'mylog'
+    mylog.outputters = outputter
+
+    mylog.debug "This is a test message sent at level DEBUG"
+
+== Using Log4r-XMPP with Log4r::YamlConfigurator
+
+Requiring 'log4r-xmpp/yamlconfigurator' will patch Log4r::YamlConfigurator to
+accept an array list of recipients. Substitutions are still taken into
+consideration.
+
+===Example YAML:
+
+    ---
+    # *** YAML2LOG4R ***
+    log4r_config:
+      # define all loggers ...
+      loggers:
+        - name      : mylog
+          level     : DEBUG
+          trace     : 'false'
+          outputters:
+            - xmpp
+
+      # define all outputters (incl. formatters)
+      outputters:
+        - type        : XMPPOutputter
+          name        : 'xmpp'
+          buffsize    : '10'
+          username    : 'log4r@localhost'
+          password    : 'secret'
+          resource    : "#{RESOURCE}"
+          recipients  : ["user1@#{DOMAIN}", "user2@#{DOMAIN}"]
+          formatter   :
+            date_pattern: '%y%m%d %H:%M:%S'
+            pattern     : '%d %l: %m'
+            type        : PatternFormatter
+
+===Example Loading:
+
+    require 'log4r-xmpp'
+    require 'log4r-xmpp/yamlconfigurator'
+
+    path = File.dirname(__FILE__)
+
+    Log4r::YamlConfigurator['RESOURCE'] = 'Log4r-XMPP'
+    Log4r::YamlConfigurator['DOMAIN']   = 'localhost'
+
+    Log4r::YamlConfigurator.load_yaml_file("#{path}/log4r-xmpp.yaml")
+
+    mylog = Log4r::Logger['mylog']
+
+    mylog.debug "This is a test message sent at level DEBUG"
+
+== Troubleshooting
+
+XMPP4r's logger facility logs to an internal logger named 'xmpp4r'. Attach an
+outputter to view additional warning information. 

data/Rakefile

@@ -0,0 +1 @@
+Dir['tasks/*.rake'].sort.each { |taskfile| load taskfile }

data/VERSION

@@ -0,0 +1 @@
+0.1.0

data/lib/log4r-xmpp.rb

@@ -0,0 +1,31 @@
+# Copyright 2011 Jonathan P. Voss
+#
+# This file is part of Log4r-XMPP
+#
+# Log4r-XMPP is free software: you can redistribute it and/or modify it under
+# the terms of the GNU General Public License as published by the Free
+# Software Foundation, either version 3 of the License, or (at your option)
+# any later version.
+#
+# Log4r-XMPP is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+# FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+# for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with Log4r-XMPP. If not, see <http://www.gnu.org/licenses/>.
+#
+
+require 'log4r'
+require 'log4r-xmpp/xmppoutputter'
+
+module Log4r
+
+  class XMPPOutputter
+
+    VERSION = '0.1.0'
+
+  end # class XMPPOutputter
+
+end # module Log4r
+  

data/lib/log4r-xmpp/xmppoutputter.rb

@@ -0,0 +1,192 @@
+# Copyright 2011 Jonathan P. Voss
+#
+# This file is part of Log4r-XMPP
+#
+# Log4r-XMPP is free software: you can redistribute it and/or modify it under
+# the terms of the GNU General Public License as published by the Free
+# Software Foundation, either version 3 of the License, or (at your option)
+# any later version.
+#
+# Log4r-XMPP is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+# FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+# for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with Log4r-XMPP. If not, see <http://www.gnu.org/licenses/>.
+#
+
+require 'log4r'
+require 'xmpp4r/client'
+
+module Log4r
+
+  class XMPPOutputter < Outputter
+
+    attr_reader :username, :password, :resource, :recipients
+
+    # XMPPOutputter is initialized the same as other Log4r Outputters with the
+    # addition of the following hash options:
+    #
+    #   :buffsize   => The number of logging events to buffer before sending (default 1)
+    #   :username   => Sending user's XMPP/Jabber account username
+    #   :password   => Sending user's XMPP/Jabber account password
+    #   :resource   => Optional sending user's XMPP/Jabber resource (default 'Log4r')
+    #   :recipients => Array of usernames to send Log4r log statements to
+    #
+    # Example:
+    #
+    #   options => { :buffsize   => 10,
+    #                :username   => 'log4r@example.com',
+    #                :password   => 'secret',
+    #                :resource   => 'Log4r',
+    #                :recipients => ['recipient1@example.com', 'recipient2@example.com']
+    #              }
+    #
+    #   outputter = Log4r::XMPPOutputter.new('xmpp', options)
+    #
+    #   mylog = Log4r::Logger.new 'mylog'
+    #   mylog.outputters = outputter
+    #
+    #   mylog.debug "This is a test message sent at level DEBUG"
+    #
+    def initialize(_name, hash={})
+
+      super(_name, hash)
+
+      @buff = []
+
+      begin
+
+        connect
+        Logger.log_internal { "XMPPOutputter '#{@name}' connected as #{@username}"}
+
+      rescue => e
+
+        xmpp_error = "#{e.class}: #{e.message}"
+
+        Logger.log_internal(-2) do
+
+          "XMPPOutputter '#{@name}' failed to connect to XMPP server: #{xmpp_error}"
+
+        end # Logger.log_internal
+
+      end # begin
+      
+    end # def initialize
+
+    # Connects to the Jabber/XMPP server as a client. This is done automatically
+    # during initialization.
+    #
+    def connect
+
+      Jabber::logger = Log4r::Logger['xmpp4r'].nil? ? Log4r::Logger.new('xmpp4r')\
+                                                    : Log4r::Logger['xmpp4r']
+
+      # Enable XMPP4r library to log DEBUG events to the internal logger
+      #
+      Jabber::warnings = true
+
+      jid = Jabber::JID::new("#{@username}/#{@resource}")
+
+      @client = Jabber::Client::new(jid)
+      @client.connect
+      @client.auth(@password)
+
+    end # def connect
+
+    # Call to force an outputter to write any buffered log events.
+    #
+    def flush
+
+      synch do
+
+        messages = []
+
+        @buff.each{ |event| messages.push( format(event) ) }
+
+        write(messages)
+
+      end # synch
+
+      @buff.clear
+
+      Logger.log_internal { "Flushed XMPPOutputter '#{@name}'" }
+
+    end # def flush
+
+    protected
+
+    # Validates the common hash arguments as required by Log4r then sets up the XMPP options
+    # for the outputter.
+    #
+    def validate_hash(hash)
+
+      super(hash)
+
+      # Convert hash keys to symbols if provided as strings (as if configured by YAML)
+      hash = hash.inject({}){|temp,(k,v)| temp[k.to_sym] = v; temp}
+
+      @buffsize = hash[:buffsize].to_i ||= 1
+
+      @username = hash[:username]      or raise ArgumentError, "Username required"
+      @password = hash[:password]      or raise ArgumentError, "Password required"
+      @resource = hash[:resource]      ||= 'Log4r'
+
+      @recipients = hash[:recipients]  or raise ArgumentError, "Recipients required"
+
+    end # def validate_hash
+
+    private
+
+    # This method handles all log events passed to this Outputter.
+    #
+    def canonical_log(event)
+
+      synch do
+
+        @buff.push event if @buff.size <= @buffsize
+
+        flush if @buff.size >= @buffsize
+
+      end # synch
+
+    end # def canonical_log
+
+    # Method to actually write the formatted data to XMPP.
+    #
+    def write(data)
+
+      body = ''
+
+      data.kind_of?(Array) ? data.each{|x| body << x} : body = data
+      
+      [@recipients].flatten.each do |recipient|
+
+        to = recipient
+
+        message = Jabber::Message.new(to, body).set_type(:normal).set_id('1')
+
+        begin
+
+          @client.send message
+
+        rescue => e
+
+          xmpp_error = "#{e.class}: #{e.message}"
+
+          Logger.log_internal(-2) do
+
+            "XMPPOutputter '#{@name}' failed to send message: #{xmpp_error}"
+
+          end # Logger.log_internal
+
+        end # begin
+
+      end # @recipients.each
+
+    end # def write
+
+  end # class XMPPOutputter
+
+end # module Log4r

data/lib/log4r-xmpp/yamlconfigurator.rb

@@ -0,0 +1,43 @@
+# Copyright 2011 Jonathan P. Voss
+#
+# This file is part of Log4r-XMPP
+#
+# Log4r-XMPP is free software: you can redistribute it and/or modify it under
+# the terms of the GNU General Public License as published by the Free
+# Software Foundation, either version 3 of the License, or (at your option)
+# any later version.
+#
+# Log4r-XMPP is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+# FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+# for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with Log4r-XMPP. If not, see <http://www.gnu.org/licenses/>.
+#
+
+require 'log4r/yamlconfigurator'
+
+module Log4r
+
+  class YamlConfigurator
+
+    class << self
+
+      alias_method :paramsub_old, :paramsub
+
+    end # class << self
+
+    # Monkey patches paramsub to accept arrays as hash values
+    #
+    def self.paramsub(str)
+
+      [str].flatten.each { |val| self.paramsub_old(val) }
+
+      str.inspect
+
+    end # def self.paramsub
+
+  end # class YamlConfigurator
+
+end # module Log4r

data/spec/log4r-xmpp/log4r-xmpp.yaml

@@ -0,0 +1,24 @@
+---
+# *** YAML2LOG4R ***
+log4r_config:
+  # define all loggers ...
+  loggers:
+    - name      : mylogger
+      level     : INFO
+      trace     : 'false'
+      outputters:
+        - xmpp
+
+  # define all outputters (incl. formatters)      
+  outputters:
+    - type        : XMPPOutputter
+      name        : 'xmpp'
+      buffsize    : '10'
+      username    : 'log4r@localhost'
+      password    : 'secret'
+      resource    : "#{RESOURCE}"
+      recipients  : ["user1@#{DOMAIN}", "user2@#{DOMAIN}"]
+      formatter   :
+        date_pattern: '%y%m%d %H:%M:%S'
+        pattern     : '%d %l: %m'
+        type        : PatternFormatter

data/spec/log4r-xmpp/xmppoutputter_spec.rb

@@ -0,0 +1,243 @@
+# Copyright 2011 Jonathan P. Voss
+#
+# This file is part of Log4r-XMPP
+#
+# Log4r-XMPP is free software: you can redistribute it and/or modify it under
+# the terms of the GNU General Public License as published by the Free
+# Software Foundation, either version 3 of the License, or (at your option)
+# any later version.
+#
+# Log4r-XMPP is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+# FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+# for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with Log4r-XMPP. If not, see <http://www.gnu.org/licenses/>.
+#
+
+require "rspec"
+require "log4r-xmpp"
+require "log4r-xmpp/yamlconfigurator"
+
+describe "XMPP Outputter" do
+
+  before(:each) do
+
+    @options = { :buffsize   => 10,
+                 :username   => 'log4r@localhost',
+                 :password   => 'secret',
+                 :resource   => 'Log4r',
+                 :recipients => ['testuser@localhost']
+               }
+
+    @outputter = Log4r::XMPPOutputter.new('xmpp', @options)
+
+    @log = Log4r::Logger.new 'testlog'
+    @log.outputters = @outputter
+
+  end # before(:all)
+
+  after(:each) do
+
+    @log = nil
+
+  end # after(:each)
+
+  describe "initialization" do
+
+    it "should require a username" do
+
+      options = @options.dup
+      options.delete(:username)
+
+      l = lambda { Log4r::XMPPOutputter.new('xmpp', options) }
+
+      l.should raise_error(ArgumentError)
+
+    end # it "should require a username"
+
+    it "should require a password" do
+
+      options = @options.dup
+      options.delete(:password)
+
+      l = lambda { Log4r::XMPPOutputter.new('xmpp', options) }
+
+      l.should raise_error(ArgumentError)
+
+    end # it "should require a password"
+
+    it "should require recipients" do
+
+      options = @options.dup
+      options.delete(:recipients)
+
+      l = lambda { Log4r::XMPPOutputter.new('xmpp', options) }
+
+      l.should raise_error(ArgumentError)
+
+    end # it "should require recipients"
+
+    it "should not require a buffer size" do
+
+      options = @options.dup
+      options.delete(:buffsize)
+
+      l = lambda { Log4r::XMPPOutputter.new('xmpp', options) }
+
+      l.should_not raise_error(ArgumentError)
+
+    end # it "should not require a buffer size"
+
+    it "should not require a resource" do
+
+      options = @options.dup
+      options.delete(:resource)
+
+      l = lambda{ Log4r::XMPPOutputter.new('xmpp', options) }
+
+      l.should_not raise_error(ArgumentError)
+
+    end # it "should not require a resource"
+
+  end  # describe "initialization"
+
+  describe "Log4r support" do
+
+    it "should satisfy Log4r::Outputter requirements" do
+
+      # Public Instance Methods
+      flush         = :flush
+      formatter     = :formatter
+      level         = :level
+      only_at       = :only_at
+
+      # Protected Instance Methods
+      validate_hash = :validate_hash
+
+      # Private Instance Methods
+      canonical_log = :canonical_log
+      format        = :format
+      synch         = :synch
+      write         = :write
+
+      # Pre Ruby 1.9, method arrays included strings instead of symbols
+      if RUBY_VERSION < '1.9'
+
+        canonical_log = canonical_log.to_s
+        flush         = flush.to_s
+        format        = format.to_s
+        formatter     = formatter.to_s
+        level         = level.to_s
+        only_at       = only_at.to_s
+        synch         = synch.to_s
+        validate_hash = validate_hash.to_s
+        write         = write.to_s
+
+      end # if RUBY_VERSION
+
+      @outputter.public_methods.include?(flush).should            == true
+      @outputter.public_methods.include?(formatter).should        == true
+      @outputter.public_methods.include?(level).should            == true
+      @outputter.public_methods.include?(only_at).should          == true
+
+      @outputter.protected_methods.include?(validate_hash).should == true
+
+      @outputter.private_methods.include?(canonical_log).should   == true
+      @outputter.private_methods.include?(format).should          == true
+      @outputter.private_methods.include?(synch).should           == true
+      @outputter.private_methods.include?(write).should           == true
+
+    end # it "should satisfy Log4r::Outputter requirements"
+
+    it "should accept strings as keys in the configuration hash" do
+
+      options = { 'buffsize'   => 10,
+                  'username'   => 'log4r@localhost',
+                  'password'   => 'secret',
+                  'resource'   => 'Log4r',
+                  'recipients' => ['testuser@localhost']
+               }
+
+      outputter = Log4r::XMPPOutputter.new('xmpp', options)
+
+      log = Log4r::Logger.new 'testlog'
+      log.outputters = @outputter
+
+      log.outputters[0].username.should   == options['username']
+      log.outputters[0].password.should   == options['password']
+      log.outputters[0].resource.should   == options['resource']
+      log.outputters[0].recipients.should == options['recipients']
+
+    end # it "should accept strings as keys in the configuration hash" do
+
+    it "should satisfy Log4r::YamlConfigurator requirements" do
+
+      path = File.dirname(__FILE__)
+
+      Log4r::YamlConfigurator['RESOURCE'] = 'Log4r-XMPP'
+      Log4r::YamlConfigurator['DOMAIN']   = 'localhost'
+
+      Log4r::YamlConfigurator.load_yaml_file("#{path}/log4r-xmpp.yaml")
+
+      log = Log4r::Logger['mylogger']
+
+      log.outputters[0].class.should      == Log4r::XMPPOutputter
+      log.outputters[0].username.should   == 'log4r@localhost'
+      log.outputters[0].password.should   == 'secret'
+      log.outputters[0].resource.should   == 'Log4r-XMPP'
+      log.outputters[0].recipients.should == ['user1@localhost', 'user2@localhost']
+
+    end # it "should satisfy Log4r::YamlConfigurator requirements"
+
+  end # describe "Log4r support"
+
+  describe "logging events" do
+
+    it "should buffer messages" do
+
+      message = "This is a message with level DEBUG"
+
+      response = @log.debug message
+      buff = response[0].instance_variable_get(:@buff)
+
+      buff.empty?.should_not == true
+      buff.class.should == Array
+      buff[0].data.should == message
+
+      buff.clear
+
+    end # it "should send messages"
+
+    it "should flush messages when the buffer is full" do
+
+      @outputter.should_receive(:flush)
+
+      @options[:buffsize].times { @log.debug "Test message" }
+
+    end # it "should send messages"
+
+    it "flush should clear the buffer after messages are sent" do
+
+      @options[:buffsize].times { @log.debug "Test message" }
+
+      buffer = @outputter.instance_variable_get(:@buff)
+
+      buffer.empty?.should == true
+
+    end # it "flush should clear the buffer after being sent"
+
+    it "should send messages to Jabber server" do
+
+      jabber = @outputter.instance_variable_get(:@client)
+
+      jabber.should_receive(:send).exactly(1).times
+
+      @options[:buffsize].times { @log.debug "Test message" }
+
+    end # it "should send messages to XMPP server"
+
+  end # describe "logging events"
+
+end # describe "XMPP Outputter"