ExAudit

To use ExAudit, add it to your project dependencies and hook ExAudit.Repo into your existing Ecto repository module. This allows ExAudit to transparently wrap standard Ecto mutation functions.

# 1. Add to deps
def deps do
  [ {:ex_audit, "~> 0.9"} ]
end

# 2. Hook into your Repo
defmodule MyApp.Repo do
  use Ecto.Repo,
    otp_app: :my_app,
    adapter: Ecto.Adapters.Postgres

  use ExAudit.Repo
end

To record additional context (like the current user's ID) with an audit log, you have two primary methods:

1. Manual passing: Use the ex_audit_custom option in any Repo function call.
2. Plug-based tracking: Use ExAudit.track/1 in a Phoenix Plug. This attaches the data to the current process (PID), which ExAudit will then automatically pick up when Repo functions are called within that same process tree.

# Method 1: Manual option
MyApp.Repo.insert(changeset, ex_audit_custom: [user_id: conn.assigns.current_user.id])

# Method 2: Using a Plug
defmodule MyApp.ExAuditPlug do
  def init(_), do: nil

  def call(conn, _) do
    ExAudit.track(user_id: conn.assigns.current_user.id)
    conn
  end
end

You must configure which Ecto repositories to use, which schemas should be tracked, and which module defines your version schema. You can also define :primitive_structs to prevent ExAudit from recursing into specific types (like Date), recording them as a single change instead.

config :ex_audit,
  ecto_repos: [MyApp.Repo],
  version_schema: MyApp.Version,
  tracked_schemas: [
    MyApp.Accounts.User,
    MyApp.BlogPost,
    MyApp.Comment
  ],
  primitive_structs: [
    Date
  ]

The ExAudit.Tracker protocol allows you to control which fields of a struct are captured during an audit. By implementing this protocol, you can filter out sensitive data or reduce audit noise by specifying exactly which fields should be tracked.

For most use cases, you do not need to implement the protocol manually. Instead, you can use the @derive attribute with only or except options to declaratively define your tracking logic.

# Track only specific fields
@derive {ExAudit.Tracker, only: [:name, :email]}
defmodule User do
  use ExAudit.Schema
end

# Ignore specific fields
@derive {ExAudit.Tracker, except: [:password_hash, :internal_notes]}
defmodule User do
  use ExAudit.Schema
end

To enable automatic version tracking for your database operations, add use ExAudit.Repo to your existing Ecto.Repo module. This extends standard Ecto functions to detect if the struct or changeset being operated on is included in the :tracked_schemas configuration list.

defmodule MyApp.Repo do
  use Ecto.Repo, 
    otp_app: :my_app, 
    adapter: Ecto.Adapters.Postgres

  use ExAudit.Repo
end

Once configured, ExAudit automatically tracks changes made via insert/2, insert!/2, update/2, update!/2, delete/2, and delete!/2. It also provides two new functions for managing history:

• history(struct): Returns a list of all versions of the given struct, ordered from oldest to newest.
• revert(struct, version): Rolls the entity back to the state it was in before the specified version was changed.

ExAudit supports additional options passed to its extended Ecto functions to control auditing behavior:

• :ex_audit_custom - A keyword list of custom data to be included in the new version entries. These entries will overwrite data with the same keys from the ExAudit.track call.
• :ignore_audit - If set to true, ExAudit will skip tracking changes made to the entity.

ExAudit uses a central schema to store audit logs. You can configure which schema is used by setting the :version_schema key in your application configuration.

Config Key:

• :ex_audit -> :version_schema: The module name of the schema used for storing versions.

# In config/config.exs
config :ex_audit, version_schema: MyAuditSchema

When using @derive {ExAudit.Tracker, options}, you can pass the following options to control field extraction:

• only: [:field1, :field2]: Tracks only the specified fields. All other fields are ignored.
• except: [:field1, :field2]: Tracks all fields except the ones specified. Note that __meta__ and __struct__ are always ignored by default.
• No options: If no options are provided, the tracker defaults to dropping only the internal __meta__ and __struct__ fields.

# Example: Using 'only' to whitelist fields
@derive {ExAudit.Tracker, only: [:id, :status]}

# Example: Using 'except' to blacklist fields
@derive {ExAudit.Tracker, except: [:secret_token]}

ExAudit uses application environment configuration to determine which schemas to track and which schema to use for storing audit versions.

Configuration Keys:

• :tracked_schemas: A list of module names (schemas) that ExAudit.Tracking is allowed to generate diffs for.
• :version_schema: The module name of the schema used to store the audit/version records.

## Example configuration in config/config.exs

config :ex_audit, 
  tracked_schemas: [MyApp.User, MyApp.Post],
  version_schema: MyApp.AuditLog

Ensure you use the correct version of ex_audit based on your Ecto version: