README.md in sentry-raven-0.4.5 vs README.md in sentry-raven-0.4.6
- old
+ new
@@ -1,94 +1,56 @@
# Raven-Ruby
-[](http://travis-ci.org/getsentry/raven-ruby)
+[](http://badge.fury.io/rb/sentry-raven) [](http://travis-ci.org/getsentry/raven-ruby) [](https://coveralls.io/r/getsentry/raven-ruby)
A client and integration layer for the [Sentry](https://github.com/getsentry/sentry) error reporting API.
-This library is still forming, so if you are looking to just use it, please check back in a few weeks.
+## Requirements
+We test on Ruby MRI 1.8.7, 1.9.2, 1.9.3 and 2.0.0. Other versions/VMs are untested but we will accept pull requests to support them.
+
## Installation
-Add the following to your `Gemfile`:
-
```ruby
-gem "sentry-raven", :git => "https://github.com/getsentry/raven-ruby.git"
+gem "sentry-raven" #, :github => "getsentry/raven-ruby"
```
-Or install manually
-```bash
-$ gem install sentry-raven
-```
-
## Usage
+You'll want to set your ```SENTRY_DSN``` environment variable to the URL on your project's API Keys setting page (e.g. ```https://secret:public@app.getsentry.com/9999```). For more information, see [Configuration](#configuration).
+
### Rails 3
-Add a `config/initializers/raven.rb` containing:
+In Rails 3, Sentry will "just work," capturing any exceptions thrown in your app. All Rails integrations also
+have mixed-in methods for capturing exceptions you've rescued yourself inside of controllers:
```ruby
-require 'raven'
-
-Raven.configure do |config|
- config.dsn = 'http://public:secret@example.com/project-id'
-end
+ # ...
+ rescue => exception
+ capture_exception(exception) # or capture_message('Flux overload')
+ flash[:error] = 'Your flux capacitor is overloaded!'
+ end
```
### Rails 2
-No support for Rails 2 yet.
+No support for Rails 2 yet, but it is being worked on.
### Rack
-Basic RackUp file.
+Add ```use Raven::Rack``` to your ```config.ru``` (or other rackup file).
-```ruby
-require 'raven'
-
-Raven.configure do |config|
- config.dsn = 'http://public:secret@example.com/project-id'
-end
-
-use Raven::Rack
-```
-
### Sinatra
-```ruby
-require 'sinatra'
-require 'raven'
+Like any other Rack middleware, add ```use Raven::Rack``` to your Sinatra app.
-Raven.configure do |config|
- config.dsn = 'http://public:secret@example.com/project-id'
-end
-
-use Raven::Rack
-
-get '/' do
- 1 / 0
-end
-```
-
-### Other Ruby
-
-```ruby
-require 'raven'
-
-Raven.configure do |config|
- config.dsn = 'http://public:secret@example.com/project-id'
-
- # manually configure environment if ENV['RACK_ENV'] is not defined
- config.current_environment = 'production'
-end
-```
-
## 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 helps are available to assist with this.
+Several helpers are available to assist with this.
### Capture Exceptions in a Block
```ruby
Raven.capture do
@@ -126,46 +88,62 @@
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 describing this event
+* `tags`: a mapping of [tags](https://www.getsentry.com/docs/tags/) describing this event
* `extra`: a mapping of arbitrary context
## Testing
```bash
$ bundle install
$ rake spec
```
-## Notifications in development mode
+## Configuration
-By default events will only be sent to Sentry if your application is running in a production environment. This is configured by default if you are running a Rack application (i.e. anytime `ENV['RACK_ENV']` is set).
+### SENTRY_DSN
-You can configure Raven to run in non-production environments by configuring the `environments` whitelist:
+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.
-```ruby
-require 'raven'
+With Raven, you may either set the ```SENTRY_DSN``` environment variable (recommended), or set your DSN manually in a config block:
+```ruby
Raven.configure do |config|
config.dsn = 'http://public:secret@example.com/project-id'
- config.environments = %w[ development production ]
end
```
-## Excluding Exceptions
+### Environments
+By default events will be sent to Sentry in all environments except 'test', 'development', and 'cucumber'.
+
+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
-require 'raven'
-
Raven.configure do |config|
- config.dsn = 'http://public:secret@example.com/project-id'
config.excluded_exceptions = ['ActionController::RoutingError', 'ActiveRecord::RecordNotFound']
end
```
## Sanitizing Data (Processors)
@@ -175,13 +153,10 @@
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
-require 'raven'
-
Raven.configure do |config|
- config.dsn = 'http://public:secret@example.com/project-id'
config.processors = [Raven::Processor::SanitizeData]
end
```
## Command Line Interface