timberio 1.0.0.beta1 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: afe17c9b981b2874cc9904a025bc1b644241e9fb
-  data.tar.gz: 249022ca368e1e7eb482c204ac4764d720777169
+  metadata.gz: 7561d4af5b30a06c3964a04ff0ff21d3f36bca31
+  data.tar.gz: 5072e0329ba5799c2c73622b483f2301d2055797
 SHA512:
-  metadata.gz: 0491b73371eb2d6f77a986aa7853f1811a1d2b0522c825232edf43c94fbacc2e55f290e7be98df494511853e7067fe7d3a75aa772930af29c204a8bc27ef8786
-  data.tar.gz: 150da28499ece3b4c99bc9067f525e3c4ffb08ef61499bd85b154f89726e4359ed7b8abdacd407f4435c29ac5641d675df4791564fa0cbee9c0da7b740efb921
+  metadata.gz: 977a6aff51b60657619677e63892a129fbe43fe90cdbffcb1678a3c19434676b264b79853a046a9e1aa3596f2d66d09cc6185d9755bc48a3499409a3670269e8
+  data.tar.gz: f17d76bef300091e365087f7c8c892f0ef5407fdee4fc12b7f739c23fc0255386636c21e6d636e324b5fb183ddf60ff32c3f07628345602505b458ebe39dc40b

data/.gitignore

@@ -1,14 +1,15 @@
 .DS_Store
 .rvmrc
+.ruby-version
 coverage
 Gemfile.lock
 *.swp
+*.gem
 
 /.bundle
 /.yardoc
 /doc
-/gemfiles/*.lock
-/gemfiles/vendor
+/gemfiles
 /log
 /tmp
 /pkg

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--order rand

data/.yardopts

@@ -0,0 +1,6 @@
+--protected
+--no-private
+--embed-mixin ClassMethods
+-
+LICENSE.md
+README.md

data/Appraisals

@@ -1,3 +1,7 @@
+appraise "rails-2.3.X" do
+  gem "rails", "~> 2.3.18"
+end
+
 appraise "rails-3.0.X" do
   gem "rails", "~> 3.0.20"
 end

data/Gemfile

@@ -14,7 +14,15 @@ group :test do
   gem 'sqlite3'
   gem 'terminal-table'
   gem 'timecop'
-  gem 'webmock', '~> 2.0.3'
+
+  ruby_version = Gem::Version.new("#{RUBY_VERSION}")
+  if ruby_version < Gem::Version.new("2.0.0")
+    gem 'public_suffix', '~> 1.4.6'
+    gem 'term-ansicolor', '~> 1.3.2'
+    gem 'webmock', '~> 2.2.0'
+  else
+    gem 'webmock'
+  end
 
   # for coveralls
   gem 'rest-client', '~> 1.8' # >= 2.0 requires ruby 2+, we have tests for 1.9

data/LICENSE.md

@@ -0,0 +1,15 @@
+# License
+
+Copyright (c) 2016, Timber Technologies, Inc.
+
+Permission to use, copy, modify, and/or distribute this software for any purpose
+with or without fee is hereby granted, provided that the above copyright notice
+and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
+FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS
+OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
+TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF
+THIS SOFTWARE.

data/README.md

@@ -1,7 +1,7 @@
-# Timber.io - Ruby Gem - Powerful Ruby Logging
+# Timber
 
 <p align="center" style="background: #140f2a;">
-<a href="http://github.com/timberio/timber-ruby"><img src="http://res.cloudinary.com/timber/image/upload/c_scale,w_537/v1464797600/how-it-works_sfgfjp.gif" /></a>
+<a href="http://github.com/timberio/timber-ruby"><img src="http://files.timber.io/images/ruby-library-readme-header.gif" height="370" /></a>
 </p>
 
 [![CircleCI](https://circleci.com/gh/timberio/timber-ruby.svg?style=shield&circle-token=:circle-token)](https://circleci.com/gh/timberio/timber-ruby/tree/master)
@@ -9,14 +9,176 @@
 [![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)
 
-**Note: Timber is in alpha testing, if interested in joining, please visit http://timber.io**
 
-[Timber](http://timber.io) is a different kind of logging platform; it goes beyond traditional logging by enriching your logs with *app* context. Turning them into rich structured events without altering the essence of logging. See for yourself at [timber.io](http://timber.io).
+1. [What is timber?](#what-is-timber)
+2. [Examples](#examples)
+3. [Pricing](#pricing)
+2. [Install](#install)
+
+
+## What is Timber?
+
+Glad you asked :) Timber tames the crazy world that is logging. First, it *automatically*
+augments your logs with structured data. Second, it provides a transparent, no lock-in, API
+for logging your own events. Lastly, it can be paired with a [simple modern console](https://timber.io) for querying.
+
+For example, it automatically turns this:
+
+```
+Completed 200 OK in 117ms (Views: 85.2ms | ActiveRecord: 25.3ms)
+```
+
+Into this:
+
+```json
+{
+  "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": {
+      "id": 2,
+      "name": "Ben Johnson",
+      "email": "ben@johnson.com"
+    }
+  },
+  "event": {
+    "http_response": {
+      "status": 200,
+      "time_ms": 117
+    }
+  }
+}
+```
+
+It does the same for `http requests`, `sql queries`, `exceptions`, `template renderings`,
+and any other event your framework logs. (for a full list see `Timber::Events`)
+
+This enables you to query your logs in a way that
+[even your mother would get excited about](http://i.giphy.com/7JYWGKgwxga5i.gif)!
+
+  1. `context.user.email:ben@johnson.com` - 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!
+
+
+## Examples
+
+> Another service? More lock-in? More code debt? More sadness? :*(
+
+Nope! This is exactly why we created Timber. Timber is Just Logging™. No special API, no risk
+of code debt, no weird proprietary data format locked away in our servers. Absolutely no lock-in!
+
+Besides automatically capturing known events, you can also log custom events. Check it out:
+
+```ruby
+# 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 Timber specific code anywhere! In fact, this approach pushes things the opposite way. What if,
+as a result of structured logging, you could start decoupling other services from your application?
+
+Before:
+
+```
+               |---[HTTP]---> sentry / bugsnag / etc
+My Application |---[HTTP]---> librato / graphite / etc
+               |---[HTTP]---> new relic / etc
+               |--[STDOUT]--> logs
+                                |---> Logging service
+                                |---> S3
+                                |---> RedShift
+```
+
+
+After:
+
+```
+                                                    |-- sentry / bugsnag / etc
+                                                    |-- librato / graphite / etc
+My Application |--[STDOUT]--> logs ---> Timber ---> |-- new relic / etc
+                               ^                    |-- S3
+                               |                    |-- RedShift
+                               |                                 ^
+                    fast, efficient, durable,                    |
+                     replayable, auditable,        change any of these without
+                          just logging                  touching your code
+                                                       *and* backfill them!
+```
+
+
+## Pricing
+
+> This is all gravy, but wouldn't it get expensive?
+
+If you opt to send your data to the [Timber service](https://timber.io), 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?!](http://i.giphy.com/l0HlL2vlfpWI0meJi.gif). This ensures
+pricing remains predictable. And our pricing is simple, we charge per GB transferred to us and
+retained, no user limits, and no weird feature matrixes. Lastly, the data is yours, in a simple
+non-proprietary JSON format.
+
+For more details checkout our [timber.io](https://timber.io).
 
 ## Install
 
-To ensure logs are transported efficiently, Timber offers a variety of solutions. Please choose your preferred method below:
+### 1. Install the gem:
+
+```ruby
+# Gemfile
+gem 'timberio', require: "timber"
+```
+
+### 2. Install the logger:
+
+#### Heroku:
+
+```ruby
+# config/environments/production.rb (or staging, etc)
+config.logger = ActiveSupport::TaggedLogging.new(Timber::Logger.new(STDOUT))
+```
+
+The command to add your log drain will be displayed in the [Timber app](https://app.timber.io)
+after you add your application.
+
+#### Non-Heroku:
+
+```ruby
+# 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 = ActiveSupport::TaggedLogging.new(Timber::Logger.new(log_device))
+```
+
+Your Timber application key will be displayed in the [Timber app](https://app.timber.io)
+after you add your application.
+
+
+*Other transport methods coming soon!*
+
+---
+
+That's it! Log to your heart's content.
 
-1. **[Rails on Heroku](docs/installation/rails_on_heroku.md)** - Takes advantage of Heroku's logplex.
-2. **[Rails over HTTP](docs/installation/rails_over_http.md)** - Quick and easy. No agent. Deploy and go.
-3. ...more coming soon!
+For documentation on logging structured events, and other features,
+checkout [the docs](http://thedocs.com/). For more information on Timber visit [timber.io](https://timber.io).

data/circle.yml

@@ -5,6 +5,8 @@ machine:
 dependencies:
   override:
     - PATH=/home/ubuntu/.rvm/gems/ruby-1.9.3-p448/bin:$PATH rvm-exec 1.9.3 bundle install
+    - PATH=/home/ubuntu/.rvm/gems/ruby-1.9.3-p448/bin:$PATH rvm-exec 1.9.3 appraisal generate
+    - PATH=/home/ubuntu/.rvm/gems/ruby-1.9.3-p448/bin:$PATH rvm-exec 1.9.3 appraisal rails-2.3.X bundle install
     - PATH=/home/ubuntu/.rvm/gems/ruby-1.9.3-p448/bin:$PATH rvm-exec 1.9.3 appraisal rails-3.0.X bundle install
     - PATH=/home/ubuntu/.rvm/gems/ruby-1.9.3-p448/bin:$PATH rvm-exec 1.9.3 appraisal rails-3.1.X bundle install
     - PATH=/home/ubuntu/.rvm/gems/ruby-1.9.3-p448/bin:$PATH rvm-exec 1.9.3 appraisal rails-3.2.X bundle install
@@ -17,11 +19,12 @@ dependencies:
 
 test:
   override:
-    - PATH=/home/ubuntu/.rvm/gems/ruby-1.9.3-p448/bin:$PATH rvm-exec 1.9.3 appraisal rails-3.0.X rake spec
-    - PATH=/home/ubuntu/.rvm/gems/ruby-1.9.3-p448/bin:$PATH rvm-exec 1.9.3 appraisal rails-3.1.X rake spec
-    - PATH=/home/ubuntu/.rvm/gems/ruby-1.9.3-p448/bin:$PATH rvm-exec 1.9.3 appraisal rails-3.2.X rake spec
-    - PATH=/home/ubuntu/.rvm/gems/ruby-2.3.0/bin:$PATH rvm-exec 2.3.0 appraisal rails-4.0.X rake spec
-    - PATH=/home/ubuntu/.rvm/gems/ruby-2.3.0/bin:$PATH rvm-exec 2.3.0 appraisal rails-4.1.X rake spec
-    - PATH=/home/ubuntu/.rvm/gems/ruby-2.3.0/bin:$PATH rvm-exec 2.3.0 appraisal rails-4.2.X rake spec
-    - PATH=/home/ubuntu/.rvm/gems/ruby-2.3.0/bin:$PATH rvm-exec 2.3.0 appraisal rails-5.0.X rake spec
-    - PATH=/home/ubuntu/.rvm/gems/ruby-2.3.0/bin:$PATH rvm-exec 2.3.0 appraisal rails-edge rake spec
+    - RAILS_23=true PATH=/home/ubuntu/.rvm/gems/ruby-1.9.3-p448/bin:$PATH rvm-exec 1.9.3 appraisal rails-2.3.X rspec --tag rails_23
+    - PATH=/home/ubuntu/.rvm/gems/ruby-1.9.3-p448/bin:$PATH rvm-exec 1.9.3 appraisal rails-3.0.X rspec
+    - PATH=/home/ubuntu/.rvm/gems/ruby-1.9.3-p448/bin:$PATH rvm-exec 1.9.3 appraisal rails-3.1.X rspec
+    - PATH=/home/ubuntu/.rvm/gems/ruby-1.9.3-p448/bin:$PATH rvm-exec 1.9.3 appraisal rails-3.2.X rspec
+    - PATH=/home/ubuntu/.rvm/gems/ruby-2.3.0/bin:$PATH rvm-exec 2.3.0 appraisal rails-4.0.X rspec
+    - PATH=/home/ubuntu/.rvm/gems/ruby-2.3.0/bin:$PATH rvm-exec 2.3.0 appraisal rails-4.1.X rspec
+    - PATH=/home/ubuntu/.rvm/gems/ruby-2.3.0/bin:$PATH rvm-exec 2.3.0 appraisal rails-4.2.X rspec
+    - PATH=/home/ubuntu/.rvm/gems/ruby-2.3.0/bin:$PATH rvm-exec 2.3.0 appraisal rails-5.0.X rspec
+    - PATH=/home/ubuntu/.rvm/gems/ruby-2.3.0/bin:$PATH rvm-exec 2.3.0 appraisal rails-edge rspec

data/lib/timber/config.rb

@@ -1,25 +1,18 @@
+require "singleton"
+
 module Timber
+  # Interface for configuring Timber.
+  #
+  # @note If using rails this will be installed in the `config` object via `config.timber`.
   class Config
-    include Patterns::DelegatedSingleton
-
-    attr_writer :application_key, :enabled, :logger
-
-    def application_key
-      @application_key ||= ENV['TIMBER_KEY']
-    end
+    include Singleton
 
-    def enabled
-      return @enabled if defined?(@enabled)
-      @enabled = true
-    end
-
-    def enabled?
-      enabled == true
-    end
+    attr_writer :logger
 
-    # Internal logger for the Timber library, only for debugging purposes.
+    # Set a logger to view internal Timber library log message.
+    # Useful for debugging. Defaults to `::Logger.new(nil)`.
     def logger
-      @logger ||= InternalLogger.new(nil)
+      @logger ||= Logger.new(nil)
     end
   end
-end
+end

data/lib/timber/context.rb

@@ -1,76 +1,17 @@
-require "securerandom"
-
 module Timber
+  # Base class for all `Timber::Contexts::*` classes.
+  # @private
   class Context
-    include Patterns::ToJSON
-    include Patterns::ToLogfmt
-
-    PATH_DELIMITER = ".".freeze
-    SECURE_RANDOM_LENGTH = 16.freeze
-
-    class << self
-      def json_shell(&_block)
-        {_root_key => yield}
-      end
-
-      def _path
-        @path ||= Macros::LogfmtEncoder.encode(json_shell { 1 }).split("=").first
-      end
-
-      def _root_key
-        @_root_key ||= const_get(:ROOT_KEY)
-      end
-
-      def _version
-        @_version ||= const_get(:VERSION)
-      end
-    end
-
-    def _dt
-      @_dt ||= Time.now.utc
-    end
-
-    def _path
-      self.class._path
+    def keyspace
+      raise NoImplementedError.new
     end
 
-    def _version
-      self.class._version
+    def as_json(options = {})
+      raise NotImplementedError.new
     end
 
-    def _root_key
-      self.class._root_key
+    def to_json(options = {})
+      Util::Hash.compact(as_json).to_json(options)
     end
-
-    def as_json(*args)
-      @as_json ||= json_shell { super }
-    end
-
-    def json_shell(&block)
-      self.class.json_shell(&block)
-    end
-
-    def inspect(*_args)
-      "#<#{self.class.name}:#{object_id} ...>"
-    end
-
-    # Some contexts hold mutable object that change as the context block
-    # executes. This method checks the state of that object to ensure
-    # that the context is valid and ready to be copied for each log line.
-    def valid?
-      true
-    end
-
-    private
-      def json_payload
-        @json_payload ||= {
-          :_dt => Macros::DateFormatter.format(_dt),
-          :_version => _version
-        }
-      end
-
-      def generate_secure_random
-        SecureRandom.urlsafe_base64(SECURE_RANDOM_LENGTH)
-      end
   end
-end
+end

data/lib/timber/contexts/custom.rb

@@ -0,0 +1,27 @@
+module Timber
+  module Contexts
+    # Custom contexts allow you to add application specific context not covered elsewhere.
+    #
+    # @example Adding a context
+    #   custom_context = Timber::Contexts::Custom.new(type: :keyspace, data: %{my: "data"})
+    #   Timber::CurrentContext.with(custom_context) do
+    #     # ... anything logged here will have the context ...
+    #   end
+    class Custom < Context
+      attr_reader :type, :data
+
+      def initialize(attributes)
+        @type = attributes[:type] || raise(ArgumentError.new(":type is required"))
+        @data = attributes[:data] || raise(ArgumentError.new(":data is required"))
+      end
+
+      def keyspace
+        :custom
+      end
+
+      def as_json(_options = {})
+        {type => data}
+      end
+    end
+  end
+end

data/lib/timber/contexts/http.rb

@@ -0,0 +1,28 @@
+module Timber
+  module Contexts
+    # The HTTP content tracks the current HTTP request being processed. This serves
+    # as join data across your logs, allowing you to query all logs for any attribute
+    # presented here. For example, viewing all logs for a given request_id.
+    #
+    # @note This context should be installed automatically through probes,
+    #   such as the {Probes::RackHTTPContext} probe.
+    class HTTP < Context
+      attr_reader :method, :path, :remote_addr, :request_id
+
+      def initialize(attributes)
+        @method = attributes[:method] || raise(ArgumentError.new(":method is required"))
+        @path = attributes[:path] || raise(ArgumentError.new(":path is required"))
+        @remote_addr = attributes[:remote_addr]
+        @request_id = attributes[:request_id]
+      end
+
+      def keyspace
+        :http
+      end
+
+      def as_json(_options = {})
+        {:method => method, :path => path, :remote_addr => remote_addr, :request_id => request_id}
+      end
+    end
+  end
+end

data/lib/timber/contexts/organization.rb

@@ -1,33 +1,35 @@
 module Timber
   module Contexts
+    # The organization context tracks the organization of the currently
+    # authenticated user.
+    #
+    # You will want to add this context at the time you determine
+    # the organization a user belongs to, typically in the authentication
+    # flow.
+    #
+    # Example:
+    #
+    #   organization_context = Timber::Contexts::Organization.new(id: "abc1234", name: "Timber Inc")
+    #   Timber::CurrentContext.with(organization_context) do
+    #     # Logging will automatically include this context
+    #     logger.info("This is a log message")
+    #   end
+    #
     class Organization < Context
-      ROOT_KEY = :organization.freeze
-      VERSION = 1.freeze
+      attr_reader :id, :name
 
-      attr_reader :organization
-
-      def id
-        return @id if defined?(@id)
-        @id = organization.respond_to?(:id) ? organization.id : nil
+      def initialize(attributes)
+        @id = attributes[:id]
+        @name = attributes[:name]
       end
 
-      def name
-        return @name if defined?(@name)
-        @name = organization.respond_to?(:name) ? organization.name : nil
+      def keyspace
+        :organization
       end
 
-      def valid?
-        !organization.nil?
+      def as_json(_options = {})
+        {id: id, name: name}
       end
-
-      private
-        def json_payload
-          @json_payload ||= Macros::DeepMerger.merge({
-            # order is relevant for logfmt styling
-            :id => id,
-            :name => name
-          }, super).freeze
-        end
     end
   end
-end
+end

data/lib/timber/contexts/user.rb

@@ -1,39 +1,36 @@
 module Timber
   module Contexts
+    # The user context tracks the currently authenticated user.
+    #
+    # You will want to add this context at the time log the user in, typically
+    # during the authentication flow.
+    #
+    # Note: Timber will attempt to automatically add this if you add a #current_user
+    # method to your controllers. Most authentication solutions do this for you automatically.
+    #
+    # Example:
+    #
+    #   user_context = Timber::Contexts::User.new(id: "abc1234", name: "Ben Johnson")
+    #   Timber::CurrentContext.with(user_context) do
+    #     # Logging will automatically include this context
+    #     logger.info("This is a log message")
+    #   end
+    #
     class User < Context
-      ROOT_KEY = :user.freeze
-      VERSION = 1.freeze
+      attr_reader :id, :name
 
-      attr_reader :user
-
-      def email
-        return @email if defined?(@email)
-        @email = user.respond_to?(:email) ? user.email : nil
-      end
-
-      def id
-        return @id if defined?(@id)
-        @id = user.respond_to?(:id) ? user.id : nil
+      def initialize(attributes)
+        @id = attributes[:id]
+        @name = attributes[:name]
       end
 
-      def name
-        return @name if defined?(@name)
-        @name = user.respond_to?(:name) ? user.name : nil
+      def keyspace
+        :user
       end
 
-      def valid?
-        !user.nil?
+      def as_json(_options = {})
+        {id: id, name: name}
       end
-
-      private
-        def json_payload
-          @json_payload ||= Macros::DeepMerger.merge({
-            # order is relevant for logfmt styling
-            :id => id,
-            :name => name,
-            :email => email
-          }, super).freeze
-        end
     end
   end
-end
+end

data/lib/timber/contexts.rb

@@ -1,23 +1,10 @@
-# Base, order is relevant
-require "timber/contexts/dynamic_values"
-require "timber/contexts/exception"
-require "timber/contexts/http_request"
-require "timber/contexts/http_response"
-require "timber/contexts/logger"
+require "timber/contexts/custom"
+require "timber/contexts/http"
 require "timber/contexts/organization"
-require "timber/contexts/server"
-require "timber/contexts/sql_query"
-require "timber/contexts/template_render"
 require "timber/contexts/user"
 
-# Sub contexts, order is relevant
-require "timber/contexts/http_requests/rack"
-require "timber/contexts/http_requests/action_controller_specific"
-require "timber/contexts/http_responses/action_controller"
-require "timber/contexts/organizations/action_controller"
-require "timber/contexts/servers/heroku_specific"
-require "timber/contexts/sql_queries/active_record"
-require "timber/contexts/sql_queries/active_record_specific"
-require "timber/contexts/template_renders/action_view"
-require "timber/contexts/template_renders/action_view_specific"
-require "timber/contexts/users/action_controller"
+module Timber
+  # @private
+  module Contexts
+  end
+end