errlog 0.3.3 → 0.3.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 11d79f46d2df12286b3049c79c7229ee4f694ccb
-  data.tar.gz: 12b6ebffab66595105892bc245bc7048e72635de
+  metadata.gz: 17e96f6052645fe7624fcde6a74b51d026cd1411
+  data.tar.gz: bd1de2e4d3b099273b6431e1f960cd799c991a96
 SHA512:
-  metadata.gz: 0610be3f9b72943a602bfe8d537a00f881300693c2d72f6932d7e0a9fa967daf85fbe5741dc9883c310b4bd2af61ea99140d90e04d6f3b4a7850656088f22a49
-  data.tar.gz: 6443751a6535f965db8538c1ba8fdf3d55fb4c0ff6919c4bda1a5c7cd442d0e5ca9c2594748677ff7946cd89fbc2dc4476015d57e9970045cee0c14a69d4e8eb
+  metadata.gz: 50139bfaecb2c2efce08c9e2026c975b5dc5be3c191b5053f5d93db96d2ba8e4b8d2c8b779b73f1332c10062c00a6b549bb69274740157643993e2976b83a3a5
+  data.tar.gz: bbc4e3a5e7736f4df68572c4d3ff020fc263e4be04a38c6a315666c5c5eb34a7f613145178d3fd2ce19e9ab51c760d2b4ae32f668855cb3c8533738938a3f808

data/LICENSE.txt

@@ -1,4 +1,5 @@
-Copyright (c) 2012 sergeych
+Copyright (c) 2012 sergeych (Sergey S. Chernov)
+real.sergeych@gmail.com
 
 MIT License
 

data/README.md

@@ -1,11 +1,7 @@
 # Errlog
 
-*ATTENTION!*
-
-This is a reporting tool tor errlog.co service under development, not yet available fpr public.
-
-
-The rest is a template for not to type it later on. Please ignore.
+The Errlog logging client (http://errorlog.co). with rails & delayed_job integrations. See usage details
+at http://errorlog.co/help/rails. The service is in beta test now.
 
 
 ## Installation
@@ -22,9 +18,45 @@ Or install it yourself as:
 
     $ gem install errlog
 
+More: http://errorlog.co/help/rails
+
 ## Usage
 
-TODO: Write usage instructions here
+    Errlog.configure(...) # visit the link above for help on credentials
+
+    Errlog.protect { |ctx|
+        # Any exception from here will be caught and reported
+        ctx.extra_data = "Anything you want to attach to trace/warning/error report"
+    }
+
+    Errlog.protect_rethrow { |ctx|
+        # Same as above, but the exception will be rethrown
+    }
+
+    Errlog.trace "So far so good"
+
+    # some syntax sugar
+
+    x == y or Errlog.error "Something is wrong" do |ctx|
+        ctx.expected_value = x
+        ctx.real_one = y
+    }
+
+    begin
+        ...
+    rescue Exception => e
+        Errlog.context.exception e
+        ...
+    end
+
+    logger = Errlog::ChainLogger.new
+    logger.info "This string will be collected"
+
+
+Consult API docs for more: http://rdoc.info/github/sergeych/errlog/master/frames. Configuration
+details are available at http://errorlog.co/help/rails
+
+As the service is under active development, be sure to `bundle update errlog` regularly.
 
 ## Contributing
 

data/lib/errlog/chain_loggger.rb

@@ -2,23 +2,32 @@ require 'logger'
 
 module Errlog
 
+  # The chain logger is used to collect data for Errlog context (current context is used)
+  # and optionally pass through logs to previous logger (that's why chain).
+  # Potential problem: you can not bound logger to some context instance so far. Leave
+  # issue at the github if you'll need
   class ChainLogger < Logger
 
+    # @return previous logger instance if any
     attr_reader :prev_logger
 
+    # Create instance optionally atop of an existing logger.
     def initialize prev=nil
       @prev_logger = prev
       super(nil)
     end
 
+    # Set log level
     def level= l
       @prev_logger and @prev_logger.level = l
     end
 
+    # @return current log level
     def level
       @prev_logger and @prev_logger.level
     end
 
+    # Standard add log method, see (Logger#add)
     def add severity, message = nil, progname = nil
       message = yield if block_given?
       @prev_logger and @prev_logger.add(severity, message, progname)

data/lib/errlog/constants.rb

@@ -1,11 +1,17 @@
 module Errlog
+  # This module could be extended for easy access to constants and severity test
+  # helpers
   module Constants
 
+    # @!group severity constants
+
     ERROR     = 100
     WARNING   = 50
-    NOT_FOUND = 50
+    NOT_FOUND = 49
     TRACE     = 1
 
+    # @!endgroup
+
     def is_error?(code)
       code >= ERROR
     end

data/lib/errlog/context.rb

@@ -1,8 +1,22 @@
 require 'hashie'
 
 module Errlog
+  # Context is a central object in Errlog reporting. It is used to collect and
+  # report necessary data about trace, warning and exception. It also carries
+  # arbitrary extra data you might want to see in the errlog report, you just
+  # assign it to the Context object much like with OpenStruct:
+  #
+  #   context = Errlog::clear_context
+  #   context.instance_name = 'www143'
+  #   # ...
+  #   context.trace "Something just happened"
   class Context < Hashie::Mash
 
+    # Perform a given block rescuing and reporting any uncaught exception.
+    # Exception will not be thrown out of the block:
+    #
+    # @param component_name [String] optional name of the component to report exceptions from
+    # @yieldparam ctx the context itself
     def protect component_name=nil, options={}
       component_name and self.component_name = component_name
       begin
@@ -13,35 +27,58 @@ module Errlog
       end
     end
 
+    # Perform a given block reporting and rethrowing any uncaught exception (see #protect)
     def protect_rethrow component_name=nil, &block
       self.protect component_name, retrhow: true, &block
     end
 
+    # Report exception.
+    #
+    # @param [Exception] e exception to report
+    # @param [Integer] severity severity to report, some exceptions mught be useful to report as warnings or
+    #                  even traces.
+    # @yieldparam context the context itself, you can set more fields in a block
+    # @note that exception reports its class and backtrace, so there is no need to provide details
     def exception e, severity=Errlog::ERROR, &block
       self.stack           = e.backtrace
       self.exception_class = e.class.name
       report e.to_s, severity
     end
 
+    # Report trace. There is a syntax sugar to provide extra information in the block where the context
+    # is passed as the parameter:
+    #
+    #      everything_is_ok or context.trace "Not all is ok" do |ctx|
+    #          ctx.valuable_data = some_value
+    #      end
+    #
+    # Reporting methods except #exception uses the caller's stack in the report.
     def trace text, details=nil, severity=Errlog::TRACE, &block
       details and self.details = details
       report text, severity
     end
 
+    # Report a warning, see {#trace}
     def warning text, details=nil, severity=Errlog::WARNING, &block
       details and self.details = details
       report text, severity
     end
 
+    # Report an error, see {#trace}
     def error text, details=nil, severity=Errlog::ERROR, &block
       details and self.details = details
       report text, severity, &block
     end
 
+    # Add a handler that will be called with a context as the sole parameter before reporting.
+    # If the context will not be user for reporting, the handler will not be called. Use it
+    # to collect additional information that won't be needed otherwise, especially if collecting takes
+    # significant resources.
     def before_report &block
       (@before_handlers ||= []) << block
     end
 
+    # Report test with e given severity. See #{trace} for optional block usage.
     def report text, severity = Errlog::ERROR
       yield self if block_given?
 
@@ -67,8 +104,10 @@ module Errlog
       end
     end
 
+    # @private
     MAX_LOG_LINES = 100
 
+    # @private
     def add_log_record record
       @log_records ||= []
       @log_records << record

data/lib/errlog/version.rb

@@ -1,3 +1,3 @@
 module Errlog
-  VERSION = "0.3.3"
+  VERSION = "0.3.4"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: errlog
 version: !ruby/object:Gem::Version
-  version: 0.3.3
+  version: 0.3.4
 platform: ruby
 authors:
 - sergeych
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-04-07 00:00:00.000000000 Z
+date: 2013-04-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: boss-protocol
@@ -149,3 +149,4 @@ test_files:
 - spec/errlog_spec.rb
 - spec/packager_spec.rb
 - spec/spec_helper.rb
+has_rdoc: