cabin 0.1.0

data/examples/sample.rb

@@ -0,0 +1,48 @@
+require "rubygems"
+require "cabin"
+require "logger"
+
+# Logging::... is something I'm implemented and experimenting with.
+@logger = Cabin::Channel.new
+
+# A logging channel can have any number of subscribers.
+# Any subscriber is simply expected to respond to '<<' and take a single
+# argument (the event)
+# Special case of stdlib Logger instances that are wrapped smartly to 
+# log JSON and call the right Logger method (Logger#info, etc).
+@logger.subscribe(Logger.new(STDOUT))
+
+# You can store arbitrary key-value pairs in the logging channel. 
+# These are emitted with every event.
+@logger[:program] = "sample program"
+
+def foo(val)
+  # A context is something that lets you modify key-value pieces in the
+  # logging channel and gives you a trivial way to undo the changes later.
+  context = @logger.context()
+  context[:foo] = val
+  context[:example] = 100
+
+  # The point of the context above is to save context so that the bar() method 
+  # and it's logging efforts can include said context.
+  timer = @logger.time("Timing bar")
+  bar()
+  timer.stop   # logs the result.
+
+  @logger.time("Another bar timer") do
+    bar()
+  end
+
+  # Clearing this context will exactly undo the changes made to the logger by
+  # this context.
+  context.clear()
+end
+
+def bar
+  @logger.info("bar bar bar!")
+  sleep(rand * 2)
+end
+
+foo("Hello")
+@logger.info("All done.")
+

data/examples/sinatra-logging.rb

@@ -0,0 +1,27 @@
+require "rubygems"
+require "sinatra"
+$: << "./lib"
+require "cabin"
+require "logger"
+
+$logger = Cabin::Channel.new
+$logger.subscribe(Cabin.new(STDOUT))
+
+def serve_it_up(arg)
+  $logger.info("Serving it up")
+  sleep 2
+  "Hello, #{arg}!"
+end
+
+get "/hello/:name" do
+  context = $logger.context
+  context[:name] = params[:name]
+  context[:verb] = "GET"
+  timer = $logger.time("serve_it_up latency")
+  result = serve_it_up(params[:name])
+  timer.stop
+
+  # Clear the context so that the next request doesn't have tainted context.
+  context.clear
+  return result
+end

data/lib/cabin.rb

@@ -0,0 +1 @@
+require "cabin/channel"

data/lib/cabin/channel.rb

@@ -0,0 +1,142 @@
+require "cabin/logger"
+require "cabin/namespace"
+require "cabin/timer"
+require "cabin/context"
+require "cabin/outputs/stdlib-logger"
+require "logger"
+
+# A wonderful channel for logging.
+#
+# You can log normal messages through here, but you should be really
+# shipping structured data. A message is just part of your data.
+# "An error occurred" - in what? when? why? how?
+#
+# Logging channels support the usual 'info' 'warn' and other logger methods
+# provided by Ruby's stdlib Logger class
+#
+# It additionally allows you to store arbitrary pieces of data in it like a
+# hash, so your call stack can do be this:
+#
+#     @logger = Cabin::Channel.new
+#     rubylog = Logger.new(STDOUT) # ruby's stlib logger
+#     @logger.subscribe(rubylog)
+#
+#     def foo(val)
+#       context = @logger.context()
+#       context[:foo] = val
+#       context[:example] = 100
+#       bar()
+#
+#       # Clear any context we just wanted bar() to know about
+#       context.clear()
+#
+#       @logger.info("Done in foo")
+#     end
+#
+#     def bar
+#       @logger.info("Fizzle")
+#     end
+#
+# The result:
+#
+#     I, [2011-10-11T01:00:57.993200 #1209]  INFO -- : {:timestamp=>"2011-10-11T01:00:57.992353-0700", :foo=>"Hello", :example=>100, :message=>"Fizzle", :level=>:info}
+#     I, [2011-10-11T01:00:57.993575 #1209]  INFO -- : {:timestamp=>"2011-10-11T01:00:57.993517-0700", :message=>"Done in foo", :level=>:info}
+#
+class Cabin::Channel
+  include Cabin::Logger
+
+  # Create a new logging channel.
+  # The default log level is 'info'
+  public
+  def initialize
+    @outputs = []
+    @data = {}
+    @level = :info
+  end # def initialize
+
+  # Subscribe a new input
+  public
+  def subscribe(output)
+    # Wrap ruby stdlib Logger if given.
+    if output.is_a?(::Logger)
+      output = Cabin::Outputs::StdlibLogger.new(output)
+    end
+    @outputs << output
+    # TODO(sissel): Return a method or object that allows you to easily
+    # unsubscribe?
+  end # def subscribe
+ 
+  # Set some contextual map value
+  public
+  def []=(key, value)
+    @data[key] = value
+  end # def []= 
+
+  # Get a context value by name.
+  public
+  def [](key)
+    @data[key]
+  end # def []
+
+  # Remove a context value by name.
+  public
+  def remove(key)
+    @data.delete(key)
+  end # def remove
+
+  # Publish data to all outputs. The data is expected to be a hash or a string. 
+  #
+  # A new hash is generated based on the data given. If data is a string, then
+  # it will be added to the new event hash with key :message.
+  #
+  # A special key :timestamp is set at the time of this method call. The value
+  # is a string ISO8601 timestamp with microsecond precision.
+  public
+  def publish(data)
+    event = {
+      :timestamp => Time.now.strftime("%Y-%m-%dT%H:%M:%S.%6N%z")
+    }
+    event.merge!(@data)
+    # TODO(sissel): need to refactor string->hash shoving.
+    if data.is_a?(String)
+      event[:message] = data
+    else
+      event.merge!(data)
+    end
+
+    @outputs.each do |out|
+      out << event
+    end
+  end # def publish
+
+  # Start timing something.
+  # Returns an instance of Cabin::Timer bound to this Cabin::Channel.
+  # To stop the timer and immediately emit the result to this channel, invoke
+  # the Cabin::Timer#stop method.
+  public
+  def time(data, &block)
+    # TODO(sissel): need to refactor string->hash shoving.
+    if data.is_a?(String)
+      data = { :message => data }
+    end
+
+    timer = Cabin::Timer.new do |duration|
+      # TODO(sissel): Document this field
+      data[:duration] = duration
+      publish(data)
+    end
+
+    if block_given?
+      block.call
+      return timer.stop
+    else
+      return timer
+    end
+  end # def time
+
+  public
+  def context
+    ctx = Cabin::Context.new(self)
+    return ctx
+  end # def context
+end # class Cabin::Channel

data/lib/cabin/context.rb

@@ -0,0 +1,45 @@
+require "cabin/namespace"
+
+# Logging context exists to make it easy to add and later undo any changes made
+# to the context data associated with a given Logging::Channel
+# 
+# Usage:
+#
+#     context = channel.context
+#     context["foo"] = "Hello world!"
+#     channel.info("Sample log") # output includes { "foo" => "Hello world!" }
+#     context.clear
+#     channel.info("Sample log 2") # context cleared, key "foo" removed.
+#
+class Cabin::Context
+  def initialize(channel)
+    @changes = []
+    @channel = channel
+  end # def initialize
+
+  def on_clear(&block)
+    @clear_callback = block
+  end # def on_clear
+
+  def []=(key, value)
+    # Maintain a record of what was changed so clear() can undo this context.
+    # This record is in reverse order so it can be undone in reverse later.
+    @changes.unshift([key, value, @channel[key]])
+    @channel[key] = value
+  end # def []=
+
+  def [](key)
+    @channel[key]
+  end # def []
+  
+  # Undo any changes made to the channel by this context.
+  def clear
+    @changes.each do |key, value, original|
+      if original.nil?
+        @channel.remove(key)
+      else
+        @channel[key] = original
+      end
+    end
+  end # def clear
+end # class Cabin::Context

data/lib/cabin/logger.rb

@@ -0,0 +1,29 @@
+require "cabin/namespace"
+
+module Cabin::Logger
+  attr_accessor :level
+  LEVELS = {
+    :fatal => 0,
+    :error => 1,
+    :warn => 2,
+    :info => 3,
+    :debug => 4
+  }
+
+  # Define the usual log methods: info, fatal, etc.
+  # Each level-based method accepts both a message and a hash data.
+  %w(fatal error warn info debug).each do |level|
+    level = level.to_sym
+    # def info, def warn, etc...
+    define_method(level) do |message, data={}|
+      next unless LEVELS[@level] >= LEVELS[level]
+      if message.is_a?(Hash)
+        data.merge!(message)
+      else
+        data[:message] = message
+      end
+      data[:level] = level
+      publish(data)
+    end
+  end # end defining level-based log methods
+end # module Cabin::Logger

data/lib/cabin/namespace.rb

@@ -0,0 +1,3 @@
+module Cabin
+  module Outputs; end
+end

data/lib/cabin/outputs/stdlib-logger.rb

@@ -0,0 +1,20 @@
+require "cabin"
+require "json"
+
+# Wrap Ruby stdlib's logger. This allows you to output to a normal ruby logger
+# with Cabin. Since Ruby's Logger has a love for strings alone, this 
+# wrapper will convert the data/event to json before sending it to Logger.
+class Cabin::Outputs::StdlibLogger
+  public
+  def initialize(logger)
+    @logger = logger
+  end # def initialize
+
+  # Receive an event
+  public
+  def <<(data)
+    method = data[:level] || "info"
+    # This will call @logger.info(data) or something similar.
+    @logger.send(method, data.to_json)
+  end # def <<
+end # class Cabin::Outputs::StdlibLogger

data/lib/cabin/timer.rb

@@ -0,0 +1,20 @@
+require "cabin/namespace"
+
+# A simple timer class for timing events like a stop watch. Normally you don't
+# invoke this yourself, but you are welcome to do so.
+#
+# See also: Cabin::Channel#time
+class Cabin::Timer
+  def initialize(&block)
+    @start = Time.now
+    @callback = block if block_given?
+  end # def initialize
+
+  # Stop the clock and call the callback with the duration.
+  # Also returns the duration of this timer.
+  def stop
+    duration = Time.now - @start
+    @callback.call(duration) if @callback
+    return duration
+  end # def stop
+end # class Cabin::Timer

data/test/minitest-patch.rb

@@ -0,0 +1,13 @@
+require "rubygems"
+require "minitest/spec"
+# XXX: This code stolen from logstash's test bits.
+
+# I don't really like monkeypatching, but whatever, this is probably better
+# than overriding the 'describe' method.
+class MiniTest::Spec
+  class << self
+    # 'it' sounds wrong, call it 'test'
+    alias :test :it
+  end
+end
+

data/test/test_logging.rb

@@ -0,0 +1,101 @@
+$: << File.dirname(__FILE__)
+$: << File.join(File.dirname(__FILE__), "..", "lib")
+
+require "rubygems"
+require "minitest-patch"
+require "cabin"
+require "stringio"
+require "minitest/autorun" if __FILE__ == $0
+
+describe Cabin::Channel do
+  class Receiver
+    attr_accessor :data
+
+    public
+    def initialize
+      @data = []
+    end
+
+    public
+    def <<(data)
+      @data << data
+    end
+  end # class Receiver
+
+  before do
+    @logger = Cabin::Channel.new
+    @target = Receiver.new
+    @logger.subscribe(@target)
+  end
+
+  test "simple string publishing" do
+    @logger.publish("Hello world")
+    assert_equal(1, @target.data.length)
+    assert_equal("Hello world", @target.data[0][:message])
+  end
+
+  test "simple context data" do
+    @logger[:foo] = "bar"
+    @logger.publish("Hello world")
+    assert_equal(1, @target.data.length)
+    assert_equal("Hello world", @target.data[0][:message])
+    assert_equal("bar", @target.data[0][:foo])
+  end
+
+  test "time something" do
+    timer = @logger.time("some sample")
+    timer.stop
+
+    event = @target.data[0]
+    assert_equal("some sample", event[:message])
+    assert(event[:duration].is_a?(Numeric))
+  end
+
+  test "double subscription" do
+    @logger.subscribe(@target)
+    @logger.publish("Hello world")
+    assert_equal(2, @target.data.length)
+    assert_equal("Hello world", @target.data[0][:message])
+    assert_equal("Hello world", @target.data[1][:message])
+  end 
+
+  test "context values" do
+    context = @logger.context
+    context["foo"] = "hello"
+    @logger.publish("testing")
+    assert_equal(1, @target.data.length)
+    assert_equal("hello", @target.data[0]["foo"])
+    assert_equal("testing", @target.data[0][:message])
+  end
+
+  test "context values clear properly" do
+    context = @logger.context
+    context["foo"] = "hello"
+    context.clear
+    @logger.publish("testing")
+    assert_equal(1, @target.data.length)
+    assert(!@target.data[0].has_key?("foo"))
+    assert_equal("testing", @target.data[0][:message])
+  end
+
+  %w(fatal error warn info debug).each do |level|
+    level = level.to_sym
+    test "standard use case, '#{level}' logging when enabled" do
+      @logger.level = level
+      @logger.send(level, "Hello world")
+      event = @target.data[0]
+      assert_equal("Hello world", event[:message])
+      assert_equal(level, event[:level])
+    end
+  end
+
+  %w(error warn info debug).each do |level|
+    level = level.to_sym
+    test "standard use case, '#{level}' logging when wrong level" do
+      @logger.level = :fatal
+      # Should not log since log level is :fatal and we are above that.
+      @logger.send(level, "Hello world")
+      assert_equal(0, @target.data.length)
+    end
+  end
+end

metadata

@@ -0,0 +1,70 @@
+--- !ruby/object:Gem::Specification
+name: cabin
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+  prerelease: 
+platform: ruby
+authors:
+- Jordan Sissel
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2011-10-11 00:00:00.000000000Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: &10650540 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: *10650540
+description: This is an experiment to try and make logging more flexible and more
+  consumable. Plain text logs are bullshit, let's emit structured and contextual logs.
+email:
+- jls@semicomplete.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/cabin.rb
+- lib/cabin/outputs/stdlib-logger.rb
+- lib/cabin/channel.rb
+- lib/cabin/namespace.rb
+- lib/cabin/timer.rb
+- lib/cabin/context.rb
+- lib/cabin/logger.rb
+- examples/sinatra-logging.rb
+- examples/sample.rb
+- test/minitest-patch.rb
+- test/test_logging.rb
+homepage: https://github.com/jordansissel/ruby-cabin
+licenses:
+- Apache License (2.0)
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+- 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: 
+rubygems_version: 1.8.10
+signing_key: 
+specification_version: 3
+summary: Experiments in structured and contextual logging
+test_files: []