shog 0.0.2 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: e02b8810b0926489472a9c3ae7172681c903d247
-  data.tar.gz: 82e7c9c7d3fbc7ea093b79f3afd0c638c9bab046
+  metadata.gz: d11bb673ce2d41a4d247e564223a567f17a3b327
+  data.tar.gz: c2f4489f6612357260fdfd8d5279ebaa53605c94
 SHA512:
-  metadata.gz: 3a851ea89f9357838dd1d6b2f31108757b1b846cdcfec47004887a08cf825c4afd086217251c49e403f2589f1697b15d5d1094043e715ba821c2e70258bf25c1
-  data.tar.gz: 515b080f51d3f66fa3d49f48c1a9e6fbc26916c46e27261195c38eb3aa244a384981b229ef3584e8f45314a198be31842cd0a4907b55f35c2f291fae4fe384e6
+  metadata.gz: 1cdb0e922b0536b88ff3ea00f8e4fce9fe5dd95ba54400e00cf103ef5cc506cead951f7f816be42724f967b3053dd6c874c32233e95dda8fbf7bedcba8c705b1
+  data.tar.gz: e18c58381f770385352b1ad7123c96fccf466b9e5122f07a9d2b755ba4ca67a9684d4e82abe815082f0e1657d30ada3d59adc73a72424caeb2aa6e010dee4119

data/README.md

@@ -2,32 +2,53 @@
 
 [![Gem Version](https://badge.fury.io/rb/shog.svg)](http://badge.fury.io/rb/shog)
 [![Code Climate](https://codeclimate.com/github/phallguy/shog.png)](https://codeclimate.com/github/phallguy/shog)
-[![Dependency Status](https://gemnasium.com/phallguy/shog.svg)](https://gemnasium.com/phallguy/shog)
 
 
 Make rails 4.0 log details more colorful.
 
 There are plenty of logging frameworks for making tags (like timestamp, log
 level, etc.) more colorful - but what about the details in the line of text?
-What about the HTTP method used to make the request? What about the times.
+What about the HTTP method used to make the request? What about the render
+times?
 
-## Installation
+Shog adds colors to highlight context and make it easier to pick out the
+important parts of the message. Unformatted logs like this
 
-Add this line to your application's Gemfile:
+![Plain Logs](docs/images/plain.png)
 
-    gem 'shog'
+become easy to ready and process logs like this
 
-And then execute:
+![Shogged Logs](docs/images/shogged.png)
 
-    $ bundle
+## Using Shog
 
-Or install it yourself as:
+Just add the following to your Gemfile to enable shiny output logs.
 
-    $ gem install shog
+```
+gem 'shog'
+```
 
-## Usage
+Shog comes built in with some sane defaults for rails apps. But you can
+customize the output  to match additional log message by your app, or to use
+different options in production.
 
-TODO: Write usage instructions here
+To change the defaults, add `shog.rb` to your `config/initializers` folder
+
+```ruby
+Shog.configure do
+  if ::Rails.env.production?
+    reset_config!
+    timestamp
+  end
+
+  match /execution expired/ do |msg,matches|
+    # Highlight timeout errors
+    msg.red
+  end
+end
+```
+
+See [Shog::Formatter#configure](lib/shog/formatter.rb) for more configuration options.
 
 ## Contributing
 

data/lib/shog/formatter.rb

@@ -2,31 +2,43 @@ require 'active_support/tagged_logging'
 require 'colored'
 
 module Shog
+
+  # A rails logger formatter that spices up the log message adding color to
+  # and context to log messages.
+  #
+  # Shog automatically overrides the default formatter in your rails app. Use
+  # {Shog.configure} to configure the default logger.
   class Formatter < ::ActiveSupport::Logger::SimpleFormatter
 
     include ActiveSupport::TaggedLogging::Formatter
 
+    def initialize
+      reset_config!
+    end
+
+    # Called by the logger to prepare a message for output.
+    # @return [String]
     def call( severity, time, progname, msg )
-      return if msg.blank?
-      tagged formatted_severity_tag( severity ) do
-        msg = formatted_message( severity, msg )
-        msg = timestamped_message( time, msg )
-        msg = prognamed_message( progname, msg )
+      return if msg.blank? || _silence?( msg )
 
-        super severity, time, progname, msg
-      end
-    end
+      msg = [
+        _tagged( time, :timestamp ),
+        _tagged( progname, :progname ),
+        formatted_severity_tag( severity ),
+        formatted_message( severity, msg )
+      ].compact.join(" ")
 
-    def initialize
-      reset_config!
+      super severity, time, progname, msg
     end
 
-    # Formats the message according to the configured settings.
+    # Formats the message according to the configured {#match} blocks.
+    #
     # @param [String] msg to format.
+    # @return [String] the formatted message.
     def formatted_message( severity, msg )
       msg = String === msg ? msg : msg.inspect
 
-      if args = matched( msg )
+      if args = _matched( msg )
         args.first.call msg, args.last
       elsif proc = configuration[:severities][severity]
         proc.call msg
@@ -37,6 +49,7 @@ module Shog
 
     # Formats the severity indicator prefixed before each line when writing to
     # the log.
+    #
     # @param [String] the severity of the message (ex DEBUG, WARN, etc.)
     # @return [String] formatted version of the severity
     def formatted_severity_tag( severity )
@@ -44,16 +57,27 @@ module Shog
         configuration[:severity_tags].reduce(0){ |l,(k,_)| [k.length,l].max }
       end
 
+      return if length == 0
+
       padded_severity = severity.ljust length
 
-      if proc = configuration[:severity_tags][severity]
-        proc.call padded_severity
-      else
-        padded_severity
-      end
+      formatted = if proc = configuration[:severity_tags][severity]
+                    proc.call padded_severity
+                  else
+                    padded_severity
+                  end
+      _tagged formatted, :severity_tags
     end
 
-    # Formats a ms time value.
+    # Formats a time value expressed in ms, adding color to highlight times
+    # outside the expected range.
+    #
+    # If `time` is more thatn `expected` it's highligted yellow. If it's more
+    # than double it's highlighted red.
+    #
+    # @param [String] time in ms.
+    # @param [Float] expected maximum amount of time it should have taken.
+    # @return [String] the formatted time.
     def format_time( time, expected = 30 )
       timef = time.to_f
       case
@@ -67,57 +91,181 @@ module Shog
     # ==========================================================================
     # @!group Configuration
 
-    # Configure messages formatting for this formatter.
+    # Set up log message formatting for this formatter.
+    #
+    # @yield and executes the block where self is this formatter.
+    # @return [Formatter] self.
+    #
+    # @example
+    #   Formatter.new.configure do
+    #     with :defaults
+    #     timestamp
+    #     severity(:error){ |msg| msg.red }
+    #     severity(:fatal){ |msg| "\b#{msg}".red }
+    #   end
     def configure( &block )
       instance_eval( &block )
       self
     end
 
-    # Format the severity tagged before each line.
-    def severity_tag( level, &block )
-      configuration[:severity_tags][ level.to_s.upcase ] = block
+    # Format the severity indicator tagged before each line. To format the
+    # actual message itself use {#severity}.
+    #
+    # @overload severity_tag( level, proc )
+    #   @param [String,Symbol] level to format.
+    #   @param [#call(level)] proc that receives the log level and returns the
+    #     reformatted level.
+    #
+    # @overload severity_tag( level )
+    #   @param [String,Symbol] level to format.
+    #   @yieldparam level [String] the log level to reformat.
+    #   @yieldreturn [String] the reformatted level.
+    #
+    # @return [Formatter] self.
+    #
+    # @example
+    #   configure do
+    #     severity_tag(:warn){|level| level.yellow }
+    #     severity_tag(:error){|level| level.red }
+    #   end
+    def severity_tag( level, proc = nil, &block )
+      proc ||= block
+      configuration[:severity_tags][ level.to_s.upcase ] = proc
+      self
     end
 
-    # Provide customized formatting for messages of the given severity when they
-    # a custom matcher cannot be found.
-    # @param [String,Symbol] level to format.
-    def severity( level, &block )
-      configuration[:severities][ level.to_s.upcase ] = block
+    # Provide default formatting for messages of the given severity when
+    # a {#match} is not found.
+    #
+    # @overload severity( level, proc )
+    #   @param [String,Symbol] level to format.
+    #   @param [#call(msg)] proc that receives the message and returns the
+    #     reformatted message.
+    # @overload severity( level )
+    #   @param [String,Symbol] level to format.
+    #   @yieldparam msg [String] the message to reformat.
+    #   @yieldreturn [String] the reformatted message.
+    #
+    # @return [Formatter] self.
+    #
+    # @example
+    #   configure do
+    #     severity(:fatal){ |msg| msg.white_on_red }
+    #   end
+    def severity( level, proc = nil, &block )
+      proc ||= block
+      configuration[:severities][ level.to_s.upcase ] = proc
+      self
     end
 
     # Resets any previously configured formatting settings.
+    # @return [Formatter] self.
     def reset_config!
       @configuration ||= {
         severity_tags: {},
         severities: {},
-        matchers: {}
+        matchers: {},
+        silencers: []
       }
       self
     end
 
-    # When a log message matches the given pattern, provide a custom format
-    # for it.
-    def match( pattern, &block )
-      configuration[:matchers][pattern] = block
+    # Re-format any log messages that match the given `pattern`.
+    #
+    # @overload match( pattern, proc)
+    #   @param [Regexp] pattern to match against the log message.
+    #   @param [#call(message,last_match)] proc a callable object that receives
+    #     the message and the last match and re-formats the message.
+    #
+    # @overload match( pattern )
+    #   @param [Regexp] pattern to match against the log message.
+    #   @yieldparam message [String] the matched log message.
+    #   @yieldparam last_match [MatchData] the regex matches.
+    #   @yieldreturn [String] the re-formatted message.
+    #
+    # @example
+    #   configure do
+    #     match /GET (?<address>.*)/ do |message,last_match|
+    #       "GETTING -> #{last_match['address'].green}"
+    #     end
+    #   end
+    # @return [Formatter] self.
+    def match( pattern, proc = nil, &block )
+      proc ||= block
+      configuration[:matchers][pattern] = proc
+      self
+    end
+
+    # When a log message matches the given `pattern` don't log it.
+    #
+    # @param [Regexp] pattern to match.
+    #
+    # @return [Formatter] self.
+    #
+    # @example
+    #   configure do
+    #     silence /assets\/bootstrap/
+    #   end
+    def silence( pattern )
+      configuration[:silencers] << pattern
+      self
     end
 
-    # Adds the named matchers to the log
-    def formatter( mod )
+    # Use configuration defined in the given module.
+    #
+    # @param [Symobl,#configure] mod the name of the shog module to use or an
+    #   object that responds to `#configure`.
+    #
+    # @return [Formatter] self.
+    #
+    # When `mod` is a symobl, it loads one of the modules from
+    # {Shog::Formatters} and uses any configuration options sepcified in that
+    # module.
+    #
+    # Otherwise `mod` must respond to `#configure` taking a single argument -
+    # this formatter.
+    #
+    # @example Built-in Formatters
+    #   configure do
+    #     with :defaults
+    #     with :requests
+    #   end
+    #
+    # @example Custom Shared Formatters
+    #   module MyFormatters
+    #     def self.configure( formatter )
+    #       formatter.configure do
+    #         timestamp
+    #       end
+    #     end
+    #   end
+    #
+    #   configure do
+    #     with MyFormatters
+    #   end
+    def with( mod )
       unless mod.is_a? Module
         mod = "Shog::Formatters::#{mod.to_s.camelize}".constantize
       end
 
       mod.configure self
+      self
     end
 
     # Include timestamp in logged messages.
-    def timestamp( enabled = true )
-      configuration[:timestamp] = enabled
+    # @param [Boolean] enable or disable timestamping of log messages.
+    # @return [Formatter] self.
+    def timestamp( enable = true )
+      configuration[:timestamp] = enable
+      self
     end
 
     # Include the progname in logged messages.
-    def progname( enabled = true )
-      configuration[:progname] = enabled
+    # @param [Boolean] enable or disable tagging with the prog name of log messages.
+    # @return [Formatter] self.
+    def progname( enable = true )
+      configuration[:progname] = enable
+      self
     end
 
     # @!endgroup
@@ -126,7 +274,7 @@ module Shog
 
       attr_accessor :configuration
 
-      def matched( msg )
+      def _matched( msg )
         if matched =  configuration[:matchers].find do |pattern,_|
                         pattern === msg
                       end
@@ -134,16 +282,13 @@ module Shog
         end
       end
 
-      def timestamped_message( time, msg )
-        return msg unless configuration[:timestamp]
-
-        "[#{time}] #{msg}"
+      def _tagged( val, config_key )
+        return unless configuration[config_key]
+        "[#{val}]"
       end
 
-      def prognamed_message( progname, msg )
-        return msg unless configuration[:progname]
-
-        "[#{progname}] #{msg}"
+      def _silence?( msg )
+        configuration[:silencers].any?{|p| p === msg }
       end
   end
 end

data/lib/shog/formatters/defaults.rb

@@ -1,9 +1,12 @@
 module Shog
   module Formatters
-    # Default formatting options
+
+    # Provide common default log formatting options.
     module Defaults
       module_function
 
+      # @see Shog::Formatter#configure
+      # @see Shog::Formatter#with
       def configure( formatter )
         formatter.configure do
           severity_tag( :debug ) { |msg| msg.black.bold }

data/lib/shog/formatters/requests.rb

@@ -1,21 +1,28 @@
 module Shog
   module Formatters
-    # Format log messages from the request processing such as controller endpoints and views.
+    # Provide common log formatting options for rails request logs such as
+    # controller names views, and render times.
     module Requests
       module_function
 
+      # @see Shog::Formatter#configure
+      # @see Shog::Formatter#with
       def configure( formatter )
         formatter.configure do
+
+          # Highlight HTTP request methods
           match /Started\s+(?<method>PUT|PATCH|GET|POST|DELETE)\s+(?<path>"[^"]*")[^\d\.]+(?<ip>[\d\.]+)(?<time>.*)/ do |msg,match|
             # http://refiddle.com/ge6
             "#{match["method"].ljust 6} ".green.bold + " #{match["path"]} ".white.bold + " for " + "#{match["ip"]}".yellow + " #{match["time"]}".black.bold
           end
 
+          # Dim detailed info about rendering views
           match /\s*Rendered\s+(?<view>[^\s]+)\swithin\s(?<layout>[^\s]+)\s\((?<time>.*)\)/ do |msg,match|
             # http://refiddle.com/18qr
-            "  Rendered " + match["view"].white.bold + " within " + match["layout"].white + " " + format_time( match['time'] )
+            "  Rendered #{ match["view"] } within ".black + match["layout"].black.bold + " " + format_time( match['time'].black )
           end
 
+          # Highlight the final rendered response
           match /\s*Completed\s(?<code>\d+)\s(?<friendly>.*)\sin\s(?<time>\d+[^\s]*)\s(?<details>.*)/ do |msg,match|
             # http://refiddle.com/18qq
             parts = [ "Completed" ]
@@ -32,6 +39,7 @@ module Shog
             parts.join(" ")
           end
 
+          # Highlight the controller and action responding to the request
           match /Processing by (?<controller>[^\s]*) as (?<format>.*)/ do |msg,match|
             # http://refiddle.com/18qs
             "Processing by #{match['controller'].magenta.bold} as #{match['format'].yellow}"

data/lib/shog/rails.rb

@@ -2,13 +2,16 @@ require 'rails'
 
 module Shog
   module Rails
+
+    # Automatically integrate Shog with the rails logger.
     class Railtie < ::Rails::Railtie
       config.before_initialize do
         ::Rails.logger.formatter = Shog::Formatter.new.configure do
-          formatter :defaults
-          formatter :requests
+          with :defaults
+          with :requests
         end
       end
     end
+
   end
 end

data/lib/shog/version.rb

@@ -1,5 +1,5 @@
 module Shog
-  VERSION_NUMBER  = "0.0.2"
+  VERSION_NUMBER  = "0.1.0"
   VERSION_SUFFIX  = ""
   VERSION         = "#{VERSION_NUMBER}#{VERSION_SUFFIX}"
 end

data/lib/shog.rb

@@ -5,6 +5,9 @@ require 'shog/rails'
 require 'pry'
 
 module Shog
+
+  # Set up formatting options for the default rails logger.
+  # @see Shog::Formatter#configure
   def self.configure(&block)
     ::Rails.logger.formatter.configure &block
   end

data/spec/lib/shog/formatter_spec.rb

@@ -12,16 +12,70 @@ end
 describe Shog::Formatter do
   let(:formatter){ Shog::Formatter.new }
 
+  describe "#call" do
+    it "without configuration doesn't modify the request" do
+      output = formatter.call "TEST", Time.now, nil, "Unformatted"
+      expect( output ).to eq "Unformatted\n"
+    end
+
+    it "adds severity when at least one is configured" do
+      formatter.severity_tag :debug, ->(msg){ msg }
+      output = formatter.call "DEBUG", Time.now, nil, "Tagged"
+
+      expect( output ).to eq "[DEBUG] Tagged\n"
+    end
+
+    it "adds timestamp when configured" do
+      formatter.timestamp
+      output = formatter.call "WHEN", "just now", nil, "we missed them"
+
+      expect( output ).to eq "[just now] we missed them\n"
+    end
+
+    it "adds progname when configured" do
+      formatter.progname
+      output = formatter.call "NAME", Time.now, "proggy", "magic"
+
+      expect( output ).to eq "[proggy] magic\n"
+    end
+
+    it "adds them all" do
+      formatter.configure do
+        timestamp
+        progname
+        severity_tag :debug, ->(msg){ msg }
+      end
+
+      output = formatter.call "DEBUG", "NOW", "proggy", "gets them all"
+      expect( output ).to eq "[NOW] [proggy] [DEBUG] gets them all\n"
+    end
+  end
+
   describe "#formatted_severity_tag" do
     it "buffers to the same size" do
       formatter.severity_tag( :warn ){ |msg| msg }
       formatter.severity_tag( :longer ){ |msg| msg }
 
-      expect( formatter.formatted_severity_tag( "WARN" ) ).to   eq "WARN  "
-      expect( formatter.formatted_severity_tag( "LONGER" ) ).to eq "LONGER"
+      expect( formatter.formatted_severity_tag( "WARN" ) ).to   eq "[WARN  ]"
+      expect( formatter.formatted_severity_tag( "LONGER" ) ).to eq "[LONGER]"
     end
   end
 
+  describe "#format_time" do
+    it "doesn't change when within expected" do
+      expect( formatter.format_time( "10ms".cyan, 30 ) ).to eq "10ms".cyan
+    end
+
+    it "is yellow when above expected" do
+      expect( formatter.format_time( "50ms", 30 ) ).to eq "50ms".yellow
+    end
+
+    it "is red when way above expected" do
+      expect( formatter.format_time( "150ms", 30 ) ).to eq "150ms".red
+    end
+
+  end
+
   describe "#match" do
     it "formats a matched line" do
       formatter.match /GET/ do |msg,match|
@@ -29,7 +83,7 @@ describe Shog::Formatter do
       end
 
       result = formatter.call "INFO", Time.now, nil, "Started GET \"/Home\""
-      expect( result ).to eq "[INFO] R'DONE\n"
+      expect( result ).to eq "R'DONE\n"
     end
 
     it "includes the match" do
@@ -42,26 +96,44 @@ describe Shog::Formatter do
 
     it "doesn't match" do
       result = formatter.call "INFO", Time.now, nil, "Started GET \"/Home\""
-      expect( result ).to eq "[INFO] Started GET \"/Home\"\n"
+      expect( result ).to eq "Started GET \"/Home\"\n"
     end
 
     it "uses default severity when no matcher is found" do
       formatter.severity( :info ){ |msg| "DEFAULT" }
 
       result = formatter.call "INFO", Time.now, nil, "Started GET \"/Home\""
-      expect( result ).to eq "[INFO] DEFAULT\n"
+      expect( result ).to eq "DEFAULT\n"
     end
   end
 
-  describe "#formatters" do
+  describe "#silence" do
+    it "silences matching logs" do
+      formatter.silence /loud/
+      output = formatter.call "DEBUG", Time.now, nil, "I'm a really loud message"
+      expect(output).to be_nil
+    end
+  end
+
+  describe "#formatter" do
     it "loads from a symbol" do
-      formatter.should_receive(:severity).with(:test, anything())
+      expect( Shog::Formatters::Spec).to receive :configure
+
+      formatter.configure do
+        with :spec
+      end
+    end
+
+    it "lods from a module" do
+      expect( Shog::Formatters::Spec).to receive :configure
 
       formatter.configure do
-        formatter :spec
+        with Shog::Formatters::Spec
       end
     end
   end
 
 
+
+
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: shog
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.1.0
 platform: ruby
 authors:
 - Paul Alexander
@@ -100,6 +100,8 @@ files:
 - Procfile
 - README.md
 - Rakefile
+- docs/images/plain.png
+- docs/images/shogged.png
 - lib/shog.rb
 - lib/shog/formatter.rb
 - lib/shog/formatters.rb