<commit_before>Loggr
=====

Loggr provides a factory for creating logger instances. It:

- Provides a wrapper for SLF4J (on JRuby)
- Has adapters for Stdlib Logger and ActiveSupport::BufferedLogger
- Supports Rails
- Handles using a Mapped Diagnostic Context (MDC)

**So, why should I use a logger factory instead of just `Logger.new('out.log')`
or `Rails.logger`?** Deploying the same application to different environments,
with different logging requirements, might make such a step necessary. Or when
trying to take advante of SLF4J-only features like the MDC or markers.

Information
-----------

**Wiki** The Loggr Wiki will hopefully soon be filled with how-to articles and
frequently asked questions.

https://github.com/at-point/loggr/wiki

**Bug Reports** No software is without bugs, if you discover a problem please report the issue.

https://github.com/at-point/loggr/issues

**Documentation** The latest RDocs are available on rubydoc.info.

http://rubydoc.info/github/at-point/loggr/master/frames

Installation
------------

Like any gem, just add it to the Gemfile:

    # stable version
    gem 'loggr', '~> 1.0.0'
    
    # latest development version
    gem 'loggr', :git => 'git://github.com/at-point/loggr.git'
    
Getting started
===============

Guides through creating some sample Logger instances and integration with Rails, if interested
in using the SLF4J Logger directly (without the factory), skip to _The SLF4J Wrapper_.

An example, application runs in development on MRI and production in a Jetty container
(Java/JRuby), lets assume you want to log there SQL using a logger named `jruby.rails.ActiveRecord`.

    # config/initializers/logging.rb:
    LoggerFactory.adapter = Rails.env.production? ? :slf4j : :rails
    ActiveRecord::Base.logger = LoggerFactory.logger 'jruby.rails.ActiveRecord'

Once an adapter has been specified new logger instances can be easily created using:

    def logger
      @logger ||= LoggerFactory.logger 'my.app.SomeClass', :marker => "WORKER"
    end
    
The adapter then handles creating new logger instances and uses features like the ability
to set markers (if supported), or setting a logger name. Based on the adapter a new logger
will be returned with all things defined like the marker, or a custom logger name - if the
adapter supports it, else it just tries to return a logger which has an API compatible with
those found by Stdlibs Logger.

The LoggerFactory
------------------

Yap, is responsible for creating new loggers, a logger factory has an adapter, the adapter
defines how logger instances are really created.

### Creating new loggers

    LoggerFactory.logger 'app'                      # create a logger with named app
    LoggerFactory.logger 'app', :to => 'debug.out'  # write to debug.out
    LoggerFactory.logger 'app', :to => $stderr      # write to stderr
    
**Note:** not all adapters support all options, so some adapters might just ignore certain
options, but this is intended :)

### Bundled Adapters

**<code>LoggerFactory.adapter = :base</code>**

The base adapter creates ruby stdlib `Logger` instances. Supported options for
`LoggerFactory.logger(name, options = {})` are:

- `:to`, String or IO, where to log should be written to (default: `"#{name}.log"`)
- `:level`, Fixnum, one of `Logger::Severity`, the minimum severity to log (default: `Logger::Severity::DEBUG`)

**<code>LoggerFactory.adapter = :buffered</code>**

Creates `ActiveSupport::BufferedLogger` instances and supports the same options
as the `:base` adapter.

**<code>LoggerFactory.adapter = :rails</code>**

This adapter alwasy returns the `Rails.logger`, which is very useful e.g. in development
environments or testing, where we just care that it's somewhere in our `logs/development.log`.
*Note:* Rails is automatically detected and the rails adapter is the default adapter when
`::Rails` is present - else the base adapter is the default.

**<code>LoggerFactory.adapter = :slf4j</code>**

SLF4J only works with JRuby (because it's Java) and you are responsible for a) having an
SLF4J implementation on the classpath and it's configuration. Furthermore slf4j supports
these options for `LoggerFactory.logger(name, options = {})`:

- `:marker`, String, additional marker logged with each statement (default: `nil`)

### Using the Mapped Diagnostic Context (MDC)

Some loggers provide a MDC (or mapped diagnostic context), which can be used to annotate
log outputs with additional bits of information. At the moment only SLF4J really can make<commit_msg>fix bold & code formatting<commit_after>Loggr
=====

Loggr provides a factory for creating logger instances. It:

- Provides a wrapper for SLF4J (on JRuby)
- Has adapters for Stdlib Logger and ActiveSupport::BufferedLogger
- Supports Rails
- Handles using a Mapped Diagnostic Context (MDC)

**So, why should I use a logger factory instead of just `Logger.new('out.log')`
or `Rails.logger`?** Deploying the same application to different environments,
with different logging requirements, might make such a step necessary. Or when
trying to take advante of SLF4J-only features like the MDC or markers.

Information
-----------

**Wiki** The Loggr Wiki will hopefully soon be filled with how-to articles and
frequently asked questions.

https://github.com/at-point/loggr/wiki

**Bug Reports** No software is without bugs, if you discover a problem please report the issue.

https://github.com/at-point/loggr/issues

**Documentation** The latest RDocs are available on rubydoc.info.

http://rubydoc.info/github/at-point/loggr/master/frames

**Gem** The latest stable gem is always on rubygems.org.

http://rubygems.org/gems/loggr

Installation
------------

Like any gem, just add it to the Gemfile:

    # stable version
    gem 'loggr', '~> 1.0.0'
    
    # latest development version
    gem 'loggr', :git => 'git://github.com/at-point/loggr.git'
    
Getting started
===============

Guides through creating some sample Logger instances and integration with Rails, if interested
in using the SLF4J Logger directly (without the factory), skip to _The SLF4J Wrapper_.

An example, application runs in development on MRI and production in a Jetty container
(Java/JRuby), lets assume you want to log there SQL using a logger named `jruby.rails.ActiveRecord`.

    # config/initializers/logging.rb:
    LoggerFactory.adapter = Rails.env.production? ? :slf4j : :rails
    ActiveRecord::Base.logger = LoggerFactory.logger 'jruby.rails.ActiveRecord'

Once an adapter has been specified new logger instances can be easily created using:

    def logger
      @logger ||= LoggerFactory.logger 'my.app.SomeClass', :marker => "WORKER"
    end
    
The adapter then handles creating new logger instances and uses features like the ability
to set markers (if supported), or setting a logger name. Based on the adapter a new logger
will be returned with all things defined like the marker, or a custom logger name - if the
adapter supports it, else it just tries to return a logger which has an API compatible with
those found by Stdlibs Logger.

The LoggerFactory
------------------

Yap, is responsible for creating new loggers, a logger factory has an adapter, the adapter
defines how logger instances are really created.

### Creating new loggers

    LoggerFactory.logger 'app'                      # create a logger with named app
    LoggerFactory.logger 'app', :to => 'debug.out'  # write to debug.out
    LoggerFactory.logger 'app', :to => $stderr      # write to stderr
    
**Note:** not all adapters support all options, so some adapters might just ignore certain
options, but this is intended :)

### Bundled Adapters

**LoggerFactory.adapter = :base**

The base adapter creates ruby stdlib `Logger` instances. Supported options for
`LoggerFactory.logger(name, options = {})` are:

- `:to`, String or IO, where to log should be written to (default: `"#{name}.log"`)
- `:level`, Fixnum, one of `Logger::Severity`, the minimum severity to log (default: `Logger::Severity::DEBUG`)

**LoggerFactory.adapter = :buffered**

Creates `ActiveSupport::BufferedLogger` instances and supports the same options
as the `:base` adapter.

**LoggerFactory.adapter = :rails**

This adapter alwasy returns the `Rails.logger`, which is very useful e.g. in development
environments or testing, where we just care that it's somewhere in our `logs/development.log`.
*Note:* Rails is automatically detected and the rails adapter is the default adapter when
`::Rails` is present - else the base adapter is the default.

**LoggerFactory.adapter = :slf4j**

SLF4J only works with JRuby (because it's Java) and you are responsible for a) having an
SLF4J implementation on the classpath and it's configuration. Furthermore slf4j supports
these options for `LoggerFactory.logger(name, options = {})`:

- `:marker`, String, additional marker logged with each statement (default: `nil`)

### Using the Mapped Diagnostic Context (MDC)

Some loggers provide a MDC (or mapped diagnostic context), which can be used to annotate
log outputs with additional bits of information. At the moment only SLF4J really can make
{'fraction_non_alphanumeric': 0.09605884290262377, 'fraction_numerical': 0.0028543199033922496, 'mean_word_length': 4.135287485907553, 'pattern_counts': {'":': 0, '<': 11, '<?xml version=': 0, '>': 21, 'https://': 4, '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': '5463451', 'n_tokens_mistral': 2542, 'n_tokens_neox': 2435, 'n_words': 1128}