README.md in timber-2.1.3 vs README.md in timber-2.1.4
- old
+ new
@@ -1,21 +1,22 @@
-# 🌲 Timber - Log Better. Solve Problems Faster.
+# 🌲 Timber - Great Ruby Logging Made Easy
[](LICENSE.md)
[](http://www.rubydoc.info/github/timberio/timber-ruby)
[](https://travis-ci.org/timberio/timber-ruby)
## Overview
-Timber for Ruby is an drop-in replacement for your ruby `Logger` that transparently augments your
-logs with critical metadata and context. It's structured logging without all of the noise; turning
-your logs into rich, useful, readable events. When paired with the
-[Timber console](#the-timber-console), Timber will fundamentally change the way you use your logs.
+Timber for Ruby is a drop-in upgrade for your Ruby logs that unobtrusively
+[structures your logs through augmentation](https://timber.io/docs/concepts/structuring-through-augmentation).
+It's clean structured logging without the effort. When paired with the
+[Timber console](#the-timber-console), Timber will
+[fundamentally change the way you use your logs](#do-amazing-things-with-your-logs).
1. [**Easy setup** - `bundle exec timber install`](#installation)
-2. [**Seamlessly integrates with popular libraries and frameworks**](#jibber-jabber)
-3. [**Modern fast console, designed for Ruby application logging**](#the-timber-console)
+2. [**Seamlessly integrates with popular libraries and frameworks**](#integrations)
+3. [**Do amazing things with your Ruby logs**](#do-amazing-things-with-your-logs)
## Installation
1. In your `Gemfile`, add the `timber` gem:
@@ -34,77 +35,88 @@
<details><summary><strong>Basic logging</strong></summary><p>
Use the `Timber::Logger` just like you would `::Logger`:
```ruby
-logger.info("My log message") # use warn, error, debug, etc.
-
-# => My log message @metadata {"level": "info", "context": {...}}
+logger.debug("Debug message")
+logger.info("Info message")
+logger.warn("Warn message")
+logger.error("Error message")
+logger.fatal("Fatal message")
```
+We encourage standard / traditional log messages for non-meaningful events. And because Timber
+[augments](https://timber.io/docs/concepts/structuring-through-augmentation) your logs with
+metadata, you don't have to worry about making every log structured!
+
---
</p></details>
<details><summary><strong>Custom events</strong></summary><p>
-Custom events allow you to extend beyond events already defined in
-the [`Timber::Events`](lib/timber/events) namespace.
+Custom events allow you to extend beyond events already defined in the
+[`Timber::Events`](http://www.rubydoc.info/github/timberio/timber-ruby/Timber/Events) namespace.
+If you aren't sure what an event is, please read the
+["Metdata, Context, and Events" doc](https://timber.io/docs/concepts/metadata-context-and-events).
+### How to use it
+
```ruby
logger.warn "Payment rejected", payment_rejected: {customer_id: "abcd1234", amount: 100, reason: "Card expired"}
-
-# => Payment rejected @metadata {"level": "warn", "event": {"payment_rejected": {"customer_id": "abcd1234", "amount": 100, "reason": "Card expired"}}, "context": {...}}
```
-* Notice the `:payment_rejected` root key. Timber will classify this event as such.
-* In the [Timber console](https://app.timber.io) use the query: `type:payment_rejected` or `payment_rejected.amount:>100`.
-* See more details on our [custom events docs page](https://timber.io/docs/ruby/usage/custom-events/)
+1. [Search it](https://timber.io/docs/app/console/searching) with queries like: `type:payment_rejected` or `payment_rejected.amount:>100`
+2. [Alert on it](https://timber.io/docs/app/console/alerts) with threshold based alerts
+3. [Graph & visualize it](https://timber.io/docs/app/console/graphing)
+4. [View this event's data and context](https://timber.io/docs/app/console/view-metdata-and-context)
+5. ...read more in our [docs](https://timber.io/docs/languages/ruby/usage/custom-events)
---
</p></details>
<details><summary><strong>Custom contexts</strong></summary><p>
-Context is additional data shared across log lines. Think of it like log join data.
-This is how a query like `context.user.id:1` can show you all logs generated by that user.
Custom contexts allow you to extend beyond contexts already defined in
-the [`Timber::Contexts`](lib/timber/contexts) namespace.
+the [`Timber::Contexts`](http://www.rubydoc.info/github/timberio/timber-ruby/Timber/Contexts)
+namespace. If you aren't sure what context is, please read the
+["Metdata, Context, and Events" doc](https://timber.io/docs/concepts/metadata-context-and-events).
+### How to use it
+
```ruby
logger.with_context(build: {version: "1.0.0"}) do
logger.info("My log message")
end
-
-# => My log message @metadata {"level": "info", "context": {"build": {"version": "1.0.0"}}}
```
-* Notice the `:build` root key. Timber will classify this context as such.
-* In the [Timber console](https://app.timber.io) use queries like: `build.version:1.0.0`
-* See more details on our [custom contexts docs page](https://timber.io/docs/ruby/usage/custom-contexts/)
+1. [Search it](https://timber.io/docs/app/console/searching) with queries like: `build.version:1.0.0`
+2. [View this context when viewing a log's metadata](https://timber.io/docs/app/console/view-metdata-and-context)
+3. ...read more in our [docs](https://timber.io/docs/languages/ruby/usage/custom-context)
---
</p></details>
<details><summary><strong>Metrics & Timings</strong></summary><p>
-Aggregates destroy details, and with Timber capturing metrics and timings is just logging events.
-Timber is built on modern big-data principles, it can calculate aggregates across terrabytes of
-data in seconds. Don't reduce the quality of your log data to accomodate a restrive
-logging system.
+Aggregates destroy details, events tell stories. With Timber, logging metrics and timings is simply
+[logging an event](https://timber.io/docs/languages/ruby/usage/custom-events). Timber is based on
+modern big-data principles and can aggregate inordinately large data sets in seconds. Logging
+events (raw data as it exists), gives you the flexibility in the future to segment and aggregate
+your data any way you see fit. This is superior to choosing specific paradigms before hand, when
+you are unsure how you'll need to use your data in the future.
-Here's a timing example. Notice how Timber automatically calculates the time and adds the timing
-to the message.
+### How to use it
+Below is a contrived example of timing a background job:
+
```ruby
timer = Timber::Timer.start
# ... code to time ...
logger.info("Processed background job", background_job: {time_ms: timer})
-
-# => Processed background job in 54.2ms @metadata {"level": "info", "event": {"background_job": {"time_ms": 54.2}}}
```
And of course, `time_ms` can also take a `Float` or `Fixnum`:
```ruby
@@ -113,38 +125,43 @@
Lastly, metrics aren't limited to timings. You can capture any metric you want:
```ruby
logger.info("Credit card charged", credit_card_charge: {amount: 123.23})
-
-# => Credit card charged @metadata {"level": "info", "event": {"credit_card_charge": {"amount": 123.23}}}
```
-In Timber you can easily sum, average, min, and max the `amount` attribute across any interval
-you desire.
+1. [Search it](https://timber.io/docs/app/console/searching) with queries like: `background_job.time_ms:>500`
+2. [Alert on it](https://timber.io/docs/app/console/alerts) with threshold based alerts
+3. [View this log's metadata in the console](https://timber.io/docs/app/console/view-metdata-and-context)
+4. ...read more in our [docs](https://timber.io/docs/languages/ruby/usage/metrics-and-timings)
+
</p></details>
## Configuration
Below are a few popular configuration options, for a comprehensive list, see
[Timber::Config](http://www.rubydoc.info/github/timberio/timber-ruby/Timber/Config).
-<details><summary><strong>Logrageify. Silence noisy logs (sql query, template renders)</strong></summary><p>
+<details><summary><strong>Logrageify. Silence noisy logs.</strong></summary><p>
Timber allows you to silence noisy logs that aren't of value to you, just like
-[lograge](https://github.com/roidrage/lograge). In fact, we've provided a convenience method
-for anyone transitioning from lograge:
+[lograge](https://github.com/roidrage/lograge). As such, we've provided a convenience configuration
+option for anyone transitioning from lograge.
+### How to use it
+
```ruby
# config/initializers/timber.rb
config = Timber::Config.instance
config.logrageify!()
```
+## How it works
+
It turns this:
```
Started GET "/" for 127.0.0.1 at 2012-03-10 14:28:14 +0100
Processing by HomeController#index as HTML
@@ -172,10 +189,12 @@
config.integrations.action_view.silence = true
config.integrations.active_record.silence = true
config.integrations.rack.http_events.collapse_into_single_event = true
```
+### Pro-tip: Keep controller call logs (recommended)
+
Feel free to deviate and customize which logs you silence. We recommend a slight deviation
from lograge with the following settings:
```ruby
# config/initializers/timber.rb
@@ -196,10 +215,15 @@
</p></details>
<details><summary><strong>Silence specific requests (LB health checks, etc)</strong></summary><p>
+Silencing noisy requests can be helpful for silencing load balance health checks, bot scanning,
+or activity that generally is not meaningful to you.
+
+### How to use it
+
The following will silence all `[GET] /_health` requests:
```ruby
# config/initializers/timber.rb
@@ -215,44 +239,19 @@
---
</p></details>
-<details><summary><strong>Change log formats</strong></summary><p>
-
-Simply set the formatter like you would with any other logger:
-
-```ruby
-# This is set in your various environment files
-logger.formatter = Timber::Logger::JSONFormatter.new
-```
-
-Your options are:
-
-1. [`Timber::Logger::AugmentedFormatter`](http://www.rubydoc.info/github/timberio/timber-ruby/Timber/Logger/AugmentedFormatter) -
- (default) A human readable format that _appends_ metadata to the original log line. The Timber
- service can parse this data appropriately.
- Ex: `My log message @metadata {"level":"info","dt":"2017-01-01T01:02:23.234321Z"}`
-
-2. [`Timber::Logger::JSONFormatter`](http://www.rubydoc.info/github/timberio/timber-ruby/Timber/Logger/JSONFormatter) -
- Ex: `{"level":"info","message":"My log message","dt":"2017-01-01T01:02:23.234321Z"}`
-
-3. [`Timber::Logger::MessageOnlyFormatter`](http://www.rubydoc.info/github/timberio/timber-ruby/Timber/Logger/MessageOnlyFormatter) -
- For use in development / test. Prints logs as strings with no metadata attached.
- Ex: `My log message`
-
----
-
-</p></details>
-
<details><summary><strong>Capture custom user context</strong></summary><p>
By default Timber automatically captures user context for most of the popular authentication
libraries (Devise, Omniauth, and Clearance). See
[Timber::Integrations::Rack::UserContext](http://www.rubydoc.info/github/timberio/timber-ruby/Timber/Integrations/Rack/UserContext)
for a complete list.
+### How to use it
+
In cases where you Timber doesn't support your strategy, or you want to customize it further,
you can do so like:
```ruby
# config/initializers/timber.rb
@@ -279,11 +278,15 @@
</p></details>
<details><summary><strong>Capture release / deploy context</strong></summary><p>
[Timber::Contexts::Release](http://www.rubydoc.info/github/timberio/timber-ruby/Timber/Contexts/Release)
-tracks the current application release and version. If you're on Heroku, simply enable the
+tracks the current application release and version.
+
+### How to use it
+
+If you're on Heroku, simply enable the
[dyno metadata](https://devcenter.heroku.com/articles/dyno-metadata) feature. If you are not,
set the following environment variables and this context will be added automatically:
1. `RELEASE_COMMIT` - Ex: `2c3a0b24069af49b3de35b8e8c26765c1dba9ff0`
2. `RELEASE_CREATED_AT` - Ex: `2015-04-02T18:00:42Z`
@@ -294,72 +297,46 @@
---
</p></details>
-## Jibber-Jabber
+## Integrations
-<details><summary><strong>Which log events does Timber structure for me?</strong></summary><p>
+[Timber for Ruby](https://github.com/timberio/timber-ruby) extends beyond your basic logging
+functionality and integrates with popular libraries and frameworks. This makes structured quality
+logging effortless. Below is a list of integrations we offer and the various events and contexts
+they create.
-Out of the box you get everything in the [`Timber.Events`](lib/timber/events) namespace.
+1. [**Rails**](https://timber.io/docs/languages/ruby/integrations/rails)
+2. [**Rack**](https://timber.io/docs/languages/ruby/integrations/rack)
+3. [**Heroku**](https://timber.io/docs/languages/ruby/integrations/heroku)
+4. [**Devise**](https://timber.io/docs/languages/ruby/integrations/devise)
+5. [**Clearance**](https://timber.io/docs/languages/ruby/integrations/clearnace)
+6. [**Omniauth**](https://timber.io/docs/languages/ruby/integrations/omniauth)
+7. [**Warden**](https://timber.io/docs/languages/ruby/integrations/devise)
+8. ...more coming soon! Make a request by [opening an issue](https://github.com/timberio/timber-ruby/issues/new)
-We also add context to every log, everything in the [`Timber.Contexts`](lib/timber/contexts)
-namespace. Context is structured data representing the current environment when the log line
-was written. It is included in every log line. Think of it like join data for your logs.
----
+## Do amazing things with your logs
-</p></details>
+What does all of this mean? Doing amazing things with your logs! Being more productive, solving
+problems faster, and _actually_ enjoying using your logs for application insight:
-<details><summary><strong>What about my current log statements?</strong></summary><p>
+1. [**Live tail users on your app**](https://timber.io/docs/app/console/tail-a-user)
+2. [**Trace HTTP requests**](https://timber.io/docs/app/console/trace-http-requests)
+3. [**Inspect HTTP request parameters**](https://timber.io/docs/app/console/inspect-http-requests)
+4. [**Powerful searching**](https://timber.io/docs/app/console/searching)
+5. [**Threshold based alerting**](https://timber.io/docs/app/alerts)
+6. ...and more! Checkout our [the Timber application docs](https://timber.io/docs/app)
-They'll continue to work as expected. Timber adheres strictly to the default `Logger` interface
-and will never deviate in *any* way.
-In fact, traditional log statements for non-meaningful events, debug statements, etc, are
-encouraged. In cases where the data is meaningful, consider [logging a custom event](#usage).
-
-</p></details>
-
-<details><summary><strong>When to use metadata or events?</strong></summary><p>
-
-At it's basic level, both metadata and events serve the same purpose: they add structured
-data to your logs. And anyone that's implemented structured logging know's this can quickly get
-out of hand. This is why we created events. Here's how we recommend using them:
-
-1. Use `events` when the log cleanly maps to an event that you'd like to alert on, graph, or use
- in a meaningful way. Typically something that is core to your business or application.
-2. Use metadata for debugging purposes; when you simply want additional insight without
- polluting the message.
-
-### Example 1: Logging that a payment was rejected
-
-This is clearly an event that is meaningful to your business. You'll probably want to alert and
-graph this data. So let's log it as an official event:
-
-```ruby
-logger.info("Payment rejected", payment_rejected: {customer_id: "xiaus1934", amount: 1900, currency: "USD"})
-```
-
-### Example 2: Logging that an email was changed
-
-This is definitely log worthy, but not something that is core to your business or application.
-Instead of an event, use metadata:
-
-```ruby
-logger.info("Email successfully changed", old_email: old_email, new_email: new_email)
-```
-
----
-
-</p></details>
-
-
## The Timber Console
-[](https://app.timber.io)
+[](https://timber.io/docs/app)
+[Learn more about our app.](https://timber.io/docs/app)
+
## Your Moment of Zen
<p align="center" style="background: #221f40;">
-<a href="http://github.com/timberio/timber-ruby"><img src="http://files.timber.io/images/readme-log-truth.png" height="947" /></a>
+<a href="https://timber.io"><img src="http://files.timber.io/images/readme-log-truth.png" height="947" /></a>
</p>