<commit_before>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.

```ruby
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.

```ruby
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 an `:inspect` message.

```ruby
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 `info`, `warn`, and `error` methods
responds to `:message` and `:backtrace` messages, you'll get output
like this:

```bash
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][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.<commit_msg>Being more explicit about what objects can be logged.<commit_after>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.

```ruby
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.

```ruby
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`.

```ruby
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 `info`, `warn`, and `error` methods
responds to `:message` and `:backtrace`, you'll get output like this:

```bash
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][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.
{'fraction_non_alphanumeric': 0.0715913179038254, 'fraction_numerical': 0.003117879841707639, 'mean_word_length': 3.7711670480549198, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '157090', 'n_tokens_mistral': 2349, 'n_tokens_neox': 2211, 'n_words': 1279}