<commit_before># Rollbar notifier for Ruby [![Build Status](https://secure.travis-ci.org/rollbar/rollbar-gem.png?branch=master)](https://travis-ci.org/rollbar/rollbar-gem)

Ruby gem for reporting exceptions, errors, and log messages to [Rollbar](https://rollbar.com).

<!-- Sub:[TOC] -->

## Installation

Add this line to your application's Gemfile:

    gem 'rollbar'

And then execute:

```bash
$ bundle install
```

Or install it yourself as:

```bash
$ gem install rollbar
```

Then, run the following command from your rails root:

```bash
$ rails generate rollbar POST_SERVER_ITEM_ACCESS_TOKEN
```

That will create the file ```config/initializers/rollbar.rb```, which holds the configuration values (currently just your access token). Make sure you're using the ```post_server_item``` access token.

If you want to store your access token outside of your repo, run the same command without arguments:

```bash
$ rails generate rollbar
```

Then, create an environment variable ```ROLLBAR_ACCESS_TOKEN``` and set it to your server-side access token.

```bash
$ export ROLLBAR_ACCESS_TOKEN=POST_SERVER_ITEM_ACCESS_TOKEN
```

### For Heroku users

```bash
$ heroku config:add ROLLBAR_ACCESS_TOKEN=POST_SERVER_ITEM_ACCESS_TOKEN
```

That's all you need to use Rollbar with Rails.

## Test your installation

To confirm that it worked, run:

```bash
$ rake rollbar:test
```

This will raise an exception within a test request; if it works, you'll see a stacktrace in the console, and the exception will appear in the Rollbar dashboard.

## Manually reporting exceptions and messages

To report a caught exception to Rollbar, simply call ```Rollbar.report_exception```:

```ruby
begin
  foo = bar
rescue Exception => e
  Rollbar.report_exception(e)
end
```

If you're reporting an exception in the context of a request and are in a controller, you can pass along the same request and person context as the global exception handler, like so:

```ruby
begin
  foo = bar
rescue Exception => e
  Rollbar.report_exception(e, rollbar_request_data, rollbar_person_data)
end
```

You can also log individual messages:

```ruby
# logs at the 'warning' level. all levels: debug, info, warning, error, critical
Rollbar.report_message("Unexpected input", "warning")

# default level is "info"
Rollbar.report_message("Login successful")

# can also include additional data as a hash in the final param. :body is reserved.
Rollbar.report_message("Login successful", "info", :user => @user)
```

## Person tracking

Rollbar will send information about the current user (called a "person" in Rollbar parlance) along with each error report, when available. This works by calling the ```current_user``` controller method. The return value should be an object with an ```id``` method and, optionally, ```username``` and ```email``` methods.

If the gem should call a controller method besides ```current_user```, add the following in ```config/initializers/rollbar.rb```:

```ruby
config.person_method = "my_current_user"
```

If the methods to extract the ```id```, ```username```, and ```email``` from the object returned by the ```person_method``` have other names, configure like so in ```config/initializers/rollbar.rb```:

```ruby
config.person_id_method = "user_id"  # default is "id"
config.person_username_method = "user_name"  # default is "username"
config.person_email_method = "email_address"  # default is "email"
```

## Including additional runtime data

You can provide a lambda that will be called for each exception or message report.  ```custom_data_method``` should be a lambda that takes no arguments and returns a hash. 

Add the following in ```config/initializers/rollbar.rb```:
<commit_msg>add scrub fields doc @brianr<commit_after># Rollbar notifier for Ruby [![Build Status](https://secure.travis-ci.org/rollbar/rollbar-gem.png?branch=master)](https://travis-ci.org/rollbar/rollbar-gem)

Ruby gem for reporting exceptions, errors, and log messages to [Rollbar](https://rollbar.com).

<!-- Sub:[TOC] -->

## Installation

Add this line to your application's Gemfile:

    gem 'rollbar'

And then execute:

```bash
$ bundle install
```

Or install it yourself as:

```bash
$ gem install rollbar
```

Then, run the following command from your rails root:

```bash
$ rails generate rollbar POST_SERVER_ITEM_ACCESS_TOKEN
```

That will create the file ```config/initializers/rollbar.rb```, which holds the configuration values (currently just your access token). Make sure you're using the ```post_server_item``` access token.

If you want to store your access token outside of your repo, run the same command without arguments:

```bash
$ rails generate rollbar
```

Then, create an environment variable ```ROLLBAR_ACCESS_TOKEN``` and set it to your server-side access token.

```bash
$ export ROLLBAR_ACCESS_TOKEN=POST_SERVER_ITEM_ACCESS_TOKEN
```

### For Heroku users

```bash
$ heroku config:add ROLLBAR_ACCESS_TOKEN=POST_SERVER_ITEM_ACCESS_TOKEN
```

That's all you need to use Rollbar with Rails.

## Test your installation

To confirm that it worked, run:

```bash
$ rake rollbar:test
```

This will raise an exception within a test request; if it works, you'll see a stacktrace in the console, and the exception will appear in the Rollbar dashboard.

## Manually reporting exceptions and messages

To report a caught exception to Rollbar, simply call ```Rollbar.report_exception```:

```ruby
begin
  foo = bar
rescue Exception => e
  Rollbar.report_exception(e)
end
```

If you're reporting an exception in the context of a request and are in a controller, you can pass along the same request and person context as the global exception handler, like so:

```ruby
begin
  foo = bar
rescue Exception => e
  Rollbar.report_exception(e, rollbar_request_data, rollbar_person_data)
end
```

You can also log individual messages:

```ruby
# logs at the 'warning' level. all levels: debug, info, warning, error, critical
Rollbar.report_message("Unexpected input", "warning")

# default level is "info"
Rollbar.report_message("Login successful")

# can also include additional data as a hash in the final param. :body is reserved.
Rollbar.report_message("Login successful", "info", :user => @user)
```

## Data sanitization (scrubbing)

By default, the notifier will "scrub" the following fields from requests before sending to Rollbar

- ```:passwd```
- ```:password```
- ```:password_confirmation```
- ```:secret```
- ```:confirm_password```
- ```:password_confirmation```
- ```:secret_token```

If a request contains one of these fields, the value will be replaced with a ```"*"``` before being sent.

Additional fields can be scrubbed by updating ```Rollbar.configuration.scrub_fields```:

```ruby
# scrub out the "user_password" field
Rollbar.configuration.scrub_fields |= [:user_password]
```

## Person tracking

Rollbar will send information about the current user (called a "person" in Rollbar parlance) along with each error report, when available. This works by calling the ```current_user``` controller method. The return value should be an object with an ```id``` method and, optionally, ```username``` and ```email``` methods.

If the gem should call a controller method besides ```current_user```, add the following in ```config/initializers/rollbar.rb```:

```ruby
config.person_method = "my_current_user"
```

If the methods to extract the ```id```, ```username```, and ```email``` from the object returned by the ```person_method``` have other names, configure like so in ```config/initializers/rollbar.rb```:

```ruby
config.person_id_method = "user_id"  # default is "id"
config.person_username_method = "user_name"  # default is "username"
config.person_email_method = "email_address"  # default is "email"
```

## Including additional runtime data

You can provide a lambda that will be called for each exception or message report.  ```custom_data_method``` should be a lambda that takes no arguments and returns a hash. 

Add the following in ```config/initializers/rollbar.rb```:

{'fraction_non_alphanumeric': 0.11235955056179775, 'fraction_numerical': 0.0, 'mean_word_length': 5.21972049689441, 'pattern_counts': {'":': 0, '<': 5, '<?xml version=': 0, '>': 11, 'https://': 6, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3152598', 'n_tokens_mistral': 2374, 'n_tokens_neox': 2270, 'n_words': 937}