Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/rudionrails/yell

Yell - Your Extensible Logging Library
https://github.com/rudionrails/yell

Last synced: 12 days ago
JSON representation

Yell - Your Extensible Logging Library

Host: GitHub
URL: https://github.com/rudionrails/yell
Owner: rudionrails
License: mit
Created: 2011-10-23T19:18:36.000Z (about 13 years ago)
Default Branch: master
Last Pushed: 2022-10-21T14:28:28.000Z (about 2 years ago)
Last Synced: 2024-04-23T10:36:17.584Z (7 months ago)
Language: Ruby
Homepage:
Size: 631 KB
Stars: 311
Watchers: 7
Forks: 23
Open Issues: 5
Metadata Files:
- Readme: README.md
- License: LICENSE.txt

Awesome Lists containing this project

awesome-ruby - Yell - Your Extensible Logging Library. (Logging)

README

# Yell [![Gem Version](https://badge.fury.io/rb/yell.svg)](http://badge.fury.io/rb/yell) [![Build Status](https://travis-ci.org/rudionrails/yell.svg?branch=master)](https://travis-ci.org/rudionrails/yell) [![Code Climate](https://codeclimate.com/github/rudionrails/yell.svg)](https://codeclimate.com/github/rudionrails/yell) [![Coverage Status](https://coveralls.io/repos/rudionrails/yell/badge.svg?branch=master)](https://coveralls.io/r/rudionrails/yell)

**Yell - Your Extensible Logging Library** is a comprehensive logging replacement for Ruby.

Yell works and its test suite currently runs on:

- ruby-head, 2.3.1, 2.2.5, 2.2.2, 2.1.0, 2.0.0
- jruby-head, jruby-9.1.0.0, jruby-9.0.0.0

If you want to conveniently use Yell with Rails, then head over to [yell-rails](https://github.com/rudionrails/yell-rails). You'll find all the documentation in this repository, though.

## Installation

System wide:

```console
gem install yell
```

Or in your Gemfile:

```ruby
gem "yell"
```

## Usage

On the basics, you can use Yell just like any other logging library with a more
sophisticated message formatter.

```ruby
logger = Yell.new STDOUT

logger.info "Hello World"
#=> "2012-02-29T09:30:00+01:00 [ INFO] 65784 : Hello World"
# ^ ^ ^ ^
# ISO8601 Timestamp Level Pid Message
```

The strength of Yell, however, comes when using multiple adapters. The already built-in
ones are IO-based and require no further configuration. Also, there are additional ones
available as separate gems. Please consult the [wiki](https://github.com/rudionrails/yell/wiki)
on that - they are listed there.

The standard adapters are:

`:stdout` : Messages will be written to STDOUT
`:stderr` : Messages will be written to STDERR
`:file` : Messages will be written to a file
`:datefile` : Messages will be written to a timestamped file

Here are some short examples on how to combine them:

##### Example: Notice messages go into `STDOUT` and error messages into `STDERR`

```ruby
logger = Yell.new do |l|
l.adapter STDOUT, level: [:debug, :info, :warn]
l.adapter STDERR, level: [:error, :fatal]
end
```

##### Example: Typical production Logger

We setup a logger that starts passing messages at the `:info` level. Severities
below `:error` go into the 'production.log', whereas anything higher is written
into the 'error.log'.

```ruby
logger = Yell.new do |l|
l.level = 'gte.info' # will only pass :info and above to the adapters

l.adapter :datefile, 'production.log', level: 'lte.warn' # anything lower or equal to :warn
l.adapter :datefile, 'error.log', level: 'gte.error' # anything greater or equal to :error
end
```

##### Example: Typical production Logger for Heroku

When deploying to Heroku, the "rails_log_stdout" gem gets injected to your Rails project.
Yell does not need that when properly configured (see [yell-rails](https://github.com/rudionrails/yell-rails)
for a more convenient integration with Rails).

```ruby
logger = Yell.new do |l|
l.level = 'gte.info'

l.adapter :stdout, level: 'lte.warn'
l.adapter :stderr, level: 'gte.error'
end
```

### But I'm used to Log4r and I don't want to move on

One of the really nice features of Log4r is its repository. The following example is
taken from the official Log4r [documentation](http://log4r.rubyforge.org/manual.html#outofbox).

```ruby
require 'log4r'
include Log4r

# create a logger named 'mylog' that logs to stdout
mylog = Logger.new 'mylog'
mylog.outputters = Outputter.stdout

# later in the code, you can get the logger back
Logger['mylog']
```

With Yell you can do the same thing with less:

```ruby
require 'yell'

# create a logger named 'mylog' that logs to stdout
Yell.new :stdout, name: 'mylog'

# later in the code, you can get the logger back
Yell['mylog']
```

There is no need to define outputters separately and you don't have to taint
you global namespace with Yell's subclasses.

### Adding a logger to an existing class

Yell comes with a simple module: +Yell::Loggable+. Simply include this in a class and
you are good to go.

```ruby
# Before you can use it, you will need to define a logger and
# provide it with the `:name` of your class.
Yell.new :stdout, name: 'Foo'

class Foo
include Yell::Loggable
end

# Now you can log
Foo.logger.info "Hello World"
Foo.new.logger.info "Hello World"
```

It even works with class inheritance:

```ruby
# Given the above example, we inherit from Foo
class Bar < Foo
end

# The logger will fallback to the Foo superclass
Bar.logger.info "Hello World"
Bar.new.logger.info "Hello World"
```

### Adding a logger to all classes at once (global logger)

Derived from the example above, simply do the following.

```ruby
# Define a logger and pass `Object` as name. Internally, Yell adds this
# logger to the repository where you can access it later on.
Yell.new :stdout, name: Object

# Enable logging for the class that (almost) every Ruby class inherits from
Object.send :include, Yell::Loggable

# now you are good to go... from wherever you are
logger.info "Hello from anything"
Integer.logger.info "Hello from Integer"
```

### Suppress log messages with silencers

In case you woul like to suppress certain log messages, you may define
silencers with Yell. Use this to get control of a noisy log environment. For
instance, you can suppress logging messages that contain secure information or
more simply, to skip information about serving your Rails assets. Provide a
string or a regular expression of the message patterns you would like to exclude.

```ruby
logger = Yell.new do |l|
l.silence /^Started GET "\/assets/
l.silence /^Served asset/
end

logger.debug 'Started GET "/assets/logo.png" for 127.0.0.1 at 2013-06-20 10:18:38 +0200'
logger.debug 'Served asset /logo.png - 304 Not Modified (0ms)'
```

### Alter log messages with modifiers

## Further Readings

[How To: Setting The Log Level](https://github.com/rudionrails/yell/wiki/101-setting-the-log-level)
[How To: Formatting Log Messages](https://github.com/rudionrails/yell/wiki/101-formatting-log-messages)
[How To: Using Adapters](https://github.com/rudionrails/yell/wiki/101-using-adapters)
[How To: The Datefile Adapter](https://github.com/rudionrails/yell/wiki/101-the-datefile-adapter)
[How To: Different Adapters for Different Log Levels](https://github.com/rudionrails/yell/wiki/101-different-adapters-for-different-log-levels)

### Additional Adapters
[Syslog](https://github.com/rudionrails/yell/wiki/additional-adapters-syslog)
[syslog-sd](https://github.com/raymond-wells/yell-adapters-syslogsd)
[Graylog2 (GELF)](https://github.com/rudionrails/yell/wiki/additional-adapters-gelf)
[Fluentd](https://github.com/red5studios/yell-adapters-fluentd)

### Development

[How To: Writing Your Own Adapter](https://github.com/rudionrails/yell/wiki/Writing-your-own-adapter)

You can find further examples and additional adapters in the [wiki](https://github.com/rudionrails/yell/wiki).
or have a look into the examples folder.