Timber

CircleCI Coverage Status Code Climate View docs

Timber is in beta testing. If interested, please email [email protected]

  1. What is timber?
  2. How it works
  3. Why timber?
  4. Logging Custom Events
  5. The Timber Console / Pricing
  6. Install

What is Timber?

Using your logs shouldn't be a time consuming, frustrating process! If you were like us, it goes something like this:

I need to centralize my logs, where should I send them? Which provider should I use? Wow, this is expensive. Why is searching so difficult and time consuming? Would structuring my logs help? Which format should I use? Will they still be human readable? What if the structure changes? What about logs from 3rd party libraries? Ahhh!!!

Timber solves this by providing a complete, managed, end-to-end logging solution that marries a beautiful, fast, console with libraries that automatically structure and enrich your logs.

How it works

The Timber ruby library takes care of all of the log structuring madness. For example, it turns this Rails log line:

Completed 200 OK in 117ms (Views: 85.2ms | ActiveRecord: 25.3ms)

Into this:

{
  "dt": "2016-12-01T02:23:12.236543Z",
  "level": "info",
  "message": "Completed 200 OK in 117ms (Views: 85.2ms | ActiveRecord: 25.3ms)",
  "context": {
    "http": {
      "method": "GET",
      "path": "/checkout",
      "remote_addr": "123.456.789.10",
      "request_id": "abcd1234"
    },
    "user": {  // <---- http://i.giphy.com/EldfH1VJdbrwY.gif
      "id": 2,
      "name": "Ben Johnson",
      "email": "[email protected]"
    }
  },
  "event": {
    "http_response": {
      "status": 200,
      "time_ms": 117
    }
  }
}

Notice we preserve the original log message. When viewing this event in the Timber Console, you'll see the simple, human readable line with the ability to view, and use, the attached structured data! Also, notice how rich the event is. Beecause we're inside your application, we can capture data beyond what's in the log line.

(for a full list see Timber::Events)

Why Timber?

Glad you asked! :)

  1. Human readable logs and rich structured data. You don't have to choose.
  2. Data beyond what's in the log line itself making your logs exceptionally useful.
  3. Normalized log data. Timber enforces a strict schema, meaning your log data, across all apps and languages will be normalized.
  4. Absolutely no lock-in or risk of code debt. No fancy API, no proprietary data format locked away in our servers, Timber is just good ol' loggin'.
  5. Fully managed, all the way from the log messages to the console you use. No fragile parsing rules or complicated interfaces.

Logging Custom Events

Another service? More lock-in? :*(

Nope! Logging custom events is Just Logging™. Check it out:

# Simple string (original Logger interface remains untouched)
Logger.warn "Payment rejected for customer abcd1234, reason: Card expired"

# Structured hash
Logger.warn message: "Payment rejected", type: :payment_rejected,
  data: {customer_id: "abcd1234", amount: 100, reason: "Card expired"}

# Using a Struct
PaymentRejectedEvent = Struct.new(:customer_id, :amount, :reason) do
  def message; "Payment rejected for #{customer_id}"; end
  def type; :payment_rejected; end
end
Logger.warn PaymentRejectedEvent.new("abcd1234", 100, "Card expired")

(for more examples, see the Timber::Logger docs)

No mention of Timber anywhere!

The Timber Console / Pricing

What good is structured log data if you can't search and visualize it?

The Timber Console is fast, modern, and beautiful console designed specifically for this library.

A few example queries:

  1. context.user.email:[email protected] - Tail a specific user!
  2. context.http.request_id:1234 - View all logs for a given HTTP request!
  3. event.http_reponse.time_ms>3000 - Easily find outliers and have the proper context to resolve them!
  4. level:warn - Log levels in your logs. Imagine that!

This is all gravy, but wouldn't the extra data get expensive?

If you opt to use the Timber Console, we only charge for the size of the message, dt, and event.custom attributes. Everything else is stored at no cost to you. Say wha?!. This ensures pricing remains predictable. We charge per GB sent to us and retained. No user limits, no weird feature matrixes, just data. Finally, the data is yours, in a simple non-proprietary JSON format that you can export to S3, Redshift, or any of our other integrations.

For more details checkout out timber.io.

Install

Timber is in beta testing. If interested, please email [email protected]

1. Install the gem:

# Gemfile
gem 'timber'

2. Install the logger:

Heroku:

# config/environments/production.rb (or staging, etc)
config.logger = Timber::Logger.new(STDOUT)

The command to add your log drain will be displayed in the Timber app after you add your application.

Non-Heroku:

# config/environments/production.rb (or staging, etc)
log_device = Timber::LogDevices::HTTP.new(ENV['TIMBER_KEY']) # key can be obtained by signing up at https://timber.io
config.logger = Timber::Logger.new(log_device)

Your Timber application key will be displayed in the Timber app after you add your application.

Other transport methods coming soon!

Rails TaggedLogging?

No probs! Use it as normal, Timber will even pull out the tags and include them in the context.

config.logger = ActiveSupport::TaggedLogging.new(Timber::Logger.new(STDOUT))