From 59c84dd22d88d52652ea7e5baca1d192e121d7c8 Mon Sep 17 00:00:00 2001 From: maliming Date: Fri, 17 Jul 2026 17:30:23 +0800 Subject: [PATCH] Improve Audit Logging documentation coverage --- .../framework/infrastructure/audit-logging.md | 2 + docs/en/modules/audit-logging-pro.md | 131 +++++++++++++++++- docs/en/modules/audit-logging.md | 29 +++- 3 files changed, 155 insertions(+), 7 deletions(-) diff --git a/docs/en/framework/infrastructure/audit-logging.md b/docs/en/framework/infrastructure/audit-logging.md index 9c748c8732..c5885f0d01 100644 --- a/docs/en/framework/infrastructure/audit-logging.md +++ b/docs/en/framework/infrastructure/audit-logging.md @@ -311,6 +311,8 @@ An **audit log object** is created for each **web request** by default. An audit * **Exception**: An audit log object may contain zero or more exception. In this way, you can get a report of the failed requests. * **Comment**: An arbitrary string value to add custom messages to the audit log entry. An audit log object may contain zero or more comments. +> When the [Audit Logging Module](../../modules/audit-logging.md) persists exceptions, it uses `AbpExceptionHandlingOptions` to convert them. `SendExceptionsDetailsToClients`, `SendStackTraceToClients` and `SendExceptionDataToClientTypes` therefore also control the exception details stored in audit logs, not only the details sent to clients. Review these options when audit logs may contain sensitive information. See the [Exception Handling](../fundamentals/exception-handling.md#abpexceptionhandlingoptions) document for configuration details. + In addition to the standard properties explained above, `AuditLogInfo`, `AuditLogActionInfo` and `EntityChangeInfo` objects implement the `IHasExtraProperties` interface, so you can add custom properties to these objects. ## Audit Log Contributors diff --git a/docs/en/modules/audit-logging-pro.md b/docs/en/modules/audit-logging-pro.md index 851787d390..1e7ab562dc 100644 --- a/docs/en/modules/audit-logging-pro.md +++ b/docs/en/modules/audit-logging-pro.md @@ -25,7 +25,7 @@ See [the module description page](https://abp.io/modules/Volo.AuditLogging.Ui) f ## How to install -Identity is pre-installed in [the startup templates](../solution-templates). So, no need to manually install it. +Audit Logging is pre-installed in [the startup templates](../solution-templates). So, no need to manually install it. ### Packages @@ -41,7 +41,7 @@ Audit logs module adds the following items to the "Main" menu, under the "Admini * **Audit Logs**: List, view and filter audit logs and entity changes. -`IAbpAuditLoggingMainMenuNames` class has the constants for the menu item names. +`AbpAuditLoggingMainMenuNames` class has the constants for the menu item names. ### Pages @@ -67,7 +67,7 @@ You can view details of an audit log by clicking the magnifier icon on each audi ##### Export to Excel -You can export audit logs to Excel by clicking the "Export to Excel" button in the toolbar. If the result set is small (less than a configurable threshold), the file will be generated and downloaded immediately. For larger result sets, the export will be processed as a background job and you'll receive an email with a download link once the export is completed. +You can export audit logs to Excel by clicking the "Export to Excel" button in the toolbar. The file is generated and downloaded immediately when the result set contains 1,000 records or fewer. If the result set contains more than 1,000 records, the export is processed as a background job and you'll receive an email with a download link once the export is completed. #### Entity Changes @@ -97,7 +97,7 @@ You can view details of all changes of an entity by clicking the "Full Change Hi ##### Export to Excel -You can export entity changes to Excel by clicking the "Export to Excel" button in the toolbar. Similar to audit logs export, for large datasets the export will be processed as a background job and you'll receive an email notification once completed. +You can export entity changes to Excel by clicking the "Export to Excel" button in the toolbar. As with audit log exports, result sets with 1,000 records or fewer are downloaded immediately. Result sets with more than 1,000 records are processed as a background job, and you'll receive an email notification once the export is completed. #### Audit Log Settings @@ -113,6 +113,111 @@ To view the audit log settings, you need to enable the feature. For the host sid > If you don't enable the *Cleanup Service System Wide* from the host side under *Settings* -> *Audit logs* -> *Global*, it won't remove the expired audit logs, even if there are tenant specific settings. +## Reusable widgets + +The module provides **Error Rate** and **Average Execution Duration Per Day** widgets. The current user needs the `AuditLogging.AuditLogs` permission to load their data. + +### Angular + +Import the widget components from `@volo/abp.ng.audit-logging`, add them to your component imports and keep references when you need to refresh their date range: + +```ts +import { Component, ViewChild } from '@angular/core'; +import { + AverageExecutionDurationWidgetComponent, + ErrorRateWidgetComponent, +} from '@volo/abp.ng.audit-logging'; + +@Component({ + selector: 'app-audit-statistics', + templateUrl: './audit-statistics.component.html', + imports: [ + AverageExecutionDurationWidgetComponent, + ErrorRateWidgetComponent, + ], +}) +export class AuditStatisticsComponent { + @ViewChild('averageExecutionDurationWidget') + averageExecutionDurationWidget!: AverageExecutionDurationWidgetComponent; + + @ViewChild('errorRateWidget') + errorRateWidget!: ErrorRateWidgetComponent; + + refresh(startDate: string, endDate: string) { + this.averageExecutionDurationWidget.draw({ startDate, endDate }); + this.errorRateWidget.draw({ startDate, endDate }); + } +} +``` + +The `width` and `height` inputs are optional. Both default to `273` and `136`, respectively. + +```html + + + +``` + +### Blazor + +The Bootstrap and MudBlazor packages expose components with the same parameters and `RefreshAsync` method. The following example uses the Bootstrap Blazor package. For MudBlazor, use the corresponding `Volo.Abp.AuditLogging.Blazor.MudBlazor` namespaces. + +```razor +@using Volo.Abp.AuditLogging.Blazor.Pages.Shared.AverageExecutionDurationPerDayWidget +@using Volo.Abp.AuditLogging.Blazor.Pages.Shared.ErrorRateWidget + + + + + +@code { + private DateTime StartDate { get; set; } = DateTime.Today.AddMonths(-1); + private DateTime EndDate { get; set; } = DateTime.Today; + + private AuditLoggingAverageExecutionDurationPerDayWidgetComponent AverageExecutionDurationWidget { get; set; } = default!; + private AuditLoggingErrorRateWidgetComponent ErrorRateWidget { get; set; } = default!; + + private async Task RefreshAsync() + { + await AverageExecutionDurationWidget.RefreshAsync(); + await ErrorRateWidget.RefreshAsync(); + } +} +``` + +### MVC / Razor Pages + +Use `IWidgetManager` to check the widget permission before invoking its view component: + +```cshtml +@using Volo.Abp.AspNetCore.Mvc.UI.Widgets +@using Volo.Abp.AuditLogging.Web.Pages.Shared.Components.AverageExecutionDurationPerDayWidget +@using Volo.Abp.AuditLogging.Web.Pages.Shared.Components.ErrorRateWidget +@inject IWidgetManager WidgetManager + +@if (await WidgetManager.IsGrantedAsync(typeof(AuditLoggingErrorRateWidgetViewComponent))) +{ + @await Component.InvokeAsync(typeof(AuditLoggingErrorRateWidgetViewComponent)) +} + +@if (await WidgetManager.IsGrantedAsync(typeof(AuditLoggingAverageExecutionDurationPerDayWidgetViewComponent))) +{ + @await Component.InvokeAsync(typeof(AuditLoggingAverageExecutionDurationPerDayWidgetViewComponent)) +} +``` + ## Data seed This module doesn't seed any data. @@ -145,7 +250,7 @@ Configure(options => // The Hangfire Cron expression is different from the Quartz Cron expression, Please refer to the following links: // https://www.quartz-scheduler.net/documentation/quartz-3.x/tutorial/crontriggers.html#cron-expressions // https://docs.hangfire.io/en/latest/background-methods/performing-recurrent-tasks.html - options.ExcelFileCleanupOptions.CronExpression = "0 23 * * *"; // Quartz Cron expression is "0 0 23 * * ?" + options.CronExpression = "0 23 * * *"; // Quartz Cron expression is "0 0 23 * * ?" }); ``` @@ -237,16 +342,30 @@ See the [connection strings](../framework/fundamentals/connection-strings.md) do * AbpAuditLogActions * AbpEntityChanges * AbpEntityPropertyChanges +* **AbpAuditLogExcelFiles** #### MongoDB ##### Collections * **AbpAuditLogs** +* **AbpAuditLogExcelFiles** ### Permissions -See the `AbpAuditLoggingPermissions` class members for all permissions defined for this module. +The module defines the following feature and permission relationships: + +* `AuditLogging.Enable` is enabled by default. The `AuditLogging.AuditLogs` permission requires this feature, and the audit log application service also checks it. +* `AuditLogging.SettingManagement` is a child feature of `AuditLogging.Enable` and is disabled by default. The `AuditLogging.AuditLogs.SettingManagement` permission requires this feature. +* `AuditLogging.AuditLogs.Export` is a child permission of `AuditLogging.AuditLogs`. Audit log and entity change export operations require this permission. + +See the `AbpAuditLoggingPermissions` and `AbpAuditLoggingFeatures` class members for the complete definitions. + +#### Entity-specific change history permissions + +You can define a permission for the change history of a specific entity by using the `AuditLogging.ViewChangeHistory:{EntityTypeFullName}` naming convention. For example, the permission name for `Acme.BookStore.Books.Book` is `AuditLogging.ViewChangeHistory:Acme.BookStore.Books.Book`. + +When a matching permission is defined and granted, the user can view that entity's change history. If the entity-specific permission is not defined or is not granted, authorization falls back to `AuditLogging.AuditLogs`. Users who have the general audit log permission can therefore still view the entity history. ### Angular UI diff --git a/docs/en/modules/audit-logging.md b/docs/en/modules/audit-logging.md index 5cba52cf34..a3f99147db 100644 --- a/docs/en/modules/audit-logging.md +++ b/docs/en/modules/audit-logging.md @@ -29,12 +29,37 @@ The source code of this module can be accessed [here](https://github.com/abpfram - `EntityChange` (collection): Changed entities of audit log. - `AuditLogAction` (collection): Executed actions of audit log. +#### Extending the Entities + +The `AuditLog`, `AuditLogAction` and `EntityChange` entities support the [Module Entity Extensions](../framework/architecture/modularity/extending/module-entity-extensions.md) system. Configure them in the `Domain.Shared` project before the database model is created. The following example adds a property to `AuditLog`: + +````csharp +ObjectExtensionManager.Instance.Modules() + .ConfigureAuditLogging(auditLogging => + { + auditLogging.ConfigureAuditLog(auditLog => + { + auditLog.AddOrUpdateProperty("ExternalId"); + }); + }); +```` + +Use `ConfigureAuditLogAction` or `ConfigureEntityChange` in the same way to extend the other supported entities. + #### Repositories Following custom repositories are defined for this module: - `IAuditLogRepository` +#### Audit Log Conversion + +The module uses `IAuditLogInfoToAuditLogConverter` to convert the `AuditLogInfo` collected by the auditing system into the persisted `AuditLog` aggregate. You can inject this service when you need the same conversion in a custom persistence flow, or replace its default implementation using the [dependency injection system](../framework/fundamentals/dependency-injection.md#replace-a-service) to customize the mapping. + +#### Persistence Limits + +Before saving an audit log, the module truncates fields that have maximum lengths defined by `AuditLogConsts`, `AuditLogActionConsts`, `EntityChangeConsts` and `EntityPropertyChangeConsts`. Action parameters are handled differently: if `AuditLogAction.Parameters` exceeds `AuditLogActionConsts.MaxParametersLength` (2,000 by default), it is persisted as an empty string instead of being truncated. + ### Database providers #### Common @@ -55,13 +80,15 @@ This module uses `AbpAuditLogging` for the connection string name. If you don't - AbpAuditLogActions - AbpEntityChanges - AbpEntityPropertyChanges +- **AbpAuditLogExcelFiles** #### MongoDB ##### Collections - **AbpAuditLogs** +- **AbpAuditLogExcelFiles** ## See Also -* [Audit logging system](../framework/infrastructure/audit-logging.md) \ No newline at end of file +* [Audit logging system](../framework/infrastructure/audit-logging.md)