Skip to content

Audit Logging

Audit Logging is the process of recording a chronological sequence of events and activities within a system. Its primary purpose is to provide a verifiable trail for security analysis, compliance auditing, and forensic investigation.

Enabling Auditing

UseAuditing() middleware should be added to the ASP.NET Core request pipeline in order to create and save the audit logs.

public override void OnApplicationInitialization(ApplicationInitializationContext context)
{
    var app = context.GetApplicationBuilder();
    var env = context.GetEnvironment();
    ...
    app.UseAuditing();
    ...
}

AbpAuditingOptions

AbpAuditingOptions is the main options object to configure the audit log system. You can configure it in the ConfigureServices method of your module:

Configure<AbpAuditingOptions>(options =>
{
    options.IsEnabled = false; //Disables the auditing system
});

Here, a list of the options you can configure:

  • IsEnabled (default: true): A root switch to enable or disable the auditing system. Other options is not used if this value is false.
  • HideErrors (default: true): Audit log system hides and write regular logsif any error occurs while saving the audit log objects. If saving the audit logs is critical for your system, set this to false to throw exception in case of hiding the errors.
  • IsEnabledForAnonymousUsers (default: true): If you want to write audit logs only for the authenticated users, set this to false. If you save audit logs for anonymous users, you will see null for UserId values for these users.
  • AlwaysLogOnException (default: true): If you set to true, it always saves the audit log on an exception/error case without checking other options (except IsEnabled, which completely disables the audit logging).
  • IsEnabledForIntegrationService (default: false): Audit Logging is disabled for integration services by default. Set this property as true to enable it.
  • IsEnabledForGetRequests (default: false): HTTP GET requests should not make any change in the database normally and audit log system doesn't save audit log objects for GET request. Set this to true to enable it also for the GET requests.
  • DisableLogActionInfo (default: false):If you set to true, Will no longer log AuditLogActionInfo.
  • ApplicationName: If multiple applications are saving audit logs into a single database, set this property to your application name, so you can distinguish the logs of different applications. If you don't set, it will set from the IApplicationInfoAccessor.ApplicationName value, which is the entry assembly name by default.
  • IgnoredTypes: A list of Types to be ignored for audit logging. If this is an entity type, changes for this type of entities will not be saved. This list is also used while serializing the action parameters.
  • EntityHistorySelectors: A list of selectors those are used to determine if an entity type is selected for saving the entity change. See the section below for details.
  • SaveEntityHistoryWhenNavigationChanges (default: true): If you set to true, it will save entity changes to audit log when any navigation property changes.
  • Contributors: A list of AuditLogContributor implementations. A contributor is a way of extending the audit log system. See the "Audit Log Contributors" section below.
  • AlwaysLogSelectors: A list of selectors to save the audit logs for the matched criteria.

Entity History Selectors

Saving all changes of all your entities would require a lot of database space. For this reason, audit log system doesn't save any change for the entities unless you explicitly configure it.

Configure<AbpAuditingOptions>(options =>
{
    options.EntityHistorySelectors.AddAllEntities();
});

options.EntityHistorySelectors actually a list of type predicate. You can write a lambda expression to define your filter.

The example selector below does the same of the AddAllEntities() extension method defined above:

Configure<AbpAuditingOptions>(options =>
{
    options.EntityHistorySelectors.Add(
        new NamedTypeSelector(
            "MySelectorName",
            type =>
            {
                if (typeof(IEntity).IsAssignableFrom(type))
                {
                    return true;
                }
                else
                {
                    return false;
                }
            }
        )
    );
});

The condition typeof(IEntity).IsAssignableFrom(type) will be true for any class implements the IEntity interface (this is technically all the entities in your application). You can conditionally check and return true or false based on your preference.

options.EntityHistorySelectors is a flexible and dynamic way of selecting the entities for audit logging. Another way is to use the Audited and DisableAuditing attributes per entity.

AbpAspNetCoreAuditingOptions

AbpAspNetCoreAuditingOptions is the options object to configure audit logging in the ASP.NET Core layer. You can configure it in the ConfigureServices method of your module:

Configure<AbpAspNetCoreAuditingOptions>(options =>
{
    options.IgnoredUrls.Add("/products");
});

IgnoredUrls is the only option. It is a list of ignored URLs prefixes. In the preceding example, all URLs starting with /products will be ignored for audit logging.

AbpAspNetCoreAuditingUrlOptions

AbpAspNetCoreAuditingUrlOptions is the options object to configure audit logging in the ASP.NET Core layer. You can configure it in the ConfigureServices method of your module:

Configure<AbpAspNetCoreAuditingUrlOptions>(options =>
{
    options.IncludeQuery = true;
});

Here, a list of the options you can configure:

  • IncludeSchema (default: false): If you set to true, it will include the schema in the URL.
  • IncludeHost (default: false): If you set to true, it will include the host in the URL.
  • IncludeQuery (default: false): If you set to true, it will include the query string in the URL.