agent.rb in honeybadger-3.2.0.beta1

- old
+ new

@@ -17,11 +17,11 @@
   # `Honeybadger::Agent.new` will share context (added via
   # `Honeybadger.context` or `Honeybadger::Agent#context`) with other agents.
   # This also includes the Rack environment when using the Honeybadger rack
   # middleware.
   #
-  # Examples:
+  # Examples
   #
   #   # Standard usage:
   #   OtherBadger = Honeybadger::Agent.new
   #
   #   # With local context:
@@ -68,17 +68,26 @@
     #
     # exception_or_opts - An Exception object, or a Hash of options which is used
     #                     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)
+    #                     :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:
+    # Examples
     #
     #   # With an exception:
     #   begin
     #     fail 'oops'
     #   rescue => exception
@@ -86,13 +95,12 @@
     #       my_data: 'value'
     #     }) # => '-1dfb92ae-9b01-42e9-9c13-31205b70744a'
     #   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'
     #
     # Returns a String UUID reference to the notice within Honeybadger or false
     # when ignored.
@@ -135,28 +143,46 @@
       notice.id
     end
 
     # 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'})
     #
     #   # Inside a Rails controller:
     #   before_action do
     #     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
 
     # Internal: Used to clear context via `#context.clear!`.
     def clear!
@@ -164,11 +190,11 @@
     end
 
     # 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'}
     #
     # Returns hash or nil.
@@ -181,11 +207,11 @@
     # nature of this library could create race conditions.
     #
     # 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
     #     expect {
     #       Honeybadger.notify(StandardError.new('test backend'))
@@ -213,11 +239,11 @@
       worker.flush
     end
 
     # Public: Stops the Honeybadger service.
     #
-    # Examples:
+    # Examples
     #
     #   Honeybadger.stop # => nil
     #
     # Returns nothing
     def stop(force = false)
@@ -229,11 +255,11 @@
 
     # Public: Configure the Honeybadger agent via Ruby.
     #
     # block - The configuration block.
     #
-    # Examples:
+    # Examples
     #
     #   Honeybadger.configure do |config|
     #     config.api_key = 'project api key'
     #     config.exceptions.ignore += [CustomError]
     #   end
@@ -247,11 +273,11 @@
     # See public API documentation for Honeybadger::Notice for available attributes.
     #
     # 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|
     #     notice[:error_message] =~ /sensitive data/
     #   end
@@ -270,11 +296,11 @@
     #
     # See public API documentation for Honeybadger::Notice for available attributes.
     #
     # 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(':')
     #   end
     #
@@ -287,11 +313,11 @@
     #
     # block - A block which can be used to modify the Backtrace lines sent to
     #         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]")
     #    end
     #
@@ -303,10 +329,10 @@
     #
     # rack_env - The Hash Rack environment.
     # block    - A block to call. Errors reported from within the block will
     #            include request data.
     #
-    # Examples:
+    # Examples
     #
     #   Honeybadger.with_rack_env(env) do
     #     begin
     #       # Risky operation
     #     rescue => e