Notarius
Notarius is a logging library with opinions. The word "notarius" is Latin for "shorthand writer". To this end, Notarius does everything possible to encourage you to write short useful log messages.
- Whitespace is converted to spaces.
- Lines are truncated to 140 characters.
- Timestamps are formatted as ISO 8601.
- Call stacks are easy to grep.
- Duplicate messages are discarded.
Notarius does not want you to be happy now, while you're writing code. It wants the person reading your logs at 3am trying to figure out why your code doesn't work to be happy. If those happen to be the same person, Notarius would rather future you be happier.
There is infinitely more future than there is now.
Installation
Notarius is packaged as a Ruby gem. You do gem install notarius
from
the command line to get it.
Configuration
Notarius is namespaced. This lets multiple libraries use Notarius without clobbering each others logs.
require 'notarius'
Notarius.configure 'BIG' do |log|
log.file = '/var/log/notarius/notebook.log'
end
If you try to log to the same file as another library, Notarius will yell at you and throw an exception. Notarius does not want you to obliterate someone else's carefully crafted logs. However, it will tell you what they've namespaced their logs so you can redirect them elsewhere.
By default, Notarius doesn't log to anything, not even the console. If you want console logging, you have to enable it.
Notarius.configure 'BIG' do |log|
log.console = true
end
Notarius is fine with you calling the configure
method multiple times.
This means you can set up defaults when your program starts and change
them later.
Usage
Using Notarius is simple. Include the Notarius::NAME
module (where
NAME is the string you passed to the configure
method) and call
log.info
, log.warn
, or log.error
. You can log anything that
responds to :message
, :backtrace
, or :inspect
.
class Player
include Notarius::BIG
def move direction
log.info "You head off down the #{direction} path."
end
def poke object
log.warn "Gingerly, you nudge the #{object}."
end
def attack monster
if monster.nil?
log.error "You attack the darkness."
else
log.info "You whack the #{monster} with a stick."
end
end
end
Opinions
Notarius only has three logging levels: info, warning, and error. You don't need more than that. If think you do, your logs are too verbose.
There is one line of output per message. If you insert carriage returns and newlines in a message, they will be converted into spaces. The same goes for tabs. Log statements shouldn't read like poetry. Exceptions are the exceptional exception to this rule.
Messages are truncated so the total length of a line is less than 140 characters. This makes them easy to tweet. Tweetablility is important, because it's what the people reading logs at 3am do when they find something hilarious. If you're writing non-tweetable messages, your logs are too verbose.
To make it easy to grep for warnings and errors, messages are output as
"level [timestamp] message". You can do cat notarius.log | grep ^WARN
and find all the warnings in a log.
If the object you pass to the log.info
, log.warn
, and log.error
methods responds to :message
and :backtrace
, you'll get output like
this:
level [timestamp] message
! backtrace
! backtrace
! backtrace
This makes it easy to log exceptions. More importantly, it makes it easy
to find exceptions: cat notarius.log | grep -B 1 "^\!"
If you try to write the same message multiple times, only the first one will show up. This is true even if you change the logging level, or the timestamps of the messages are different. Multiple identical lines in the log are a sign that your code is broken.
Inspiration
At lot of the Notarius philosophy was copied from Logula. The rest of it comes from several years watching sysadmins work, and realizing that programmers often make their lives more difficult than we intend.
Notarius tries to make things easier.
History
See the roadmap for where this is going, and history for where it's been.
License
Notarius is available under an MIT-style license. See the LICENSE document for more information.