kcaco 0.0.1

data/Gemfile

@@ -0,0 +1,4 @@
+source 'http://rubygems.org'
+
+# Specify your gem's dependencies in kcaco.gemspec
+gemspec

data/Gemfile.lock

@@ -0,0 +1,28 @@
+PATH
+  remote: .
+  specs:
+    kcaco (0.0.1)
+      guid
+
+GEM
+  remote: http://rubygems.org/
+  specs:
+    diff-lcs (1.1.3)
+    guid (0.1.1)
+    rake (0.9.2.2)
+    rspec (2.8.0)
+      rspec-core (~> 2.8.0)
+      rspec-expectations (~> 2.8.0)
+      rspec-mocks (~> 2.8.0)
+    rspec-core (2.8.0)
+    rspec-expectations (2.8.0)
+      diff-lcs (~> 1.1.2)
+    rspec-mocks (2.8.0)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  kcaco!
+  rake
+  rspec

data/README.md

@@ -0,0 +1,123 @@
+# Keep Calm and Carry On
+
+## Synopsis
+
+Ever written a long running process before? Ever had it raise
+and exception and die? Ever wrapped your main loop in a
+`begin..rescue` so you can just Keep Calm and Carry On? Ever found it
+really annoying that logging the damn thing is so difficult?
+
+Kcaco helps by providing some helper functions around dealing with
+exceptions. Specifically with regards to logging the bastard so you
+can deal with it. Example:
+
+``` ruby
+require "kcaco"
+begin
+  raise RuntimeError.new("Goodbye, cruel world")
+rescue => e
+  puts Kcaco.pretty(e)
+end
+```
+
+This will print out a line like so:
+`a84aedf9-8cda-13dd-123f-c8572078ea90 RuntimeError: Goodbye, cruel
+world [(irb) L3]`. In case it's not obvious, the output contains a
+GUID, the class of the error and the filename and linenumber it
+occured on. In a single line ideal for logging. Additionally, we
+serialize the exception to disk (hence the GUID - the filename we save
+it too) so you can look at it later.
+
+## Usage
+
+``` ruby
+require "kcaco"
+# in a rescue block, instead of the manual work:
+logger.error Kcaco.pretty(exception)
+```
+
+This will print out a message to your logs in the format: `GUID
+ExceptionClass: the message [filename.rb L123]`. Additionally, it will
+write out the exception object to `Kcaco.save_path` in a file named
+the same as that GUID. You can disable the save behavior with
+`Kcaco.auto_save = false`.
+
+## Example
+
+    $ bundle exec examples/simple.rb
+    900308c3-16ac-2803-ac97-db64464baae8 MichaelBay::Boom: ba da bloom [simple.rb L10]
+    
+    cat /tmp/kcaco/exceptions/900308c3-16ac-2803-ac97-db64464baae8 
+    time: 2012-01-06T16:01:53+02:00
+    type: MichaelBay::Boom
+    message: ba da bloom
+    backtrace:
+    examples/simple.rb:10:in `explosions'
+    examples/simple.rb:16
+    
+    --- !ruby/exception:MichaelBay::Boom 
+    message: ba da bloom
+
+## Why?
+
+Long running processes (daemons) tend to err on the side of logging
+exceptions and carrying on. This is peachy, but there are some things
+you definitely want to do. Without a catch-all `begin..rescue`, your
+application might do this:
+
+    irb> raise RuntimeError.new("death")
+    RuntimeError: death
+            from (irb):1
+
+That's pretty useful. Right?
+
+In a daemon, its natural to want just as much information. Except you
+will want to use a logger - especially at the appropriate level. You
+may write something like this to get similar output in your logs:
+
+``` ruby
+begin
+  # ...
+rescue => e
+  logger.error "#{e.class.name}: #{e.message}"
+end
+```
+
+But now you don't know where the error came from (backtrace line #1)
+or actually anything else from the backtrace. You can extend the code
+with something like:
+
+``` ruby
+e.backtrace.each do |line| logger.error(line); end
+```
+
+But now you've done something horrible: if you `grep ERROR` in your
+log file, the number of lines returned is no longer the number of
+errors in your log. There are a bunch of ways around this:
+
+Log the entire backtrace on 1 line, This gives you ugly logs
+especially with long backtraces. For example:
+
+    $ bundle exec examples/no_kcaco_one_line.rb
+    E, [2012-01-06T16:26:27.705513 #647] ERROR -- : MichaelBay::Boom: ba da bloom ["examples/no_kcaco_one_line.rb:10:in `explosions'", "examples/no_kcaco_one_line.rb:17"]
+
+Log the backtrace at a different level, e.g. `DEBUG`. This means you
+have to run with verbose logging:
+
+    $ bundle exec examples/no_kcaco_different_levels.rb
+    E, [2012-01-06T16:28:33.903684 #736] ERROR -- : MichaelBay::Boom: ba da bloom
+    D, [2012-01-06T16:28:33.903784 #736] DEBUG -- : examples/no_kcaco_different_levels.rb:10:in `explosions'
+    D, [2012-01-06T16:28:33.903814 #736] DEBUG -- : examples/no_kcaco_different_levels.rb:17
+    
+Or you can roll your own smarts. Repeatedly. Or just use some like Kcaco. Quite simply what it does is:
+
+* Save you having to format the log message by doing it for you.
+* Write more detail to a separate file where you can inspect it later.
+
+.. and you get
+
+    bundle exec examples/simple.rb
+    E, [2012-01-06T16:29:50.730922 #793] ERROR -- : ae58d80f-4bc3-899a-fd0b-2c831833510c MichaelBay::Boom: ba da bloom [simple.rb L11]
+
+In this example, you could see the saved exception
+`ae58d80f-4bc3-899a-fd0b-2c831833510c` on disk to get the full backtrace.

data/Rakefile

@@ -0,0 +1,7 @@
+#!/usr/bin/env rake
+require "bundler/gem_tasks"
+
+require "rspec/core/rake_task"
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/examples/no_kcaco_different_levels.rb

@@ -0,0 +1,24 @@
+#!/usr/bin/env ruby
+
+require "logger"
+
+class MichaelBay
+
+  class Boom < RuntimeError; end
+  
+  def explosions
+    raise Boom.new("ba da bloom")
+  end
+end
+
+if __FILE__ == $0
+  logger = Logger.new(STDOUT)
+  begin
+    MichaelBay.new.explosions
+  rescue => e
+    logger.error "#{e.class.name}: #{e.message}"
+    e.backtrace.each do |line|
+      logger.debug line
+    end
+  end
+end

data/examples/no_kcaco_one_line.rb

@@ -0,0 +1,21 @@
+#!/usr/bin/env ruby
+
+require "logger"
+
+class MichaelBay
+
+  class Boom < RuntimeError; end
+  
+  def explosions
+    raise Boom.new("ba da bloom")
+  end
+end
+
+if __FILE__ == $0
+  logger = Logger.new(STDOUT)
+  begin
+    MichaelBay.new.explosions
+  rescue => e
+    logger.error "#{e.class.name}: #{e.message} #{e.backtrace.inspect}"
+  end
+end

data/examples/simple.rb

@@ -0,0 +1,22 @@
+#!/usr/bin/env ruby
+
+require "logger"
+require "kcaco"
+
+class MichaelBay
+
+  class Boom < RuntimeError; end
+  
+  def explosions
+    raise Boom.new("ba da bloom")
+  end
+end
+
+if __FILE__ == $0
+  logger = Logger.new(STDOUT)
+  begin
+    MichaelBay.new.explosions
+  rescue => e
+    logger.error Kcaco.pretty(e)
+  end
+end

data/kcaco.gemspec

@@ -0,0 +1,20 @@
+# -*- encoding: utf-8 -*-
+require File.expand_path('../lib/kcaco/version', __FILE__)
+
+Gem::Specification.new do |gem|
+  gem.authors       = ["Marc Bowes"]
+  gem.email         = ["marcbowes@gmail.com"]
+  gem.description   = %q{Helpers for dealing with exceptions}
+  gem.summary       = %q{Bored of writing out exceptions to logs?}
+  gem.homepage      = ""
+
+  gem.files         = Dir["**/*"]
+  gem.test_files    = Dir["spec/**/*"]
+  gem.name          = "kcaco"
+  gem.require_paths = ["lib"]
+  gem.version       = Kcaco.version
+
+  gem.add_runtime_dependency("guid")
+  gem.add_development_dependency("rake")
+  gem.add_development_dependency("rspec")
+end

data/lib/kcaco.rb

@@ -0,0 +1,41 @@
+require "kcaco/version"
+require "kcaco/wrapped_exception"
+require "kcaco/file_writer"
+
+module Kcaco
+
+  class << self
+
+    def auto_save=(bool)
+      @auto_save = bool
+    end
+    
+    def auto_save?
+      @auto_save != false
+    end
+
+    def save_path=(path)
+      @save_path = path
+    end
+
+    def save_path(wrapped_exception = nil)
+      @save_path ||= "/tmp/kcaco/exceptions"
+      if wrapped_exception
+        File.join(@save_path, wrapped_exception.uuid)
+      else
+        @save_path
+      end
+    end
+
+    def save(wrapped_exception)
+      Kcaco::FileWriter.new(wrapped_exception).
+        save(save_path(wrapped_exception))
+    end
+    
+    def pretty(exception)
+      wrapped_exception = Kcaco::WrappedException.new(exception)
+      save(wrapped_exception) if auto_save?
+      wrapped_exception.pretty
+    end
+  end
+end

data/lib/kcaco/file_writer.rb

@@ -0,0 +1,37 @@
+module Kcaco
+  class FileWriter
+
+    require "time"
+    require "fileutils"
+    require "yaml"
+
+    
+    attr_accessor :exception
+    
+    def initialize(exception)
+      self.exception = exception
+    end
+
+
+    def save(path)
+      FileUtils.mkdir_p(File.dirname(path))
+      File.open(path, "w") do |f|
+        [
+         ["time", Time.now.iso8601],
+         ["type", exception.type],
+         ["message", exception.message],
+        ].each do |label, text|
+          f.puts([label, text].join(": "))
+        end
+
+        f.puts("backtrace:")
+        exception.backtrace.each do |line|
+          f.puts(line)
+        end
+
+        f.puts
+        f.puts(exception.to_yaml)
+      end
+    end
+  end
+end

data/lib/kcaco/version.rb

@@ -0,0 +1,7 @@
+module Kcaco
+
+  def version
+    "0.0.1"
+  end
+  module_function :version
+end

data/lib/kcaco/wrapped_exception.rb

@@ -0,0 +1,65 @@
+module Kcaco
+  class WrappedException
+
+    require "guid"
+
+    
+    attr_accessor :exception
+    
+    def initialize(exception)
+      self.exception = exception
+    end
+
+
+    def type
+      exception.class.name
+    end
+    
+    def message
+      exception.message
+    end
+    
+    def backtrace
+      exception.backtrace
+    end
+    
+    def to_yaml
+      exception.to_yaml
+    end
+    
+    def extract_filename_and_line_no(line)
+      if (m = line.match(/(.+):(\d+):/))
+        [File.basename(m[1]), m[2].to_i]
+      end
+    end
+
+    def filename_and_line_no
+      @filename_and_line_no ||= 
+        extract_filename_and_line_no(backtrace.first)
+    end
+
+    def filename
+      filename_and_line_no.first
+    end
+
+    def line_no
+      filename_and_line_no.last
+    end
+    
+    def title
+      [type, message].join(": ")
+    end
+
+    def pretty
+      [
+       uuid,
+       title,
+       "[%s L%i]" % [filename, line_no],
+      ].join(" ")
+    end
+
+    def uuid
+      @uuid ||= Guid.new.to_s
+    end
+  end
+end

data/spec/file_writer_spec.rb

@@ -0,0 +1,27 @@
+require "spec_helper"
+
+require "fileutils"
+require "kcaco/wrapped_exception"
+require "kcaco/file_writer"
+
+module Kcaco
+  describe Exception do
+
+    let(:boom) { Boom.new }
+    let(:wrapped_exception) { WrappedException.new(boom.rescued) }
+    let(:fw) { FileWriter.new(wrapped_exception) }
+
+    
+    it "should save the exception" do
+      path = File.join("/tmp", [File.basename(__FILE__), Process.pid.to_s].join("-"))
+      begin
+        fw.save(path)
+      ensure
+        FileUtils.rm(path)
+      end
+
+      # Kind of difficult to test the content of this file because of
+      # times and paths.
+    end
+  end
+end

data/spec/kcaco_spec.rb

@@ -0,0 +1,18 @@
+require "spec_helper"
+
+require "kcaco"
+
+describe Kcaco do
+
+  let(:boom) { Boom.new }
+
+  before do
+    Kcaco.auto_save = false
+  end
+  
+  it "should create a pretty log entry" do
+    exception = boom.rescued
+    rest = Regexp.escape("RuntimeError: exception [boom.rb L10]")
+    Kcaco.pretty(exception).should =~ /[a-z0-9\-]+ #{rest}/
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1 @@
+require "support/boom"

data/spec/support/boom.rb

@@ -0,0 +1,36 @@
+class Boom
+  
+  DEFAULT_MESSAGE = "exception"
+
+  def create(message = DEFAULT_MESSAGE)
+    RuntimeError.new(message)
+  end
+
+  def raise(message = DEFAULT_MESSAGE)
+    Kernel.raise(create(message))
+  end
+  
+  def rescued(message = DEFAULT_MESSAGE)
+    begin
+      self.raise
+    rescue RuntimeError => e
+      e
+    end
+  end
+
+  class << self
+    
+    def raise_line_no
+      @raise_line_no ||= get_raise_line_no
+    end
+
+    def get_raise_line_no
+      File.open(__FILE__, "r") do |f|
+        f.each do |line|
+          return f.lineno if line.include?("Kernel.raise")
+        end
+      end
+      nil
+    end
+  end
+end

data/spec/wrapped_exception_spec.rb

@@ -0,0 +1,35 @@
+require "spec_helper"
+
+require "kcaco/wrapped_exception"
+
+module Kcaco
+  describe WrappedException do
+
+    let(:boom) { Boom.new }
+    let(:we) { WrappedException.new(boom.rescued) }
+
+    
+    it "should generate an we title" do
+      we.title.should == "RuntimeError: exception"
+    end
+
+    it "should figure out the file name that caused the we" do
+      we.filename.should == "boom.rb"
+    end
+    
+    it "should figure out the line number that caused the we" do
+      we.line_no.should == Boom.raise_line_no
+    end
+
+    it "should create a pretty version" do
+      we.should_receive(:uuid).and_return("uuid")
+      we.pretty.should == "uuid RuntimeError: exception [boom.rb L10]"
+    end
+
+    it "should make a uuid" do
+      uuid = we.uuid
+      we.uuid.should =~ /[a-z0-9\-]+/
+      we.uuid.should == uuid
+    end
+  end
+end

metadata

@@ -0,0 +1,129 @@
+--- !ruby/object:Gem::Specification 
+name: kcaco
+version: !ruby/object:Gem::Version 
+  hash: 29
+  prerelease: 
+  segments: 
+  - 0
+  - 0
+  - 1
+  version: 0.0.1
+platform: ruby
+authors: 
+- Marc Bowes
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2012-01-06 00:00:00 +02:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  type: :runtime
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  name: guid
+  version_requirements: *id001
+  prerelease: false
+- !ruby/object:Gem::Dependency 
+  type: :development
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  name: rake
+  version_requirements: *id002
+  prerelease: false
+- !ruby/object:Gem::Dependency 
+  type: :development
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  name: rspec
+  version_requirements: *id003
+  prerelease: false
+description: Helpers for dealing with exceptions
+email: 
+- marcbowes@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- examples/no_kcaco_different_levels.rb
+- examples/simple.rb
+- examples/no_kcaco_one_line.rb
+- Rakefile
+- README.md
+- Gemfile
+- kcaco.gemspec
+- spec/support/boom.rb
+- spec/wrapped_exception_spec.rb
+- spec/spec_helper.rb
+- spec/kcaco_spec.rb
+- spec/file_writer_spec.rb
+- Gemfile.lock
+- lib/kcaco.rb
+- lib/kcaco/file_writer.rb
+- lib/kcaco/wrapped_exception.rb
+- lib/kcaco/version.rb
+has_rdoc: true
+homepage: ""
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.6.2
+signing_key: 
+specification_version: 3
+summary: Bored of writing out exceptions to logs?
+test_files: 
+- spec/support/boom.rb
+- spec/wrapped_exception_spec.rb
+- spec/spec_helper.rb
+- spec/kcaco_spec.rb
+- spec/file_writer_spec.rb