scrolls 0.3.6 → 0.3.7

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 0dd730a76cce1b9b08ea5dfe7bae8edb9bed2fc3
+  data.tar.gz: 1d48b1371bff58dc40ce28148ce95f91c756aefa
+SHA512:
+  metadata.gz: 587412cda539145df827237b30a54d651ab67641689b972fe21bf75fcb79702b9263e7bc646b298301d95bcee75e7951be28e294179de3d77e1b3f93b8198b95
+  data.tar.gz: db5eb2c16f307861ffaa1f9ab724e0eae99e675017736466a8e819f358a42cacba914473ce3291f640112ad3bde4d35045e824d78a1ee11e1e2484e5b271441a

data/README.md

@@ -20,6 +20,10 @@ Or install it yourself as:
 
 Scrolls follows the belief that logs should be treated as data. One way to think of them is the blood of your infrastructure. Logs are a realtime view of what is happening on your systems.
 
+## Need to know!
+
+The way Scrolls handles "global_context" is changing after v0.3.8. Please see the [release notes](https://github.com/asenchi/scrolls/releases/tag/v0.3.8) and [this documentation](https://github.com/asenchi/scrolls/tree/master/docs/global-context.md) for more information. I apologize for any trouble this may cause.
+
 ## Documentation:
 
 I apologize, some of these are a WIP.

data/docs/global-context.md

@@ -0,0 +1,53 @@
+## Scrolls: Global Context
+
+Early on Scrolls established a method for adding a "global_context" to log messages. This was perfect for data that should be appended to every log message in a project. Items like environment, request_id, app name all fit perfectly within the global logging context of a project. Later on @slemiere added in a way to dynamically update this global context.
+
+However, due to [changes in Ruby 2.0](https://github.com/asenchi/scrolls/issues/53) it has become necessary to make the global context immutable and thus remove the locking necessary in our atomic operation. The effects of which Scrolls API changes slightly.
+
+Previously, the global context was set using the following:
+
+```ruby
+require 'scrolls'
+
+Scrolls.global_context(:app => example)
+Scrolls.log(:at => test)
+```
+
+However, this will no longer be the method used. All releases after 0.3.8 will use the following method:
+
+```ruby
+require 'scrolls'
+
+Scrolls.init(
+  :global_context => { :app => example }
+)
+Scrolls.log(:at => test)
+```
+
+`Scrolls#init` is a new method for initializing the internal Logger in Scrolls and will allow other configuration details to be set. Once the work is finalized more documentation on this method will be available and linked here. Until then you can follow along with development [here](https://github.com/asenchi/scrolls/pulls/54). It was introduced in `0.3.8` to allow developers to start moving toward that pattern.
+
+Here is a another example:
+
+```ruby
+Scrolls.init(
+  :global_context => {:g => "g"},
+  :timestamp      => true,
+  :exceptions     => "single",
+)
+
+Scrolls.log(:t => "t")
+```
+
+Is the same as this currently:
+
+```ruby
+Scrolls.global_context(:g => "g")
+Scrolls.add_timestamp = true
+Scrolls.single_line_exceptions = true
+
+Scrolls.log(:t => "t")
+```
+
+All of this also means that the "global_context" is no longer mutable and `Scrolls#add_global_context` will be deprecated.
+
+I apologize for the incompatability of these changes, I work very hard not to break existing behavior. However, with the changes in Ruby core, I think we have a better path forward. I'm looking forward to "cementing" the API and releasing a 1.0 soon after this major refactor.

data/lib/scrolls.rb

@@ -6,6 +6,37 @@ require "scrolls/version"
 module Scrolls
   extend self
 
+  # Public: Initialize a Scrolls logger
+  #
+  # Convienence method to prepare for future releases. Currently mimics
+  # behavior found in other methods. This prepares the developer for a future
+  # backward incompatible change, see:
+  # https://github.com/asenchi/scrolls/pull/54
+  #
+  # options - A hash of key/values for configuring Scrolls
+  #
+  def init(options)
+    stream     = options.fetch(:stream, STDOUT)
+    facility   = options.fetch(:facility, Syslog::LOG_USER)
+    time_unit  = options.fetch(:time_unit, "seconds")
+    timestamp  = options.fetch(:timestamp, false)
+    exceptions = options.fetch(:exceptions, "multi")
+    global_ctx = options.fetch(:global_context, {})
+
+    Log.stream    = stream
+    Log.facility  = facility if facility
+    Log.time_unit = time_unit unless time_unit == "seconds"
+    Log.add_timestamp = timestamp unless timestamp == false
+
+    if exceptions == "single"
+      Log.single_line_exceptions = true
+    end
+
+    unless global_ctx == {}
+      Log.global_context = global_ctx
+    end
+  end
+
   # Public: Set a context in a block for logs
   #
   # data - A hash of key/values to prepend to each log in a block
@@ -17,11 +48,16 @@ module Scrolls
     Log.with_context(data, &blk)
   end
 
-  # Public: Get or set a global context that prefixs all logs
+  # Deprecated: Get or set a global context that prefixs all logs
   #
   # data - A hash of key/values to prepend to each log
   #
+  # This method will be deprecated two releases after 0.3.8.
+  # See https://github.com/asenchi/scrolls/releases/tag/v0.3.8
+  # for more details.
+  #
   def global_context(data=nil)
+    $stderr.puts "global_context() will be deprecated after v0.3.8, please see https://github.com/asenchi/scrolls for more information."
     if data
       Log.global_context = data
     else
@@ -29,7 +65,16 @@ module Scrolls
     end
   end
 
+  # Deprecated: Get or set a global context that prefixs all logs
+  #
+  # data - A hash of key/values to prepend to each log
+  #
+  # This method will be deprecated two releases after 0.3.8.
+  # See https://github.com/asenchi/scrolls/releases/tag/v0.3.8
+  # for more details.
+  #
   def add_global_context(data)
+    $stderr.puts "add_global_context will be deprecated after v0.3.8, please see https://github.com/asenchi/scrolls for more information."
     Log.add_global_context(data)
   end
 
@@ -45,9 +90,9 @@ module Scrolls
   #   => nil
   #
   #   Scrolls.log(test: "test") { puts "inner block" }
-  #   at=start
+  #   test=test at=start
   #   inner block
-  #   at=finish elapsed=0.000
+  #   test=test at=finish elapsed=0.000
   #   => nil
   #
   def log(data, &blk)
@@ -191,4 +236,110 @@ module Scrolls
     Log.single_line_exceptions
   end
 
+  # Public: Convience method for Logger replacement
+  #
+  # data - A hash of key/values to log
+  # blk  - A block to be wrapped by log lines
+  #
+  # Examples:
+  #
+  #   Scrolls.debug(test: "test")
+  #   test=test level=debug
+  #   => nil
+  #
+  def debug(data, &blk)
+    data = data.merge(:level => "debug")
+    Log.log(data, &blk)
+  end
+
+  # Public: Convience method for Logger replacement
+  #
+  # Translates the `level` to Syslog equivalent
+  #
+  # data - A hash of key/values to log
+  # blk  - A block to be wrapped by log lines
+  #
+  # Examples:
+  #
+  #   Scrolls.error(test: "test")
+  #   test=test level=warning
+  #   => nil
+  #
+  def error(data, &blk)
+    data = data.merge(:level => "warning")
+    Log.log(data, &blk)
+  end
+
+  # Public: Convience method for Logger replacement
+  #
+  # Translates the `level` to Syslog equivalent
+  #
+  # data - A hash of key/values to log
+  # blk  - A block to be wrapped by log lines
+  #
+  # Examples:
+  #
+  #   Scrolls.fatal(test: "test")
+  #   test=test level=error
+  #   => nil
+  #
+  def fatal(data, &blk)
+    data = data.merge(:level => "error")
+    Log.log(data, &blk)
+  end
+
+  # Public: Convience method for Logger replacement
+  #
+  # Translates the `level` to Syslog equivalent
+  #
+  # data - A hash of key/values to log
+  # blk  - A block to be wrapped by log lines
+  #
+  # Examples:
+  #
+  #   Scrolls.info(test: "test")
+  #   test=test level=info
+  #   => nil
+  #
+  def info(data, &blk)
+    data = data.merge(:level => "info")
+    Log.log(data, &blk)
+  end
+
+  # Public: Convience method for Logger replacement
+  #
+  # Translates the `level` to Syslog equivalent
+  #
+  # data - A hash of key/values to log
+  # blk  - A block to be wrapped by log lines
+  #
+  # Examples:
+  #
+  #   Scrolls.warn(test: "test")
+  #   test=test level=notice
+  #   => nil
+  #
+  def warn(data, &blk)
+    data = data.merge(:level => "notice")
+    Log.log(data, &blk)
+  end
+
+  # Public: Convience method for Logger replacement
+  #
+  # Translates the `level` to Syslog equivalent
+  #
+  # data - A hash of key/values to log
+  # blk  - A block to be wrapped by log lines
+  #
+  # Examples:
+  #
+  #   Scrolls.unknown(test: "test")
+  #   test=test level=alert
+  #   => nil
+  #
+  def unknown(data, &blk)
+    data = data.merge(:level => "alert")
+    Log.log(data, &blk)
+  end
+
 end

data/lib/scrolls/log.rb

@@ -12,7 +12,7 @@ module Scrolls
     extend Parser
     extend Utils
 
-    LOG_LEVEL = (ENV['LOG_LEVEL'] || 3).to_i
+    LOG_LEVEL = (ENV['LOG_LEVEL'] || 6).to_i
     LOG_LEVEL_MAP = {
       "emergency" => 0,
       "alert"     => 1,

data/lib/scrolls/version.rb

@@ -1,3 +1,3 @@
 module Scrolls
-  VERSION = "0.3.6"
+  VERSION = "0.3.7"
 end

data/test/test_scrolls.rb

@@ -24,14 +24,16 @@ class TestScrolls < Test::Unit::TestCase
   def test_setting_global_context
     Scrolls.global_context(:g => "g")
     Scrolls.log(:d => "d")
-    assert_equal "g=g d=d\n", @out.string
+    global = @out.string.gsub("\n", 'XX')
+    assert_match /g=g.*d=d/, global
   end
   
   def test_adding_to_global_context
     Scrolls.global_context(:g => "g")
     Scrolls.add_global_context(:h => "h")
     Scrolls.log(:d => "d")
-    assert_equal "g=g h=h d=d\n", @out.string
+    global = @out.string.gsub("\n", 'XX')
+    assert_match /g=g.*h=h.*d=d/, global
   end
 
   def test_default_context
@@ -53,9 +55,8 @@ class TestScrolls < Test::Unit::TestCase
       end
       Scrolls.log(:i => "i")
     end
-    @out.truncate(37)
-    output = "g=g o=o at=start\ng=g c=c ic=i\ng=g i=i"
-    assert_equal output, @out.string
+    global = @out.string.gsub("\n", 'XX')
+    assert_match /g=g.*at=start.*i=i/, global
   end
 
   def test_deeply_nested_context
@@ -175,4 +176,32 @@ class TestScrolls < Test::Unit::TestCase
     Scrolls.log("string")
     assert_equal "log_message=string\n", @out.string
   end
+
+  def test_default_logging_levels
+    Scrolls.debug(:t => "t")
+    assert_equal "", @out.string
+    Scrolls.info(:t => "t")
+    assert_equal "t=t level=info\n", @out.string
+  end
+
+  def test_level_translation_error
+    Scrolls.error(:t => "t")
+    assert_equal "t=t level=warning\n", @out.string
+  end
+
+  def test_level_translation_fatal
+    Scrolls.fatal(:t => "t")
+    assert_equal "t=t level=error\n", @out.string
+  end
+
+  def test_level_translation_warn
+    Scrolls.warn(:t => "t")
+    assert_equal "t=t level=notice\n", @out.string
+  end
+
+  def test_level_translation_unknown
+    Scrolls.unknown(:t => "t")
+    assert_equal "t=t level=alert\n", @out.string
+  end
+
 end

metadata

@@ -1,15 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: scrolls
 version: !ruby/object:Gem::Version
-  version: 0.3.6
-  prerelease: 
+  version: 0.3.7
 platform: ruby
 authors:
 - Curt Micol
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-01-23 00:00:00.000000000 Z
+date: 2014-02-10 00:00:00.000000000 Z
 dependencies: []
 description: Logging, easier, more consistent.
 email:
@@ -18,11 +17,12 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- .gitignore
+- ".gitignore"
 - Gemfile
 - LICENSE
 - README.md
 - Rakefile
+- docs/global-context.md
 - docs/syslog.md
 - lib/scrolls.rb
 - lib/scrolls/atomic.rb
@@ -39,27 +39,26 @@ files:
 homepage: https://github.com/asenchi/scrolls
 licenses:
 - MIT
+metadata: {}
 post_install_message: 
 rdoc_options: []
 require_paths:
 - 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.23
+rubygems_version: 2.2.0
 signing_key: 
-specification_version: 3
+specification_version: 4
 summary: When do we log? All the time.
 test_files:
 - test/test_atomic.rb