README.md in timber-2.1.4 vs README.md in timber-2.1.5
- old
+ new
@@ -2,21 +2,21 @@
[](LICENSE.md)
[](http://www.rubydoc.info/github/timberio/timber-ruby)
[](https://travis-ci.org/timberio/timber-ruby)
+[Timber.io](https://timber.io) is a simple cloud-based logging platform built for developers.
+This is our official Ruby library.
+
## Overview
-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).
+Ruby logs are broken. They're noisy, unparesable, and in the context of multiple servers and processes, unreadable. Current logging systems built for ops engineers haven't helped. This is why we built Timber. It's a different approach to Ruby logging. Instead of prefixing your logs with noisy tags, Timber integrates directly with your application, capturing rich context and metadata without altering your logs. This makes your logs easy to [search, use, and _read_](#do-amazing-things-with-your-logs), giving you _complete_ insight into your Ruby app.
1. [**Easy setup** - `bundle exec timber install`](#installation)
-2. [**Seamlessly integrates with popular libraries and frameworks**](#integrations)
-3. [**Do amazing things with your Ruby logs**](#do-amazing-things-with-your-logs)
+2. [**Powerful logging**](#usage)
+3. [**Seamlessly integrates with popular libraries and frameworks**](#integrations)
+4. [**Do amazing things with your Ruby logs**](#do-amazing-things-with-your-logs)
## Installation
1. In your `Gemfile`, add the `timber` gem:
@@ -50,16 +50,17 @@
---
</p></details>
-<details><summary><strong>Custom events</strong></summary><p>
+<details><summary><strong>Logging events (structured data)</strong></summary><p>
-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).
+Logging events allows you to log structured data without sacrificing readability or worrying about
+structured data name or type conflicts. Keep in mind, Timber defines common events in the
+[`Timber::Events`](http://www.rubydoc.info/github/timberio/timber-ruby/Timber/Events) namespace,
+which are automatically logged for you through our [integrations](#integrations). You should not
+have to maually log events defined there except in special circumstances.
### How to use it
```ruby
logger.warn "Payment rejected", payment_rejected: {customer_id: "abcd1234", amount: 100, reason: "Card expired"}
@@ -73,26 +74,33 @@
---
</p></details>
-<details><summary><strong>Custom contexts</strong></summary><p>
+<details><summary><strong>Setting context</strong></summary><p>
-Custom contexts allow you to extend beyond contexts already defined in
-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).
+Context is amazingly powerful, think of it like join data for your logs. It represents the
+environment when the log was written, allowing you to relate logs so you can easily segment them.
+It's how Timber is able to accomplish features like
+[tailing users](https://timber.io/docs/app/console/tail-a-user) and
+[tracing HTTP requests](https://timber.io/docs/app/console/trace-http-requests).
+Keep in mind, Timber defines common contexts in the
+[`Timber::Contexts`](http://www.rubydoc.info/github/timberio/timber-ruby/Timber/Contexts) namespace,
+which are automatically set for you through our [integrations](#integrations). You should not
+have to maually set these contexts except in special circumstances.
### How to use it
```ruby
-logger.with_context(build: {version: "1.0.0"}) do
- logger.info("My log message")
+logger.with_context(job: {id: 123}) do
+ logger.info("Background job execution started")
+ # ... code here
+ logger.info("Background job execution completed")
end
```
-1. [Search it](https://timber.io/docs/app/console/searching) with queries like: `build.version:1.0.0`
+1. [Search it](https://timber.io/docs/app/console/searching) with queries like: `job.id:123`
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)
---
@@ -156,11 +164,11 @@
config = Timber::Config.instance
config.logrageify!()
```
-## How it works
+### How it works
It turns this:
```
Started GET "/" for 127.0.0.1 at 2012-03-10 14:28:14 +0100
@@ -299,14 +307,14 @@
</p></details>
## Integrations
-[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.
+Timber integrates with popular frameworks and libraries to capture context and metadata you
+couldn't otherwise. This automatically upgrades logs produced by these libraries, making them
+[easier to search and use](#do-amazing-things-with-your-logs). Below is a list of libraries we
+support:
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)
@@ -316,17 +324,16 @@
8. ...more coming soon! Make a request by [opening an issue](https://github.com/timberio/timber-ruby/issues/new)
## Do amazing things with your logs
-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:
+Unlock the potential of your logs:
-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)
+1. [**Powerful searching.** - Find what you need faster.](https://timber.io/docs/app/console/searching)
+2. [**Live tail users.** - Easily solve customer issues.](https://timber.io/docs/app/console/tail-a-user)
+3. [**Viw logs per HTTP request.** - See the full story without the noise.](https://timber.io/docs/app/console/trace-http-requests)
+4. [**Inspect HTTP request parameters.** - Quickly reproduce issues.](https://timber.io/docs/app/console/inspect-http-requests)
+5. [**Threshold based alerting.** - Know when things break.](https://timber.io/docs/app/alerts)
6. ...and more! Checkout our [the Timber application docs](https://timber.io/docs/app)
## The Timber Console