Home

Awesome

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
strict_logfmt: 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.

LICENSE

MIT License