<commit_before># Nexaas::Auditor

Common code for audit logs and statistcs tracking for [Nexaas](http://www.nexaas.com) Rails apps, via [ActiveSupport instrumentation](http://edgeguides.rubyonrails.org/active_support_instrumentation.html).

## Installation

Add this line to your application's Gemfile:

```ruby
gem 'nexaas-auditor'
```

And then execute:

```
$ bundle
```

Or install it yourself as:

```
$ gem install nexaas-auditor
```

## Usage

In a Rails initializer file such as `config/initializers/nexaas_auditor.rb`, put something like this:

```ruby
require 'nexaas/auditor'

Nexaas::Auditor.configure do |config|
  config.enabled = true
  config.logger = Rails.logger

  # use audit logging for 'app.*' instrumented events
  config.log_app_events = true

  # use statistics tracking for 'app.*' instrumented events
  config.track_app_events = true

  # use statistics tracking for default rails instrumented events
  config.track_rails_events = true

  # optionally, prepend statistics metric names on the service. use this if you
  # use the same statistics service (ie StatHat) for multiple apps
  config.statistics_namespace = 'myappname'

  if Rails.env.production?
    # use StatHat service in production only
    config.statistics_service = 'stathat'
    config.stathat_settings = {key: 'stathat-ez-key'}
  else
    # the 'log' service only writes the stats to the logger instead of sending
    # them to an external service.
    config.statistics_service = 'log'
  end
end

# setups all subscribers
Nexaas::Auditor.subscribe_all
```

Then, create your loggers and statistic trackers in `app/loggers/` and `app/statistics/` for example, inheriting from `Nexaas::Auditor::LogSubscriber` and `Nexaas::Auditor::StatsSubscriber` respectively.

For example:

```ruby
class UsersAppLogger < ::Nexaas::Auditor::LogSubscriber
  # The namespace for events to subscribe to. In this example, subscribe to all
  # events beggining with "app.users.".
  def self.pattern
    /\Aapp\.users\..+\Z/
  end

  # Called when an event with name == 'app.users.login.success' is received.
  #
  #   name = the event name, 'app.users.login.success' in this case
  #   start = the time the event started
  #   finish = the time the event finished
  #     (tip: finish - start gives you the duration in seconds as a float)
  #   event_id = an unique id for the event
  #   payload = a hash of extra data the event may have supplied when instrumented<commit_msg>Improve README<commit_after># Nexaas::Auditor

Common **opnionated** code for audit logs and statistcs tracking for Rails apps, via [ActiveSupport instrumentation](http://edgeguides.rubyonrails.org/active_support_instrumentation.html). Used in production in a few [Nexaas](http://www.nexaas.com) systems.

This has been tested with Rails 4.2.x only so far. It probably works fine as well in Rails 4.1.x, but I'm not sure about Rails 3.x yet.

The audit log is created in a [logfmt](https://www.brandur.org/logfmt) format only for now. Support for more log formats is planned in the future.

Both the audit log and statistics tracking assume all instrumented events are named in a dot notation format, for example you could use `'app.users.login.sucess'` to instrument a successful user login event. The `'app.'` prefix is a suggestion to separate your bussiness-logic events from framework-specific (Rails) events, which will always have a `'rails.'` prefix, for example `'rails.action_controller.runtime.total'` for example.

## Installation

Add this line to your application's Gemfile:

```ruby
gem 'nexaas-auditor'
```

And then execute:

```
$ bundle
```

Or install it yourself as:

```
$ gem install nexaas-auditor
```

## Usage

In a Rails initializer file such as `config/initializers/nexaas_auditor.rb`, put something like this:

```ruby
require 'nexaas/auditor'

Nexaas::Auditor.configure do |config|
  config.enabled = true
  config.logger = Rails.logger

  # use audit logging for bussiness-logic instrumented events
  config.log_app_events = true

  # use statistics tracking for bussiness-logic instrumented events
  config.track_app_events = true

  # use statistics tracking for default Rails instrumented events
  # don't forget to add the 'nunes' gem to your Gemfile (we use Nunes to do the
  # heavy lifting on the instrumented Rails events)
  config.track_rails_events = true

  # optionally, prepend statistics metric names with your app name. use this if
  # you use the same statistics service (ie StatHat) for multiple apps.
  config.statistics_namespace = 'myappname'

  if Rails.env.production?
    # use StatHat service in production only
    # don't forget to add the 'stathat' gem to your Gemfile
    config.statistics_service = 'stathat'
    config.stathat_settings = {key: 'stathat-ez-key'}
  else
    # the 'log' service only writes the stats to the audit log instead of
    # sending them to an external service.
    config.statistics_service = 'log'
  end
end

# setup all subscribers
Nexaas::Auditor.subscribe_all
```

Then, create your loggers and statistic trackers in `app/loggers/` and `app/statistics/` for example, inheriting from `Nexaas::Auditor::LogSubscriber` and `Nexaas::Auditor::StatsSubscriber` respectively.

For example:

```ruby
class UsersAppLogger < ::Nexaas::Auditor::LogSubscriber
  # The namespace for events to subscribe to. In this example, subscribe to all
  # events beggining with "app.users.".
  def self.pattern
    /\Aapp\.users\..+\Z/
  end

  # Called when an event with name == 'app.users.login.success' is received.
  #
  #   name = the event name, 'app.users.login.success' in this case
  #   start = the time the event started
  #   finish = the time the event finished
  #     (tip: finish - start gives you the duration in seconds as a float)
  #   event_id = an unique id for the event
  #   payload = a hash of extra data the event may have supplied when instrumented
{'fraction_non_alphanumeric': 0.08835000847888758, 'fraction_numerical': 0.0008478887569950823, 'mean_word_length': 4.049657534246576, 'pattern_counts': {'":': 0, '<': 5, '<?xml version=': 0, '>': 3, 'https://': 1, 'lorem ipsum': 0, 'www.': 3, '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': '7401378', 'n_tokens_mistral': 1830, 'n_tokens_neox': 1734, 'n_words': 674}