slog 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: f6281566b29155ca25d47ffda05399f95087c368
-  data.tar.gz: c10525a3d80f1a8d8f77aef31f84328472e1d505
+  metadata.gz: 5d3de78de50b7caaa19ac71dd29c9a7b5acfc3a5
+  data.tar.gz: 0a2ba828d3563e997df44394cee048b1d9ef6638
 SHA512:
-  metadata.gz: 7cbfa8a4d518fe83543b90cd8260b7be6d633630f5be17fb2ac9c3bd1686cd5c5bbee917d4204b16ed1f76e142f44f7991bf3bf4af867546af6b31c6a5f07e4f
-  data.tar.gz: ef037550aebd01bffd8a814879031da6007b18046793a5493ea6dc28e92c82399bedf076ba671e67d9e366e56828e2cb80a4f6c66285fb3e269fbf4c68d04f5e
+  metadata.gz: fda260806e74c4109edd77f0bdebf6b9e236427e0387300fd83eba5828ce396eb2d58340451b42497d70a037769612fc7b02ceb1ab43faed098c2e4d28b46d06
+  data.tar.gz: 76ddc56ef3243f5e3a800f1f47a167a65af6d456f491cceae4e7705fffad2668394a96cbf5da3a2a6fb7e69e9e9e340deb5514ee4943e2a62dd3a0b8ceff2415

data/README.md

@@ -1,38 +1,85 @@
 # Slog
 
-Simple, colorful, JSON-based logging.
-
-## Installation
-
-Add `slog` to your application's Gemspec or Gemfile.
-
-## Usage
+Easy structured logging.
 
 `Slog::Logger` extends the base `Logger` with JSON serialization, colorization,
-a hashified initializer, and a new `TRACE` level:
+and a new `TRACE` level. Output is suitable for collection by Logstash or Franz.
 
 ```ruby
 require 'slog'
 
-# First, these two are equivalent
-logger_one = Slog::Logger.new
-logger_two = Slog.new
 
-# Redirect your logs to STDERR
-Slog.new out: $stderr
+# Full initializer
+Slog::Logger.new \
+             out: $stdout,         # Set the log output handle
+       shift_age: 7,               # Number of log files to keep
+      shift_size: 1_048_576,       # Maximum size of log files (in bytes)
+        colorize: true,            # Toggle colorized output
+        prettify: true,            # Toggle pretty JSON output
+           level: :info,           # Set log level (Logger constant or Symbol)
+ level_transform: 'downcase',      # Transform the log level (String methods)
+     level_field: 'level',         # Set level field name (nil to disable)
+   message_field: 'message',       # Set message field name (nil to disable)
+ timestamp_field: '@timestamp',    # Set timestamp field name (nil to disable)
+timestamp_format: '%FT%T.%3N%:z',  # Set timestamp format (Time#strftime)
+       # Map each log level to fore- and background colors
+       # Colors provided by the fantastic "colorize" gem
+       color_map: { 'debug' => [ :blue,    :default ],
+                    'info'  => [ :green,   :default ],
+                    'warn'  => [ :yellow,  :default ],
+                    'error' => [ :red,     :default ],
+                    'fatal' => [ :red,     :black   ],
+                    'trace' => [ :magenta, :default ] }
+
+
+# These two are equivalent
+Slog::Logger.new
+Slog.new
+
+
+# By default, output is pretty and colored (I swear)
+Slog.new.info 'example'
+#
+#   {
+#     "level": "info",
+#     "@timestamp": "2014-12-25T06:22:43.459-08:00",
+#     "message": "example"
+#   }
+#
+
+
+# When logging to file, you prolly want to disable that
+Slog.new(out: 'test.log', colorize: false, prettify: false).info 'example'
+#
+#   {"level":"info","@timestamp":"2014-12-25T06:25:54.793-08:00","message":"example"}
+#
+
 
-# Set the level with a symbol or Logger constant
-Slog.new level: :trace
+# You'll no doubt have noticed you passed a String into the Logger, but a Hash
+# came out the other end. That's "structured" logging. The String turned into
+# the "message" field, and "level" and "@timestamp" fields were added. All
+# that's totally configurable:
+Slog.new({
+  message_field: nil,
+  timestamp_field: 'date',
+  timestamp_format: '%Y.%m.%d'
+}).info 'example'
+#
+#   {
+#     "level": "info",
+#     "date": "2014.12.25"
+#   }
+#
 
-# When logging to file, you may want to disable colors and pretty output
-Slog.new out: 'test.log', colorization: false, pretty: false
 
-# Finally, all the options and their defaults
-Slog.new \
-         out: $stdout,   # Set the log output handle
-   shift_age: 7,         # Number of log files to keey
-  shift_size: 1_048_576, # Maximum size of log files
-    colorize: true,      # Toggle colorization of logs
-      pretty: true,      # Toggle pretty JSON output
-       level: :info      # Set the initial level
+# You can write structured logs by passing a Hash
+Slog.new({
+  level_field: nil,
+}).info event: 'example', level: 'MINE', '@timestamp' => nil
+#
+#   {
+#     "event": "example",
+#     "level": "MINE"
+#   }
+#
 ```

data/Rakefile

@@ -15,7 +15,7 @@ task default: :test
 
 require 'yard'
 YARD::Rake::YardocTask.new do |t|
-  t.files = %w[ --readme Readme.md lib/**/*.rb - VERSION ]
+  t.files = %w[ --readme Readme.md lib/**/*.rb - VERSION LICENSE ]
 end
 
 

data/VERSION

@@ -1 +1 @@
-1.0.0
+1.1.0

data/lib/slog/logger.rb

@@ -5,7 +5,7 @@ require 'json'
 require 'colorize'
 
 
-# Extending the base Logger class with TRACE capabilities.
+# Extending the base Logger with TRACE capabilities.
 class Logger
 
   # Adding the new severity level
@@ -14,7 +14,7 @@ class Logger
   # So we can reference it by name
   TRACE = SEV_LABEL.index('TRACE')
 
-  # Send a TRACE-level log line
+  # Send a TRACE-level log
   def trace progname, &block
     return true unless @trace
     add TRACE, nil, progname, &block
@@ -26,30 +26,48 @@ end
 
 module Slog
 
-  # A colorful JSON logger.
+  # A colorful structured logger.
   class Logger < Logger
 
     DEFAULT_LEVEL = ::Logger::INFO
 
-    # Maps each log level to a unique combination of fore- and background colors
-    SEVERITY_COLORS = {
-      'debug' => [ :blue,    :default ],
-      'info'  => [ :green,   :default ],
-      'warn'  => [ :yellow,  :default ],
-      'error' => [ :red,     :default ],
-      'fatal' => [ :red,     :black   ],
-      'trace' => [ :magenta, :default ]
-    }
-
-
     # Create a new Logger.
     #
     # A little different than the canonical Logger. Add options to set the
-    # log level and todisable both colorization and pretty JSON output.
-    def initialize out:$stdout, shift_age:7, shift_size:1048576, colorize:true, pretty:true, level:DEFAULT_LEVEL
-      @colorize, @pretty = colorize, pretty
+    # log level and to disable both colorization and pretty JSON output. In
+    # this form, it's perfect for use with either Logstash or Franz.
+    def initialize \
+      out:$stdout,                     # Output handle
+      shift_age:7,                     # Max seven logs
+      shift_size:1_048_576,            # 1024 KiB
+      colorize:true,                   # Disable for files
+      prettify:true,                   # Disable for files
+      level:DEFAULT_LEVEL,             # INFO
+      level_transform:'downcase',      # Any String method
+      level_field:'level',             # nil to disable
+      message_field: 'message',        # nil to disable
+      timestamp_field:'@timestamp',    # nil to disable
+      timestamp_format:'%FT%T.%3N%:z', # ISO-8601
+      color_map: {
+        'debug' => [ :blue,    :default ],
+        'info'  => [ :green,   :default ],
+        'warn'  => [ :yellow,  :default ],
+        'error' => [ :red,     :default ],
+        'fatal' => [ :red,     :black   ],
+        'trace' => [ :magenta, :default ]
+      }
+
+      @prettify = prettify
+      @colorize = colorize
+      @color_map = color_map
+      @level_field = level_field
+      @level_transform = level_transform
+      @timestamp_field = timestamp_field
+      @timestamp_format = timestamp_format
+
       super out, shift_age, shift_size
       self.level = level
+
       set_formatter
     end
 
@@ -57,7 +75,7 @@ module Slog
     # Set the formatter to work our magic
     def set_formatter
       self.formatter = proc do |severity, datetime, _, message|
-        severity.downcase! # It's nicer this way
+        severity.downcase!
 
         # If it ain't a structured log, it is now.
         event = structure_event severity, datetime, message
@@ -67,7 +85,7 @@ module Slog
           event.merge! marker: File.basename(caller[4])
         end
 
-        # Pretty JSON on STDOUT, line-oriented otherwise
+        # Apply colorization and prettification as required
         format_json event, severity
       end
     end
@@ -75,29 +93,33 @@ module Slog
 
     # Turn a call to the formatter into a Hash structure
     def structure_event severity, datetime, message
-      message = { message: message } unless message.is_a? Hash
-      { 'level' => severity,
-        '@timestamp' => datetime.iso8601(3) # Logstash/Franz format
-      }.merge message
+      message = { @message_field => message } unless message.is_a? Hash
+      event = {
+        @level_field => severity.send(@level_transform),
+        @timestamp_field => datetime.strftime(@timestamp_format)
+      }
+      event.merge message
+      event.delete nil # ignore @field if @field.nil?
+      event
     end
 
 
     # Convert the structured event into it's JSON representation
     def format_json event, severity
-      generator = @pretty ? :pretty_generate : :generate
+      generator = @prettify ? :pretty_generate : :generate
       event = JSON.send(generator, event) + "\n"
       return event unless @colorize
       event.colorize \
-          color: SEVERITY_COLORS[severity][0],
-          background: SEVERITY_COLORS[severity][1]
+        color: @color_map[severity][0],
+        background: @color_map[severity][1]
     end
 
 
     # Override the level setter to allow symbols and TRACE
     def level= l
       l = ::Logger.const_get l.upcase if l.is_a? Symbol
-      @trace = l == ::Logger::TRACE
-      l = ::Logger::DEBUG if @trace
+      @trace = l == ::Logger::TRACE # TRACE is really a fancy DEBUG
+      l = ::Logger::DEBUG if @trace # Here's the proof.
       super l
     end
 

data/lib/slog/metadata.rb

@@ -8,7 +8,7 @@ module Slog
   VERSION  = File.read(File.join(ROOT, 'VERSION')).strip
 
   # We don't really do all that much, be humble
-  SUMMARY  = 'Simple, colorful, JSON-based logging'
+  SUMMARY  = 'Easy structured logging'
 
   # Your benevolent dictator for life
   AUTHOR   = 'Sean Clemmer'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: slog
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Sean Clemmer
@@ -24,7 +24,7 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0'
-description: Simple, colorful, JSON-based logging.
+description: Easy structured logging.
 email: sczizzo@gmail.com
 executables: []
 extensions: []
@@ -66,7 +66,7 @@ rubyforge_project:
 rubygems_version: 2.2.2
 signing_key: 
 specification_version: 4
-summary: Simple, colorful, JSON-based logging
+summary: Easy structured logging
 test_files:
 - test/test_helper.rb
 - test/test_slog.rb