timber 2.0.24 → 2.1.0.rc1

data/lib/timber/cli/io.rb

@@ -0,0 +1,97 @@
+require "timber/cli/io/ansi"
+require "timber/cli/io/messages"
+
+module Timber
+  class CLI
+    # This is an abstraction for interfacing with IO devices. By default
+    # it uses the STDOUT and STDIN io devices, but can be passed other devices
+    # upon initialization.
+    class IO
+      attr_reader :io_out, :io_in
+      attr_accessor :api
+
+      def initialize(options = {})
+        @io_out = options[:io_out] || STDOUT
+        @io_in = options[:io_in] || STDIN
+      end
+
+      def ask(prompt, allowed_inputs, options = {}, iteration = 0)
+        event_prompt = options[:event_prompt] || prompt
+
+        if api
+          api.event(:waiting_for_input, prompt: event_prompt)
+        end
+
+        write prompt + " "
+        input = gets.downcase
+
+        if api
+          api.event(:received_input, prompt: event_prompt, value: input)
+        end
+
+        if allowed_inputs.include?(input)
+          input
+        else
+          if iteration == 10
+            raise "It appears we're having an issue receiving correct input for:\n\n" \
+              "#{prompt}\n\n" \
+              "We were expecting one of #{allowed_inputs}, but got #{input.inspect}."
+          else
+            puts "Woops! That's not a valid input. Please enter one of #{allowed_inputs.join(", ")}."
+            ask(prompt, allowed_inputs, options, iteration + 1)
+          end
+        end
+      end
+
+      def ask_to_proceed
+        message = "Ready to proceed?"
+        case ask_yes_no(message)
+        when :yes
+          true
+        when :no
+          ask_to_proceed
+        end
+      end
+
+      def ask_yes_no(message, options = {})
+        case ask(message + " (y/n)", ["y", "n"], options)
+        when "y"
+          :yes
+        when "n"
+          :no
+        end
+      end
+
+      def gets
+        value = io_in.gets
+        value ? value.chomp.downcase : ""
+      end
+
+      def puts(message, color = nil)
+        if color
+          message = ANSI.colorize(message, color)
+        end
+
+        io_out.puts(message)
+      end
+
+      def task(message, &block)
+        write IO::Messages.task_start(message), :blue
+        result = yield
+        puts IO::Messages.task_complete(message), :green
+        result
+      rescue Exception => e
+        puts IO::Messages.task_failed(message), :red
+        raise e
+      end
+
+      def write(message, color = nil)
+        if color
+          message = ANSI.colorize(message, color)
+        end
+
+        io_out.write(message)
+      end
+    end
+  end
+end

data/lib/timber/cli/io/ansi.rb

@@ -0,0 +1,22 @@
+module Timber
+  class CLI
+    class IO
+      module ANSI
+        def self.colorize(text, color)
+          return text if Gem.win_platform?
+
+          code =
+            case color
+            when :blue then 34
+            when :red then 31
+            when :green then 32
+            when :yellow then 33
+            else 0
+            end
+
+          "\e[#{code}m#{text}\e[0m"
+        end
+      end
+    end
+  end
+end

data/lib/timber/cli/io/messages.rb

@@ -0,0 +1,213 @@
+# encoding: utf-8
+
+require "timber/cli/io/ansi"
+require "timber/cli/os_helper"
+
+module Timber
+  class CLI
+    class IO
+      module Messages
+        extend self
+
+        APP_URL = "https://app.timber.io"
+        DOCS_URL = "https://timber.io/docs"
+        OBTAIN_KEY_DOCS_URL = "https://timber.io/docs/app/obtain-api-key/"
+        REPO_URL = "https://github.com/timberio/timber-ruby"
+        SUPPORT_EMAIL = "support@timber.io"
+        TWITTER_HANDLE = "@timberdotio"
+        WEBSITE_URL = "https://timber.io"
+        MAX_LENGTH = 80.freeze
+
+        def application_details(app)
+          message = <<-MESSAGE
+Woot! Your API 🔑  is valid:
+
+Name:      #{app.name} (#{app.environment})
+Framework: #{app.framework_type}
+Platform:  #{app.platform_type}
+MESSAGE
+          message.rstrip
+        end
+
+        def edit_app_url(app)
+          "#{APP_URL}"
+        end
+
+        def bad_experience_message
+          message = <<-MESSAGE
+Bummer! That is certainly not the experience we were going for.
+
+Could you tell us why you a bad experience?
+
+(this will be sent directly to the Timber engineering team)
+MESSAGE
+          message.rstrip
+        end
+
+        def git_commands
+          message = <<-MESSAGE
+    #{ANSI.colorize("git add config/initializers/timber.rb", :blue)}
+    #{ANSI.colorize("git commit -am 'Install the timber logger'", :blue)}
+MESSAGE
+          message.rstrip
+        end
+
+        def console_url(app)
+          message = <<-MESSAGE
+Your console URL: https://app.timber.io/organizations/timber/apps/#{app.slug}/console
+MESSAGE
+        end
+
+        def contact
+          message = <<-MESSAGE
+Website:       #{WEBSITE_URL}
+Documentation: #{DOCS_URL}
+Support:       #{SUPPORT_EMAIL}
+MESSAGE
+          message.rstrip
+        end
+
+        def copied_to_clipboard
+          IO::ANSI.colorize("(✓ copied to clipboard)", :green)
+        end
+
+        def http_environment_variables(api_key)
+          command = "export TIMBER_API_KEY=\"#{api_key}\""
+          copied = OSHelper.copy_to_clipboard(command)
+
+          message = <<-MESSAGE
+Great! Add this variable to your environment:
+
+    #{ANSI.colorize(command, :blue)}
+
+MESSAGE
+          message = message.rstrip
+
+          if copied
+            message << "\n    #{copied_to_clipboard}"
+          end
+
+          message
+        end
+
+        def free_data
+          message = <<-MESSAGE
+Because you're awesome, we've credited your account with ✨ 50mb✨. Get more:
+
+* Get ✨ 250mb✨ for tweeting your experience to #{TWITTER_HANDLE}
+* Get ✨ 100mb✨ for starring our repo: #{REPO_URL}
+* Get ✨ 100mb✨ for following #{TWITTER_HANDLE} on twitter
+MESSAGE
+          message.rstrip
+        end
+
+        def header
+          message = <<-MESSAGE
+🌲 Timber.io Ruby Installer
+
+ ^  ^  ^   ^      ___I_      ^  ^   ^  ^  ^   ^  ^
+/|\\/|\\/|\\ /|\\    /\\-_--\\    /|\\/|\\ /|\\/|\\/|\\ /|\\/|\\
+/|\\/|\\/|\\ /|\\   /  \\_-__\\   /|\\/|\\ /|\\/|\\/|\\ /|\\/|\\
+/|\\/|\\/|\\ /|\\   |[]| [] |   /|\\/|\\ /|\\/|\\/|\\ /|\\/|\\
+MESSAGE
+          message.rstrip
+        end
+
+        def heroku_install(app)
+          command = "heroku drains:add #{app.heroku_drain_url}"
+          copied = OSHelper.copy_to_clipboard(command)
+
+          message = <<-MESSAGE
+First, let's setup your Heroku drain. Run this command in a separate window:
+
+    #{ANSI.colorize(command, :blue)}
+MESSAGE
+          message = message.rstrip
+
+          if copied
+            message << "\n    #{copied_to_clipboard}"
+          end
+
+          message
+        end
+
+        def no_api_key_provided
+          message = <<-MESSAGE
+Hey there! Welcome to Timber. In order to proceed, you'll need an API key.
+If you already have one, you can run this installer like:
+
+    #{ANSI.colorize("bundle exec timber install my-api-key", :blue)}
+
+#{obtain_key_instructions}
+MESSAGE
+          message.rstrip
+        end
+
+        def obtain_key_instructions
+          message = <<-MESSAGE
+Don't have a key? Head over to:
+
+    #{ANSI.colorize(APP_URL, :blue)}
+
+For a simple guide, checkout out:
+
+    #{ANSI.colorize(OBTAIN_KEY_DOCS_URL, :blue)}
+
+If you're stuck, contact us:
+
+    #{ANSI.colorize(SUPPORT_EMAIL, :blue)}
+MESSAGE
+          message.rstrip
+        end
+
+        def separator
+          "--------------------------------------------------------------------------------"
+        end
+
+        def spinner(iteration)
+          rem = iteration % 3
+          case rem
+          when 0
+            "/"
+          when 1
+            "-"
+          when 2
+            "\\"
+          end
+        end
+
+        def failed
+          "Failed :("
+        end
+
+        def success
+          "✓ Success!"
+        end
+
+        def task_complete(message)
+          remainder = MAX_LENGTH - message.length - success.length
+
+          dots = "." * remainder
+          "\r#{message}#{dots}#{success}"
+        end
+
+        def task_failed(message)
+          remainder = MAX_LENGTH - message.length - failed.length
+
+          dots = "." * remainder
+          "\r#{message}#{dots}#{failed}"
+        end
+
+        def task_start(message)
+          remainder = MAX_LENGTH - message.length - success.length
+
+          "\r#{message}" + ("." * remainder)
+        end
+
+        def we_love_you_too
+          "Thanks! We 💖 you too!"
+        end
+      end
+    end
+  end
+end

data/lib/timber/cli/os_helper.rb

@@ -0,0 +1,53 @@
+module Timber
+  class CLI
+    module OSHelper
+      def self.copy_to_clipboard?
+        `which pbcopy` != ""
+      rescue Exception
+        false
+      end
+
+      def self.copy_to_clipboard(input)
+        ::IO.popen('pbcopy', 'w') { |f| f << input }
+        true
+      rescue Exception
+        false
+      end
+
+      def self.git_commit_changes
+        begin
+          `git add config/initializers/timber.rb`
+        rescue Exception
+        end
+
+        `git commit -am 'Install the timber logger'`
+        true
+      rescue Exception
+        false
+      end
+
+      def self.has_git?
+        begin
+          `which git` != ""
+        rescue Exception
+          false
+        end
+      end
+
+      # Attemps to open a URL in the user's default browser across
+      # the popular operating systems.
+      def self.open(link)
+        if RbConfig::CONFIG['host_os'] =~ /mswin|mingw|cygwin/
+          system "start #{link}"
+        elsif RbConfig::CONFIG['host_os'] =~ /darwin/
+          system "open #{link}"
+        elsif RbConfig::CONFIG['host_os'] =~ /linux|bsd/
+          system "xdg-open #{link}"
+        end
+        true
+      rescue Exception
+        false
+      end
+    end
+  end
+end

data/lib/timber/config.rb

@@ -1,10 +1,12 @@
 require "logger"
 require "singleton"
 
+require "timber/config/integrations"
+
 module Timber
-  # Interface for setting and reading Timber configuration.
+  # Singleton class for reading and setting Timber configuration.
   #
-  # For Rails apps this is installed into `config.timber`. See examples below.
+  # For Rails apps, this is installed into `config.timber`. See examples below.
   #
   # @example Rails example
   #   config.timber.append_metadata = false
@@ -12,9 +14,11 @@ module Timber
   #   config = Timber::Config.instance
   #   config.append_metdata = false
   class Config
+    # @private
     class NoLoggerError < StandardError; end
 
-    class SimpleFormatter < ::Logger::Formatter
+    # @private
+    class SimpleLogFormatter < ::Logger::Formatter
       # This method is invoked when a log event occurs
       def call(severity, timestamp, progname, msg)
         "[Timber] #{String === msg ? msg : msg.inspect}\n"
@@ -26,11 +30,10 @@ module Timber
 
     include Singleton
 
-    attr_writer :append_metadata, :debug_logger, :header_filters, :http_body_limit, :logger
+    attr_writer :http_body_limit
 
     # @private
     def initialize
-      @header_filters = []
       @http_body_limit = 2000
     end
 
@@ -44,11 +47,16 @@ module Timber
     #   config.timber.debug_logger = ::Logger.new(STDOUT)
     # @example Everything else
     #   Timber::Config.instance.debug_logger = ::Logger.new(STDOUT)
+    def debug_logger=(value)
+      @debug_logger = value
+    end
+
+    # Accessor method for {#debug_logger=}.
     def debug_logger
       @debug_logger
     end
 
-    # A convenience method for writing debug messages to a file.
+    # A convenience method for writing internal Timber debug messages to a file.
     #
     # @example Rails
     #   config.timber.debug_to_file("#{Rails.root}/log/timber.log")
@@ -62,19 +70,19 @@ module Timber
       file.binmode
       file.sync = config.autoflush_log
       file_logger = ::Logger.new(file)
-      file_logger.formatter = SimpleFormatter.new
+      file_logger.formatter = SimpleLogFormatter.new
       self.debug_logger = file_logger
     end
 
-    # A convenience method for writing debug messages to a file.
+    # A convenience method for writing internal Timber debug messages to STDOUT.
     #
     # @example Rails
-    #   config.timber.debug_to_file("#{Rails.root}/log/timber.log")
+    #   config.timber.debug_to_stdout
     # @example Everything else
-    #   Timber::Config.instance.debug_to_file("log/timber.log")
+    #   Timber::Config.instance.debug_to_stdout
     def debug_to_stdout
       stdout_logger = ::Logger.new(STDOUT)
-      stdout_logger.formatter = SimpleFormatter.new
+      stdout_logger.formatter = SimpleLogFormatter.new
       self.debug_logger = stdout_logger
     end
 
@@ -82,10 +90,13 @@ module Timber
     # It should be rare that you have to set this. If the aforementioned env vars are not
     # set please do.
     #
-    # @example Rails
-    #   config.timber.environment = "staging"
-    # @example Everything else
+    # @example If you do not set `RACK_ENV` or `RAILS_ENV`
     #   Timber::Config.instance.environment = "staging"
+    def environment=(value)
+      @environment = value
+    end
+
+    # Accessor method for {#environment=}
     def environment
       @environment ||= ENV["RACK_ENV"] || ENV["RAILS_ENV"] || "development"
     end
@@ -95,9 +106,14 @@ module Timber
     #
     # @example Rails
     #   # config/environments/production.rb
-    #   config.timber.filter_headers += ['api-key']
-    def header_filters
-      @header_filters
+    #   config.timber.header_filter_headers += ['api-key']
+    def http_header_filters=(value)
+      @http_header_filters = value
+    end
+
+    # Accessor method for {#http_header_filters=}
+    def http_header_filters
+      @http_header_filters ||= []
     end
 
     # Truncates captured HTTP bodies to this specified limit. The default is `2000`.
@@ -110,38 +126,75 @@ module Timber
     #   config.timber.http_body_limit = 500
     # @example Everything else
     #   Timber::Config.instance.http_body_limit = 500
+    def http_body_limit=(value)
+      @http_body_limit = value
+    end
+
+    # Accessor method for {#http_body_limit=}
     def http_body_limit
       @http_body_limit
     end
 
-    # This determines if the log messages should have metadata appended. Ex:
+    # Convenience method for accessing the various `Timber::Integrations::*` class
+    # settings. These provides settings for enabling, disabled, and silencing integrations.
+    # See {Integrations} for a full list of available methods.
+    def integrations
+      Integrations
+    end
+
+    # A convenience method that automatically sets Timber's configuration to closely match
+    # the behavior of the ruby lograge library. This makes it easier when transitioning
+    # from lograge.
     #
-    #     log message @metadata {...}
+    # It turns this:
     #
-    # By default, this is turned on for production and staging environments only. Other
-    # environment should set this setting explicitly.
+    #   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)
     #
-    # @example Rails
-    #   config.timber.append_metadata = false
-    # @example Everything else
-    #   Timber::Config.instance.append_metadata = false
-    def append_metadata?
-      if defined?(@append_metadata)
-        return @append_metadata == true
-      end
-
-      production? || staging?
+    # Into this:
+    #
+    #   Get "/" sent 200 OK in 79ms @metadata {...}
+    #
+    # In other words it:
+    #
+    # 1. Silences ActiveRecord SQL query logs.
+    # 2. Silences ActiveView template rendering logs.
+    # 3. Silences ActionController controller call logs.
+    # 4. Collapses HTTP request and response logs into a single event.
+    #
+    # Notice also that is is not exactly like lograge. This is intentional. Lograge has
+    # a number of downsides:
+    #
+    # 1. The attribute names (`method`, `format`, `status`, `db`, etc) are too generalized and vague.
+    #    This makes it _very_ likely that it will clash with other structured data you're
+    #    logging.
+    # 2. It doesn't support context making it near impossible to view in-app logs generated for
+    #    the same request.
+    def logrageify!
+      integrations.action_controller.silence = true
+      integrations.action_view.silence = true
+      integrations.active_record.silence = true
+      integrations.rack.http_events.collapse_into_single_event = true
     end
 
     # This is the _main_ logger Timber writes to. All of the Timber integrations write to
     # this logger instance. It should be set to your global logger. For Rails, this is set
     # automatically to `Rails.logger`, you should not have to set this.
     #
-    # @example Rails
-    #   Rails.logger = Timber::Logger.new(STDOUT)
-    #   config.timber.logger = Rails.logger
-    # @example Everything else
-    #   Timber::Config.instance.logger = Timber::Logger.new(STDOUT)
+    # @example Non-rails frameworks
+    #   my_global_logger = Timber::Logger.new(STDOUT)
+    #   Timber::Config.instance.logger = my_global_logger
+    def logger=(value)
+      @logger = value
+    end
+
+    # Accessor method for {#logger=}.
     def logger
       if @logger.is_a?(Proc)
         @logger.call()
@@ -150,13 +203,14 @@ module Timber
       end
     end
 
-    private
-      def production?
-        environment == PRODUCTION_NAME
-      end
+    # @private
+    def production?
+      environment == PRODUCTION_NAME
+    end
 
-      def staging?
-        environment == STAGING_NAME
-      end
+    # @private
+    def staging?
+      environment == STAGING_NAME
+    end
   end
 end