diff --git a/server/channels/app/audit.go b/server/channels/app/audit.go index 4bcd96a9899..2b8a6f9e732 100644 --- a/server/channels/app/audit.go +++ b/server/channels/app/audit.go @@ -23,6 +23,14 @@ import ( "github.com/mattermost/mattermost/server/v8/config" ) +// Audit level aliases for convenient access within the app package. +// These map directly to the audit levels defined in mlog. +// +// See [github.com/mattermost/mattermost/server/public/shared/mlog.LvlAuditAPI], +// [github.com/mattermost/mattermost/server/public/shared/mlog.LvlAuditContent], +// [github.com/mattermost/mattermost/server/public/shared/mlog.LvlAuditPerms], +// [github.com/mattermost/mattermost/server/public/shared/mlog.LvlAuditCLI] +// for detailed documentation on when to use each level. var ( LevelAPI = mlog.LvlAuditAPI LevelContent = mlog.LvlAuditContent diff --git a/server/public/shared/mlog/levels.go b/server/public/shared/mlog/levels.go index 3004ea0df39..906109f52f3 100644 --- a/server/public/shared/mlog/levels.go +++ b/server/public/shared/mlog/levels.go @@ -26,11 +26,33 @@ var ( // Register custom (discrete) levels here. // !!!!! Custom ID's must be between 20 and 32,768 !!!!!! var ( - // used by the audit system - LvlAuditAPI = Level{ID: 100, Name: "audit-api"} + // Audit system levels. + // + // LvlAuditAPI is used for auditing REST API endpoint access. This is the most commonly used + // audit level and should be applied whenever a REST API endpoint is accessed. It provides + // a record of API usage patterns and access. + // + // Example usage: Logging when a user accesses the /api/v4/posts endpoint. + LvlAuditAPI = Level{ID: 100, Name: "audit-api"} + + // LvlAuditContent is used for auditing content-generating operations such as creating posts, + // adding reactions, or other actions that create new content in the system. Note that this + // level can generate a large volume of logs and is typically disabled by default in production + // environments. + // + // Example usage: Logging when a user creates a new post or adds a reaction. LvlAuditContent = Level{ID: 101, Name: "audit-content"} - LvlAuditPerms = Level{ID: 102, Name: "audit-permissions"} - LvlAuditCLI = Level{ID: 103, Name: "audit-cli"} + + // LvlAuditPerms is used for auditing permissions checks. This level is automatically applied + // when permission-related errors occur, helping to track authorization failures and access + // control issues. + // + // Example usage: Logging when a user attempts to access a resource they don't have permission for. + LvlAuditPerms = Level{ID: 102, Name: "audit-permissions"} + + // LvlAuditCLI is intended for auditing command-line interface operations. This level was + // originally designed for the legacy CLI. It's mostly unused now. + LvlAuditCLI = Level{ID: 103, Name: "audit-cli"} // used by Remote Cluster Service LvlRemoteClusterServiceDebug = Level{ID: 130, Name: "RemoteClusterServiceDebug"}