README.md in sentry-raven-0.7.1 vs README.md in sentry-raven-0.8.0
- old
+ new
@@ -1,8 +1,10 @@
# Raven-Ruby
-[](http://badge.fury.io/rb/sentry-raven) [](http://travis-ci.org/getsentry/raven-ruby) [](https://coveralls.io/r/getsentry/raven-ruby)
+[](https://rubygems.org/gems/sentry-raven)
+[](https://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.
## Requirements
@@ -16,11 +18,11 @@
## Usage
The easiest way to configure Raven is by setting the ``SENTRY_DSN`` environment variable.
-You'll find this value on your project settings page, and it should resemble something like ```https://secret:public@app.getsentry.com/9999```.
+You'll find this value on your project settings page, and it should resemble something like ```https://public:secret@app.getsentry.com/9999```.
For alternative configuration methods, and other options see [Configuration](#configuration).
### Rails 3
@@ -33,10 +35,34 @@
capture_exception(exception) # or capture_message('Flux overload')
flash[:error] = 'Your flux capacitor is overloaded!'
end
```
+#### Delayed::Job
+
+The easiest way of enabling Raven for all your delayed jobs is to use [delayed-plugins-raven](https://github.com/qiushihe/delayed-plugins-raven) gem. First add it to your application's Gemfile:
+
+```
+gem 'delayed-plugins-raven'
+```
+
+And then extend your Raven configuration (eg. in ```config/initializers/raven.rb``` file):
+
+```ruby
+require 'raven'
+require 'delayed-plugins-raven'
+
+Raven.configure do |config|
+ config.dsn = 'https://public:secret@app.getsentry.com/9999'
+ ...
+end
+
+Delayed::Worker.plugins << Delayed::Plugins::Raven::Plugin
+```
+
+For more configuration options check delayed-plugins-raven [documentation](https://github.com/qiushihe/delayed-plugins-raven).
+
### Rails 2
No support for Rails 2 yet, but it is being worked on.
### Rack
@@ -88,19 +114,18 @@
### Additional Context
Additional context can be passed to the capture methods.
```ruby
-Raven.capture_message("My event", {
- :logger => 'logger',
- :extra => {
- 'my_custom_variable' => 'value'
+Raven.capture_message "My event",
+ logger: 'logger',
+ extra: {
+ my_custom_variable: 'value'
},
- :tags => {
- 'environment' => 'production',
+ tags: {
+ environment: 'production'
}
-})
```
The following attributes are available:
* `logger`: the logger name to record this event under
@@ -119,17 +144,17 @@
There are three primary methods for providing request context:
```ruby
# bind the logged in user
-Raven.user_context({'email' => 'foo@example.com'})
+Raven.user_context email: 'foo@example.com'
# tag the request with something interesting
-Raven.tags_context({'interesting' => 'yes'})
+Raven.tags_context interesting: 'yes'
# provide a bit of additional context
-Raven.extra_context({'happiness' => 'very'})
+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
@@ -137,15 +162,36 @@
```
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!
+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.
@@ -211,10 +257,27 @@
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.