logging-couchdb 1.0.0

data/History.txt

@@ -0,0 +1,4 @@
+== 1.0.0 / 2009-07-16
+
+* 1 major enhancement
+  * Birthday!

data/README.rdoc

@@ -0,0 +1,49 @@
+= Logging CouchDB
+* by Tim Pease
+* http://github.com/TwP/logging-couchdb/tree/master
+
+== DESCRIPTION:
+
+Provides a CouchDB appender to the Ruby Logging framework. This appender
+enables log messages to be written to a CouchDB instance.
+
+== SYNOPSIS:
+
+  Logging.plugin :couch_db
+
+  Logging.appenders.couch_db( "app_id", :uri => "http://localhost:5984", :db_name => "logging" )
+
+== REQUIREMENTS:
+
+logging
+rest-client
+json (or json_pure)
+
+== INSTALL:
+
+  gem install logging-couchdb
+
+== LICENSE:
+
+(The MIT License)
+
+Copyright (c) 2009
+
+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.

data/Rakefile

@@ -0,0 +1,43 @@
+# Look in the tasks/setup.rb file for the various options that can be
+# configured in this Rakefile. The .rake files in the tasks directory
+# are where the options are used.
+
+begin
+  require 'bones'
+  Bones.setup
+rescue LoadError
+  begin
+    load 'tasks/setup.rb'
+  rescue LoadError
+    raise RuntimeError, '### please install the "bones" gem ###'
+  end
+end
+
+ensure_in_path 'lib'
+require 'logging'
+require 'logging/plugins/couch_db'
+
+task :default => 'spec:specdoc'
+
+PROJ.name = 'logging-couchdb'
+PROJ.authors = 'Tim Pease'
+PROJ.email = 'tim.pease@gmail.com'
+PROJ.url = 'http://logging.rubyforge.org/logging-couchdb'
+PROJ.version = '1.0.0'
+PROJ.rubyforge.name = 'logging'
+PROJ.exclude << 'logging-couchdb.gemspec'
+PROJ.readme_file = 'README.rdoc'
+PROJ.ignore_file = '.gitignore'
+PROJ.rdoc.remote_dir = 'logging-couchdb'
+
+PROJ.spec.opts << '--color'
+
+PROJ.ann.email[:server] = 'smtp.gmail.com'
+PROJ.ann.email[:port] = 587
+PROJ.ann.email[:from] = 'Tim Pease'
+
+depend_on 'logging'
+depend_on 'rest-client'
+depend_on 'rspec'
+
+# EOF

data/lib/logging/couch_db_appender.rb

@@ -0,0 +1,169 @@
+
+require 'rest_client'
+begin
+  require 'json/ext'
+rescue LoadError
+  require 'json'
+end
+
+
+module Logging::Appenders
+
+  # Accessor / Factory for the CouchDB appender.
+  #
+  def couch_db( *args )
+    return ::Logging::Appenders::CouchDB if args.empty?
+    ::Logging::Appenders::CouchDB.new(*args)
+  end
+
+  # This class provides an Appender that sends log messages to a CouchDB
+  # instance.
+  #
+  class CouchDB < ::Logging::Appender
+    include ::Logging::Appenders::Buffering
+
+    # The string that uniquely identifies this application in the CouchDB
+    # messages.
+    #
+    attr_accessor :app_id
+
+    # call-seq:
+    #    CouchDB.new( name, :uri => 'http://localhost:5984',
+    #                       :db_name => 'logging', :app_id => name )
+    #
+    # Creates a new CouchDB appender that will format log events and send
+    # them to the CouchDB specified by the <tt>:uri</tt> and the
+    # <tt>:db_name</tt>. Your applications should specify a unique
+    # <tt>:app_id</tt> so that metrics about your application can be easily
+    # generated. If an app_id is not given, then the appender <tt>name</tt>
+    # is used as the app_id.
+    #
+    # The CouchDB appender uses message buffering. Log events are saved in
+    # bulk to the CouchDB instance. You can specify the buffer size by
+    # setting <tt>:auto_flushing</tt> to the number of messages to buffer.
+    # Setting the auto_flushing to +true+ will cause messages to be
+    # immediately sent to the CouchDB instance.
+    #
+    # Communication with the CouchDB instance is asynchronous; calls to the
+    # appender sould return quickly. However, there will be some delay
+    # before the log events appear in the CouchDB instance. The
+    # communication thread must be woken up and scheduled in order for the
+    # events to be posted.
+    #
+    def initialize( name, opts = {} )
+      opts = opts.merge(:layout => ::Logging::Layouts::CouchDB.new)
+      super(name, opts)
+
+      # initialize the connection to the CouchDB instance
+      uri = opts.getopt(:uri, 'http://localhost:5984')
+      db_name = opts.getopt(:db_name, 'logging')
+      self.app_id = opts.getopt(:app_id, name)
+
+      @db_uri = uri + '/' + db_name + '/_bulk_docs'
+      configure_buffering(opts)
+      start_thread
+    end
+
+    # Close the appender and wait for the internal writer thread to finish.
+    #
+    def close( *args )
+      super
+      Thread.pass until @dispatcher.status == 'sleep' or !@dispatcher.status
+      @dispatcher.wakeup if @dispatcher.status
+      @dispatcher.join(60)
+      self
+    end
+
+    # Send all buffered log events to the CouchDB instance. If the messages
+    # cannot be saved the appender will be disabled, and all messages in the
+    # buffer and all subsequent messages will be lost.
+    #
+    def flush
+      return self if buffer.empty?
+      @dispatch = true
+      @dispatcher.wakeup if @dispatcher.status == 'sleep'
+      self
+    end
+
+
+    private
+
+    # Write the given _event_ to the CouchDB instance. The message is
+    # formatted into a Ruby Hash instance suitable for conversion into a
+    # CouchDB JSON document.
+    #
+    def write( event )
+      h =
+        if event.instance_of?(::Logging::LogEvent)
+          layout.format event
+        else
+          {
+            :timestamp => ::Logging::Layouts::CouchDB.timestamp,
+            :logger    => 'Unknown',
+            :level     => 0,
+            :message   => event.to_s
+          }
+        end
+      h[:app_id] = @app_id
+
+      buffer << h
+      flush if buffer.length >= auto_flushing || immediate?(event)
+
+      self
+    end
+
+    # This method performs the actual HTTP POST to the CouchDB instance. All
+    # messages in the buffer are posted using the CouchDB bulk storage
+    # semantics.
+    #
+    def post_events
+      return if @dispatch_buffer.empty?
+
+      payload = {:docs => @dispatch_buffer}.to_json
+      RestClient.post(@db_uri, payload)
+      #JSON.parse(RestClient.post(@db_uri, payload))
+      self
+    rescue StandardError => err
+      self.level = :off
+      ::Logging.log_internal {"appender #{name.inspect} has been disabled"}
+      ::Logging.log_internal(-2) {err}
+      raise
+    ensure
+      @dispatch_buffer.clear
+    end
+
+    # Creats the dispatcher thread that reads from the buffer and writes log
+    # events to the CouchDB instance.
+    #
+    def start_thread
+      @dispatch_buffer = []
+      @dispatch = false
+
+      @dispatcher = Thread.new(self) {
+        loop {
+          sleep(60) unless @dispatch or closed?
+
+          if closed?
+            sync {
+              @dispatch = false
+              @dispatch_buffer.concat @buffer
+              @buffer.clear
+            }
+            post_events
+            break
+
+          else
+            sync {
+              @dispatch = false
+              @buffer, @dispatch_buffer = @dispatch_buffer, @buffer
+            }
+            post_events
+          end
+        }  # loop
+      }  # Thread.new
+    end
+
+  end  # class CouchDB
+end  # module Logging::Appenders
+
+# EOF

data/lib/logging/couch_db_layout.rb

@@ -0,0 +1,140 @@
+
+module Logging::Layouts
+
+  # Accessor / Factory for the CouchDB layout.
+  #
+  def couch_db( *args )
+    return ::Logging::Layouts::CouchDB if args.empty?
+    ::Logging::Layouts::CouchDB.new(*args)
+  end
+
+  # This layout will produce log output in JSON format. This is different
+  # than the standard "Parseable" layout in that the JSON is tailored
+  # specifically for the CouchDB appender. Differences are mainly in the
+  # timestamp format and available options. The LogEvent data is only
+  # formatted into JSON and not inspect format or the standard to_s format.
+  #
+  # The information about the log event can be configured when the layout is
+  # created. Any or all of the following labels can be set as the _items_ to
+  # log:
+  #
+  #   'logger'     Used to output the name of the logger that generated the
+  #                log event.
+  #   'timestamp'  Used to output the timestamp of the log event.
+  #   'level'      Used to output the level of the log event.
+  #   'message'    Used to output the application supplied message
+  #                associated with the log event in JSON format.
+  #   'file'       Used to output the file name where the logging request
+  #                was issued.
+  #   'line'       Used to output the line number where the logging request
+  #                was issued.
+  #   'method'     Used to output the method name where the logging request
+  #                was issued.
+  #   'pid'        Used to output the process ID of the currently running
+  #                program.
+  #   'thread_id'  Used to output the object ID of the thread that generated
+  #                the log event.
+  #   'thread'     Used to output the name of the thread that generated the
+  #                log event. Name can be specified using Thread.current[:name]
+  #                notation. Output empty string if name not specified. This
+  #                option helps to create more human readable output for
+  #                multithread application logs.
+  #
+  # These items are supplied to the layout as an array of strings. The items
+  # 'file', 'line', and 'method' will only work if the Logger generating the
+  # events is configured to generate tracing information. If this is not the
+  # case these fields will always be empty.
+  #
+  class CouchDB < ::Logging::Layout
+
+    # :stopdoc:
+    # Arguments to sprintf keyed to directive letters
+    DIRECTIVE_TABLE = {
+      'logger'    => 'event.logger',
+      'timestamp' => 'CouchDB.timestamp(event.time)',
+      'level'     => 'event.level',
+      'message'   => 'format_obj(event.data)',
+      'file'      => 'event.file',
+      'line'      => 'event.line',
+      'method'    => 'event.method',
+      'pid'       => 'Process.pid',
+      'thread_id' => 'Thread.current.object_id',
+      'thread'    => 'Thread.current[:name]'
+    }
+    TIME_FMT = '%Y-%m-%dT%H:%M:%S.%%06dZ'
+
+    # call-seq:
+    #    CouchDB.create_format_method( layout )
+    #
+    # This method will create the +format+ method in the given CouchDB
+    # _layout_ based on the configured items for the layout instance.
+    #
+    def self.create_format_method( layout )
+      code = "undef :format if method_defined? :format\n"
+      code << "def format( event )\n{"
+
+      code << layout.items.map {|name|
+        "#{name.to_sym.inspect} => #{CouchDB::DIRECTIVE_TABLE[name]}"
+      }.join(',')
+      code << "\n}\nend"
+      
+      (class << layout; self end).class_eval(code, __FILE__, __LINE__)
+    end
+    # :startdoc:
+
+    # call-seq:
+    #    CouchDB.timestamp
+    #
+    # Returns a timestamp that can be sorted in CouchDB.
+    #
+    def self.timestamp( time = nil )
+      utc = (time || Time.now).utc
+      utc.strftime(TIME_FMT) % utc.usec
+    end
+
+    # call-seq:
+    #    CouchDB.new( opts )
+    #
+    # Creates a new CouchDB layout using the following options:
+    #
+    #    :items  => %w[timestamp level logger message]
+    #
+    def initialize( opts = {} )
+      super
+      self.items = opts.getopt(:items, %w[timestamp level logger message])
+    end
+
+    attr_reader :items
+
+    # call-seq:
+    #    layout.items = %w[timestamp level logger message]
+    #
+    # Set the log event items that will be formatted by this layout. These
+    # items, and only these items, will appear in the log output.
+    #
+    def items=( ary )
+      @items = Array(ary).map {|name| name.to_s.downcase}
+      valid = DIRECTIVE_TABLE.keys
+      @items.each do |name|
+        raise ArgumentError, "unknown item - #{name.inspect}" unless valid.include? name
+      end
+      self.class.create_format_method(self)
+    end
+
+    # Take the given _value_ and convert it into a format suitable for use
+    # in a JSON object structure.
+    #
+    def format_obj( value )
+      case value
+      when nil, Numeric, String, Array, Hash; value
+      when Exception
+        ary = ["<#{obj.class.name}> #{obj.message}"]
+        ary.concat(obj.backtrace) unless obj.backtrace.nil?
+        ary
+      else super(value) end
+    end
+
+  end  # class CouchDB
+end  # module Logging::Layouts
+
+# EOF

data/lib/logging/plugins/couch_db.rb

@@ -0,0 +1,15 @@
+
+root = File.expand_path(
+  File.join(File.dirname(__FILE__), '..'))
+
+module Logging::Plugins
+  module CouchDB
+    def initialize_couch_db
+    end
+  end  # module CouchDB
+end  # module Logging::Plugins
+
+require File.join(root, 'couch_db_layout')
+require File.join(root, 'couch_db_appender')
+
+# EOF

data/spec/couch_db_spec.rb

@@ -0,0 +1,26 @@
+
+require File.join(File.dirname(__FILE__), %w[spec_helper])
+
+describe Logging::Appenders::CouchDB do
+
+  it "converts a string from camel-case to underscore" do
+    LittlePlugger.underscore('FooBarBaz').should == 'foo_bar_baz'
+    LittlePlugger.underscore('CouchDB').should == 'couch_db'
+    LittlePlugger.underscore('FOOBar').should == 'foo_bar'
+    LittlePlugger.underscore('Foo::Bar::BazBuz').should == 'foo/bar/baz_buz'
+  end
+
+  it "generates a default plugin path" do
+    LittlePlugger.default_plugin_path(LittlePlugger).should == 'little_plugger/plugins'
+    LittlePlugger.default_plugin_path(Spec::Runner).should == 'spec/runner/plugins'
+  end
+
+  it "generates a default plugin module" do
+    LittlePlugger.default_plugin_module('little_plugger').should == LittlePlugger
+    lambda {LittlePlugger.default_plugin_module('little_plugger/plugins')}.
+        should raise_error(NameError, 'uninitialized constant LittlePlugger::Plugins')
+    LittlePlugger.default_plugin_module('spec/runner').should == Spec::Runner
+  end
+end
+
+# EOF

data/spec/spec_helper.rb

@@ -0,0 +1,23 @@
+
+require 'rubygems'
+require 'logging'
+
+Logging.plugin.clear
+Logging.plugin << :none
+Logging.init
+
+require File.expand_path(
+    File.join(File.dirname(__FILE__), %w[.. lib logging plugins couch_db]))
+
+Spec::Runner.configure do |config|
+  # == Mock Framework
+  #
+  # RSpec uses it's own mocking framework by default. If you prefer to
+  # use mocha, flexmock or RR, uncomment the appropriate line:
+  #
+  # config.mock_with :mocha
+  # config.mock_with :flexmock
+  # config.mock_with :rr
+end
+
+# EOF

data/tasks/ann.rake

@@ -0,0 +1,80 @@
+
+begin
+  require 'bones/smtp_tls'
+rescue LoadError
+  require 'net/smtp'
+end
+require 'time'
+
+namespace :ann do
+
+  # A prerequisites task that all other tasks depend upon
+  task :prereqs
+
+  file PROJ.ann.file do
+    ann = PROJ.ann
+    puts "Generating #{ann.file}"
+    File.open(ann.file,'w') do |fd|
+      fd.puts("#{PROJ.name} version #{PROJ.version}")
+      fd.puts("    by #{Array(PROJ.authors).first}") if PROJ.authors
+      fd.puts("    #{PROJ.url}") if PROJ.url.valid?
+      fd.puts("    (the \"#{PROJ.release_name}\" release)") if PROJ.release_name
+      fd.puts
+      fd.puts("== DESCRIPTION")
+      fd.puts
+      fd.puts(PROJ.description)
+      fd.puts
+      fd.puts(PROJ.changes.sub(%r/^.*$/, '== CHANGES'))
+      fd.puts
+      ann.paragraphs.each do |p|
+        fd.puts "== #{p.upcase}"
+        fd.puts
+        fd.puts paragraphs_of(PROJ.readme_file, p).join("\n\n")
+        fd.puts
+      end
+      fd.puts ann.text if ann.text
+    end
+  end
+
+  desc "Create an announcement file"
+  task :announcement => ['ann:prereqs', PROJ.ann.file]
+
+  desc "Send an email announcement"
+  task :email => ['ann:prereqs', PROJ.ann.file] do
+    ann = PROJ.ann
+    from = ann.email[:from] || Array(PROJ.authors).first || PROJ.email
+    to   = Array(ann.email[:to])
+
+    ### build a mail header for RFC 822
+    rfc822msg =  "From: #{from}\n"
+    rfc822msg << "To: #{to.join(',')}\n"
+    rfc822msg << "Subject: [ANN] #{PROJ.name} #{PROJ.version}"
+    rfc822msg << " (#{PROJ.release_name})" if PROJ.release_name
+    rfc822msg << "\n"
+    rfc822msg << "Date: #{Time.new.rfc822}\n"
+    rfc822msg << "Message-Id: "
+    rfc822msg << "<#{"%.8f" % Time.now.to_f}@#{ann.email[:domain]}>\n\n"
+    rfc822msg << File.read(ann.file)
+
+    params = [:server, :port, :domain, :acct, :passwd, :authtype].map do |key|
+      ann.email[key]
+    end
+
+    params[3] = PROJ.email if params[3].nil?
+
+    if params[4].nil?
+      STDOUT.write "Please enter your e-mail password (#{params[3]}): "
+      params[4] = STDIN.gets.chomp
+    end
+
+    ### send email
+    Net::SMTP.start(*params) {|smtp| smtp.sendmail(rfc822msg, from, to)}
+  end
+end  # namespace :ann
+
+desc 'Alias to ann:announcement'
+task :ann => 'ann:announcement'
+
+CLOBBER << PROJ.ann.file
+
+# EOF

data/tasks/bones.rake

@@ -0,0 +1,20 @@
+
+if HAVE_BONES
+
+namespace :bones do
+
+  desc 'Show the PROJ open struct'
+  task :debug do |t|
+    atr = if t.application.top_level_tasks.length == 2
+      t.application.top_level_tasks.pop
+    end
+
+    if atr then Bones::Debug.show_attr(PROJ, atr)
+    else Bones::Debug.show PROJ end
+  end
+
+end  # namespace :bones
+
+end  # HAVE_BONES
+
+# EOF