honeybadger 3.1.2 → 3.2.0.beta1

data/TROUBLESHOOTING.md

@@ -1,137 +1,3 @@
 # Troubleshooting
 
-Common issues/workarounds are documented here. If you don't find a solution to
-your problem here or in our [support
-documentation](http://docs.honeybadger.io/), email support@honeybadger.io and
-one or all of our helpful founders will assist you!
-
-## Upgrade the gem
-
-Before digging deeper into this guide, **make sure you are on the latest minor
-release of the honeybadger gem** (i.e. 3.x.x). There's a chance you've found a bug
-which has already been fixed!
-
-## Send a Test Exception
-
-You can send a test exception using the `honeybadger` command line utility:
-
-```bash
-$ honeybadger test
-```
-
-## How to enable verbose logging
-
-Troubleshooting any of these issues will be much easier if you can see what's
-going on with Honeybadger when your app starts. To enable verbose debug logging,
-run your app with the `HONEYBADGER_DEBUG=true` environment variable or add the
-following to your *honeybadger.yml* file:
-
-```yml
-debug: true
-```
-
-By default Honeybadger will log to the default Rails logger or STDOUT outside of
-Rails. When debugging it can be helpful to have a dedicated log file for
-Honeybadger. To enable one, set the
-`HONEYBADGER_LOGGING_PATH=log/honeybadger.log` environment variable or add the
-following to your *honeybadger.yml* file:
-
-```yml
-logging:
-  path: 'log/honeybadger.log'
-```
-
-## Common Issues
-
-### My errors aren't being reported
-
-Error reporting may be disabled for several reasons:
-
-#### Honeybadger is not configured
-
-Honeybadger requires at minimum the `api_key` option to be set. If Honeybadger
-is unable to start due to invalid configuration, you should see something like
-the following in your logs:
-
-```
-** [Honeybadger] Unable to start Honeybadger -- api_key is missing or invalid. level=2 pid=18195
-```
-
-#### Honeybadger is in a development environment
-
-Errors are ignored by default in the "test", "development", and "cucumber"
-environments. To explicitly enable Honeybadger in a development environment, set
-the `HONEYBADGER_REPORT_DATA=true` environment variable or add the following
-configuration to *honeybadger.yml* file (change "development" to the name of the
-environment you want to enable):
-
-```yml
-development:
-  report_data: true
-```
-
-##### The `better_errors` gem is installed
-
-The [`better_errors` gem](https://github.com/charliesome/better_errors) conflicts with the Honeybadger gem when in development mode. To be able to report errors from development you must first temporarily disable/remove the `better_errors` gem. Better Errors should not affect production because it should never be enabled in production.
-
-#### Is the error ignored by default?
-
-Honeybadger ignores [this list of
-exceptions](https://github.com/honeybadger-io/honeybadger-ruby/blob/master/lib/honeybadger/config/defaults.rb#L7)
-by default.
-
-#### Is the error rescued without re-raising?
-
-Honeybadger will automatically report exceptions in many frameworks including
-Rails, Sinatra, Sidekiq, Rake, etc. For exceptions to reported automatically
-they must be raised; check for any `rescue` statements in your app where
-exceptions may be potentially silenced. In Rails, this includes any use of
-`rescue_from` which does not re-raise the exception.
-
-Errors which are handled in a `rescue` block without re-raising must be reported
-to Honeybadger manually:
-
-```ruby
-begin
-  fail 'This error will be handled internally.'
-rescue => e
-  Honeybadger.notify(e)
-end
-```
-
-### I'm not receiving notifications
-
-#### Was the error reported already and is unresolved?
-
-By default we only send notifications the first time an exception happens, and
-when it re-occurs after being marked resolved. If an exception happens 100
-times, but was never resolved you'll only get 1 email about it.
-
-## Sidekiq/Resque/ActiveJob/etc.
-
-- See [Common Issues](#common-issues)
-
-### If the error is ignored by default
-
-Honeybadger ignores [this list of
-exceptions](https://github.com/honeybadger-io/honeybadger-ruby/blob/master/lib/honeybadger/config/defaults.rb#L7)
-by default. It may be surprising that `ActiveRecord::RecordNotFound` is on that
-list; that's because in a Rails controller that error class is treated as a 404
-not-found and handled internally (and thus we shouldn't report it).  Support for
-Sidekiq and friends was added later and inherited the default. We would like to
-provide alternate defaults for job processors in the future, but for now you can
-provide your own list of ignored class names if you want to change this
-behavior:
-
-```
-HONEYBADGER_EXCEPTIONS_IGNORE_ONLY=Error,ClassNames,Here bundle exec sidekiq
-```
-
-## Command line utility
-
-If you get an error while running the `honeybadger` command line utility:
-
-0. Try prefixing the command with `bundle exec`...even if you normally rely on bin-stubs to do this for you
-1. Check `honeybadger help` if you're having trouble with the syntax for a specific command.
-2. Try enabling [verbose logging](#how-to-enable-verbose-logging) to get more info
-3. Ask Us! We're always here to help. Just copy the terminal output and email it to us at support@honeybadger.io
+Troubleshooting instructions have been moved to our [documentation site](http://docs.honeybadger.io/ruby/support/troubleshooting.html)!

data/lib/honeybadger/agent.rb

@@ -19,7 +19,7 @@ module Honeybadger
   # This also includes the Rack environment when using the Honeybadger rack
   # middleware.
   #
-  # Examples:
+  # Examples
   #
   #   # Standard usage:
   #   OtherBadger = Honeybadger::Agent.new
@@ -70,13 +70,22 @@ module Honeybadger
     #                     to build the notice. All other types of objects will
     #                     be converted to a String and used as the `:error_message`.
     # opts              - The options Hash when the first argument is an
-    #                     Exception. (default: {}):
+    #                     Exception (default: {}):
     #                     :error_message - The String error message.
-    #                     :error_class   - The String class name of the error. (optional)
-    #                     :force         - Always report the exception, even when
-    #                                      ignored. (optional)
-    #
-    # Examples:
+    #                     :error_class   - The String class name of the error (default: "Notice").
+    #                     :backtrace     - The Array backtrace of the error (optional).
+    #                     :fingerprint   - The String grouping fingerprint of the exception (optional).
+    #                     :force         - Always report the exception when true, even when ignored (default: false).
+    #                     :tags          - The String comma-separated list of tags (optional).
+    #                     :context       - The Hash context to associate with the exception (optional).
+    #                     :controller    - The String controller name (such as a Rails controller) (optional).
+    #                     :action        - The String action name (such as a Rails controller action) (optional).
+    #                     :parameters    - The Hash HTTP request paramaters (optional).
+    #                     :session       - The Hash HTTP request session (optional).
+    #                     :url           - The String HTTP request URL (optional).
+    #                     :cause         - The Exception cause for this error (optional).
+    #
+    # Examples
     #
     #   # With an exception:
     #   begin
@@ -88,9 +97,8 @@ module Honeybadger
     #   end
     #
     #   # Custom notification:
-    #   Honeybadger.notify({
+    #   Honeybadger.notify('Something went wrong.', {
     #     error_class: 'MyClass',
-    #     error_message: 'Something went wrong.',
     #     context: {my_data: 'value'}
     #   }) # => '06220c5a-b471-41e5-baeb-de247da45a56'
     #
@@ -137,10 +145,18 @@ module Honeybadger
 
     # Public: Save global context for the current request.
     #
-    # hash - A Hash of data which will be sent to Honeybadger when an error
-    #        occurs. (default: nil)
+    # context - A Hash of data which will be sent to Honeybadger when an error
+    #           occurs. If the object responds to #to_honeybadger_context, the return
+    #           value of that method will be used (explicit conversion). Can
+    #           include any key/value, but a few keys have a special meaning in
+    #           Honeybadger (default: nil):
+    #           :user_id    - The String user ID used by Honeybadger to aggregate
+    #                         user data across occurrences on the error page (optional).
+    #           :user_email - The String user email address (optional).
+    #           :tags       - The String comma-separated list of tags. When present,
+    #                         tags will be applied to errors with this context (optional).
     #
-    # Examples:
+    # Examples
     #
     #   Honeybadger.context({my_data: 'my value'})
     #
@@ -149,12 +165,22 @@ module Honeybadger
     #     Honeybadger.context({user_id: current_user.id})
     #   end
     #
+    #   # Explicit conversion
+    #   class User < ActiveRecord::Base
+    #     def to_honeybadger_context
+    #       { user_id: id, user_email: email }
+    #     end
+    #   end
+    #
+    #   user = User.first
+    #   Honeybadger.context(user)
+    #
     #   # Clearing global context:
     #   Honeybadger.context.clear!
     #
     # Returns self so that method calls can be chained.
-    def context(hash = nil)
-      context_manager.set_context(hash) unless hash.nil?
+    def context(context = nil)
+      context_manager.set_context(context) unless context.nil?
       self
     end
 
@@ -166,7 +192,7 @@ module Honeybadger
     # Public: Get global context for the current request.
     #
     #
-    # Examples:
+    # Examples
     #
     #   Honeybadger.context({my_data: 'my value'})
     #   Honeybadger.get_context #now returns {my_data: 'my value'}
@@ -183,7 +209,7 @@ module Honeybadger
     # block - The optional block to execute (exceptions will propagate after data
     # is flushed).
     #
-    # Examples:
+    # Examples
     #
     #   # Without a block:
     #   it "sends a notification to Honeybadger" do
@@ -215,7 +241,7 @@ module Honeybadger
 
     # Public: Stops the Honeybadger service.
     #
-    # Examples:
+    # Examples
     #
     #   Honeybadger.stop # => nil
     #
@@ -231,7 +257,7 @@ module Honeybadger
     #
     # block - The configuration block.
     #
-    # Examples:
+    # Examples
     #
     #   Honeybadger.configure do |config|
     #     config.api_key = 'project api key'
@@ -249,7 +275,7 @@ module Honeybadger
     # block - A block returning TrueClass true (to ignore) or FalseClass false
     #         (to send).
     #
-    # Examples:
+    # Examples
     #
     #   # Ignoring based on error message:
     #   Honeybadger.exception_filter do |notice|
@@ -272,7 +298,7 @@ module Honeybadger
     #
     # block - A block returning any Object responding to #to_s.
     #
-    # Examples:
+    # Examples
     #
     #   Honeybadger.exception_fingerprint do |notice|
     #     [notice[:error_class], notice[:component], notice[:backtrace].to_s].join(':')
@@ -289,7 +315,7 @@ module Honeybadger
     #         Honeybadger. The block expects one argument (line) which is the String line
     #         from the Backtrace, and must return the String new line.
     #
-    # Examples:
+    # Examples
     #
     #    Honeybadger.backtrace_filter do |line|
     #      line.gsub(/^\/my\/unknown\/bundle\/path/, "[GEM_ROOT]")
@@ -305,7 +331,7 @@ module Honeybadger
     # block    - A block to call. Errors reported from within the block will
     #            include request data.
     #
-    # Examples:
+    # Examples
     #
     #   Honeybadger.with_rack_env(env) do
     #     begin

data/lib/honeybadger/backend/base.rb

@@ -21,7 +21,7 @@ module Honeybadger
       # Public: Initializes the Response instance.
       #
       # response - With 1 argument Net::HTTPResponse, the code, body, and
-      #            message will be determined automatically. (optional)
+      #            message will be determined automatically (optional).
       # code      - The Integer status code. May also be :error for requests which
       #             failed to reach the server.
       # body      - The String body of the response.
@@ -76,10 +76,10 @@ module Honeybadger
       # Internal: Process payload for feature.
       #
       # feature - A Symbol feature name (corresponds to HTTP endpoint). Current
-      #           options are: :notices, :deploys, :ping
-      # payload - Any Object responding to #to_json.
+      #           options are: `:notices`, `:deploys`, `:ping`.
+      # payload - Any Object responding to `#to_json`.
       #
-      # Examples:
+      # Examples
       #
       #   backend.notify(:notices, Notice.new(...))
       #

data/lib/honeybadger/backend/null.rb

@@ -3,12 +3,22 @@ require 'honeybadger/backend/base'
 module Honeybadger
   module Backend
     class Null < Base
+      class StubbedResponse < Response
+        def initialize
+          super(:stubbed, '{}'.freeze)
+        end
+
+        def success?
+          true
+        end
+      end
+
       def initialize(*args)
         super
       end
 
       def notify(feature, payload)
-        Response.new(201, '{}')
+        StubbedResponse.new
       end
     end
   end

data/lib/honeybadger/backend/test.rb

@@ -5,7 +5,7 @@ module Honeybadger
     class Test < Null
       # Public: The notification list.
       #
-      # Examples:
+      # Examples
       #
       #   Test.notifications[:notices] # => [Notice, Notice, ...]
       #

data/lib/honeybadger/backtrace.rb

@@ -92,7 +92,7 @@ module Honeybadger
       #
       # Returns an array of line(s) from source file.
       def get_source(file, number, radius = 2)
-        if file && File.exists?(file)
+        if file && File.exist?(file)
           before = after = radius
           start = (number.to_i - 1) - before
           start = 0 and before = 1 if start <= 0

data/lib/honeybadger/cli/main.rb

@@ -151,7 +151,7 @@ WELCOME
       def load_env
         # Initialize Rails when running from Rails root.
         environment_rb = File.join(Dir.pwd, 'config', 'environment.rb')
-        load_rails_env(environment_rb) if File.exists?(environment_rb)
+        load_rails_env(environment_rb) if File.exist?(environment_rb)
 
         # Ensure config is loaded (will be skipped if initialized by Rails).
         Honeybadger.config.load!

data/lib/honeybadger/cli/test.rb

@@ -94,9 +94,9 @@ module Honeybadger
         # logging the framework trace (moved to ActionDispatch::DebugExceptions),
         # which caused cluttered output while running the test task.
         defined?(::ActionDispatch::DebugExceptions) and
-          ::ActionDispatch::DebugExceptions.class_eval { def logger(*args) ; @logger ||= Logger.new('/dev/null') ; end }
+          ::ActionDispatch::DebugExceptions.class_eval { def logger(*args) ; @logger ||= Logger.new(nil) ; end }
         defined?(::ActionDispatch::ShowExceptions) and
-          ::ActionDispatch::ShowExceptions.class_eval { def logger(*args) ; @logger ||= Logger.new('/dev/null') ; end }
+          ::ActionDispatch::ShowExceptions.class_eval { def logger(*args) ; @logger ||= Logger.new(nil) ; end }
 
         # Detect and disable the better_errors gem
         if defined?(::BetterErrors::Middleware)
@@ -162,7 +162,7 @@ module Honeybadger
         if calling = TestBackend.callings[:notices].find {|c| c[0].exception.eql?(TEST_EXCEPTION) }
           notice, response = *calling
 
-          if response.code != 201
+          if !response.success?
             host = Honeybadger.config.get(:'connection.host')
             say(<<-MSG, :red)
 !! --- Honeybadger test failed ------------------------------------------------ !!
@@ -212,7 +212,7 @@ MSG
           notices.each {|n| say("\n  - #{n.error_class}: #{n.error_message}", :red) }
         end
 
-        say("\nSee https://git.io/vXCYp for more troubleshooting help.\n\n", :red)
+        say("\nSee https://docs.honeybadger.io/gem-troubleshooting for more troubleshooting help.\n\n", :red)
         say("!! --- End -------------------------------------------------------------------- !!", :red)
 
         exit(1)
@@ -237,16 +237,16 @@ Honeybadger. For now, we've generated a test exception for you:
 Optional steps:
 
   - Show a feedback form on your error page:
-    http://docs.honeybadger.io/gem-feedback
+    https://docs.honeybadger.io/gem-feedback
   - Show a UUID or link to Honeybadger on your error page:
-    http://docs.honeybadger.io/gem-informer
+    https://docs.honeybadger.io/gem-informer
   - Track deployments (if you're using Capistrano, we already did this):
-    http://docs.honeybadger.io/gem-deploys
+    https://docs.honeybadger.io/gem-deploys
 
 If you ever need help:
 
-  - Read the gem troubleshooting guide: https://git.io/vXCYp
-  - Check out our documentation: http://docs.honeybadger.io/
+  - Read the gem troubleshooting guide: https://docs.honeybadger.io/gem-troubleshooting
+  - Check out our documentation: https://docs.honeybadger.io/
   - Email the founders: support@honeybadger.io
 
 Most people don't realize that Honeybadger is a small, bootstrapped company. We

data/lib/honeybadger/config.rb

@@ -56,7 +56,7 @@ module Honeybadger
       init_backend!
 
       logger.info(sprintf('Initializing Honeybadger Error Tracker for Ruby. Ship it! version=%s framework=%s', Honeybadger::VERSION, detected_framework))
-      logger.warn('Entering development mode: data will not be reported.') if dev? && backend.kind_of?(Backend::Null)
+      logger.warn('Development mode is enabled. Data will not be reported until you deploy your app.') if warn_development?
 
       self
     end
@@ -148,6 +148,10 @@ module Honeybadger
       self[:env] && Array(self[:development_environments]).include?(self[:env])
     end
 
+    def warn_development?
+      dev? && backend.kind_of?(Backend::Null)
+    end
+
     def public?
       return true if self[:report_data]
       return false if self[:report_data] == false
@@ -359,7 +363,7 @@ module Honeybadger
 
       return framework[:logger] if framework[:logger]
 
-      Logger.new('/dev/null')
+      Logger.new(nil)
     end
 
     def init_logging!