README.md in timber-2.1.0.rc3 vs README.md in timber-2.1.0.rc4
- old
+ new
@@ -24,12 +24,13 @@
in a consistent format. See [how it works](#how-it-works) below.
3. **Seamlessly integrates with popular libraries and frameworks.** - Rails, Rack, Devise,
Omniauth, etc. [Automatically captures user context, HTTP context, and event data.](#third-party-integrations)
-4. **Pairs with a modern console.** - Designed specifically for this librariy, hosted, instantly
- usable, zero configuration. [Checkout the docs](https://timber.io/docs/app/overview/).
+4. **Pairs with a modern structured-logging console.** - Designed specifically for structured data,
+ hosted, instantly usable, tail users, trace requests.
+ [Checkout the docs](https://timber.io/docs/app/tutorials/).
## Installation
1. In `Gemfile`, add the `timber` gem:
@@ -43,20 +44,20 @@
3. In your `shell`, run `bundle exec timber install`
## How it works
-Let's start with an example. Timber turns this:
+Let's start with an example. Timber turns this production log line:
```
-Sent 200 in 45.2ms
+I, [2017-06-04T18:04:53.653812 #42348] INFO -- : [my.host.com] [df88dbaa-50fd-4178-85d7-d66279ea33b6] [192.32.23.12] [bfa8242cd9733bf0211e334be203f0d0] Sent 200 in 45.2ms
```
-Into a rich [`http_server_response` event](https://timber.io/docs/ruby/events-and-context/http-server-response-event/).
+Into a structured [`http_server_response` event](https://timber.io/docs/ruby/events-and-context/http-server-response-event/).
```
-Sent 200 in 45.2ms @metadata {"dt": "2017-02-02T01:33:21.154345Z", "level": "info", "context": {"http": {"method": "GET", "path": "/path", "remote_addr": "192.32.23.12", "request_id": "abcd1234"}, "system": {"hostname": "1.server.com", "pid": "254354"}, "user": {"id": 1, "name": "Ben Johnson", "email": "bens@email.com"}}, "event": {"http_server_response": {"status": 200, "time_ms": 45.2}}}
+Sent 200 in 45.2ms @metadata {"dt": "2017-02-02T01:33:21.154345Z", "level": "info", "context": {"http": {"method": "GET", "path": "/path", "remote_addr": "192.32.23.12", "request_id": "df88dbaa-50fd-4178-85d7-d66279ea33b6"}, "session": {"id": "bfa8242cd9733bf0211e334be203f0d0"}, "system": {"hostname": "my.host.com", "pid": "254354"}, "user": {"id": 1, "name": "Ben Johnson", "email": "bens@email.com"}}, "event": {"http_server_response": {"status": 200, "time_ms": 45.2}}}
```
Notice that instead of completely replacing your log messages,
Timber _augments_ your logs with structured metadata. Turning turns them into
[rich events with context](https://timber.io/docs/ruby/events-and-context) without sacrificing
@@ -70,26 +71,29 @@
logger.info("Sent 200 in 45.2ms")
```
Here's a better look at the metadata:
-```json
+```js
{
"dt": "2017-02-02T01:33:21.154345Z",
"level": "info",
"context": {
"http": {
"method": "GET",
"path": "/path",
"remote_addr": "192.32.23.12",
"request_id": "abcd1234"
},
+ "session": {
+ "id": "bfa8242cd9733bf0211e334be203f0d0"
+ },
"system": {
"hostname": "1.server.com",
"pid": "254354"
},
- "user": {
+ "user": { // user identifiable logs :O
"id": 1,
"name": "Ben Johnson",
"email": "bens@email.com"
},
},
@@ -416,18 +420,21 @@
</p></details>
<details><summary><strong>Won't this increase the size of my log data?</strong></summary><p>
-Yes. In terms of size, it's no different than adding tags to your logs or any other useful
-data. A few things to point out though:
+Yes, but it's no different than adding any other useful data to your logs, such as
+[tags](http://api.rubyonrails.org/classes/ActiveSupport/TaggedLogging.html). A few
+of things to note:
-1. Timber generally _reduces_ the amount of logs your app generates by providing options to
- consolidate request / response logs, template logs, and even silence logs that are not
- of value to you. (see [configuration](#configuration) for examples).
-2. Your log provider should be compressing your data and charging you accordingly. Log data
- is notoriously repetitive, and the context Timber generates is repetitive as well.
- Because of compression we've seen somes apps only incur a 10% increase in data size.
+1. Timber generally _reduces_ the amount of logs your app generates, trading quality for quantity.
+ It does so by providing options to consolidate request / response logs, template logs, and
+ even silence logs that are not of value to you. (see [configuration](#configuration) for examples).
+2. Timber lets you pick exactly which events and contexts you want.
+ (see [configuration](#configuration) for examples)
+3. Your logging provider should be compressing your data and charging you accordingly. Log data
+ is notoriously repetitive, and the context Timber generates is repetitive.
+ Because of compression we've seen somes apps only incur a ~15% increase in data size.
Finally, log what is useful to you. Quality over quantity certainly applies to logging.
---
\ No newline at end of file