logging4hackers 0.1

data/CHANGELOG

@@ -0,0 +1,7 @@
+= 0.0.1
+
+  * Initial release.
+  * IO modules: Raw, Null, File, Buffer, Pipe and AMQP.
+  * Formatters: Default, JustMessage and Colourful.
+  * Data syntax highlighting by converting data into JSON using CodeRay.
+  * CLI utility for simple log inspection.

data/Gemfile

@@ -0,0 +1,18 @@
+# encoding: utf-8
+
+source 'https://rubygems.org'
+
+gem 'coderay'
+
+group(:test) do
+  gem 'rspec'
+end
+
+group(:documentation) do
+  gem 'yard'
+  gem 'redcarpet'
+end
+
+group(:release) do
+  gem 'changelog'
+end

data/LICENCE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2013 James C Russell aka botanicus
+
+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/README.md

@@ -0,0 +1,146 @@
+# About [![Travis CI](https://travis-ci.org/botanicus/logging4hackers.png)](https://travis-ci.org/botanicus/logging4hackers)
+
+In the Ruby community it's very popular to **just append** to a file in `log/` directory in the current app. In many frameworks the developer **can't even change** the file. Damn it guys, **we can do better**!
+
+## Why Should I Care?
+
+* You might want to have the log files in `/var/log` for simpler **log rotation**.
+* You might not want to use files for logging at all. Not on the app server anyway. Especially considering that for **security reasons** it's better to send logs to a different server.
+* You might want to **aggregate logs** from multiple servers.
+* You might want to **filter logs** based on given pattern. Give me all error messages from all applications `logs.#.error`, all log items for database layer of testapp `logs.testapp.db.*`, all error messages for testapp `logs.testapp.*.error` etc.
+* Isn't ssh & tail -f really, really, I mean **really** lame? With AMQP, just [subscribe to any pattern](#inspecting-remote-server) on any server you want from comfort of your own dev machine. Rock'n'roll!
+
+## Readable Logs (If You Want)
+
+Besides, logs should be easy to read for the developers. That's why logging4hackers provides [colourful formatter](http://rubydoc.info/github/botanicus/logging4hackers/master/Logging/Formatters/Colourful) which uses colours instead of displaying log level as text and [Logger#inspect](http://rubydoc.info/github/botanicus/logging4hackers/master/Logging/Logger#inspect-instance_method) for showing objects as syntax-highlighted JSON.
+
+<img src="https://raw.github.com/botanicus/logging4hackers/master/logger.png" />
+
+```ruby
+require 'logging'
+require 'logging/code'
+
+logger = Logging::Logger.new do |logger|
+  logger.io = Logging::IO::Raw.new('testapp.logs.db')
+  logger.formatter = Logging::Formatters::Colourful.new
+end
+
+logger.info("Starting the app.")
+logger.inspect({method: 'GET', path: '/ideas.json', response: '200'})
+logger.warn("Now I'm a tad bored ...")
+logger.error("OK, gotta sleep now.")
+```
+
+*Note: Actually the screenshot shows how would you inspect messages published into RabbitMQ, whereas in the code I'm using the `IO::Raw` which only prints to console. [Example with AMQP](#logging-into-rabbitmq-local-or-remote) is longer.*
+
+## About [@botanicus](https://twitter.com/botanicus) ([blog](http://blog.101ideas.cz))
+
+![botanicus](http://www.gravatar.com/avatar/74c419a50563fa9e5044820c2697ffd6)
+I'm a **launch-addict**, creating stuff that matters is my biggest passion. I **dropped out of high school** and learnt programming before I'd end up on a street. In just a few months I moved from <a title="Small town in mountains of Czech Republic">middle of nowhere</a> to **London** where I worked as a freelancer for companies like **VMware** on the **RabbitMQ team** for which I, <a title="Michael wasn't employed by VMware, he was hacking on AMQP in his free time. Kudos!">alongside</a> great hacker [michaelklishin](https://github.com/michaelklishin), rewrote the [AMQP gem](https://github.com/ruby-amqp/amqp).
+
+I **contributed** to many famous OSS projects including **RubyGems**, **rSpec** and back in the g'd old days also to **Merb**. When EY decided to <a title="The so-called merge ... bunch of crap!">abandon Merb</a> I wrote my own web framework, [Rango](http://www.rubyinside.com/rango-ruby-web-app-framework-2858.html) (now <a title="These days my apps are API servers with heavy JS frontend.">discontinued</a>), the only framework in Ruby with [template inheritance](https://github.com/botanicus/template-inheritance).
+
+My other hobbies include **travelling**, learning **languages** (你好!) and **personal development**. My [3 + 2 rule](http://lifehacker.com/5853732/take-a-more-realistic-approach-to-your-to+do-list-with-the-3-%252B-2-rule) was featured on LifeHacker.
+
+My only goal for this year is to **launch a successful start-up**. Could [MatcherApp](http://www.matcherapp.com) be it?
+
+# Use-Cases
+
+### Logging Into RabbitMQ (Local or Remote)
+
+*TODO: Disconnect the AMQP, stop EM & terminate.*
+
+* You can connect to RabbitMQ on **localhost** or **remote server**.
+* So far it requires **some setup**. In the future I might **provide helpers** for this.
+* It's the **most powerful** setup. You can **filter patterns**, you can **discard messages** just by **not subscribing** to those you're not interested in, you can **consume** given message **multiple times**, so you can for instance **duplicate logs** on two servers etc.
+* Instead writing directly to AMQP you can **write to a named pipe** and have a **daemon** which **reroutes messages** to RabbitMQ as described [below](#clientserver-on-localhost-using-named-pipe).
+
+```ruby
+require 'logging'
+require 'logging/code'
+require 'eventmachine'
+
+EM.run do
+  require 'amq/client'
+
+  AMQ::Client.connect(adapter:  'eventmachine') do |connection|
+    channel = AMQ::Client::Channel.new(connection, 1)
+
+    channel.open
+
+    exchange = AMQ::Client::Exchange.new(connection, channel, 'amq.topic', :topic)
+
+    logger = Logging::Logger.new do |logger|
+      logger.io = Logging::IO::AMQP.new('testapp.logs.db', exchange)
+      logger.formatter = Logging::Formatters::Colourful.new
+    end
+
+    logger.info('Starting the app.')
+    logger.inspect({method: 'GET', path: '/ideas.json', response: '200'})
+    logger.error('Whops, no app defined, terminating.')
+  end
+end
+```
+
+### Client/Server on Localhost using Named Pipe
+
+* You **might not** want to **run EventMachine**.
+* Setting up the Pipe logger on the client side requires **much less setup**, hence **much less stuff can wrong**.
+* It's easy to write a daemon to **publish those messages** from the pipe **into RabbitMQ**. In the future I might provide one.
+
+```bash
+# Create a named pipe.
+mkfifo /tmp/loggingd.pipe
+
+# Listen for messages coming to /tmp/loggingd.pipe.
+tail -f /tmp/loggingd.pipe
+```
+
+```ruby
+logger = Logging::Logger.new do |logger|
+  logger.io = Logging::IO::Pipe.new('testapp.logs.db', '/tmp/loggingd.pipe')
+  logger.formatter = Logging::Formatters::Colourful.new
+end
+```
+
+# Inspecting Remote Server
+
+Often you want to figure out **what's going on on server**. This is how you do it:
+
+```bash
+./bin/logs_listen.rb 'logs.myapp.#' amqp://user:pass@remote_server/vhost
+```
+
+It creates temporary queue which it binds to the `amq.topic` exchange which exists by default in any RabbitMQ installation. Then it binds the temporary queue to this exchange with pattern we provide (in this case it's `logs.myapp.#`). This makes sure all the subscribers gets all the messages they're interested in.
+
+# Logging Best Practices
+
+### Don't Use Just One Logger Per App
+
+In Ruby community people **often don't use loggers** at all. If they do, they work with **only one instance**. One logger instance for database, web server, application code and metrics. That **doesn't scale**.
+
+If you use one logger instance per each module you can very easily **filter** based on **specific pattern**.
+
+```ruby
+class DB
+  def self.logger
+    @logger ||= Logging::Logger.new do |logger|
+      logger.io = Logging::IO::Pipe.new('testapp.logs.db', '/tmp/loggingd.pipe')
+      logger.formatter = Logging::Formatters::Colourful.new
+    end
+  end
+end
+
+class App
+  def self.logger
+  @logger ||= Logging::Logger.new do |logger|
+    logger.io = Logging::IO::Pipe.new('testapp.app.db', '/tmp/loggingd.pipe')
+    logger.formatter = Logging::Formatters::Colourful.new
+  end
+end
+```
+
+# Links
+
+* [YARD API Documentation](http://rubydoc.info/github/botanicus/logging4hackers/master)
+* [Semantic Versioning](http://semver.org)

data/bin/logs_listen.rb

@@ -0,0 +1,65 @@
+#!/usr/bin/env ruby
+# encoding: utf-8
+
+require 'eventmachine'
+require 'amq/client'
+
+# Usage:
+#   ./bin/logs_listen.rb [routing key] [AMQP URI] [log dir]
+#
+# Routing Key Examples:
+#   myapp.logs.*.error
+#   myapp.logs.db.*
+#   myapp.logs.#
+#
+# AMQP URI:
+#   For instance amqp://user:pass@host/vhost
+#   See http://www.rabbitmq.com/uri-spec.html
+#
+# Log Directory (TBD):
+#   If the log directory is specified, messages will be saved into files.
+#   For example when specifying /var/log as my log directory, then when
+#   I'll get message with routing key myapp.logs.db.error, it will be
+#   written into /var/log/myapp.db.log.
+
+# ARGV parsing.
+routing_key   = ARGV.first || '#.logs.#'
+log_directory = ARGV[2]
+amqp_opts = if ARGV[1]
+  puts "~ AMQP: #{AMQ::Client::Settings.parse_amqp_url(ARGV[1])}"
+  AMQ::Client::Settings.parse_amqp_url(ARGV[1]).merge(adapter: 'eventmachine')
+else
+  {adapter: 'eventmachine'}
+end
+
+EM.run do
+  AMQ::Client.connect(amqp_opts) do |connection|
+
+    channel = AMQ::Client::Channel.new(connection, 1)
+    channel.open
+
+    queue = AMQ::Client::Queue.new(connection, channel)
+
+    queue.declare(false, false, false, true) do
+      puts "~ Creating autodeletable queue."
+    end
+
+    exchange = AMQ::Client::Exchange.new(connection, channel, 'amq.topic', :topic)
+
+    queue.bind(exchange.name, routing_key) do |frame|
+      puts "~ Binding it to the amq.topic exchange with routing key #{routing_key}."
+    end
+
+    queue.consume(true) do |consume_ok|
+      puts "~ Listening for messages ..."
+
+      queue.on_delivery do |basic_deliver, header, payload|
+        if log_directory
+          # basic_deliver.routing_key
+        else
+          puts payload
+        end
+      end
+    end
+  end
+end

data/lib/logging.rb

@@ -0,0 +1,7 @@
+# encoding: utf-8
+
+# This is the full package, including syntax highlighting
+# for data using CodeRay and serialisation into JSON format.
+
+require_relative 'logging/logger'
+require_relative 'logging/code'

data/lib/logging/code.rb

@@ -0,0 +1,79 @@
+# encoding: utf-8
+
+require 'json'
+require 'coderay'
+
+module Logging
+  class Logger
+    # Inspect Ruby objects with syntax highlighting in JSON format.
+    #
+    # @overload inspect(*objects)
+    #   @param objects [Array<#to_json>] List of objects for inspection.
+    #
+    # @overload inspect(label, *objects)
+    #   @param label [String, Symbol] Label. For instance "Request time".
+    #   @param objects [Array<#to_json>] List of objects for inspection.
+    #
+    # @example
+    #   # Single object, no label.
+    #   logger.inspect(path: "/", time: 0.0001)
+    #
+    #   # Single object with String label.
+    #   logger.inspect("Request data", path: "/", time: 0.0001)
+    #
+    #   # Single object with Symbol label.
+    #   logger.inspect(:request, {path: "/", time: 0.0001})
+    #
+    #   # Multiple objects, no label.
+    #   logger.inspect({path: "/", time: 0.001}, {path: "/test"})
+    #
+    #   # Multiple objects with label.
+    #   logger.inspect("Requests", {path: "/", time: 0.001}, {path: "/test"})
+    #
+    # @note
+    #   This method is defined in {file:lib/logging/code.rb logging/code.rb}
+    #   and requires {http://coderay.rubychan.de coderay}.
+    #
+    # @api public
+    def inspect(*objects)
+      label = ((objects.first.is_a?(String) ||
+              objects.first.is_a?(Symbol)) &&
+              objects.length > 1) ? objects.shift : nil
+
+      code = objects.map do |object|
+        begin
+          json = JSON.generate(object, object_nl: ' ', array_nl: ' ', space: ' ')
+          CodeRay.scan(json, :json).terminal
+        rescue
+          CodeRay.scan(object.inspect, :ruby).terminal
+        end
+      end.join("\n")
+
+      self.log(:inspect, label ? "#{label}: #{code}" : code)
+    end
+
+    # Measure how long does it take to execute provided block.
+    #
+    # @param label [#%] Formatting string.
+    # @param block [Proc] The block of which we'll measure the execution time.
+    #
+    # @example
+    #   logger.measure_time("Request took %s") do
+    #     sleep 0.1
+    #   end
+    #
+    # @note
+    #   This method is defined in {file:lib/logging/code.rb logging/code.rb}
+    #   and requires {http://coderay.rubychan.de coderay}.
+    #
+    # @api public
+    def measure_time(label, &block)
+      before = Time.now.to_f; block.call
+      self.info(label % (Time.now.to_f - before))
+    end
+  end
+end
+
+require_relative 'formatters'
+
+Logging::Formatters::Colourful::LEVELS[:inspect] = "\033[36m"

data/lib/logging/formatters.rb

@@ -0,0 +1,168 @@
+# encoding: utf-8
+
+module Logging
+  # Formatters are used for formatting the log message.
+  # They can access level, label and the message.
+  # Their output is always string.
+  module Formatters
+
+    # Default formatter. No colours, just log level, time stamp,
+    # label and the actual log message.
+    class Default
+      # Format strings.
+      #
+      # The `single` key is used by {#format_single_message},
+      # whereas `header` is used by {#format_multiple_messages}.
+      FORMAT_STRINGS = {
+        single: '%-5s %s -- %s',
+        header: '%-5s %s'
+      }
+
+      # Format single log message.
+      #
+      # @param level [Symbol] Log level.
+      # @param label [String] Identifier, for instance logs.app.db.
+      # @param message [#to_s] The actual log message.
+      #
+      # @return [String] The log message.
+      #
+      # @see `FORMAT_STRINGS[:single]`
+      #
+      # @api plugin.
+      #
+      # @todo
+      #   There's no documentation for the block yet, it's being
+      #   used only for extending functionality from the subclasses.
+      #   It should be probably refactored, otherwise it will get
+      #   proper documentation.
+      def format_single_message(level, label, message, &block)
+        args = [label, timestamp, message]
+        args = block.call(*args) if block
+        sprintf(self.class::FORMAT_STRINGS[:single], *args)
+      end
+
+      # Format multiple log messages.
+      #
+      # @param level [Symbol] Log level.
+      # @param label [String] Identifier, for instance logs.app.db.
+      # @param messages [Array<#to_s>] The actual messages.
+      #
+      # @return [String] The log message.
+      #
+      # @see `FORMAT_STRINGS[:header]`
+      #
+      # @api plugin.
+      #
+      # @todo
+      #   There's no documentation for the block yet, it's being
+      #   used only for extending functionality from the subclasses.
+      #   It should be probably refactored, otherwise it will get
+      #   proper documentation.
+      def format_multiple_messages(level, label, messages, &block)
+        args = [level.to_s.upcase, timestamp]
+        args = block.call(*args) if block
+
+        header = sprintf(self.class::FORMAT_STRINGS[:header], *args)
+        messages.unshift(nil)
+        header + messages.join("\n  ")
+      end
+
+      protected
+
+      # @api protected
+      def timestamp
+        Time.now.strftime('%H:%M:%S')
+      end
+    end
+
+    # This is useful for logging on console.
+    class JustMessage < Default
+      # The `single` key is used by {#format_single_message},
+      # whereas `header` is used by {#format_multiple_messages}.
+      FORMAT_STRINGS = {
+        single: '~ %s',
+        header: '~ %s'
+      }
+
+      # Format single log message.
+      #
+      # @param level [Symbol] Log level.
+      # @param label [String] Identifier, for instance logs.app.db.
+      # @param message [#to_s] The actual log message.
+      #
+      # @return [String] The log message.
+      #
+      # @see `FORMAT_STRINGS[:single]`
+      #
+      # @api plugin.
+      def format_single_message(level, label, message)
+        super(level, label, message) do |*args|
+          [args.last]
+        end
+      end
+
+      # Format multiple log messages.
+      #
+      # @param level [Symbol] Log level.
+      # @param label [String] Identifier, for instance logs.app.db.
+      # @param messages [Array<#to_s>] The actual messages.
+      #
+      # @return [String] The log message.
+      #
+      # @see `FORMAT_STRINGS[:header]`
+      #
+      # @api plugin.
+      def format_multiple_messages(level, label, messages)
+        super(level, label, messages) do |*args|
+          [args.last]
+        end
+      end
+    end
+
+    class Colourful < Default
+      # Colours for each log level.
+      LEVELS ||= {error: "\033[31m", warn: "\033[33m", info: "\033[36m"}
+
+      # The `single` key is used by {#format_single_message},
+      # whereas `header` is used by {#format_multiple_messages}.
+      FORMAT_STRINGS = {
+        single: "%s%-5s \033[37m%s\033[0m -- %s",
+        header: "%s%-5s \033[37m%s\033[0m"
+      }
+
+      # Format single log message.
+      #
+      # @param level [Symbol] Log level.
+      # @param label [String] Identifier, for instance logs.app.db.
+      # @param message [#to_s] The actual log message.
+      #
+      # @return [String] The log message.
+      #
+      # @see `FORMAT_STRINGS[:single]`
+      #
+      # @api plugin.
+      def format_single_message(level, label, message)
+        super(level, label, message) do |*args|
+          args.unshift(LEVELS[level])
+        end
+      end
+
+      # Format multiple log messages.
+      #
+      # @param level [Symbol] Log level.
+      # @param label [String] Identifier, for instance logs.app.db.
+      # @param messages [Array<#to_s>] The actual messages.
+      #
+      # @return [String] The log message.
+      #
+      # @see `FORMAT_STRINGS[:header]`
+      #
+      # @api plugin.
+      def format_multiple_messages(level, label, messages)
+        super(level, label, messages) do |*args|
+          args.unshift(LEVELS[level])
+        end
+      end
+    end
+  end
+end

data/lib/logging/io.rb

@@ -0,0 +1,131 @@
+# encoding: utf-8
+
+require_relative 'formatters'
+
+module Logging
+  # IO objects define how to write the log message.
+  # It can be on console, to a socket, to RabbitMQ,
+  # named pipe ... you name it!
+  module IO
+
+    # @abstract
+    #   Subclass and override {#write}.
+    class Base
+      attr_reader :label
+
+      # @param label [String] Label. For instance `logs.app.db`.
+      def initialize(label)
+        @label = label
+      end
+
+      def write(message)
+        raise NotImplementedError.new
+      end
+    end
+
+    # Write on console.
+    class Raw < Base
+      def write(message)
+        puts message
+      end
+
+      def write_single_message(formatter, level, message)
+        self.write(formatter.format_single_message(level, self.label, message))
+      end
+
+      def write_multiple_messages(formatter, level, messages)
+        self.write(formatter.format_multiple_messages(level, self.label, messages))
+      end
+    end
+
+    # Discard everything.
+    class Null < Raw
+      def write(*)
+      end
+    end
+
+    # Write to a file.
+    class File < Raw
+      attr_reader :path
+      def initialize(label, path)
+        @label, @path = label, path
+      end
+
+      def file
+        @file ||= File.open(self.path, 'a')
+      end
+
+      def write(message)
+        file.puts(message)
+      end
+    end
+
+    # Write to a buffer.
+    class Buffer < Raw
+      def buffer
+        @buffer ||= Array.new
+      end
+
+      def log(level, *messages)
+        self.buffer << [level, messages]
+      end
+
+      def replay(io)
+        self.buffer.each do |level, *messages|
+          self.io.log(level, *messages)
+        end
+      end
+    end
+
+    # Write to a named pipe.
+    class Pipe < Raw
+      attr_reader :path
+      def initialize(label, path)
+        @label, @path = label, path
+      end
+
+      def pipe
+        # The w+ means we don't block.
+        @pipe ||= open(self.path, 'w+')
+      end
+
+      def write(message)
+        self.pipe.puts(message)
+        self.pipe.flush
+      end
+    end
+
+    # Send message to an AMQP broker.
+    class AMQP < Base
+      def self.bootstrap(config)
+        require 'amq/client'
+
+        AMQ::Client.connect(config) do |connection|
+          channel = AMQ::Client::Channel.new(connection, 1)
+
+          channel.open
+
+          exchange = AMQ::Client::Exchange.new(connection, channel, 'amq.topic', :topic)
+
+          self.new(exchange)
+        end
+      end
+
+      def initialize(label, exchange)
+        @label, @exchange = label, exchange
+      end
+
+      def write_single_message(formatter, level, message)
+        self.write(formatter.format_single_message(level, self.label, message), "#{self.label}.#{level}")
+      end
+
+      def write_multiple_messages(formatter, level, messages)
+        self.write(formatter.format_multiple_messages(level, self.label, messages), "#{self.label}.#{level}")
+      end
+
+      def write(message, routing_key)
+        @exchange.publish(message, routing_key)
+      end
+    end
+  end
+end

data/lib/logging/logger.rb

@@ -0,0 +1,104 @@
+# encoding: utf-8
+
+require_relative 'io'
+require_relative 'formatters'
+
+module Logging
+  # Main class. Instantiate it to start logging.
+  # In reality all this class does is to provide
+  # convenience proxy to {file:lib/logging/io.rb io objects}
+  # and {file:lib/logging/formatters.rb formatters}.
+  class Logger
+    # Log levels. At the moment adding new log levels
+    # isn't supported. This might or might not change.
+    LEVELS ||= [:error, :warn, :info]
+
+    # Label is required only when you use the default
+    # {file:lib/logging/io.rb io object}.
+    attr_reader :label
+
+    # Create a new logger.
+    #
+    # @param label [String, nil] Label. For instance `logs.myapp.db`.
+    # @param block [Proc] Block with the newly created instance.
+    #
+    # @yield [logger] The logger instance which just has been created.
+    #
+    # @example
+    #   # Create logger with default values, specifying
+    #   # only the label (mandatory when not specifying io).
+    #   logger = Logging::Logger.new('logs.my_app.db')
+    #
+    #   # Create a logger specifying a custom formatter and io.
+    #   logger = Logging::Logger.new('logs.my_app.db') do |logger|
+    #     logger.io = Logging::IO::Pipe.new(logger.label, '/var/mypipe')
+    #     logger.formatter = Logging::Formatters::Colourful.new
+    #   end
+    def initialize(label = nil, &block)
+      @label = label
+      block.call(self) if block
+    end
+
+    # The cached io instance. If there's none, one will be created.
+    #
+    # @raise [RuntimeError] If the label isn't specified (when creating new deafult io).
+    def io
+      @io ||= begin
+        if self.label
+          IO::Raw.new(self.label)
+        else
+          raise "You have to provide label in Logger.new if you want to use the default io object!"
+        end
+      end
+    end
+
+    attr_writer :io
+
+    # The cached formatter instance. If there's none, one will be created.
+    def formatter
+      @formatter ||= Formatters::Default.new
+    end
+
+    attr_writer :formatter
+
+    # @!method error(*messages)
+    #   Log an error message.
+    #   @param messages [Array<#to_s>] Messages to be logged.
+    #   @api public
+    #
+    # @!method warn(*messages)
+    #   Log a warning message.
+    #   @param messages [Array<#to_s>] Messages to be logged.
+    #   @api public
+    #
+    # @!method info(*messages)
+    #   Log an info message.
+    #   @param messages [Array<#to_s>] Messages to be logged.
+    #   @api public
+    LEVELS.each do |level|
+      define_method(level) do |*messages|
+        log(level, *messages)
+      end
+    end
+
+    # Underlaying function for logging any kind of message.
+    # The actual functionality is delegated to {#io}.
+    #
+    # @param level [Symbol] Log level.
+    # @param messages [Array<#to_s>] Messages to be logged.
+    def log(level, *messages)
+      if messages.length == 1
+        self.io.write_single_message(self.formatter, level, messages.first)
+      else
+        self.io.write_multiple_messages(self.formatter, level, messages)
+      end
+    end
+
+    # Delegate to `self.io#write.
+    #
+    # @param message [#to_s] Message to be written on the IO object.
+    def write(message)
+      self.io.write(message)
+    end
+  end
+end

data/logging4hackers.gemspec

@@ -0,0 +1,38 @@
+#!/usr/bin/env gem build
+# encoding: utf-8
+
+Gem::Specification.new do |s|
+  s.name = 'logging4hackers'
+  s.version = '0.1'
+  s.authors = ['James C Russell aka botanicus']
+  s.homepage = 'http://github.com/botanicus/logging4hackers'
+  s.summary = 'Logging using AMQP, pipes, sockets, ZeroMQ ... you name it!'
+  s.description = 'Any idiot can append to file. How about using AMQP? Pipes? ZeroMQ? Other cool shit??? Huh???'
+  s.email = 'james@101ideas.cz'
+
+  # Files.
+  ignore_patterns = ['Gemfile.lock', /\.gem$/, /^doc\//]
+
+  s.files = begin Dir.glob('**/*').
+    select { |path| File.file?(path) }.
+    delete_if do |file|
+      ignore_patterns.any? do |pattern|
+        file.match(pattern)
+      end
+    end
+  end
+
+  s.executables = Dir['bin/*'].map(&File.method(:basename))
+  s.require_paths = ['lib']
+
+  begin
+    require 'changelog'
+  rescue LoadError
+    warn "~ Please install the changelog gem to correctly set the post install message!\n\n"
+  else
+    s.post_install_message = CHANGELOG.new.version_changes
+  end
+
+  # RubyForge.
+  s.rubyforge_project = 'logging4hackers'
+end

data/spec/logging/code_spec.rb

@@ -0,0 +1,64 @@
+# encoding: utf-8
+
+require 'spec_helper'
+
+describe Logging::Logger do
+  it "should add colour for inspect" do
+    Logging::Formatters::Colourful::LEVELS.should include(:inspect)
+  end
+
+  subject do
+    described_class.new('logs.my_app.db') do |logger|
+      logger.io = TestIO.new(logger.label)
+      logger.formatter = Logging::Formatters::JustMessage.new
+    end
+  end
+
+  def strip_escape_sequences(data)
+    data.gsub(/\e\[\d+(;\d+)?m/, '')
+  end
+
+  describe '#inspect' do
+    context 'with label' do
+      it "should use first string as the label if there's more than one argument" do
+        subject.inspect('Request data', path: '/')
+        message = strip_escape_sequences(subject.io.messages.last)
+        message.should eql('~ Request data: { "path": "/" }')
+      end
+
+      it "should use first symbol as the label if there's more than one argument" do
+        subject.inspect(:request, path: '/')
+        message = strip_escape_sequences(subject.io.messages.last)
+        message.should eql('~ request: { "path": "/" }')
+      end
+    end
+
+    context 'without label' do
+      it "should just inspect the string if it's the only argument" do
+        subject.inspect("Hello\nWorld!")
+        message = strip_escape_sequences(subject.io.messages.last)
+        message.should eql('~ "Hello\nWorld!"')
+      end
+
+      it "should inspect all arguments" do
+        subject.inspect({path: '/'}, {path: '/test'})
+
+        message  = strip_escape_sequences(subject.io.messages.last)
+        expected = ['~ ', '{ "path": "/" }', "\n", '{ "path": "/test" }']
+
+        message.should eql(expected.join)
+      end
+    end
+  end
+
+  describe '#measure_time' do
+    # TODO: This is obviously wrong, but for the time being ...
+    it "should measure how long it takes to execute its block" do
+      subject.measure_time("Request took %s") do
+        sleep 0.055
+      end
+
+      subject.io.messages.last.should start_with("~ Request took 0.05")
+    end
+  end
+end

data/spec/logging/formatters_spec.rb

@@ -0,0 +1,135 @@
+# encoding: utf-8
+
+require 'spec_helper'
+
+describe Logging::Formatters::Default do
+  describe '#format_single_message' do
+    let(:message) do
+      subject.format_single_message(:info, 'logs.test.app', "Hello World!")
+    end
+
+    it "should combine identifier with log level" do
+      pending "it's not including the log level yet" do
+        message.should match('logs.test.app.info')
+      end
+    end
+
+    it "should display timestamp" do
+      message.should match(/\d{2}:\d{2}:\d{2}/)
+    end
+
+    it "should display the actual message" do
+      message.should match("Hello World!")
+    end
+  end
+
+  describe '#format_multiple_messages' do
+    let(:message) do
+      subject.format_multiple_messages(:info, 'logs.test.app', ["Hello", "World!"])
+    end
+
+    it "should combine identifier with log level" do
+      pending "it's not including the log level yet" do
+        message.should match('logs.test.app.info')
+      end
+    end
+
+    it "should display timestamp" do
+      message.should match(/\d{2}:\d{2}:\d{2}/)
+    end
+
+    it "should display the actual message" do
+      message.should match("Hello\n  World!")
+    end
+  end
+end
+
+describe Logging::Formatters::JustMessage do
+  describe '#format_single_message' do
+    let(:message) do
+      subject.format_single_message(:info, 'logs.test.app', "Hello World!")
+    end
+
+    it "should not display the identifier" do
+      message.should_not match('logs.test.app')
+    end
+
+    it "should not display the log level" do
+      message.should_not match('info')
+    end
+
+    it "should not display timestamp" do
+      message.should_not match(/\d{2}:\d{2}:\d{2}/)
+    end
+
+    it "should display the actual message" do
+      message.should eql("~ Hello World!")
+    end
+  end
+
+  describe '#format_multiple_messages' do
+    let(:message) do
+      subject.format_multiple_messages(:info, 'logs.test.app', ["Hello", "World!"])
+    end
+
+    it "should not display the identifier" do
+      message.should_not match('logs.test.app')
+    end
+
+    it "should not display the log level" do
+      message.should_not match('info')
+    end
+
+    it "should not display timestamp" do
+      pending "This obviously doesn't work now" do
+        message.should_not match(/\d{2}:\d{2}:\d{2}/)
+      end
+    end
+
+    it "should display the actual message" do
+      message.should match("Hello\n  World!")
+    end
+  end
+end
+
+describe Logging::Formatters::Colourful do
+  describe '#format_single_message' do
+    let(:message) do
+      subject.format_single_message(:info, 'logs.test.app', "Hello World!")
+    end
+
+    it "should combine identifier with log level" do
+      pending "it's not including the log level yet" do
+        message.should match('logs.test.app.info')
+      end
+    end
+
+    it "should display timestamp" do
+      message.should match(/\d{2}:\d{2}:\d{2}/)
+    end
+
+    it "should display the actual message" do
+      message.should match("Hello World!")
+    end
+  end
+
+  describe '#format_multiple_messages' do
+    let(:message) do
+      subject.format_multiple_messages(:info, 'logs.test.app', ["Hello", "World!"])
+    end
+
+    it "should combine identifier with log level" do
+      pending "it's not including the log level yet" do
+        message.should match('logs.test.app.info')
+      end
+    end
+
+    it "should display timestamp" do
+      message.should match(/\d{2}:\d{2}:\d{2}/)
+    end
+
+    it "should display the actual message" do
+      message.should match("Hello\n  World!")
+    end
+  end
+end

data/spec/logging/io_spec.rb

@@ -0,0 +1,41 @@
+# encoding: utf-8
+
+require 'spec_helper'
+
+describe Logging::IO::Base do
+  subject { described_class.new('logs.app.tests') }
+
+  it "should have label" do
+    subject.label.should eql('logs.app.tests')
+  end
+end
+
+describe Logging::IO::Raw do
+  # TODO: Capture STDOUT and test.
+end
+
+describe Logging::IO::Null do
+  subject { described_class.new('logs.app.tests') }
+
+  it "should provide #write" do
+    expect {
+      subject.write("Hello World!")
+    }.not_to raise_error
+  end
+end
+
+describe Logging::IO::File do
+  # TODO
+end
+
+describe Logging::IO::Buffer do
+  # TODO
+end
+
+describe Logging::IO::Pipe do
+  # TODO
+end
+
+describe Logging::IO::AMQP do
+  # TODO
+end

data/spec/logging/logger_spec.rb

@@ -0,0 +1,88 @@
+# encoding: utf-8
+
+require 'spec_helper'
+
+describe Logging::Logger do
+  it "should define log levels" do
+    described_class::LEVELS.should include(:error)
+    described_class::LEVELS.should include(:warn)
+    described_class::LEVELS.should include(:info)
+  end
+
+  describe ".new" do
+    it "should create a new instance when no arguments are given" do
+      described_class.new.should be_kind_of(described_class)
+    end
+
+    it "should optionally take label" do
+      instance = described_class.new('logs.my_app.db')
+      instance.label.should eql('logs.my_app.db')
+    end
+
+    it "should create a new instance and yield the instance into a block" do
+      described_class.new { |logger| @instance = logger}
+      @instance.should be_kind_of(described_class)
+    end
+  end
+
+  context "instance methods" do
+    subject do
+      described_class.new('logs.my_app.db')
+    end
+
+    describe "#io" do
+      it "should have sensible default" do
+        subject.io.should be_kind_of(Logging::IO::Raw)
+      end
+
+      it "should fail if label isn't provided" do
+        expect { described_class.new.io }.to raise_error
+      end
+
+      it "should be writable" do
+        expect { subject.io = TestIO.new('label') }.not_to raise_error
+      end
+    end
+
+    describe "#formatter" do
+      it "should have sensible default" do
+        subject.formatter.should be_kind_of(Logging::Formatters::Default)
+      end
+
+      it "should be writable" do
+        formatter = Logging::Formatters::Colourful.new
+        expect { subject.formatter = formatter }.not_to raise_error
+      end
+    end
+
+    describe "logging methods" do
+      it "should define #info" do
+        expect { subject.info("Hello World!") }.not_to raise_error
+      end
+
+      it "should define #warn" do
+        expect { subject.warn("Hello World!") }.not_to raise_error
+      end
+
+      it "should define #error" do
+        expect { subject.error("Hello World!") }.not_to raise_error
+      end
+    end
+
+    describe "#log" do
+      it "should take log level and a single message"
+      it "should take log level and multiple messages"
+    end
+
+    describe "#write" do
+      before(:each) do
+        subject.io = TestIO.new('test')
+      end
+
+      it "should write to the io object" do
+        subject.io.write("Hello World!")
+        subject.io.messages.last.should eql("Hello World!")
+      end
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,21 @@
+# encoding: utf-8
+
+require 'logging'
+
+class TestIO < Logging::IO::Base
+  def write(message)
+    self.messages << message
+  end
+
+  def messages
+    @messages ||= Array.new
+  end
+
+  def write_single_message(formatter, level, message)
+    self.write(formatter.format_single_message(level, self.label, message))
+  end
+
+  def write_multiple_messages(formatter, level, messages)
+    self.write(formatter.format_multiple_messages(level, self.label, messages))
+  end
+end

data/tasks.todo

@@ -0,0 +1,21 @@
+Launch:
+- README.
+
+- Git tag first version (http://semver.org).
+- Push the gem to RubyGems.org
+- Announce on my blog.
+
+Next Release:
+- AMQP connection in bootstrap.
+- CLI: Save log files if log directory provided.
+- YARD & Markdown (I'm using `code` and it doesn't work) http://rubydoc.info/docs/yard/file/docs/GettingStarted.md#Configuring_YARD
+- Is @api plugin in formatters what we really want?
+- Finish specs & docs for io.
+- Gemspec: changelog.
+- Script for listening on pipe and populating RabbitMQ.
+- Integration tests. Is it really writing into pipe? Into RabbitMQ? Test it!
+
+Features for Future Versions:
+- Sockets.
+- Unix domain socket support (faster than sockets).
+- ZeroMQ support.

data/test_app.rb

@@ -0,0 +1,56 @@
+#!/usr/bin/env ruby
+# encoding: utf-8
+
+require_relative 'lib/logging'
+require_relative 'lib/logging/code'
+
+# logger = Logging::Logger.new('testapp.logs.db')
+#
+# logger.info("Hello World!")
+# logger.info("Just sayi' hi 'cause I'm gonna hang out here for a while")
+# logger.info("No one up for a chat :/ ?")
+
+=begin
+logger = Logging::Logger.new do |logger|
+  logger.io = Logging::IO::Pipe.new('testapp.logs.db', '/tmp/loggingd.pipe')
+  logger.formatter = Logging::Formatters::Colourful.new
+end
+
+logger.info("App started")
+logger.warn("I'm bored")
+=end
+
+__END__
+require 'eventmachine'
+
+EM.run do
+  require 'amq/client'
+
+  AMQ::Client.connect(adapter:  'eventmachine') do |connection|
+    channel = AMQ::Client::Channel.new(connection, 1)
+
+    channel.open
+
+    exchange = AMQ::Client::Exchange.new(connection, channel, 'amq.topic', :topic)
+
+    logger = Logging::Logger.new do |logger|
+      logger.io = Logging::IO::AMQP.new('testapp.logs.db', exchange)
+      logger.formatter = Logging::Formatters::Colourful.new
+    end
+
+    EM.add_periodic_timer(1) do
+      level = Logging::Logger::LEVELS[rand(Logging::Logger::LEVELS.length)]
+      logger.send(level, 'GET /ideas.json -- 20s')
+      logger.inspect({method: 'GET', path: '/ideas.json', response: '200'}.to_json)
+      logger.measure_time("Request took %s") do
+        sleep 0.23
+      end
+      logger.inspect({method: 'GET', path: '/ideas.json', response: '200'})
+    end
+
+    EM.add_periodic_timer(2.3) do
+      level = Logging::Logger::LEVELS[rand(Logging::Logger::LEVELS.length)]
+      logger.send(level, 'line 1', 'line 2', 'line 3')
+    end
+  end
+end

metadata

@@ -0,0 +1,73 @@
+--- !ruby/object:Gem::Specification
+name: logging4hackers
+version: !ruby/object:Gem::Version
+  version: '0.1'
+  prerelease: 
+platform: ruby
+authors:
+- James C Russell aka botanicus
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-05-06 00:00:00.000000000 Z
+dependencies: []
+description: Any idiot can append to file. How about using AMQP? Pipes? ZeroMQ? Other
+  cool shit??? Huh???
+email: james@101ideas.cz
+executables:
+- logs_listen.rb
+extensions: []
+extra_rdoc_files: []
+files:
+- bin/logs_listen.rb
+- CHANGELOG
+- Gemfile
+- lib/logging/code.rb
+- lib/logging/formatters.rb
+- lib/logging/io.rb
+- lib/logging/logger.rb
+- lib/logging.rb
+- LICENCE
+- logger.png
+- logging4hackers.gemspec
+- README.md
+- spec/logging/code_spec.rb
+- spec/logging/formatters_spec.rb
+- spec/logging/io_spec.rb
+- spec/logging/logger_spec.rb
+- spec/spec_helper.rb
+- tasks.todo
+- test_app.rb
+homepage: http://github.com/botanicus/logging4hackers
+licenses: []
+post_install_message: !binary |-
+  WxtbMzJtMC4wLjEbWzBtXSBJbml0aWFsIHJlbGVhc2UuClsbWzMybTAuMC4x
+  G1swbV0gSU8gbW9kdWxlczogUmF3LCBOdWxsLCBGaWxlLCBCdWZmZXIsIFBp
+  cGUgYW5kIEFNUVAuClsbWzMybTAuMC4xG1swbV0gRm9ybWF0dGVyczogRGVm
+  YXVsdCwgSnVzdE1lc3NhZ2UgYW5kIENvbG91cmZ1bC4KWxtbMzJtMC4wLjEb
+  WzBtXSBEYXRhIHN5bnRheCBoaWdobGlnaHRpbmcgYnkgY29udmVydGluZyBk
+  YXRhIGludG8gSlNPTiB1c2luZyBDb2RlUmF5LgpbG1szMm0wLjAuMRtbMG1d
+  IENMSSB1dGlsaXR5IGZvciBzaW1wbGUgbG9nIGluc3BlY3Rpb24uCg==
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: logging4hackers
+rubygems_version: 1.8.23
+signing_key: 
+specification_version: 3
+summary: Logging using AMQP, pipes, sockets, ZeroMQ ... you name it!
+test_files: []
+has_rdoc: