Simple logging
Ruby
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
docs Fix up documentation Sep 4, 2017
lib Dev Version: 0.9.1.pre Sep 4, 2017
test Fix #log_exception tests Aug 31, 2017
.gitignore Initial Feb 25, 2012
Gemfile Switch to minitest and clean up testing in general Aug 30, 2017
LICENSE Adjust copyright and begin fleshing out docs. Jan 17, 2014
README.md
Rakefile
scrolls.gemspec Add a license to our gemspec Sep 26, 2013

README.md

Scrolls

Scrolls is a library for generating logs of the structure key=value.

Installation

Add this line to your application's Gemfile:

gem 'scrolls'

And then execute:

$ bundle

Or install it yourself as:

$ gem install scrolls

Philosophy

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.

Usage

0.9.0 and later

require 'scrolls'

Scrolls.init(
  timestamp: true,
  global_context: {app: "scrolls", deploy: "production"},
  exceptions: "multi"
)

Scrolls.log(at: "test")

Scrolls.context(context: "block") do
  Scrolls.log(at: "exec")
end

begin
  raise
rescue Exception => e
  Scrolls.log_exception(e, at: "raise")
end

You can also use Scrolls#log and Scrolls#log_exception without initalizing:

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

require 'scrolls'

Scrolls.add_timestamp = true
Scrolls.global_context(:app => "scrolls", :deploy => "production")

Scrolls.log(:at => "test")

Scrolls.context(:context => "block") do
  Scrolls.log(:at => "exec")
end

begin
  raise
rescue Exception => e
  Scrolls.log_exception(:at => "raise", e)
end

Produces:

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

This library originated from various logging methods used internally 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 to the following people for influencing this library.

  • Mark McGranaghan
  • Noah Zoschke
  • Mark Fine
  • Fabio Kung
  • Ryan Smith

LICENSE

MIT License