README.md in timber-1.0.3 vs README.md in timber-1.0.4
- old
+ new
@@ -9,38 +9,52 @@
[](https://codeclimate.com/github/timberio/timber-ruby)
[](http://www.rubydoc.info/github/timberio/timber-ruby)
1. [What is timber?](#what-is-timber)
-1. [How does it work?](#what-is-timber)
-2. [Logging Custom Events](#logging-custom-events)
-3. [The Timber Console / Pricing](#the-timber-console-pricing)
-2. [Install](#install)
+2. [Why timber?](#why-timber)
+3. [How does it work?](#how-does-it-work)
+4. [Logging Custom Events](#logging-custom-events)
+5. [The Timber Console / Pricing](#the-timber-console-pricing)
+6. [Install](#install)
## What is Timber?
-Timber automatically structures your logs with events and context in a non-proprietary JSON format.
-It’s simple, quick, managed, and has absolutely no risk of code debt or lock-in.
-It’s just good ol’ logging.
+Glad you asked! :) Timber takes a different approach to logging, in that it automatically
+enriches and structures your logs without altering the essence of your original log messages.
+Giving you the best of both worlds: human readable logs *and* rich structured data.
-Timber’s philosophy is that application insight should be open and owned by you.
-And there is no better vehicle than logging:
+And it does so with absolutely no lock-in or risk of code debt. It's just good ol' loggin'™!
+For example:
-1. It’s a shared practice that has been around since the dawn of computers.
-2. It’s baked into every language, library, and framework. Even your own apps.
-3. The data is entirely owned by you.
+1. The resulting log format, by deafult, is a simple, non-proprietary, JSON structure.
+2. The [`Timber::Logger`](lib/timber/events) class extends `Logger`, and will never change or
+ extend the public API.
+3. Where you send your logs is entirely up to you, but we hope you'll check out
+ [timber.io](https://timber.io). We've built a beautiful, modern, and *fast* console specifically
+ for the strutured data captured here.
-The problem is that logs are messy, noisy, and hard to use. Timber solves this by being
-application aware, properly structuring your logs, and optionally providing a [fast, modern,
-and beautiful console](https://timber.io) -- allowing you to realize the power of
-your logs.
+## Why Timber?
+Timber’s philosophy is that application insight should be open and owned by you. It should not
+require a myriad of services to accomplish. And there is no better vehicle than logging:
+
+1. The log is immutable and complete. [It is the truth](http://files.timber.io/images/log-is-the-truth.png) :)
+2. It’s a shared practice that has been around since the dawn of computers.
+3. It’s baked into every language, library, and framework. Even your own apps!
+4. The data is open, accessible, and entirely owned by you. Yay!
+
+The problem is that logs are unstructured, noisy, and hard to use. `grep` can only take you so
+far! Timber solves this by properly structuring your logs, making them easy to search and
+visualize -- enabling you to sanely realize the power of your logs.
+
+
## How does it work?
-Glad you asked! :) Timber automatically structures your logs by taking advantage of public APIs.
+Timber automatically structures your logs by taking advantage of public APIs.
For example, by subscribing to `ActiveSupport::Notifications`, Timber can automatically turn this:
```
Completed 200 OK in 117ms (Views: 85.2ms | ActiveRecord: 25.3ms)
@@ -74,16 +88,16 @@
}
}
```
It does the same for `http requests`, `sql queries`, `exceptions`, `template renderings`,
-and any other event your framework logs. (for a full list see `Timber::Events`)
+and any other event your framework logs. (for a full list see [`Timber::Events`](lib/timber/events))
## Logging Custom Events
-> Another service? More code debt? :*(
+> Another service? More lock-in? :*(
Nope! Logging custom events is Just Logging™. Check it out:
```ruby
# Simple string (original Logger interface remains untouched)
@@ -99,47 +113,15 @@
def type; :payment_rejected; end
end
Logger.warn PaymentRejectedEvent.new("abcd1234", 100, "Card expired")
```
-(for more examples, see the `Timber::Logger` docs)
+(for more examples, see [the `Timber::Logger` docs](lib/timber/logger.rb))
-No mention of Timber anywhere! In fact, this approach pushes things the opposite way. What if,
-as a result of structured logging, you could start decoupling other services from your application?
+No mention of Timber anywhere!
-Before:
-```
- |---[HTTP]---> sentry / bugsnag / etc
-My Application |---[HTTP]---> librato / graphite / etc
- |---[HTTP]---> new relic / etc
- |--[STDOUT]--> logs
- |---> Logging service
- |---> S3
- |---> RedShift
-```
-
-
-After:
-
-```
- |-- sentry / bugsnag / etc
- |-- librato / graphite / etc
-My Application |--[STDOUT]--> logs ---> Timber ---> |-- new relic / etc
- ^ |-- S3
- | |-- RedShift
- | ^
- fast, efficient, durable, |
- replayable, auditable, change any of these without
- just logging touching your code
- *and* backfill them!
-```
-
-[Mind-blown!](http://i.giphy.com/EldfH1VJdbrwY.gif)
-
-
-
## The Timber Console / Pricing
> This is all gravy, but wouldn't the extra data get expensive?
If you opt use the [Timber Console](https://timber.io), we only charge for
@@ -183,9 +165,22 @@
Your Timber application key will be displayed in the [Timber app](https://app.timber.io)
after you add your application.
*Other transport methods coming soon!*
+
+
+#### Rails TaggedLogging?
+
+No probs! Use it as normal, Timber will even pull out the tags and include them in the `context`.
+
+```ruby
+config.logger = ActiveSupport::TaggedLogging.new(Timber::Logger.new(STDOUT))
+```
+
+**Warning**: Tags lack meaningful descriptions, they are a poor mans context. Not to worry though!
+Timber provides a simple system for adding custom context that you can optionally use. Checkout
+[the `Timber::CurrentContext` docs](lib/timber/current_context.rb) for examples.
---
That's it! Log to your heart's content.