<!--
This file was generated by Spark. Do not edit it by hand.
-->
# AshAuthentication.AuditLogResource

This is an Ash resource extension which generates the default audit log resource.

The audit log resource is used to store user interactions with the authentication system in order to derive extra security behaviour from this information.

## Storage

The information stored in this resource is essentially time-series, and should be stored in a resilient data-layer such as postgres.

## Usage

There is no need to define any attributes or actions (thought you can if you want). The extension will wire up everything that's needed for the audit log to function.

```elixir
defmodule MyApp.Accounts.AuditLog do
  use Ash.Resource,
    data_layer: AshPostgres.DataLayer,
    extensions: [AshAuthentication.AuditLogResource],
    domain: MyApp.Accounts


  postgres do
    table "account_audit_log"
    repo MyApp.Repo
  end
end
```

Whilst it is possible to have multiple audit log resources, there is no need to do so.

## Batched writes

In order to reduce the write load on the database writes to the audit log (via the `AuditLogResource.log_activity/2` function) will be buffered in a GenServer and written in batches.

Batching can be disabled entirely by setting `audit_log.write_batching.enabled?` to `false`.
By default it write a batch every 100 records or every 10 seconds, whichever happens first. This can also be controlled by options in the `audit_log.write_batching` DSL.

## Removing old records

When the `log_lifetime` DSL option is set to a positive integer then log entries will be automatically removed after that many days.  To disable this behaviour, or to manage it manually set it to `:infinity`.  Defaults to 90 days.


## audit_log
Configuration options for this audit log resource

### Nested DSLs
 * [write_action](#audit_log-write_action)
 * [destroy_action](#audit_log-destroy_action)
 * [read_expired_action](#audit_log-read_expired_action)
 * [attributes](#audit_log-attributes)
 * [write_batching](#audit_log-write_batching)





### Options

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`domain`](#audit_log-domain){: #audit_log-domain } | `module` |  | The Ash domain to use to access this resource. |
| [`log_lifetime`](#audit_log-log_lifetime){: #audit_log-log_lifetime } | `pos_integer \| :infinity` | `90` | How long to keep event logs before removing them in days. |
| [`expunge_interval`](#audit_log-expunge_interval){: #audit_log-expunge_interval } | `pos_integer` | `12` | How often (in hours) to scan this resource for records which have expired and thus can be removed. |


### audit_log.write_action
Configuration applied for the write action






### Options

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`name`](#audit_log-write_action-name){: #audit_log-write_action-name } | `atom` | `:log_activity` | The name of the generated write action. |




### audit_log.destroy_action
Configuration applied for the expunge action






### Options

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`name`](#audit_log-destroy_action-name){: #audit_log-destroy_action-name } | `atom` | `:expunge_logs` | The name of the generated expunge action. |




### audit_log.read_expired_action
Configuration applied for the read action used to find records for removal






### Options

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`name`](#audit_log-read_expired_action-name){: #audit_log-read_expired_action-name } | `atom` | `:read_expired` | The name of the generated read action. |




### audit_log.attributes
Attribute renaming configuration






### Options

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`id`](#audit_log-attributes-id){: #audit_log-attributes-id } | `atom` | `:id` | The name of the primary key attribute |
| [`subject`](#audit_log-attributes-subject){: #audit_log-attributes-subject } | `atom` | `:subject` | The attribute within which to store the user's authentication subject (if available). |
| [`identity`](#audit_log-attributes-identity){: #audit_log-attributes-identity } | `atom` | `:identity` | The attribute within which to store the identity field value submitted to the action (e.g. the email or username), if known. |
| [`client_ip`](#audit_log-attributes-client_ip){: #audit_log-attributes-client_ip } | `atom` | `:client_ip` | The attribute within which to store the client IP address of the request, if known. The stored value is subject to the `ip_privacy_mode` configured on the audit log add-on. |
| [`strategy`](#audit_log-attributes-strategy){: #audit_log-attributes-strategy } | `atom` | `:strategy` | The attribute within which to store the authentication strategy's name. |
| [`audit_log`](#audit_log-attributes-audit_log){: #audit_log-attributes-audit_log } | `atom` | `:audit_log` | The attribute within which to store the audit log add-on's name. |
| [`logged_at`](#audit_log-attributes-logged_at){: #audit_log-attributes-logged_at } | `atom` | `:logged_at` | The attribute within which to store the time that the event occurred. |
| [`action_name`](#audit_log-attributes-action_name){: #audit_log-attributes-action_name } | `atom` | `:action_name` | The attribute within which to store the triggering action. |
| [`status`](#audit_log-attributes-status){: #audit_log-attributes-status } | `atom` | `:status` | The attribute within which to store the status of the event as defined by the authentication strategy. |
| [`extra_data`](#audit_log-attributes-extra_data){: #audit_log-attributes-extra_data } | `atom` | `:extra_data` | The attribute within which to store any additional information about the event. |
| [`resource`](#audit_log-attributes-resource){: #audit_log-attributes-resource } | `atom` | `:resource` | The attribute within which to store the name of the affected resource. |




### audit_log.write_batching
Configuration of event log write batching






### Options

| Name | Type | Default | Docs |
|------|------|---------|------|
| [`enabled?`](#audit_log-write_batching-enabled?){: #audit_log-write_batching-enabled? } | `boolean` | `true` | Whether or not write batching should be enabled.  When set to false every event will be written to the log in it's own transaction. |
| [`timeout`](#audit_log-write_batching-timeout){: #audit_log-write_batching-timeout } | `timeout` | `10000` | Maximum time to wait between writing batches in milliseconds. |
| [`max_size`](#audit_log-write_batching-max_size){: #audit_log-write_batching-max_size } | `pos_integer` | `100` | Maximum number of events that can be written in a single batch. |









<style type="text/css">.spark-required::after { content: "*"; color: red !important; }</style>