scrolls 0.3.7 → 0.9.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 0dd730a76cce1b9b08ea5dfe7bae8edb9bed2fc3
-  data.tar.gz: 1d48b1371bff58dc40ce28148ce95f91c756aefa
+SHA256:
+  metadata.gz: ef35d7cda907156c55fc36b1486539ac755beb03fc91fd686e396f06609dc9f3
+  data.tar.gz: aa19774eeb977616f7e5e64b713bd612c870357ed640134c9dc9ad50d33e7c46
 SHA512:
-  metadata.gz: 587412cda539145df827237b30a54d651ab67641689b972fe21bf75fcb79702b9263e7bc646b298301d95bcee75e7951be28e294179de3d77e1b3f93b8198b95
-  data.tar.gz: db5eb2c16f307861ffaa1f9ab724e0eae99e675017736466a8e819f358a42cacba914473ce3291f640112ad3bde4d35045e824d78a1ee11e1e2484e5b271441a
+  metadata.gz: fab8615f38a24e2767bb2f4b1d291f744130af82ee3326109e2c74b8d769d525cfeb761c021f4dc5c95e7fbf859a9bb5db21b29a90c11b948107e11bfc935245
+  data.tar.gz: 37b338406b11a641ec6afb8ae28384d0460d3bf3970dd9c083cdc8eaa999d4bd4cf7b5c0dd2929719bda7751ea03cb2f7771dc06fe8911a306a0c74bedc355f0

data/Gemfile

@@ -4,5 +4,7 @@ source 'https://rubygems.org'
 gemspec
 
 group :test do
+  gem "minitest", require: 'minitest/autorun'
+  gem "minitest-reporters"
   gem "rake"
 end

data/README.md

@@ -20,26 +20,64 @@ 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!
+## Usage
+
+### 0.9.0 and later
 
-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.
+```ruby
+require 'scrolls'
 
-## Documentation:
+Scrolls.init(
+  timestamp: true,
+  global_context: {app: "scrolls", deploy: "production"},
+  exceptions: "multi"
+)
 
-I apologize, some of these are a WIP.
+Scrolls.log(at: "test")
 
-* [Sending logs to syslog using Scrolls](https://github.com/asenchi/scrolls/tree/master/docs/syslog.md)
-* Logging contexts
-* Adding timestamps by default
-* Misc Features
+Scrolls.context(context: "block") do
+  Scrolls.log(at: "exec")
+end
 
-## Usage
+begin
+  raise
+rescue Exception => e
+  Scrolls.log_exception(e, at: "raise")
+end
+```
+
+You can also use `Scrolls#log` and `Scrolls#log_exception` without initalizing:
+
+```ruby
+require 'scrolls'
+
+Scrolls.log(test: "test")
+```
+
+### Defaults
+
+Here are the defaults `Scrolls#init`:
+
+```
+stream: STDOUT
+facility: Syslog::LOG_USER
+time_unit: "seconds"
+timestamp: false
+exceptions: "single"
+global_context: {}
+syslog_options: Syslog::LOG_PID|Syslog::LOG_CONS
+escape_keys: false
+```
+
+## Older Versions
+
+### Pre 0.9.0
 
 ```ruby
 require 'scrolls'
 
 Scrolls.add_timestamp = true
-Scrolls.global_context(:app => "scrolls", :deploy => ENV["DEPLOY"])
+Scrolls.global_context(:app => "scrolls", :deploy => "production")
 
 Scrolls.log(:at => "test")
 
@@ -57,10 +95,10 @@ end
 Produces:
 
 ```
-now="2014-01-17T16:11:39Z" app=scrolls deploy=nil at=test
-now="2014-01-17T16:11:39Z" app=scrolls deploy=nil context=block at=exec
-now="2014-01-17T16:11:39Z" app=scrolls deploy=nil at=exception class=RuntimeError message= exception_id=70312608019740
-now="2014-01-17T16:11:39Z" app=scrolls deploy=nil at=exception class= exception_id=70312608019740 site="./test.rb:16:in <main>"
+now="2017-09-01T00:37:13Z" app=scrolls deploy=production at=test
+now="2017-09-01T00:37:13Z" app=scrolls deploy=production context=block at=exec
+now="2017-09-01T00:37:13Z" app=scrolls deploy=production at=exception class=RuntimeError exception_id=70149797587080
+now="2017-09-01T00:37:13Z" app=scrolls deploy=production at=exception class=RuntimeError exception_id=70149797587080 site="./test-scrolls.rb:16:in <main>"
 ```
 
 ## History

data/Rakefile

@@ -1,11 +1,13 @@
 #!/usr/bin/env rake
+
 require "bundler/gem_tasks"
+require "rake/testtask"
 
 ENV['TESTOPTS'] = "-v"
 
-require "rake/testtask"
 Rake::TestTask.new do |t|
-  t.pattern = "test/test_*.rb"
+  t.test_files = FileList["test/**/test_*.rb"]
+  t.verbose = true
 end
 
 task :default => :test

data/docs/global-context.md

@@ -38,7 +38,7 @@ Scrolls.init(
 Scrolls.log(:t => "t")
 ```
 
-Is the same as this currently:
+Is the same as this in versions prior to 0.9.0:
 
 ```ruby
 Scrolls.global_context(:g => "g")

data/docs/syslog.md

@@ -6,6 +6,14 @@ By default Scrolls writes log messages to `STDOUT`. With the release of [v0.2.8]
 Scrolls.stream = "syslog"
 ```
 
+Or using `Scrolls#init` in versions 0.9.0 and after:
+
+```ruby
+Scrolls.init(
+    stream: "syslog"
+)
+```
+
 This defaults to syslog facility USER and log level ERROR. You can adjust the log facility like so:
 
 ```ruby
@@ -14,4 +22,9 @@ Scrolls.facility = "local7"
 
 Scrolls generally doesn't care about log levels. The library defaults to ERROR (or 3), but ultimately is of the opinion that levels are useless. The reasoning behind this is that applications should log useful data, all of the time. Debugging data is great for development, but should never be deployed. The richness of structured logging allows exceptions and error messages to sit along side the context of the data in which the error was thrown, there is no need to send to an "emergency" level.
 
-With that said, if one wanted to adjust the log level, you can set an environment variable `LOG_LEVEL`. This allows this particular feature to be rather fluid throughout your application.
+With that said, if one wanted to adjust the log level, you can set an environment variable `LOG_LEVEL` or use one of the level methods. This allows this particular feature to be rather fluid throughout your application.
+
+```ruby
+Scrolls.info(d: "data")
+Scrolls.warn(d: "data")
+```

data/lib/scrolls.rb

@@ -1,6 +1,4 @@
-require "thread"
-require "scrolls/atomic"
-require "scrolls/log"
+require "scrolls/logger"
 require "scrolls/version"
 
 module Scrolls
@@ -8,33 +6,26 @@ module Scrolls
 
   # 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
+  #   stream         - Stream to output data (default: STDOUT)
+  #   log_facility   - Syslog facility (default: Syslog::LOG_USER)
+  #   time_unit      - Unit of time (default: seconds)
+  #   timestamp      - Prepend logs with a timestamp (default: false)
+  #   exceptions     - Method for outputting exceptions (default: single line)
+  #   global_context - Immutable context to prepend all messages with
+  #   syslog_options - Syslog options (default: Syslog::LOG_PID|Syslog::LOG_CONS)
+  #   escape_keys    - Escape chars in keys
+  #
+  def init(options={})
+    # Set a hint whether #init was called.
+    @initialized = true
+    @log = Logger.new(options)
+  end
 
-    unless global_ctx == {}
-      Log.global_context = global_ctx
-    end
+  # Public: Get the primary logger
+  #
+  def logger
+    @log.logger
   end
 
   # Public: Set a context in a block for logs
@@ -45,37 +36,13 @@ module Scrolls
   # Examples:
   #
   def context(data, &blk)
-    Log.with_context(data, &blk)
-  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 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
-      Log.global_context
-    end
+    @log.with_context(data, &blk)
   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.
+  # Public: Get the global context that prefixs all logs
   #
-  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)
+  def global_context
+    @log.global_context
   end
 
   # Public: Log data and/or wrap a block with start/finish
@@ -96,26 +63,32 @@ module Scrolls
   #   => nil
   #
   def log(data, &blk)
-    Log.log(data, &blk)
+    # Allows us to call #log directly and initialize defaults
+    @log = Logger.new({}) unless @initialized
+
+    @log.log(data, &blk)
   end
 
   # Public: Log an exception
   #
-  # data - A hash of key/values to log
   # e    - An exception to pass to the logger
+  # data - A hash of key/values to log
   #
   # Examples:
   #
   #   begin
   #     raise Exception
   #   rescue Exception => e
-  #     Scrolls.log_exception({test: "test"}, e)
+  #     Scrolls.log_exception(e, {test: "test"})
   #   end
   #   test=test at=exception class=Exception message=Exception exception_id=70321999017240
   #   ...
   #
-  def log_exception(data, e)
-    Log.log_exception(data, e)
+  def log_exception(e, data)
+    # Allows us to call #log directly and initialize defaults
+    @log = Logger.new({}) unless @initialized
+
+    @log.log_exception(e, data)
   end
 
   # Public: Setup a logging facility (default: Syslog::LOG_USER)
@@ -127,7 +100,7 @@ module Scrolls
   #   Scrolls.facility = Syslog::LOG_LOCAL7
   #
   def facility=(f)
-    Log.facility=(f)
+    @log.facility=(f)
   end
 
   # Public: Return the Syslog facility
@@ -138,7 +111,7 @@ module Scrolls
   #   => 8
   #
   def facility
-    Log.facility
+    @log.facility
   end
 
   # Public: Setup a new output (default: STDOUT)
@@ -154,7 +127,7 @@ module Scrolls
   #   Scrolls.stream = StringIO.new
   #
   def stream=(out)
-    Log.stream=(out)
+    @log.stream=(out)
   end
 
   # Public: Return the stream
@@ -165,7 +138,7 @@ module Scrolls
   #   => #<IO:<STDOUT>>
   #
   def stream
-    Log.stream
+    @log.stream
   end
 
   # Public: Set the time unit we use for 'elapsed' (default: "seconds")
@@ -177,7 +150,7 @@ module Scrolls
   #   Scrolls.time_unit = "milliseconds"
   #
   def time_unit=(unit)
-    Log.time_unit=(unit)
+    @log.time_unit = unit
   end
 
   # Public: Return the time unit currently configured
@@ -188,7 +161,7 @@ module Scrolls
   #   => "seconds"
   #
   def time_unit
-    Log.time_unit
+    @log.time_unit
   end
 
   # Public: Set whether to include a timestamp (now=<ISO8601>) field in the log
@@ -199,7 +172,7 @@ module Scrolls
   #   Scrolls.add_timestamp = true
   #
   def add_timestamp=(boolean)
-    Log.add_timestamp = boolean
+    @log.timestamp = boolean
   end
 
   # Public: Return whether the timestamp field will be included in the log
@@ -211,7 +184,7 @@ module Scrolls
   #   => true
   #
   def add_timestamp
-    Log.add_timestamp
+    @log.timestamp
   end
 
   # Public: Set whether exceptions should generate a single log
@@ -222,7 +195,7 @@ module Scrolls
   #   Scrolls.single_line_exceptions = true
   #
   def single_line_exceptions=(boolean)
-    Log.single_line_exceptions = boolean
+    @log.exceptions = boolean
   end
 
   # Public: Return whether exceptions generate a single log message.
@@ -233,7 +206,7 @@ module Scrolls
   #   => true
   #
   def single_line_exceptions?
-    Log.single_line_exceptions
+    @log.single_line_exceptions?
   end
 
   # Public: Convience method for Logger replacement
@@ -248,8 +221,8 @@ module Scrolls
   #   => nil
   #
   def debug(data, &blk)
-    data = data.merge(:level => "debug")
-    Log.log(data, &blk)
+    data = data.merge(:level => "debug") if data.is_a?(Hash)
+    @log.log(data, &blk)
   end
 
   # Public: Convience method for Logger replacement
@@ -266,8 +239,8 @@ module Scrolls
   #   => nil
   #
   def error(data, &blk)
-    data = data.merge(:level => "warning")
-    Log.log(data, &blk)
+    data = data.merge(:level => "warning") if data.is_a?(Hash)
+    @log.log(data, &blk)
   end
 
   # Public: Convience method for Logger replacement
@@ -284,8 +257,8 @@ module Scrolls
   #   => nil
   #
   def fatal(data, &blk)
-    data = data.merge(:level => "error")
-    Log.log(data, &blk)
+    data = data.merge(:level => "error") if data.is_a?(Hash)
+    @log.log(data, &blk)
   end
 
   # Public: Convience method for Logger replacement
@@ -302,8 +275,8 @@ module Scrolls
   #   => nil
   #
   def info(data, &blk)
-    data = data.merge(:level => "info")
-    Log.log(data, &blk)
+    data = data.merge(:level => "info") if data.is_a?(Hash)
+    @log.log(data, &blk)
   end
 
   # Public: Convience method for Logger replacement
@@ -320,8 +293,8 @@ module Scrolls
   #   => nil
   #
   def warn(data, &blk)
-    data = data.merge(:level => "notice")
-    Log.log(data, &blk)
+    data = data.merge(:level => "notice") if data.is_a?(Hash)
+    @log.log(data, &blk)
   end
 
   # Public: Convience method for Logger replacement
@@ -338,8 +311,14 @@ module Scrolls
   #   => nil
   #
   def unknown(data, &blk)
-    data = data.merge(:level => "alert")
-    Log.log(data, &blk)
+    data = data.merge(:level => "alert") if data.is_a?(Hash)
+    @log.log(data, &blk)
+  end
+
+  # Internal: The Logger initialized by #init
+  #
+  def internal
+    @log
   end
 
 end