From a2e9b8202a0444b5fc52e443927e2d7978a05030 Mon Sep 17 00:00:00 2001 From: Nik Wakelin Date: Fri, 3 May 2024 09:07:25 +1200 Subject: [PATCH] Tweaks README and updates changelog to reflect recent updates to the gem --- CHANGELOG.md | 126 +++++++++++++++++++++++++++--------------- README.md | 72 ++++++++++++------------ lib/raygun/version.rb | 2 +- 3 files changed, 120 insertions(+), 80 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 1d12db5..db329a6 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,133 +1,169 @@ +## 4.0.0.pre (prerelease): + +- BREAKING CHANGE: Remove support for end-of-life Ruby verisons and Rails versions prior to 6.0.0 +- Bug fix: Fix issue with breadcrumbs not being sent to Raygun when `send_in_background` is enabled (thanks to @jjb for the bug report) +- Updates testing to reflect the above +- Use `Kernel.caller` when backtrace is not available (thanks to @TSMMark) + ## 3.2.6 (17/03/2021): - - Bug fix: Rename Testable class to DemoException to ensure it is added to the bundle ([#166](https://github.com/MindscapeHQ/raygun4ruby/pull/166)) + +- Bug fix: Rename Testable class to DemoException to ensure it is added to the bundle ([#166](https://github.com/MindscapeHQ/raygun4ruby/pull/166)) ## 3.2.5 (15/03/2021): - - Bug fix: Ensure tags passed into track_exception are not persisted ([#164](https://github.com/MindscapeHQ/raygun4ruby/pull/164)) + +- Bug fix: Ensure tags passed into track_exception are not persisted ([#164](https://github.com/MindscapeHQ/raygun4ruby/pull/164)) ## 3.2.4 (11/02/2021): - - Set sidekiq tag on sidekiq errors ([#161](https://github.com/MindscapeHQ/raygun4ruby/pull/161)) + +- Set sidekiq tag on sidekiq errors ([#161](https://github.com/MindscapeHQ/raygun4ruby/pull/161)) ## 3.2.2 (10/06/2020): - - Introduce support for Raygun APM exceptions correlation ([#154](https://github.com/MindscapeHQ/raygun4ruby/pull/154)) + +- Introduce support for Raygun APM exceptions correlation ([#154](https://github.com/MindscapeHQ/raygun4ruby/pull/154)) ## 3.2.1 (25/02/2019): + Bugfix: - - Remove Ruby 2.3 syntax to retain support for Ruby >= 2.0 ([#148](https://github.com/MindscapeHQ/raygun4ruby/pull/148)) + +- Remove Ruby 2.3 syntax to retain support for Ruby >= 2.0 ([#148](https://github.com/MindscapeHQ/raygun4ruby/pull/148)) ## 3.2.0 (21/02/2019): + Bugfix: - - Fix NoMethodError Exception: undefined method `include?' for nil:NilClass in `JavascriptExceptionTracking` class. Thanks @yamanaltereh for this ([#141](https://github.com/MindscapeHQ/raygun4ruby/pull/141)) - - Fix ([#145](https://github.com/MindscapeHQ/raygun4ruby/issues/145)), "raygun4ruby will load pry if it is in the gem bundle". Thanks to @eoinkelly for reporting this + +- Fix NoMethodError Exception: undefined method `include?' for nil:NilClass in `JavascriptExceptionTracking` class. Thanks @yamanaltereh for this ([#141](https://github.com/MindscapeHQ/raygun4ruby/pull/141)) +- Fix ([#145](https://github.com/MindscapeHQ/raygun4ruby/issues/145)), "raygun4ruby will load pry if it is in the gem bundle". Thanks to @eoinkelly for reporting this Feature: - - If you have recorded a large number of Breadcrumbs, or just very large ones, Raygun4Ruby will now only send up to 100KB of them instead of all of them, potentially going over the 128KB payload limit Raygun accepts ([#147](https://github.com/MindscapeHQ/raygun4ruby/pull/147)) + +- If you have recorded a large number of Breadcrumbs, or just very large ones, Raygun4Ruby will now only send up to 100KB of them instead of all of them, potentially going over the 128KB payload limit Raygun accepts ([#147](https://github.com/MindscapeHQ/raygun4ruby/pull/147)) ## 3.1.1 (16/01/2019): + Bugfix: - - Don't attempt to modify response unless JS api key is present - - Don't attempt to modify response unless it responds to indexing ([]) - - See PR ([#140](https://github.com/MindscapeHQ/raygun4ruby/pull/140)) + +- Don't attempt to modify response unless JS api key is present +- Don't attempt to modify response unless it responds to indexing ([]) +- See PR ([#140](https://github.com/MindscapeHQ/raygun4ruby/pull/140)) ## 3.1.0 (15/01/2019): -Feature: - - Ability to automatically configure Raygun4JS on the client side by injecting it into outbound HTML pages. Thanks @MikeRogers0 for this ([#138](https://github.com/MindscapeHQ/raygun4ruby/pull/138)) +Feature: - Ability to automatically configure Raygun4JS on the client side by injecting it into outbound HTML pages. Thanks @MikeRogers0 for this ([#138](https://github.com/MindscapeHQ/raygun4ruby/pull/138)) ## 3.0.0 (18/12/2018): - Breaking changes: - Parameter filters are now applied if you are using the `filter_payload_with_whitelist` functionality. Previously if this was set to true the parameter filtering was bailed out of ([#136](https://github.com/MindscapeHQ/raygun4ruby/pull/136/files)) + +Breaking changes: +Parameter filters are now applied if you are using the `filter_payload_with_whitelist` functionality. Previously if this was set to true the parameter filtering was bailed out of ([#136](https://github.com/MindscapeHQ/raygun4ruby/pull/136/files)) ## 2.7.1 (11/06/2018) - This is a patch release to update the required ruby version to correctly be 2.0 or greater + +This is a patch release to update the required ruby version to correctly be 2.0 or greater ## 2.7.0 (19/02/2018) Features - - Add configuration option to control network timeouts when sending error reports, default value is 10 seconds ([#129](https://github.com/MindscapeHQ/raygun4ruby/pull/129)) + +- Add configuration option to control network timeouts when sending error reports, default value is 10 seconds ([#129](https://github.com/MindscapeHQ/raygun4ruby/pull/129)) ## 2.6.0 (25/10/2017) Features - - Enhanced debug logging to assist in resolving issues from support requests ([#128](https://github.com/MindscapeHQ/raygun4ruby/pull/128)) + +- Enhanced debug logging to assist in resolving issues from support requests ([#128](https://github.com/MindscapeHQ/raygun4ruby/pull/128)) ## 2.5.0 (04/10/2017) Features - - Teach tags configuration how to handle a proc to allow dynamically settings tags ([#127](https://github.com/MindscapeHQ/raygun4ruby/pull/127)) + +- Teach tags configuration how to handle a proc to allow dynamically settings tags ([#127](https://github.com/MindscapeHQ/raygun4ruby/pull/127)) Bugfixes - - Fix crash when recording breadcrumb with uninitialized store ([#126](https://github.com/MindscapeHQ/raygun4ruby/pull/126)) - - Make raw data handling more robust and fix in unicorn ([#125](https://github.com/MindscapeHQ/raygun4ruby/pull/125)) - - Backwards compatible affected_user_identifier_methods ([#120](https://github.com/MindscapeHQ/raygun4ruby/pull/120)) + +- Fix crash when recording breadcrumb with uninitialized store ([#126](https://github.com/MindscapeHQ/raygun4ruby/pull/126)) +- Make raw data handling more robust and fix in unicorn ([#125](https://github.com/MindscapeHQ/raygun4ruby/pull/125)) +- Backwards compatible affected_user_identifier_methods ([#120](https://github.com/MindscapeHQ/raygun4ruby/pull/120)) ## 2.4.1 (29/08/2017) Bugfixes - - Fix crash in `Client#raw_data` method when `rack.input` buffer is missing `pos` method + +- Fix crash in `Client#raw_data` method when `rack.input` buffer is missing `pos` method ## 2.4.0 (31/07/2017) Features - - Add functionality to track affected user/customer in Sidekiq jobs, refer to the README for more information, under the "Affected User Tracking/Customers in Sidekiq" heading ([#121](https://github.com/MindscapeHQ/raygun4ruby/pull/121)) + +- Add functionality to track affected user/customer in Sidekiq jobs, refer to the README for more information, under the "Affected User Tracking/Customers in Sidekiq" heading ([#121](https://github.com/MindscapeHQ/raygun4ruby/pull/121)) ## 2.3.0 (09/05/2017)" Bugfixes - - Fix issue preventing affected users/customers for a crash report from showing up in the affected users/customers page ([#119](https://github.com/MindscapeHQ/raygun4ruby/pull/119)) + +- Fix issue preventing affected users/customers for a crash report from showing up in the affected users/customers page ([#119](https://github.com/MindscapeHQ/raygun4ruby/pull/119)) ## 2.2.0 (05/05/2017) Features - - Opt in support for sending exceptions in a background thread to not block web request thread during IO ([#117](https://github.com/MindscapeHQ/raygun4ruby/pull/117)) + +- Opt in support for sending exceptions in a background thread to not block web request thread during IO ([#117](https://github.com/MindscapeHQ/raygun4ruby/pull/117)) Bugfixes - - Don't attempt to read raw data during GET requests or if rack.input buffer is empty + +- Don't attempt to read raw data during GET requests or if rack.input buffer is empty ## 2.1.0 (27/04/2017) 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)) + +- 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 - + +- 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 + Since this is a major version bump this release also deprecates ruby versions < 2.0 ## 1.5.0 (16/03/2017) Features - - Send utcOffset with Raygun payload to calculate local server time in Raygun dashboard ([#112](https://github.com/MindscapeHQ/raygun4ruby/pull/112)) + +- Send utcOffset with Raygun payload to calculate local server time in Raygun dashboard ([#112](https://github.com/MindscapeHQ/raygun4ruby/pull/112)) ## 1.4.0 (14/03/2017) Features: - - Raygun API url is now configurable via `Configuration.api_url` ([#111](https://github.com/MindscapeHQ/raygun4ruby/pull/111)) - - Added support for `Exception#cause` to be tracked as `innerError` on Raygun. Only supported on Ruby >= 2.1 ([#107](https://github.com/MindscapeHQ/raygun4ruby/pull/107)) + +- Raygun API url is now configurable via `Configuration.api_url` ([#111](https://github.com/MindscapeHQ/raygun4ruby/pull/111)) +- Added support for `Exception#cause` to be tracked as `innerError` on Raygun. Only supported on Ruby >= 2.1 ([#107](https://github.com/MindscapeHQ/raygun4ruby/pull/107)) ## 1.3.0 (10/03/2017) Features: - - Improve affected user handling to let you specify all Raygun parameters, identifier, email, first name, full name and uuid. See [README.md](https://github.com/MindscapeHQ/raygun4ruby#affected-user-tracking) for details ([#34](https://github.com/MindscapeHQ/raygun4ruby/pull/34)) - - Pass a user object as the third parameter to `Raygun.track_exception` to have affected user tracking/customers for manually tracked exceptions, see the above link for more information on configuring this ([#106](https://github.com/MindscapeHQ/raygun4ruby/pull/106)) - - If the exception instance responds to `:raygun_custom_data` that method will be called and the return value merged into the `custom_data` hash sent to Raygun. For convenience a `Raygun::Error` class is provided that takes this custom data as a second argument ([#101](https://github.com/MindscapeHQ/raygun4ruby/pull/101)) - - Allowed `Configuration.custom_data` to be set to a proc to allow a global custom data hook for all exceptions. It is passed as arguments the exception and the environment hash ([#108](https://github.com/MindscapeHQ/raygun4ruby/pull/108)) - - Added `Configuration.debug` to enable logging the reason why an exception was not reported ([#109](https://github.com/MindscapeHQ/raygun4ruby/pull/109)) + +- Improve affected user handling to let you specify all Raygun parameters, identifier, email, first name, full name and uuid. See [README.md](https://github.com/MindscapeHQ/raygun4ruby#affected-user-tracking) for details ([#34](https://github.com/MindscapeHQ/raygun4ruby/pull/34)) +- Pass a user object as the third parameter to `Raygun.track_exception` to have affected user tracking/customers for manually tracked exceptions, see the above link for more information on configuring this ([#106](https://github.com/MindscapeHQ/raygun4ruby/pull/106)) +- If the exception instance responds to `:raygun_custom_data` that method will be called and the return value merged into the `custom_data` hash sent to Raygun. For convenience a `Raygun::Error` class is provided that takes this custom data as a second argument ([#101](https://github.com/MindscapeHQ/raygun4ruby/pull/101)) +- Allowed `Configuration.custom_data` to be set to a proc to allow a global custom data hook for all exceptions. It is passed as arguments the exception and the environment hash ([#108](https://github.com/MindscapeHQ/raygun4ruby/pull/108)) +- Added `Configuration.debug` to enable logging the reason why an exception was not reported ([#109](https://github.com/MindscapeHQ/raygun4ruby/pull/109)) ## 1.2.1 (09/03/2017) Bugfixes: - - dup input hashes before applying whitelist filtering, previously this was modifying the contents of `action_dispatch.request.parameters` ([#105](https://github.com/MindscapeHQ/raygun4ruby/pull/105)) + +- dup input hashes before applying whitelist filtering, previously this was modifying the contents of `action_dispatch.request.parameters` ([#105](https://github.com/MindscapeHQ/raygun4ruby/pull/105)) ## 1.2.0 (09/03/2017) Features: - - Added two new configuration options, `filter_payload_with_whitelist` and `whitelist_payload_shape` ([#100](https://github.com/MindscapeHQ/raygun4ruby/pull/100)) - - See [README.md](https://github.com/MindscapeHQ/raygun4ruby#filtering-the-payload-by-whitelist) for an example of how to use them - - When raygun4ruby encounters an exception trying to track an exception it will try once to send that exception to Raygun so you are notified ([#104](https://github.com/MindscapeHQ/raygun4ruby/pull/104)) + +- Added two new configuration options, `filter_payload_with_whitelist` and `whitelist_payload_shape` ([#100](https://github.com/MindscapeHQ/raygun4ruby/pull/100)) + - See [README.md](https://github.com/MindscapeHQ/raygun4ruby#filtering-the-payload-by-whitelist) for an example of how to use them +- When raygun4ruby encounters an exception trying to track an exception it will try once to send that exception to Raygun so you are notified ([#104](https://github.com/MindscapeHQ/raygun4ruby/pull/104)) Bugfixes: - - raygun4ruby will no longer crash and suppress app exceptions when the API key is not configured ([#87](https://github.com/MindscapeHQ/raygun4ruby/pull/87)) + +- raygun4ruby will no longer crash and suppress app exceptions when the API key is not configured ([#87](https://github.com/MindscapeHQ/raygun4ruby/pull/87)) diff --git a/README.md b/README.md index fce14ac..e65802e 100644 --- a/README.md +++ b/README.md @@ -2,46 +2,43 @@ This is the Ruby adapter for the Raygun error reporter, https://raygun.com. - ## Installation -Add this line to your application's Gemfile: +Add to your application's Gemfile: - gem 'raygun4ruby' + $ bundle add raygun4ruby And then execute: $ bundle install -Or install it yourself as: +Or, if you're not using Bundler, install the gem directly: $ gem install raygun4ruby ## Usage -### Rails 3+ +### Rails 6+ Run: rails g raygun:install YOUR_API_KEY_HERE -You can find your API key in the [Raygun app](https://app.raygun.com/) +You can find your API key in the [Raygun app](https://app.raygun.com/) under "Application Settings". You can then test your Raygun integration by running: - rake raygun:test - -You should see an "ItWorksException" appear in your Raygun dashboard. You're ready to zap those errors! + rails raygun:test -NB: Raygun4Ruby currently requires Ruby >= 2.0 +You should see an "ItWorksException" appear in your Raygun dashboard. You're ready to zap those errors! :zap: -Note that the generator will create a file in `config/initializers` called "raygun.rb". If you need to do any further configuration or customization of Raygun, that's the place to do it! +The generator will create a file in `config/initializers` called "raygun.rb". If you need to do any further configuration or customization of Raygun, that's the place to do it! -By default the Rails integration is set to only report Exceptions in Production. To change this behaviour, set `config.enable_reporting` to something else in `config/initializers/raygun.rb`. +By default the Rails integration is set to only report Exceptions in the `production` environment. To change this behaviour, set `config.enable_reporting` to something else in `config/initializers/raygun.rb`. -### Rails 2 +#### Version Support -Raygun4Ruby doesn't currently support Rails 2. If you'd like Rails 2 support, [drop us a line](https://raygun.com/forums). +Raygun4Ruby currently supports Rails 6 or later running on Ruby >= 3.0. If you're using an older version of Ruby or Rails please use an [older version of Raygun4Ruby](https://github.com/MindscapeHQ/raygun4ruby/releases) ### Sinatra @@ -85,7 +82,7 @@ end You can also pass a Hash as the second parameter to `track_exception`. It should look like a [Rack Env Hash](https://github.com/rack/rack/blob/master/SPEC.rdoc#label-The+Environment) -### Customizing The Parameter Filtering +### Customizing Parameter Filtering If you'd like to customize how parameters are filtered, you can pass a `Proc` to `filter_parameters`. Raygun4Ruby will yield the params hash to the block, and the return value will be sent along with your error. @@ -103,6 +100,7 @@ end 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 @@ -117,9 +115,11 @@ class SomeClass 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( @@ -142,7 +142,7 @@ If you are using Sinatra or another rack framework you will need to include the 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 +### Filtering the enire payload using a 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. @@ -190,6 +190,7 @@ end ``` ### Custom User Data + Custom data can be added to `track_exception` by passing a custom_data key in the second parameter hash. ```ruby @@ -231,7 +232,7 @@ Raygun.setup do |config| end ``` -The following exceptions are ignored by default: +The following exceptions are ignored by default: ``` ActiveRecord::RecordNotFound @@ -244,7 +245,7 @@ AbstractController::ActionNotFound Mongoid::Errors::DocumentNotFound ``` - [You can see this here](https://github.com/MindscapeHQ/raygun4ruby/blob/master/lib/raygun/configuration.rb#L90) and unignore them if needed by doing the following: +[You can see this here](https://github.com/MindscapeHQ/raygun4ruby/blob/master/lib/raygun/configuration.rb#L90) and unignore them if needed by doing the following: ```ruby Raygun.setup do |config| @@ -266,7 +267,7 @@ end ### Affected Customers -Raygun can now track how many customers have been affected by an error. +Raygun can track how many customers have been affected by an error. By default, Raygun looks for a method called `current_user` on your controller, and it will populate the customer's information based on a default method name mapping. @@ -291,7 +292,7 @@ To see the defaults check out [affected_user.rb](https://github.com/MindscapeHQ/ If you're using Rails, most authentication systems will have this method set and you should be good to go. -The count of unique affected customers will appear on the error group in the Raygun dashboard. If your customer has an `Email` attribute, and that email has a Gravatar associated with that address, you will also see your customer's avatar. +The count of unique affected customers will appear on the error group in the Raygun dashboard. If your customer has an `email` attribute, and that email has a Gravatar associated with that address, you will also see your customer's avatar. If you wish to keep it anonymous, you could set this identifier to something like `SecureRandom.uuid` and store that in a cookie, like so: @@ -307,7 +308,7 @@ end (Remember to set `affected_user_method` to `:raygun_user` in your config block...) -### Version tracking +### Version Tracking Raygun can attach the version of your application to its error reports. In your Raygun.setup block, set `version` to the current version of your app. @@ -329,7 +330,7 @@ rescue Exception => e end ``` -Tags can also be specified globally either by setting `config.custom_data` to an array +Tags can also be specified globally either by setting `config.tags` to an array ```ruby Raygun.setup do |config| @@ -337,7 +338,7 @@ Raygun.setup do |config| end ``` -or to a proc, which gets passed the exception and environment hash. This proc _must_ return an array of strings +or to a Proc, which gets passed the exception and environment hash. This proc _must_ return an array of strings ```ruby Raygun.setup do |config| @@ -348,7 +349,9 @@ Raygun.setup do |config| end ``` -### Resque Error Tracking +### Background Jobs + +#### Resque Raygun4Ruby also includes a Resque failure backend. You should include it inside your Resque initializer (usually something like `config/initializers/load_resque.rb`) @@ -361,17 +364,17 @@ Resque::Failure::Multiple.classes = [Resque::Failure::Redis, Resque::Failure::Ra Resque::Failure.backend = Resque::Failure::Multiple ``` -### Sidekiq Error Tracking +#### Sidekiq -Raygun4Ruby can track errors from Sidekiq (2.x or 3+). All you need to do is add the line: +Raygun4Ruby can track errors from Sidekiq (we test on 6+ but there's no reason it shouldn't work on older versions). All you need to do is add the line: ```ruby require 'raygun/sidekiq' ``` -Either in your Raygun initializer or wherever else takes your fancy :) +Either in your Raygun initializer or wherever else takes your fancy :simple_smile: -#### Affected Customers in Sidekiq +##### Affected Customers in Sidekiq To track affected customers, define a class method on your worker class that returns a user object. Make sure the name of this method is the same as whatever you have defined as the `affected_user_method` in your Raygun configuration and that it returns an object that fits the mappings defined in `affected_user_mapping` @@ -407,14 +410,15 @@ Oops! Just let us know by opening an Issue on Github. ## Contributing -1. Fork it -2. Create your feature branch (`git checkout -b my-new-feature`) -3. Commit your changes (`git commit -am 'Add some feature'`) -4. Push to the branch (`git push origin my-new-feature`) -5. Create new Pull Request +1. Fork the repo, and install dependencies (`bundle install`) +2. Create your feature branch and write your code (`git checkout -b my-new-feature`) +3. Write some tests, and make them pass (`bundle exec rake`) +4. Commit your changes (`git commit -am 'Add some feature'`) +5. Push to the branch (`git push origin my-new-feature`) +6. Create a new Pull Request. Thank you! :sparkles: ## Building 1. Build the gem (`gem build raygun4ruby.gemspec`) - don't bother trying to build it on Windows, -the resulting Gem won't work. + the resulting Gem won't work. 2. Install the gem (`gem install raygun4ruby-VERSION.gem`) diff --git a/lib/raygun/version.rb b/lib/raygun/version.rb index fb22dbe..cbc744c 100644 --- a/lib/raygun/version.rb +++ b/lib/raygun/version.rb @@ -1,3 +1,3 @@ module Raygun - VERSION = "3.2.6" + VERSION = "4.0.0.pre" end