timber 2.1.3 → 2.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 551b1cf8e53fd0ba73e513e32377ad3d6113dfed
-  data.tar.gz: 7f701ccda19d0ba463605a217f59433484303206
+  metadata.gz: 8abcf84c32b728be216520c831ea391b2d8d4aff
+  data.tar.gz: bd66dceece6b234a4de867656eeaeebeb5c9a7a5
 SHA512:
-  metadata.gz: 2bf3d315d1f5d9a8bcfdbc4020fc712e709e7d74ddb4223e50b8f15b7dbaecfc4a068621282dbfe05c198d2b08e6704fafc1feae5ab7f798ed59de4f3a6d8c76
-  data.tar.gz: 2186c8a2d25d2d06f47af2f4b6093c0b1d364ada661b7c965387e91978323211e6387cbb078550f1ab1c29716351e9f832465acc948ffaa287f55e044ab4be15
+  metadata.gz: 71850c881fe047e8e80f850010f99989b0206be96087cbf15ff84adb09b6d9780b062ba492e65c2fffd659bd2d013c12f6e2b829c60847d0e750ae56f9d6268d
+  data.tar.gz: 27c4421fcfa563a47d6d92911effde2472a3e48b4ba5da9b7def6ee3fa031f1bcc2d3a9cd54da88a3aa13db1f0a19e5556eb6d5c84fba4394aa62f28ab353c54

data/README.md

@@ -1,4 +1,4 @@
-# 🌲 Timber - Log Better. Solve Problems Faster.
+# 🌲 Timber - Great Ruby Logging Made Easy
 
 [![ISC License](https://img.shields.io/badge/license-ISC-ff69b4.svg)](LICENSE.md)
 [![Yard Docs](http://img.shields.io/badge/yard-docs-blue.svg)](http://www.rubydoc.info/github/timberio/timber-ruby)
@@ -6,14 +6,15 @@
 
 ## 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
@@ -36,29 +37,39 @@ your logs into rich, useful, readable events. When paired with the
 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)
 
 ---
 
@@ -66,22 +77,22 @@ 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.
+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)
 
 ---
 
@@ -89,20 +100,21 @@ end
 
 <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.
+
+### How to use it
 
-Here's a timing example. Notice how Timber automatically calculates the time and adds the timing
-to the message.
+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`:
@@ -115,12 +127,13 @@ 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>
 
@@ -130,11 +143,13 @@ you desire.
 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
@@ -143,6 +158,8 @@ config = Timber::Config.instance
 config.logrageify!()
 ```
 
+## How it works
+
 It turns this:
 
 ```
@@ -174,6 +191,8 @@ 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:
 
@@ -198,6 +217,11 @@ For a full list of integration settings, see
 
 <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
@@ -217,33 +241,6 @@ The first parameter being the traditional Rack env hash, the second being a
 
 </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
@@ -251,6 +248,8 @@ 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:
 
@@ -281,7 +280,11 @@ end
 <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:
 
@@ -296,70 +299,44 @@ All variables are optional, but at least one must be present.
 </p></details>
 
 
-## Jibber-Jabber
-
-<details><summary><strong>Which log events does Timber structure for me?</strong></summary><p>
-
-Out of the box you get everything in the [`Timber.Events`](lib/timber/events) namespace.
-
-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.
-
----
-
-</p></details>
-
-<details><summary><strong>What about my current log statements?</strong></summary><p>
-
-They'll continue to work as expected. Timber adheres strictly to the default `Logger` interface
-and will never deviate in *any* way.
+## Integrations
 
-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).
+[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.
 
-</p></details>
+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)
 
-<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:
+## Do amazing things with your logs
 
-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.
+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:
 
-### 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>
+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)
 
 
 ## The Timber Console
 
-[![Timber Console](http://files.timber.io/images/readme-interface7.gif)](https://app.timber.io)
+[![Timber Console](http://files.timber.io/images/readme-interface7.gif)](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>

data/lib/timber/contexts/user.rb

@@ -13,17 +13,19 @@ module Timber
     class User < Context
       @keyspace = :user
 
-      attr_reader :id, :name, :email
+      attr_reader :id, :name, :email, :type, :meta
 
       def initialize(attributes)
         @id = attributes[:id]
         @name = attributes[:name]
         @email = attributes[:email]
+        @type = attributes[:type]
+        @meta = attributes[:meta]
       end
 
       # Builds a hash representation containing simple objects, suitable for serialization (JSON).
       def as_json(_options = {})
-        {id: Timber::Util::Object.try(id, :to_s), name: name, email: email}
+        {id: Timber::Util::Object.try(id, :to_s), name: name, email: email, type: type, meta: meta}
       end
     end
   end

data/lib/timber/log_entry.rb

@@ -9,7 +9,7 @@ module Timber
   class LogEntry #:nodoc:
     DT_PRECISION = 6.freeze
     MESSAGE_MAX_BYTES = 8192.freeze
-    SCHEMA = "https://raw.githubusercontent.com/timberio/log-event-json-schema/v3.0.7/schema.json".freeze
+    SCHEMA = "https://raw.githubusercontent.com/timberio/log-event-json-schema/v3.1.1/schema.json".freeze
 
     attr_reader :context_snapshot, :event, :level, :message, :progname, :tags, :time, :time_ms
 

data/lib/timber/version.rb

@@ -1,3 +1,3 @@
 module Timber
-  VERSION = "2.1.3"
+  VERSION = "2.1.4"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: timber
 version: !ruby/object:Gem::Version
-  version: 2.1.3
+  version: 2.1.4
 platform: ruby
 authors:
 - Timber Technologies, Inc.
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-08-14 00:00:00.000000000 Z
+date: 2017-08-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: msgpack