README.md in timberio-1.0.0.beta1 vs README.md in timberio-1.0.0
- old
+ new
@@ -1,22 +1,184 @@
-# Timber.io - Ruby Gem - Powerful Ruby Logging
+# Timber
<p align="center" style="background: #140f2a;">
-<a href="http://github.com/timberio/timber-ruby"><img src="http://res.cloudinary.com/timber/image/upload/c_scale,w_537/v1464797600/how-it-works_sfgfjp.gif" /></a>
+<a href="http://github.com/timberio/timber-ruby"><img src="http://files.timber.io/images/ruby-library-readme-header.gif" height="370" /></a>
</p>
[](https://circleci.com/gh/timberio/timber-ruby/tree/master)
[](https://coveralls.io/github/timberio/timber-ruby?branch=master)
[](https://codeclimate.com/github/timberio/timber-ruby)
[](http://www.rubydoc.info/github/timberio/timber-ruby)
-**Note: Timber is in alpha testing, if interested in joining, please visit http://timber.io**
-[Timber](http://timber.io) is a different kind of logging platform; it goes beyond traditional logging by enriching your logs with *app* context. Turning them into rich structured events without altering the essence of logging. See for yourself at [timber.io](http://timber.io).
+1. [What is timber?](#what-is-timber)
+2. [Examples](#examples)
+3. [Pricing](#pricing)
+2. [Install](#install)
+
+## What is Timber?
+
+Glad you asked :) Timber tames the crazy world that is logging. First, it *automatically*
+augments your logs with structured data. Second, it provides a transparent, no lock-in, API
+for logging your own events. Lastly, it can be paired with a [simple modern console](https://timber.io) for querying.
+
+For example, it automatically turns this:
+
+```
+Completed 200 OK in 117ms (Views: 85.2ms | ActiveRecord: 25.3ms)
+```
+
+Into this:
+
+```json
+{
+ "dt": "2016-12-01T02:23:12.236543Z",
+ "level": "info",
+ "message": "Completed 200 OK in 117ms (Views: 85.2ms | ActiveRecord: 25.3ms)",
+ "context": {
+ "http": {
+ "method": "GET",
+ "path": "/checkout",
+ "remote_addr": "123.456.789.10",
+ "request_id": "abcd1234"
+ },
+ "user": {
+ "id": 2,
+ "name": "Ben Johnson",
+ "email": "ben@johnson.com"
+ }
+ },
+ "event": {
+ "http_response": {
+ "status": 200,
+ "time_ms": 117
+ }
+ }
+}
+```
+
+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`)
+
+This enables you to query your logs in a way that
+[even your mother would get excited about](http://i.giphy.com/7JYWGKgwxga5i.gif)!
+
+ 1. `context.user.email:ben@johnson.com` - Tail a specific user!
+ 2. `context.http.request_id:1234` - View *all* logs for a given HTTP request!
+ 3. `event.http_reponse.time_ms>3000` - Easily find outliers and have the proper context to resolve them!
+ 4. `level:warn` - Log levels in your logs. Imagine that!
+
+
+## Examples
+
+> Another service? More lock-in? More code debt? More sadness? :*(
+
+Nope! This is exactly why we created Timber. Timber is Just Logging™. No special API, no risk
+of code debt, no weird proprietary data format locked away in our servers. Absolutely no lock-in!
+
+Besides automatically capturing known events, you can also log custom events. Check it out:
+
+```ruby
+# Simple string (original Logger interface remains untouched)
+Logger.warn "Payment rejected for customer abcd1234, reason: Card expired"
+
+# Structured hash
+Logger.warn message: "Payment rejected", type: :payment_rejected,
+ data: %{customer_id: "abcd1234", amount: 100, reason: "Card expired"}
+
+# Using a Struct
+PaymentRejectedEvent = Struct.new(:customer_id, :amount, :reason) do
+ def message; "Payment rejected for #{customer_id}"; end
+ def type; :payment_rejected; end
+end
+Logger.warn PaymentRejectedEvent.new("abcd1234", 100, "Card expired")
+```
+
+(for more examples, see the `Timber::Logger` docs)
+
+No Timber specific code 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?
+
+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!
+```
+
+
+## Pricing
+
+> This is all gravy, but wouldn't it get expensive?
+
+If you opt to send your data to the [Timber service](https://timber.io), we only charge for
+the size of the `message`, `dt`, and `event.custom` attributes. Everything else is
+stored at no cost to you. [Say wha?!](http://i.giphy.com/l0HlL2vlfpWI0meJi.gif). This ensures
+pricing remains predictable. And our pricing is simple, we charge per GB transferred to us and
+retained, no user limits, and no weird feature matrixes. Lastly, the data is yours, in a simple
+non-proprietary JSON format.
+
+For more details checkout our [timber.io](https://timber.io).
+
## Install
-To ensure logs are transported efficiently, Timber offers a variety of solutions. Please choose your preferred method below:
+### 1. Install the gem:
-1. **[Rails on Heroku](docs/installation/rails_on_heroku.md)** - Takes advantage of Heroku's logplex.
-2. **[Rails over HTTP](docs/installation/rails_over_http.md)** - Quick and easy. No agent. Deploy and go.
-3. ...more coming soon!
\ No newline at end of file
+```ruby
+# Gemfile
+gem 'timberio', require: "timber"
+```
+
+### 2. Install the logger:
+
+#### Heroku:
+
+```ruby
+# config/environments/production.rb (or staging, etc)
+config.logger = ActiveSupport::TaggedLogging.new(Timber::Logger.new(STDOUT))
+```
+
+The command to add your log drain will be displayed in the [Timber app](https://app.timber.io)
+after you add your application.
+
+#### Non-Heroku:
+
+```ruby
+# config/environments/production.rb (or staging, etc)
+log_device = Timber::LogDevices::HTTP.new(ENV['TIMBER_KEY']) # key can be obtained by signing up at https://timber.io
+config.logger = ActiveSupport::TaggedLogging.new(Timber::Logger.new(log_device))
+```
+
+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!*
+
+---
+
+That's it! Log to your heart's content.
+
+For documentation on logging structured events, and other features,
+checkout [the docs](http://thedocs.com/). For more information on Timber visit [timber.io](https://timber.io).