README.md in sentry-raven-0.11.2 vs README.md in sentry-raven-0.12.0

- old
+ new

@@ -8,349 +8,47 @@ ## Requirements We test on Ruby MRI 1.8.7/REE, 1.9.3, 2.0 and 2.1. JRuby support is experimental - check TravisCI to see if the build is passing or failing. -## Installation - +## Getting Started +### Install ```ruby gem "sentry-raven", :require => 'raven' #, :github => "getsentry/raven-ruby" ``` - -## Usage - -Set the ``SENTRY_DSN`` environment variable with the value found on your Sentry project settings page. It should resemble something like ```https://public:secret@app.getsentry.com/9999```. - -Many implementations will automatically capture uncaught exceptions (such as Rails, Sidekiq or by using -the Rack middleware). If you catch those exceptions yourself, but still want to report on them, see section [Capturing Events](#capturing-events). - -### Rails - -In Rails, all uncaught exceptions will be automatically reported. - -You'll still want to ensure you've disabled anything that would prevent errors from being propagated to the ```Raven::Rack``` middleware, like ```ActionDispatch::ShowExceptions```: - +### Set SENTRY_DSN +```bash +# Set your SENTRY_DSN environment variable. +export SENTRY_DSN=http://public:secret@example.com/project-id +``` ```ruby -config.action_dispatch.show_exceptions = false # this is the default setting in production +# Or you can configure the client in the code (not recommended - keep your DSN secret!) +Raven.configure do |config| + config.dsn = 'http://public:secret@example.com/project-id' +end ``` +### Call +If you use Rails, you're already done - no more configuration required! Check [Integrations](https://github.com/getsentry/raven-ruby/wiki/Integrations) for more details on other gems Sentry integrates with automatically. -### Rack - -Add ```use Raven::Rack``` to your ```config.ru``` or other rackup file (this is automatically inserted in Rails). - -### Sinatra - -Like any other Rack middleware, add ```use Raven::Rack``` to your Sinatra app. - -### Sidekiq, Delayed::Job and Rake - -Raven works out-of-the-box with all these tools! - -## Capturing Events - -Many implementations will automatically capture uncaught exceptions (such as Rails, Sidekiq or by using -the Rack middleware). Sometimes you may want to catch those exceptions, but still report on them. - -Several helpers are available to assist with this. - -### Capture Exceptions in a Block - +Otherwise, Raven supports two methods of capturing exceptions: ```ruby Raven.capture do # capture any exceptions which happen during execution of this block 1 / 0 end -``` -### Capture an Exception by Value - -```ruby begin 1 / 0 rescue ZeroDivisionError => exception Raven.capture_exception(exception) end ``` -### Additional Context +## More Information -Additional context can be passed to the capture methods. +Full documentation and more information on advanced configuration, sending more information, scrubbing sensitive data, and more can be found on [the wiki](https://github.com/getsentry/raven-ruby/wiki). -```ruby -Raven.capture_message "My event", - logger: 'logger', - extra: { - my_custom_variable: 'value' - }, - tags: { - environment: 'production' - } -``` - -The following attributes are available: - -* `logger`: the logger name to record this event under -* `level`: a string representing the level of this event (fatal, error, warning, info, debug) -* `server_name`: the hostname of the server -* `tags`: a mapping of [tags](https://www.getsentry.com/docs/tags/) describing this event -* `extra`: a mapping of arbitrary context - -## Providing Request Context - -Most of the time you're not actually calling out to Raven directly, but you still want to provide some additional context. This lifecycle generally constists of something like the following: - -- Set some context via a middleware (e.g. the logged in user) -- Send all given context with any events during the request lifecycle -- Cleanup context - -There are three primary methods for providing request context: - -```ruby -# bind the logged in user -Raven.user_context email: 'foo@example.com' - -# tag the request with something interesting -Raven.tags_context interesting: 'yes' - -# provide a bit of additional context -Raven.extra_context happiness: 'very' -``` - -Additionally, if you're using Rack (without the middleware), you can easily provide context with the ``rack_context`` helper: - -```ruby -Raven.rack_context(env) -``` - -If you're using the Rack middleware, we've already taken care of cleanup for you, otherwise you'll need to ensure you perform it manually: - -```ruby -Raven::Context.clear! -``` - -Note: the rack and user context will perform a set operation, whereas tags and extra context will merge with any existing request context. - -### Authlogic - -When using Authlogic for authentication, you can provide user context by binding to session ```after_persisting``` and ```after_destroy``` events in ```user_session.rb```: - -```ruby -class UserSession < Authlogic::Session::Base - # events binding - after_persisting :raven_set_user_context - after_destroy :raven_clear_user_context - - def raven_set_user_context - Raven.user_context( { 'id' => self.user.id, 'email' => self.user.email, 'username' => self.user.username } ) - end - - def raven_clear_user_context - Raven.user_context({}) - end -end -``` - -## Configuration - -### SENTRY_DSN - -After you complete setting up a project, you'll be given a value which we call a DSN, or Data Source Name. It looks a lot like a standard URL, but it's actually just a representation of the configuration required by Raven (the Sentry client). It consists of a few pieces, including the protocol, public and secret keys, the server address, and the project identifier. - -With Raven, you may either set the ```SENTRY_DSN``` environment variable (recommended), or set your DSN manually in a config block: - -```ruby -# in Rails, this might be in config/initializers/sentry.rb -Raven.configure do |config| - config.dsn = 'http://public:secret@example.com/project-id' -end -``` - -### Environments - -As of [v0.10.0](https://github.com/getsentry/raven-ruby/blob/21cb3164e0d0ab91394ba98b78195c4f6342b4bb/changelog.md#0100), events will be sent to Sentry in all environments. If you do not wish -to send events in an environment, we suggest you unset the ```SENTRY_DSN``` -variable in that environment. - -Alternately, you can configure Raven to run only in certain environments by configuring the `environments` whitelist. For example, to only run Sentry in production: - -```ruby -Raven.configure do |config| - config.environments = %w[ production ] -end -``` - -Sentry automatically sets the current environment to ```RAILS_ENV```, or if it is not present, ```RACK_ENV```. If you are using Sentry outside of Rack or Rails, you'll need to set the current environment yourself: - -```ruby -Raven.configure do |config| - config.current_environment = 'my_cool_environment' -end -``` - -### Excluding Exceptions - -If you never wish to be notified of certain exceptions, specify 'excluded_exceptions' in your config file. - -In the example below, the exceptions Rails uses to generate 404 responses will be suppressed. - -```ruby -Raven.configure do |config| - config.excluded_exceptions = ['ActionController::RoutingError', 'ActiveRecord::RecordNotFound'] -end -``` - -You can find the list of exceptions that are excluded by default in [Raven::Configuration::IGNORE_DEFAULT](https://github.com/getsentry/raven-ruby/blob/master/lib/raven/configuration.rb). Remember you'll be overriding those defaults by setting this configuration. - -You can also use a configuration option to determine if an individual event should -be sent to Sentry. Events are passed to the Proc or lambda you provide - returning -`false` will stop the event from sending to Sentry: - -```ruby -Raven.configure do |config| - config.should_send = Proc.new { |e| true unless e.contains_sensitive_info? } -end -``` - -### Tags - -You can configure default tags to be sent with every event. These can be -overridden in the context or event. - -```ruby -Raven.configure do |config| - config.tags = { environment: Rails.env } -end -``` - -### SSL Verification - -By default SSL certificate verification is **disabled** in the client. This choice -was made due to root CAs not being commonly available on systems. If you'd like -to change this, you can enable verification by passing the ``ssl_verification`` -flag: - -```ruby -Raven.configure do |config| - config.ssl_verification = true -end -``` - -### Asynchronous Delivery - -When an error occurs, the notification is immediately sent to Sentry. Raven can be configured -to send notifications asynchronously: - -```ruby -Raven.configure do |config| - config.async = lambda { |event| - Thread.new { Raven.send(event) } - } -end -``` - -This example uses a thread, but other tools can be used (GirlFriday, Resque, Sidekiq, etc...) as -long as the `event` argument is eventually passed to `Raven.send`. - -### Logging - -You can use any logger with Raven - just set config.logger. Raven respects logger -levels. - -```ruby -logger = ::Logger.new(STDOUT) -logger.level = ::Logger::WARN - -Raven.configure do |config| - config.logger = logger -end -``` - -If you are using Rails, Raven will default to using Rails.logger as the logger. - -### Encoding - -While unlikely that you'll need to change it, by default Raven compresses outgoing messages with gzip. This has a slight impact on performance, but due to the size of many Ruby stacktrace it's required for the serve to accept the content. - -To disable gzip, set the encoding to 'json': - -```ruby -Raven.configure do |config| - config.encoding = 'json' -end -``` - -### Silencing the ready message - -Upon start, Raven will write the following message to the log at the INFO level: - - ** [out :: hostname.example.com] I, [2014-07-22T15:32:57.498368 #30897] INFO -- : ** [Raven] Raven 0.9.4 ready to catch errors" - -You can turn off this message by passing `true` to `Raven.configure` - -```ruby -Raven.configure(true) do |config| - ... -end -``` - - -## Sanitizing Data (Processors) - -If you need to sanitize or pre-process (before its sent to the server) data, you can do so using the Processors -implementation. By default, a single processor is installed (Raven::Processor::SanitizeData), which will attempt to -sanitize keys that match various patterns (e.g. password) and values that resemble credit card numbers. - -To specify your own (or to remove the defaults), simply pass them with your configuration: - -```ruby -Raven.configure do |config| - config.processors = [Raven::Processor::SanitizeData] -end -``` - -## Testing Your Configuration - -To ensure you've setup your configuration correctly we recommend running the -included rake task:: - -```bash -$ rake raven:test[https://public:secret@app.getsentry.com/3825] -Client configuration: --> server: https://app.getsentry.com --> project_id: 3825 --> public_key: public --> secret_key: secret - -Sending a test event: --> event ID: 033c343c852b45c2a3add98e425ea4b4 - -Done! -``` - -A couple of things to note: - -* This won't test your environment configuration. The test CLI forces your - configuration to represent itself as if it were running in the production env. -* If you're running within Rails (or anywhere else that will bootstrap the - rake environment), you should be able to omit the DSN argument. - -## Contributing - -### Bootstrap - -```bash -$ bundle install -``` - -### Running the test suite - -```bash -$ rake spec -``` - -Resources ---------- - +* [Documentation](https://github.com/getsentry/raven-ruby/wiki) * [Bug Tracker](http://github.com/getsentry/raven-ruby/issues>) * [Code](http://github.com/getsentry/raven-ruby>) * [Mailing List](https://groups.google.com/group/getsentry>) * [IRC](irc://irc.freenode.net/sentry>) (irc.freenode.net, #sentry)