Skip to content
Audited (formerly acts_as_audited) is an ORM extension that logs all changes to your Rails models.
Pull request Compare This branch is 149 commits behind collectiveidea:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.

Audited Build Status Dependency Status

Audited (previously acts_as_audited) is an ORM extension that logs all changes to your models. Audited also allows you to record who made those changes, save comments and associate models related to the changes. Audited works with Rails 3.

Supported Rubies

Audited supports and is tested against the following Ruby versions:

  • 1.8.7
  • 1.9.2
  • 1.9.3
  • Head

Audited may work just fine with a Ruby version not listed above, but we can't guarantee that it will. If you'd like to maintain a Ruby that isn't listed, please let us know with a pull request.

Supported ORMs

In a previous life, Audited was ActiveRecord-only. Audited will now audit models for the following backends:

  • ActiveRecord
  • MongoMapper


The installation process depends on what ORM your app is using.


Add the appropriate gem to your Gemfile:

gem "audited-activerecord", "~> 3.0"

Then, from your Rails app directory, create the audits table:

$ rails generate audited:install
$ rake db:migrate


If you're already using Audited (or acts_as_audited), your audits table may require additional columns. After every upgrade, please run:

$ rails generate audited:upgrade
$ rake db:migrate

Upgrading will only make changes if changes are needed.


gem "audited-mongo_mapper", "~> 3.0"


Simply call audited on your models:

class User < ActiveRecord::Base

By default, whenever a user is created, updated or destroyed, a new audit is created.

user = User.create!(:name => "Steve")
user.audits.count # => 1
user.update_attributes!(:name => "Ryan")
user.audits.count # => 2
user.audits.count # => 3

Audits contain information regarding what action was taken on the model and what changes were made.

user.update_attributes!(:name => "Ryan")
audit = user.audits.last
audit.action # => "update"
audit.audited_changes # => {"name"=>["Steve", "Ryan"]}


You can attach comments to each audit using an audit_comment attribute on your model.

user.update_attributes!(:name => "Ryan", :audit_comment => "Changing name, just because")
user.audits.last.comment # => "Changing name, just because"

You can optionally add the :comment_required option to your audited call to require comments for all audits.

class User < ActiveRecord::Base
  audited :comment_required => true

Current User Tracking

If you're using Audited in a Rails application, all audited changes made within a request will automatically be attributed to the current user. By default, Audited uses the current_user method in your controller.

class PostsController < ApplicationController
  def create
    current_user # => #<User name: "Steve">
    @post = Post.create(params[:post])
    @post.audits.last.user # => #<User name: "Steve">

To use a method other than current_user, put the following in an intializer:

Audited.current_user_method = :authenticated_user

Outside of a request, Audited can still record the user with the as_user method:

Audit.as_user(User.find(1)) do
  post.update_attribute!(:title => "Hello, world!")
post.audits.last.user # => #<User id: 1>

Associated Audits

Sometimes it's useful to associate an audit with a model other than the one being changed. For instance, given the following models:

class User < ActiveRecord::Base
  belongs_to :company

class Company < ActiveRecord::Base
  has_many :users

Every change to a user is audited, but what if you want to grab all of the audits of users belonging to a particular company? You can add the :associated_with option to your audited call:

class User < ActiveRecord::Base
  belongs_to :company
  audited :associated_with => :company

class Company < ActiveRecord::Base
  has_many :users

Now, when a audit is created for a user, that user's company is also saved alongside the audit. This makes it much easier (and faster) to access audits indirectly related to a company.

company = Company.create!(:name => "Collective Idea")
user = company.users.create!(:name => "Steve")
user.update_attribute!(:name => "Steve Richert")
user.audits.last.associated # => #<Company name: "Collective Idea">
company.associated_audits.last.auditable # => #<User name: "Steve Richert">


ActiveRecord Accessible Attributes

If your model calls attr_accessible after audited, you'll need to set the :protect => false option. By default, Audited uses attr_protected to prevent malicious users from dissociating your audits, but Rails doesn't allow both attr_protected and attr_accessible.

class User < ActiveRecord::Base
  audited :protect => false
  attr_accessible :name

MongoMapper Embedded Documents

Currently, Audited does not track changes on embedded documents. Audited works by tracking a model's dirty changes but changes to embedded documents don't appear in dirty tracking.


You can find documentation at:

Or join the mailing list to get help or offer suggestions.


In the spirit of free software, everyone is encouraged to help improve this project. Here are a few ways you can pitch in:

  • Use prerelease versions of Audited.
  • Report bugs.
  • Fix bugs and submit pull requests.
  • Write, clarify or fix documentation.
  • Refactor code.
Something went wrong with that request. Please try again.