timber 2.0.24 → 2.1.0.rc1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 8c631daf0393857de501da9e12c1087f4f6cceda
-  data.tar.gz: 55b336aec1471657a0358d80e7bfabdd1c6a7a1b
+  metadata.gz: 3db79522e2f956e63a0d0954deecd94ed23ed105
+  data.tar.gz: 745fcb202414db0fd5db648b906499aadf832665
 SHA512:
-  metadata.gz: 706a67aec83bf76c5a2089c3d7ca14b15226a05fd3113a4896cc0faec27ba7976c439783e7a3f50367ec38e7cbacf9c7611a8e493a4faadfcdc3356610df5634
-  data.tar.gz: c4e70b7199e075ce052593fe0a4d9c12cb83e2ecd0599fbb3188f939d6b234517e07f50d32f7c0daaf0f5a92a635b355830560044d7407de45e57fdf9511bd56
+  metadata.gz: fcf7dcefee624791ceac83ed31d016b3429dcc261e51eddb3305f66038f1eb065c73388b6daedee06d0a89fd1ebea068941535b0f76e65967af1a40f9e1c60df
+  data.tar.gz: 4a2549874d1b67f31333665a37043bda838375c6043041221ae744b5e94d0e3669341ce78b3992b47f3b43b588aaced3e4315434bfd8369d710a6627d9433029

data/.travis.yml

@@ -5,7 +5,7 @@ rvm:
 - 1.9.3
 - 2.2.6
 - 2.3.3
-- 2.4.0
+- 2.4.1
 - jruby
 gemfile:
 - gemfiles/rails-3.0.gemfile
@@ -36,7 +36,7 @@ matrix:
     - rvm: "1.9.3"
       gemfile: "gemfiles/rails-3.2.gemfile"
   allow_failures:
-  - rvm: 2.4.0
+  - rvm: 2.4.1
   - rvm: jruby
     gemfile: gemfiles/rails-5.0.gemfile
   - rvm: jruby

data/CHANGELOG

@@ -0,0 +1,3 @@
+Please see https://github.com/timberio/timber-ruby/releases for library specific changes.
+
+For all Timber changes see https://timber.io/changelog.

data/README.md

@@ -1,7 +1,8 @@
-# 🌲 Timber - Log Better. Solve Problems Faster.
+# 🌲 Timber - Automatic Ruby Structured Logging
 
 [![ISC License](https://img.shields.io/badge/license-ISC-ff69b4.svg)](LICENSE.md)
-[![CircleCI](https://circleci.com/gh/timberio/timber-ruby.svg?style=shield&circle-token=:circle-token)](https://circleci.com/gh/timberio/timber-ruby/tree/master)
+[![Build Status](https://travis-ci.org/timberio/timber-ruby.svg?branch=master)](https://travis-ci.org/timberio/timber-ruby)
+[![Build Status](https://travis-ci.org/timberio/timber-ruby.svg?branch=master)](https://travis-ci.org/timberio/timber-ruby)
 [![Code Climate](https://codeclimate.com/github/timberio/timber-ruby/badges/gpa.svg)](https://codeclimate.com/github/timberio/timber-ruby)
 [![View docs](https://img.shields.io/badge/docs-viewdocs-blue.svg?style=flat-square "Viewdocs")](http://www.rubydoc.info/github/timberio/timber-ruby)
 
@@ -13,62 +14,129 @@
 
 ## Overview
 
-Timber for Ruby is an optional upgrade you can install for Ruby apps on the
-[Timber.io logging platform](https://timber.io). Instead of completely replacing your log messages,
-Timber efficiently augments your logs with critical metadata. Turning them into
-[rich events with context](https://timber.io/docs/ruby/events-and-context). This preserves the
-readability of your logs while still adding the critical context needed to properly analyze your
-logs.
+Timber solves ruby structured logging so you don't have to. Go from raw text logs to rich
+structured events in seconds. Spend more time focusing on your app and less time
+focusing on logging.
+
+1. **Easy setup.** - `bundle exec timber install`, [get setup in seconds](#installation).
+
+2. **Automatically structures yours logs.** - Third-party and in-app logs are all structured
+   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-support)
+
+4. **Pairs with a modern console.** - Designed specifically for this librariy, instantly
+   usable, zero configuration.
+
+
+## Installation
+
+1. In `Gemfile`, add the `timber` gem:
+
+    ```ruby
+    gem 'timber', '~> 2.0'
+    ```
+
+2. In your `shell`, run `bundle install`
+
+3. In your `shell`, run `bundle exec timber install`
 
 
 ## How it works
 
-For example, Timber turns this familiar raw text log:
+Let's start with an example. Timber turns this familiar raw text log line:
 
 ```
-Sent 200 in 45.ms
+Sent 200 in 45.2ms
 ```
 
 Into a rich [`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": {"user": {"id": 1, "name": "Ben Johnson"}, "http": {"method": "GET", "host": "timber.io", "path": "/path", "request_id": "abcd1234"}}, "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": {"user": {"id": 1, "name": "Ben Johnson"}, "http": {"method": "GET", "host": "timber.io", "path": "/path", "request_id": "abcd1234"}, "system": {"hostname": "1.server.com", "pid": "254354"}}, "event": {"http_server_response": {"status": 200, "time_ms": 45.2}}}
 ```
 
-In the [Timber console](https://app.timber.io) simply
-[click the line to view this metdata](https://timber.io/docs/app/tutorials/view-metadata/).
-Moreover, this data allows you to run powerful queries like:
+Notice that instead of completely replacing your log messages,
+Timber _augments_ your logs with structured metadata. Turning them into
+[rich events with context](https://timber.io/docs/ruby/events-and-context) without sacrificing
+readability.
 
-1. `context.request_id:abcd1234` - View all logs generated for a specific request.
-2. `context.user.id:1` - View logs generated by a specific user.
-3. `type:http_server_response` - View specific events (exceptions, sql queries, etc)
-4. `http_server_response.time_ms:>=1000` - View slow responses with the ability to zoom out and view them in context (request, user, etc).
-5. `level:info` - Levels in your logs!
+This is all accomplished by using the
+[Timber::Logger](http://www.rubydoc.info/github/timberio/timber-ruby/Timber/Logger):
 
-For a complete overview, see the [Timber for Ruby docs](https://timber.io/docs/ruby/overview/).
+```ruby
+logger = Timber::Logger.new(STDOUT)
+logger.info("Sent 200 in 45.2ms")
+```
 
+Here's a better look at the metadata:
+
+```json
+{
+  "dt": "2017-02-02T01:33:21.154345Z",
+  "level": "info",
+  "context": {
+    "user": {
+      "id": 1,
+      "name": "Ben Johnson"
+    },
+    "http": {
+      "method": "GET",
+      "host": "timber.io",
+      "path": "/path",
+      "request_id": "abcd1234"
+    },
+    "system": {
+      "hostname": "1.server.com",
+      "pid": "254354"
+    }
+  },
+  "event": {
+    "http_server_response": {
+      "status": 200,
+      "time_ms": 45.2
+    }
+  }
+}
+```
 
-## Installation
+This structure isn't arbitrary either, it follows the
+[simple log event JSON schema](https://github.com/timberio/log-event-json-schema), which
+formalizes the data structure, creates a contract with downstream consumers, and
+improves stability.
 
-1. In `Gemfile`, add the `timber` gem:
+So what can you do with this data?
 
-    ```ruby
-    gem 'timber', '~> 2.0'
-    ```
+1. [**Tail a user** - `user.id:1`](https://timber.io/docs/app/tutorials/tail-a-user/)
+2. [**Trace a request** - `http.request_id:abcd1234`](https://timber.io/docs/app/tutorials/view-in-request-context/)
+3. **Narrow by host** - `system.hostname:1.server.com`
+4. **View slow responses** - `http_server_response.time_ms:>=1000`
+5. **Filter by log level** - `level:error`
+6. **Quickly find exceptions** - `is:exception`
 
-2. In your `shell`, run `bundle install`
+For a complete overview, see the [Timber for Ruby docs](https://timber.io/docs/ruby/overview/).
 
-3. In your `shell`, run `bundle exec timber install`
+
+## Third-party support
+
+1. **Rails**: Structures ([HTTP requests](https://timber.io/docs/ruby/events-and-context/http-server-request-event/), [HTTP respones](https://timber.io/docs/ruby/events-and-context/http-server-response-event/), [controller calls](https://timber.io/docs/ruby/events-and-context/controller-call-event/), [template renders](https://timber.io/docs/ruby/events-and-context/template-render-event/), and [sql queries](https://timber.io/docs/ruby/events-and-context/sql-query-event/)).
+2. **Rack**: Structures [exceptions](https://timber.io/docs/ruby/events-and-context/exception-event/), captures [HTTP context](https://timber.io/docs/ruby/events-and-context/http-context/), captures [user context](https://timber.io/docs/ruby/events-and-context/user-context/), captures [session context](https://timber.io/docs/ruby/events-and-context/session-context/).
+3. **Devise, Omniauth, Clearance**: captures [user context](https://timber.io/docs/ruby/events-and-context/user-context/)
+5. **Heroku**: Captures [release context](https://timber.io/docs/ruby/events-and-context/release-context/) via [Heroku dyno metadata](https://devcenter.heroku.com/articles/dyno-metadata).
+
+...and more. Timber will continue to evolve and support more libraries.
 
 
 ## Usage
 
 <details><summary><strong>Basic logging</strong></summary><p>
 
-Use `Logger` as normal:
+Use the `Timber::Logger` just like you would `::Logger`:
 
 ```ruby
-logger.info("My log message")
+logger = Timber::Logger.new(STDOUT)
+logger.info("My log message") # use warn, error, debug, etc.
 
 # => My log message @metadata {"level": "info", "context": {...}}
 ```
@@ -83,6 +151,7 @@ Custom events allow you to extend beyond events already defined in
 the [`Timber::Events`](lib/timber/events) namespace.
 
 ```ruby
+logger = Timber::Logger.new(STDOUT)
 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": {...}}
@@ -99,10 +168,12 @@ logger.warn "Payment rejected", payment_rejected: {customer_id: "abcd1234", amou
 <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.
 
 ```ruby
+logger = Timber::Logger.new(STDOUT)
 logger.with_context(build: {version: "1.0.0"}) do
   logger.info("My log message")
 end
@@ -114,26 +185,229 @@ end
 * 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/custom-contexts/)
 
+---
+
+</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 data because the system processing
+your data is limited.
+
+Here's a timing example. Notice how Timber automatically calculates the time and adds the timing
+to the message.
+
+```ruby
+logger = Timber::Logger.new(STDOUT)
+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}}}
+```
+
+Or capture any metric you want:
+
+```ruby
+logger = Timber::Logger.new(STDOUT)
+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.
+
+</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>
+
+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:
+
+```ruby
+# config/initializers/timber.rb
+
+config = Timber::Config.instance
+config.logrageify!()
+```
+
+It turns this:
+
+```
+Started GET "/" for 127.0.0.1 at 2012-03-10 14:28:14 +0100
+Processing by HomeController#index as HTML
+  Rendered text template within layouts/application (0.0ms)
+  Rendered layouts/_assets.html.erb (2.0ms)
+  Rendered layouts/_top.html.erb (2.6ms)
+  Rendered layouts/_about.html.erb (0.3ms)
+  Rendered layouts/_google_analytics.html.erb (0.4ms)
+Completed 200 OK in 79ms (Views: 78.8ms | ActiveRecord: 0.0ms)
+```
+
+Into this:
+
+```
+Get "/" sent 200 OK in 79ms @metadata {...}
+```
+
+Internally this is equivalent to:
+
+```ruby
+# config/initializers/timber.rb
+
+config = Timber::Config.instance
+config.integrations.action_controller.silence = true
+config.integrations.action_view.silence = true
+config.integrations.active_record.silence = true
+config.integrations.rack.http_events.collapse_into_single_event = true
+```
+
+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
+
+config = Timber::Config.instance
+config.integrations.action_view.silence = true
+config.integrations.active_record.silence = true
+config.integrations.rack.http_events.collapse_into_single_event = true
+```
+
+This does _not_ silence the controller call log event. This is because Timber captures the
+parameters passed to the controller, which is very valuable when debugging.
+
+For a full list of integrations and settings, see
+[Timber::Integrations](http://www.rubydoc.info/github/timberio/timber-ruby/Timber/Integrations)
+
+---
+
 </p></details>
 
-<details><summary><strong>Metrics</strong></summary><p>
+<details><summary><strong>Silence specific requests (LB health checks, etc)</strong></summary><p>
+
+The following will silence all `[GET] /_health` requests:
+
+```ruby
+# config/initializers/timber.rb
+
+config = Timber::Config.instance
+config.integrations.rack.http_events.silence_request = lambda do |rack_env, rack_request|
+  rack_request.path == "/_health"
+end
+```
+
+We require a block because it gives you complete control over how you want to silence requests.
+The first parameter being the traditional Rack env hash, the second being a
+[Rack Request](http://www.rubydoc.info/gems/rack/Rack/Request) object.
 
-Logging metrics is accomplished by logging custom events. Please see our
-[metrics docs page](https://timber.io/docs/ruby/metrics/) for a more detailed explanation
-with examples.
+---
+
+</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 = Timber::Logger.new(STDOUT)
+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.
+   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.
+
+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
+
+config = Timber::Config.instance
+config.integrations.rack.user_context.custom_user_hash = lambda do |rack_env|
+  user = rack_env['warden'].user
+  if user
+    {
+      id: user.id, # unique identifier for the user, can be an integer or string,
+      name: user.name, # identifiable name for the user,
+      email: user.email, # user's email address
+    }
+  else
+    nil
+  end
+end
+```
+
+*All* of the user hash keys are optional, but you must provide at least one.
+
+---
+
+</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 are on Heroku, simply enable the
+[dyno metadata](https://devcenter.heroku.com/articles/dyno-metadata) feature to get this
+automatically. If you are not, simply add the follow environment variables to have the context
+set automatically.
+
+1. `RELEASE_COMMIT` - `2c3a0b24069af49b3de35b8e8c26765c1dba9ff0`
+2. `RELEASE_CREATED_AT` - `2015-04-02T18:00:42Z`
+3. `RELEASE_VERSION` - `v2.3.1`
+
+---
 
 </p></details>
 
 
 ## Jibber-Jabber
 
-<details><summary><strong>Which log events does Timber structure for me?</strong></summary><p>
+<details><summary><strong>Which events and context does Timber capture for me?</strong></summary><p>
 
-Out of the box you get everything in the [`Timber::Events`](lib/timber/events) namespace.
+Out of the box you get everything in the
+[`Timber::Events`](http://www.rubydoc.info/github/timberio/timber-ruby/Timber/Events) namespace.
 
-We also add context to every log, everything in the [`Timber::Contexts`](lib/timber/contexts)
+We also add context to every log, everything in the
+[`Timber::Contexts`](http://www.rubydoc.info/github/timberio/timber-ruby/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.
+was written. It is included in every log line. Think of it like join data for your logs. It's
+how Timber is able to accomplished tailing users (`context.user.id:1`).
+
+Lastly, you can checkout the specific integrations in
+[`Timber::Integrations`](lib/timber/integrations).
 
 ---
 
@@ -141,32 +415,13 @@ was written. It is included in every log line. Think of it like join data for yo
 
 <details><summary><strong>What about my current log statements?</strong></summary><p>
 
-They'll continue to work as expected. Timber adheres to the default `Logger` interface.
-Your previous logger calls will work as they always do.
+They'll continue to work as expected. Timber adheres to the default `::Logger` interface.
+Your previous logger calls will work as they always do. Just swap in `Timber::Logger` and
+you're good to go.
 
 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>How is Timber different?</strong></summary><p>
-
-1. **It's just _better_ logging**. Nothing beats well structured raw data. And that's exactly
-   what Timber aims to provide. There are no agents, special APIs, or proprietary data
-   sets that you can't access.
-2. **Improved log data quality.** Instead of relying on parsing alone, Timber ships libraries that
-   structure and augment your logs from _within_ your application. Improving your log data at the
-   source.
-3. **Human readability.** Timber _augments_ your logs without sacrificing human readability. For
-   example: `log message @metadata {...}`. And when you view your logs in the
-   [Timber console](https://app.timber.io), you'll see the human friendly messages
-   with the ability to view the associated metadata.
-4. **Long retention**. Logging is notoriously expensive with low retention. Timber
-   offers _6 months_ of retention by default with sane prices.
-5. **Normalized schema.** Have multiple apps? All of Timber's libraries adhere to our
-   [JSON schema](https://github.com/timberio/log-event-json-schema). This means queries, alerts,
-   and graphs for your ruby app can also be applied to your elixir app (for example).
-
 ---
 
 </p></details>