Auditing in SharePoint 2010 can be enabled at the site collection level and may track content changes for different object types, that you can later filter through audit log reports. This article only briefly shows where and how you interactively enable auditing and what kind of audit log reports you may see for a SPSite site collection. The focus will be on the audit server classes, because everything is recorded and exposed as audit items through the object model. Audit log trimming and audit reports through programming will be also discussed.
Main Audit Classes
Few types expose an Audit property, which returns an SPAudit store object as entry point for the SPAuditEntry audit items collection for that instance. Only those types can have audit entries. Each audit entry returns, through the ItemType property, a SPAuditItemType enumeration value, which relates to the audited type, as it follows:
- SPAuditItemType.Site – for SPSite site collections
- SPAuditItemType.Web – for SPWeb web sites
- SPAuditItemType.List – for SPList lists
- SPAuditItemType.ListItem and SPAuditItemType.Document – for SPListItem list items, including library documents
- SPAuditItemType.Folder – for SPFolder folders
SPAudit.AuditFlags and SPAudit.EffectiveAuditMask return SPAuditMaskType enumeration values which tells what kind of actions and events are being audited for a particular object. From the combination of the audited object and the kind of recorded action/event results the SPAuditEventType enumeration, exposed by the SPAuditEntry.Event property. Go now to Site Actions/Site Settings/Site Collection Administration/Site Collection Audit Settings and find the mapping between these enumeration values and the events to audit that you can interactively configure (for Documents and Items, Lists, Libraries, and Sites) in that screen (none selected by default):
- Opening or downloading documents, viewing items in lists, or viewing item properties
- Editing items
- Checking out or checking in items
- Moving or copying items to another location in the site
- Deleting or restoring items
- Editing content types and columns
- Searching site content
- Editing users and permissions
SPAuditEventSource enumeration, exposed through the SPAuditEntry.EventSource property, specifies whether an audited event occurred programmatically (ObjectModel) or as a result of user action through the SharePoint Foundation UI (SharePoint).
SPAuditLocationType enumeration, exposed through the SPAuditEntry.LocationType property, specifies the actual location of a document in a SharePoint document library: a location on the server (Url) or on the client (ClientLocation).
Structure of Audit Classes
Let’s expand the SPAudit and SPAuditEntry classes and hide the properties we already talked about. SPAudit.WriteAuditEvent method comes in different flavors (as static or instance method, or with the WriteAuditEventUnlimitedData variation). Each SPAuditEntry is identified by a ItemId GUID and several other properties:
While the collection of SPAuditEntry items may expose a large number of items, iterating through the whole collection may have performance issues. With SPAuditQuery you may limit the range of selected items and improve your search performance.
Audit Log Trimming
Go to Site Actions/Site Settings/Site Collection Administration/Site Collection Audit Settings and look at the top Audit Log Trimming section. Here is where you can interactively specify whether the audit log for the site should be automatically trimmed and optionally store all of the current audit data in a document library. The three audit configuration options have related classes and properties in the server object model of SharePoint 2010:
- Yes/No to automatically trim the audit log for the site (default No) – related to the SPSite.TrimAuditLog boolean property, to specify whether to remove excess from the audit log periodically.
- Number of days of audit log data to retain – related to the SPSite.AuditLogTrimmingRetention property.
- Location to store audit reports before trimming the audit log – related to the AuditLogTrimmingReportCallout.SetAuditReportStorageLocation static method.
AuditLogTrimmingReportCallout class can be found in the Microsoft.Office.RecordsManagement.Reporting namespace of the Microsoft.Office.Policy assembly. The class implements the IAuditLogTrimmingCallout interface to capture audit log reports before trimming the site’s audit log and after the site’s audit log is trimmed. In SPSite.AuditLogTrimmingCallout you can also specify the class name of the object that performs audit log trimming, that implements the IAuditLogTrimmingCallout interface. IAuditLogTrimmingCallout has two methods: AuditLogTrimming and AuditLogTrimmed, called before and after the audit log for the given site is trimmed.
Audit Reports
The Microsoft.Office.RecordsManagement.Reporting namespace also contains an AuditReport class:
To generate (and save at a custom location within the site collection) Microsoft Excel audit reports for a site collection, go to Site Actions/Site Settings/Site Collection Administration/Audit Log Reports. The following report types (by category) are available:
Content Activity Reports
- Content modifications - events that modified content in site.
- Content type and list modifications - events that modified content types/lists in site.
- Content viewing - events where a user viewed content in site.
- Deletion - events that caused content in this site to be deleted/restored from Recycle Bin.
Custom Reports
- Run a custom report - manually specify the filters for your Audit Report.
Information Management Policy Reports
- Expiration and Disposition - events for expiration/disposition of content in site.
- Policy modifications - events related to the creation/use of IM policies on content in site.
Security And Site Settings Reports
- Auditing settings - events that change the auditing settings.
- Security settings - events that change the security configuration.