scrolls 0.3.5 → 0.3.6

data/LICENSE

@@ -1,5 +1,6 @@
 The MIT License (MIT)
 
+Copyright © Curt Micol <asenchi@asenchi.com> 2012,2013,2014
 Copyright © Heroku 2012
 
 Permission is hereby granted, free of charge, to any person obtaining

data/README.md

@@ -1,10 +1,6 @@
 # Scrolls
 
-Scrolls is a logging library that is focused on outputting logs in a
-key=value structure. It's in use at Heroku where we use the event data
-to drive metrics and monitoring services.
-
-Scrolls is rather opinionated.
+Scrolls is a library for generating logs of the structure `key=value`.
 
 ## Installation
 
@@ -20,115 +16,47 @@ Or install it yourself as:
 
     $ gem install scrolls
 
-## Usage
-
-At Heroku we are big believers in "logs as data". We log everything so
-that we can act upon that event stream of logs. Internally we use logs
-to produce metrics and monitoring data that we can alert on.
-
-Here's an example of a log you might specify in your application:
-
-```ruby
-Scrolls.log(fn: "trap", signal: s, at: "exit", status: 0)
-```
-
-The output of which might be:
-
-    fn=trap signal=TERM at=exit status=0
-
-This provides a rich set of data that we can parse and act upon.
+## Philosophy
 
-A feature of Scrolls is setting contexts. Scrolls has two types of
-context. One is 'global_context' that prepends every log in your
-application with that data and a local 'context' which can be used,
-for example, to wrap requests with a request id.
+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.
 
-In our example above, the log message is rather generic, so in order
-to provide more context we might set a global context that links this
-log data to our application and deployment:
+## Documentation:
 
-```ruby
-Scrolls.global_context(app: "myapp", deploy: ENV["DEPLOY"])
-```
-
-This would change our log output above to:
+I apologize, some of these are a WIP.
 
-    app=myapp deploy=production fn=trap signal=TERM at=exit status=0
+* [Sending logs to syslog using Scrolls](https://github.com/asenchi/scrolls/tree/master/docs/syslog.md)
+* Logging contexts
+* Adding timestamps by default
+* Misc Features
 
-You can also dynamically add some data to the global context like this:
+## Usage
 
 ```ruby
-Scrolls.add_global_context(hostname: `hostname`)
-```
+require 'scrolls'
 
+Scrolls.add_timestamp = true
+Scrolls.global_context(:app => "scrolls", :deploy => ENV["DEPLOY"])
 
-If we were in a file and wanted to wrap a particular point of context
-we might also do something similar to:
+Scrolls.log(:at => "test")
 
-```ruby
-Scrolls.context(ns: "server") do
-  Scrolls.log(fn: "trap", signal: s, at: "exit", status: 0)
+Scrolls.context(:context => "block") do
+  Scrolls.log(:at => "exec")
 end
-```
-
-This would be the output (taking into consideration our global context
-above):
-
-    app=myapp deploy=production ns=server fn=trap signal=TERM at=exit status=0
-
-This allows us to track this log to `Server#trap` and we received a
-'TERM' signal and exited 0.
 
-As you can see we have some standard nomenclature around logging.
-Here's a cheat sheet for some of the methods we use:
-
-* `app`: Application
-* `lib`: Library
-* `ns`: Namespace (Class, Module or files)
-* `fn`: Function
-* `at`: Execution point
-* `deploy`: Our deployment (typically an environment variable i.e. `DEPLOY=staging`)
-* `elapsed`: Measurements (Time)
-* `count`: Measurements (Counters)
-
-Scrolls makes it easy to measure the run time of a portion of code.
-For example:
-
-```ruby
-    Scrolls.log(fn: "test") do
-      Scrolls.log(status: "exec")
-      # Code here
-    end
-```
-
-This will output the following log:
-
-    fn=test at=start
-    status=exec
-    fn=test at=finish elapsed=0.300
-
-You can change the time unit that Scrolls uses to "milliseconds" (the
-default is "seconds"):
-
-```ruby
-    Scrolls.time_unit = "ms"
+begin
+  raise
+rescue Exception => e
+  Scrolls.log_exception(:at => "raise", e)
+end
 ```
 
-Scrolls has a rich #parse method to handle a number of cases. Here is
-a look at some of the ways Scrolls handles certain values.
-
-Time and nil:
+Produces:
 
-```ruby
-    Scrolls.log(t: Time.at(1340118167), this: nil)
-    t=2012-06-19T11:02:47-0400 this=nil
 ```
-
-True/False:
-
-```ruby
-    Scrolls.log(that: false, this: true)
-    that=false this=true
+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>"
 ```
 
 ## History
@@ -138,14 +66,14 @@ at Heroku. Starting at version 0.2.0 Scrolls was ripped apart and
 restructured to provide a better foundation for the future. Tests and
 documentation were add at that point as well.
 
-## Thanks
-
-Most of the ideas used in Scrolls are those of other engineers at
-Heroku, I simply ripped them off to create a single library. Huge
-thanks to:
+Thanks to the following people for influencing this library.
 
 * Mark McGranaghan
 * Noah Zoschke
 * Mark Fine
 * Fabio Kung
 * Ryan Smith
+
+## LICENSE
+
+MIT License

data/docs/syslog.md

@@ -0,0 +1,17 @@
+## Scrolls: Sending data to syslog
+
+By default Scrolls writes log messages to `STDOUT`. With the release of [v0.2.8](https://github.com/asenchi/scrolls/releases/tag/v0.2.8) it is now possible to write to the local system logger. To do so, set `#stream` to "syslog":
+
+```ruby
+Scrolls.stream = "syslog"
+```
+
+This defaults to syslog facility USER and log level ERROR. You can adjust the log facility like so:
+
+```ruby
+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.

data/lib/scrolls/log.rb

@@ -85,6 +85,14 @@ module Scrolls
       @add_timestamp || false
     end
 
+    def single_line_exceptions=(b)
+      @single_line_exceptions = !!b
+    end
+
+    def single_line_exceptions?
+      @single_line_exceptions || false
+    end
+
     def log(data, &blk)
       # If we get a string lets bring it into our structure.
       if data.kind_of? String
@@ -141,20 +149,35 @@ module Scrolls
         logdata = gc.merge(rawhash)
       end
 
-      log(logdata.merge(
-          :at => "exception",
-          :class        => e.class,
-          :message      => e.message,
-          :exception_id => e.object_id.abs
-      ))
+      excepdata = {
+        :at           => "exception",
+        :class        => e.class,
+        :message      => e.message,
+        :exception_id => e.object_id.abs
+      }
+
       if e.backtrace
-        e.backtrace.each do |line|
-          log(logdata.merge(
-              :at => "exception",
-              :class => e.message,
-              :exception_id => e.object_id.abs,
-              :site => line.gsub(/[`'"]/, "")
-          ))
+        if single_line_exceptions?
+          btlines = []
+          e.backtrace.each do |line|
+            btlines << line.gsub(/[`'"]/, "")
+          end
+
+          if btlines.length > 0
+            squish = { :site => btlines.join('\n') }
+            log(logdata.merge(excepdata.merge(squish)))
+          end
+        else
+          log(logdata.merge(excepdata))
+
+          e.backtrace.each do |line|
+            log(logdata.merge(excepdata).merge(
+                :at           => "exception",
+                :class        => e.class,
+                :exception_id => e.object_id.abs,
+                :site         => line.gsub(/[`'"]/, "")
+            ))
+          end
         end
       end
     end

data/lib/scrolls/version.rb

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

data/lib/scrolls.rb

@@ -169,4 +169,26 @@ module Scrolls
     Log.add_timestamp
   end
 
+  # Public: Set whether exceptions should generate a single log
+  # message. (default: false)
+  #
+  # Examples
+  #
+  #   Scrolls.single_line_exceptions = true
+  #
+  def single_line_exceptions=(boolean)
+    Log.single_line_exceptions = boolean
+  end
+
+  # Public: Return whether exceptions generate a single log message.
+  #
+  # Examples
+  #
+  #   Scrolls.single_line_exceptions
+  #   => true
+  #
+  def single_line_exceptions?
+    Log.single_line_exceptions
+  end
+
 end

data/test/test_scrolls.rb

@@ -133,6 +133,16 @@ class TestScrolls < Test::Unit::TestCase
       oneline_backtrace
   end
 
+  def test_single_line_exceptions
+    Scrolls.single_line_exceptions = true
+    begin
+      raise Exception
+    rescue Exception => e
+      Scrolls.log_exception({:o => "o"}, e)
+    end
+    assert_equal 1, @out.string.scan(/.*site=.*/).size
+  end
+
   def test_syslog_integration
     Scrolls.stream = 'syslog'
     assert_equal Scrolls::SyslogLogger, Scrolls.stream.class

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: scrolls
 version: !ruby/object:Gem::Version
-  version: 0.3.5
+  version: 0.3.6
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-01-17 00:00:00.000000000 Z
+date: 2014-01-23 00:00:00.000000000 Z
 dependencies: []
 description: Logging, easier, more consistent.
 email:
@@ -23,6 +23,7 @@ files:
 - LICENSE
 - README.md
 - Rakefile
+- docs/syslog.md
 - lib/scrolls.rb
 - lib/scrolls/atomic.rb
 - lib/scrolls/log.rb