Merge pull request #113 from MindscapeHQ/breadcrumbs-support

Breadcrumbs support

Author: UberMouse

CHANGELOG.md

@@ -1,9 +1,15 @@
+## 2.1.0
+
+Features
+  - Ability to record breadcrumbs in your code that will be sent to Raygun along with a raised exception ([#113](https://github.com/MindscapeHQ/raygun4ruby/pull/113))
+
 ## 2.0.0 (20/04/2017)
 
 Bugfixes:
   - Fix broken handling of raw request body reading in Rack applications ([#116](https://github.com/MindscapeHQ/raygun4ruby/pull/116))
     - This is a breaking change to how raw data was being read before so it requires a major version bump
     - Raw request data reading is now disabled by default and can be enabled via the `record_raw_data` configuration option
+
 ## 1.5.0 (16/03/2017)
 
 Features

README.md

@@ -98,6 +98,49 @@ Raygun.setup do |config|
 end
 ```
 
+### Recording Breadcrumbs
+
+Breadcrumbs let you provide logging points in your code that will be collected and sent along with any exception sent to Raygun. This lets you have a better understanding of the events that happened in the system that lead up to the exception.
+
+1. Include it as a module in your class
+```ruby
+class SomeClass
+  include Raygun::Breadcrumbs
+
+  def some_method
+    record_breadcrumb(
+      message: "<log message goes here>",
+      category: "some category to group them by, maybe authentication or external-apis for example",
+      level: :info, # or debug or warning etc, you can configure what level will get sent
+      metadata: {custom_data: 'can go here'},
+    )
+  end
+end
+```
+This has the added benefit of recording the class the breadcrumb was recorded from automatically
+
+2. Call the `record_breadcrumb` method manually
+```ruby
+def some_method
+  Raygun.record_breadcrumb(
+    message: "<log message goes here>",
+    category: "some category to group them by, maybe authentication or external-apis for example",
+    level: :info, # or debug or warning etc, you can configure what level will get sent
+    metadata: {custom_data: 'can go here'},
+
+    # You can also set the class the breadcrumb was logged from
+    # It will only be set automatically using the included module approach
+    # Method and line number will get added automatically
+    class_name: self.class.name
+  )
+end
+```
+
+If you are using Sinatra or another rack framework you will need to include the Breadcrumbs middleware, this is used for storing the breadcrumbs during a request
+`use Raygun::Middleware::BreadcrumbsStoreInitializer`
+
+If you are using a non web based Ruby application you will have to call `Raygun::Breadcrumbs::Store.initialize` during your applications boot process. The store is per thread, but I have not tested it in a multi threaded application.
+
 ### Filtering the payload by whitelist
 
 As an alternative to the above, you can also opt-in to the keys/values to be sent to Raygun by providing a specific whitelist of the keys you want to transmit.

Rakefile

@@ -7,7 +7,7 @@ namespace :test do
 
   desc "Test the basics of the adapter"
   Rake::TestTask.new(:units) do |t|
-    t.test_files = FileList["test/unit/*_test.rb"]
+    t.test_files = FileList["test/unit/*_test.rb", "specs/**/*_spec.rb"]
     t.verbose = true
   end
 

lib/raygun.rb

@@ -14,10 +14,14 @@
 require "raygun/configuration"
 require "raygun/client"
 require "raygun/middleware/rack_exception_interceptor"
+require "raygun/middleware/breadcrumbs_store_initializer"
 require "raygun/testable"
 require "raygun/error"
 require "raygun/affected_user"
 require "raygun/services/apply_whitelist_filter_to_payload"
+require "raygun/breadcrumbs/breadcrumb"
+require "raygun/breadcrumbs/store"
+require "raygun/breadcrumbs"
 require "raygun/railtie" if defined?(Rails)
 
 module Raygun
@@ -78,6 +82,28 @@ def track_exceptions
       track_exception(e)
     end
 
+    def record_breadcrumb(
+        message: nil,
+        category: '',
+        level: :info,
+        timestamp: Time.now.utc,
+        metadata: {},
+        class_name: nil,
+        method_name: nil,
+        line_number: nil
+    )
+      Raygun::Breadcrumbs::Store.record(
+        message: message,
+        category: category,
+        level: level,
+        timestamp: timestamp,
+        metadata: metadata,
+        class_name: class_name,
+        method_name: method_name,
+        line_number: line_number,
+      )
+    end
+
     def log(message)
       configuration.logger.info(message) if configuration.logger
     end

lib/raygun/breadcrumbs.rb

@@ -0,0 +1,34 @@
+module Raygun
+  module Breadcrumbs
+    BREADCRUMB_LEVELS = [
+      :debug,
+      :info,
+      :warning,
+      :error,
+      :fatal
+    ]
+
+    def record_breadcrumb(
+        message: nil,
+        category: '',
+        level: :info,
+        timestamp: Time.now.utc.to_i,
+        metadata: {},
+        class_name: nil,
+        method_name: nil,
+        line_number: nil
+    )
+      class_name = class_name || self.class.name
+      Raygun::Breadcrumbs::Store.record(
+        message: message,
+        category: category,
+        level: level,
+        timestamp: timestamp,
+        metadata: metadata,
+        class_name: class_name,
+        method_name: method_name,
+        line_number: line_number,
+      )
+    end
+  end
+end

lib/raygun/breadcrumbs/breadcrumb.rb

@@ -0,0 +1,30 @@
+module Raygun
+  module Breadcrumbs
+    class Breadcrumb
+      ATTRIBUTES = [
+        :message, :category, :metadata, :class_name,
+        :method_name, :line_number, :timestamp, :level,
+        :type
+      ]
+      attr_accessor(*ATTRIBUTES)
+
+      def build_payload
+        payload = {
+          message: message,
+          category: category,
+          level: Breadcrumbs::BREADCRUMB_LEVELS.index(level),
+          CustomData: metadata,
+          timestamp: timestamp,
+          type: type
+        }
+
+        payload[:location] = "#{class_name}:#{method_name}" unless class_name == nil
+        payload[:location] += ":#{line_number}" if payload.has_key?(:location) && line_number != nil
+
+        Hash[payload.select do |k, v|
+          v != nil
+        end]
+      end
+    end
+  end
+end

lib/raygun/breadcrumbs/store.rb

@@ -0,0 +1,68 @@
+require_relative 'breadcrumb'
+
+module Raygun
+  module Breadcrumbs
+    class Store
+      def self.initialize
+        Thread.current[:breadcrumbs] ||= []
+      end
+
+      def self.clear
+        Thread.current[:breadcrumbs] = nil
+      end
+
+      def self.stored
+        Thread.current[:breadcrumbs]
+      end
+
+      def self.record(
+        message: nil,
+        category: '',
+        level: :info,
+        timestamp: Time.now.utc.to_i,
+        metadata: {},
+        class_name: nil,
+        method_name: nil,
+        line_number: nil
+      )
+        raise ArgumentError.new('missing keyword: message') if message == nil
+        crumb = Breadcrumb.new
+
+        crumb.message = message
+        crumb.category = category
+        crumb.level = level
+        crumb.metadata = metadata
+        crumb.timestamp = timestamp
+        crumb.type = 'manual'
+
+        caller = caller_locations[1]
+        crumb.class_name = class_name
+        crumb.method_name = method_name || caller.label
+        crumb.line_number = line_number || caller.lineno
+
+        Thread.current[:breadcrumbs] << crumb if should_record?(crumb)
+      end
+
+      def self.any?
+        stored != nil && stored.length > 0
+      end
+
+      private
+
+      def self.should_record?(crumb)
+        levels = Raygun::Breadcrumbs::BREADCRUMB_LEVELS
+
+        active_level = levels.index(Raygun.configuration.breadcrumb_level)
+        crumb_level = levels.index(crumb.level) || -1
+
+        discard = crumb_level < active_level
+
+        if discard && Raygun.configuration.debug
+          Raygun.log("[Raygun.breadcrumbs] discarding breadcrumb because #{crumb.level} is below active breadcrumb level (#{Raygun.configuration.breadcrumb_level})")
+        end
+
+        !discard
+      end
+    end
+  end
+end

lib/raygun/client.rb

@@ -193,6 +193,8 @@ def build_payload_hash(exception_instance, env = {}, user = nil)
               utcOffset: Time.now.utc_offset / 3600
             }
         }
+        store = ::Raygun::Breadcrumbs::Store
+        error_details[:breadcrumbs] = store.stored.map(&:build_payload) if store.any?
 
         error_details.merge!(groupingKey: grouping_key) if grouping_key
 

lib/raygun/configuration.rb

@@ -112,19 +112,20 @@ def initialize
 
       # set default attribute values
       @defaults = OpenStruct.new({
-        ignore:                           IGNORE_DEFAULT,
-        custom_data:                      {},
-        tags:                             [],
-        enable_reporting:                 true,
-        affected_user_method:             :current_user,
-        affected_user_mapping:            AffectedUser::DEFAULT_MAPPING,
-        filter_parameters:                DEFAULT_FILTER_PARAMETERS,
-        filter_payload_with_whitelist:    false,
-        whitelist_payload_shape:          DEFAULT_WHITELIST_PAYLOAD_SHAPE,
-        proxy_settings:                   {},
-        debug:                            false,
-        api_url:                          'https://api.raygun.io/',
-        record_raw_data:                  false
+        ignore:                        IGNORE_DEFAULT,
+        custom_data:                   {},
+        tags:                          [],
+        enable_reporting:              true,
+        affected_user_method:          :current_user,
+        affected_user_mapping:         AffectedUser::DEFAULT_MAPPING,
+        filter_parameters:             DEFAULT_FILTER_PARAMETERS,
+        filter_payload_with_whitelist: false,
+        whitelist_payload_shape:       DEFAULT_WHITELIST_PAYLOAD_SHAPE,
+        proxy_settings:                {},
+        debug:                         false,
+        api_url:                       'https://api.raygun.io/',
+        breadcrumb_level:              :info,
+        record_raw_data:               false
       })
     end
 
@@ -144,6 +145,18 @@ def silence_reporting=(value)
       self.enable_reporting = !value
     end
 
+    def breadcrumb_level
+      read_value(:breadcrumb_level)
+    end
+
+    def breadcrumb_level=(value)
+      if Raygun::Breadcrumbs::BREADCRUMB_LEVELS.include?(value)
+        set_value(:breadcrumb_level, value)
+      elsif read_value(:debug)
+        Raygun.log("[Raygun.configuration] unknown breadcrumb level: #{value} not setting")
+      end
+    end
+
     def affected_user_identifier_methods
       Raygun.deprecation_warning("Please note: You should now user config.affected_user_method_mapping.Identifier instead of config.affected_user_identifier_methods")
       read_value(:affected_user_method_mapping).Identifier

lib/raygun/middleware/breadcrumbs_store_initializer.rb

@@ -0,0 +1,19 @@
+module Raygun
+  module Middleware
+    class BreadcrumbsStoreInitializer
+      def initialize(app)
+        @app = app
+      end
+
+      def call(env)
+        Breadcrumbs::Store.initialize
+
+        begin
+          @app.call(env)
+        ensure
+          Breadcrumbs::Store.clear
+        end
+      end
+    end
+  end
+end