Audit Trail and Event Monitoring: Who Did What and When

1. The Architecture of Salesforce Auditing and Logging Systems

In high-security enterprise environments, monitoring system state and user activity is a critical governance pillar. Understanding "who did what and when" is not merely an operational convenience; it is a foundational requirement for regulatory compliance, threat response, and forensic analysis. When security incidents occur, the speed and accuracy of the investigation depend entirely on the quality of available system logs. Salesforce provides a robust, multi-layered auditing and logging architecture designed to track both structural metadata changes and transactional data access. However, architects must master the boundaries and capabilities of each component to design an effective security posture.

The Salesforce auditing ecosystem is divided into three distinct operational layers: metadata auditing, transactional user logging, and historical field tracking. Metadata auditing tracks modifications to the system's configuration (such as profile adjustments, permission set assignments, code deployments, and password policy updates). Transactional user logging captures user interactions with actual record data (such as querying lists, running reports, exporting files, and executing API calls). Historical field tracking captures values changed within individual records over time (such as changes to a contact's credit limit or an opportunity's stage). Each of these layers utilizes different technology stacks and enforces distinct data retention periods:

• Setup Audit Trail: Tracks configuration and administrative changes. Retains history for 180 days in the UI.
• Event Monitoring: Captures transactional activities. Provides hourly and daily log files (retained for 30 days dynamically, or up to 1 year via Shield).
• Field History Tracking: Tracks record-level field modifications. Standard tracking retains logs for 18 months, whereas Shield Field Audit Trail extends retention to 10 years.

To establish comprehensive visibility, architects must integrate these disjointed systems into a single corporate auditing strategy. Relying solely on default settings leaves significant gaps, as standard data retention limits can result in critical logs being purged before a security incident is identified.

2. Monitoring Metadata Configurations with Setup Audit Trail

The first line of defence in system auditing is the Setup Audit Trail. This utility captures structural, administrative, and configuration modifications made by developers, consultants, and system administrators. Because administrative access grants broad power to alter security settings, bypass validation rules, or create new access points, monitoring these changes is essential to prevent internal threats and configuration drift.

The Setup Audit Trail tracks an extensive array of actions, including when a user updates password policies, modifies sharing settings, installs a managed package, activates a flows, or modifies profile permissions. One of its most valuable aspects is that it tracks changes made via both the user interface and metadata deployment APIs. While Salesforce displays the last 20 administrative changes directly on the Setup page, administrators can download the previous 180 days of history in CSV format. However, for large enterprise organisations, relying on manual CSV downloads is an operational risk. Changes can be overwritten or missed, and 180 days is often too short a window for annual security audits.

To secure metadata tracking, architects should automate the extraction of Setup Audit Trail records. Salesforce exposes these logs programmatically via the SetupAuditTrail standard object. Security teams can execute periodic scheduled jobs to extract these records and archive them in an external data lake or compliance repository. The following SOQL query represents a simple, programmatic way to query all administrative actions executed by system administrators in the last 7 days, filtering by critical sections like security and profile changes:

SELECT Id, Action, Section, CreatedBy.Name, CreatedBy.Username, CreatedDate, Display 
FROM SetupAuditTrail 
WHERE CreatedDate = LAST_N_DAYS:7 AND (Section = 'security' OR Section = 'profiles' OR Section = 'users') 
ORDER BY CreatedDate DESC

By automating the retrieval of these records and feeding them into corporate governance pipelines, organisations can establish permanent compliance archives, ensuring that administrative history is preserved indefinitely and is easily searchable for historical forensics.

When designing an automated metadata monitoring tool, architects must leverage the full schema of the SetupAuditTrail object. The object contains several critical fields, including DelegateUser (the user executing the change on behalf of another user, commonly seen in support scenarios), Action (the specific system action, such as profile editing or permission assignment), Section (the configuration category), and Display (the descriptive text of the change). Programmatically parsing the Display field is essential because it contains granular details, such as the exact permission that was enabled or disabled (e.g., "Enabled Customize Application on Profile System Administrator"). By parsing this string in Apex, organisations can build a custom security dashboard that highlights high-risk modifications, such as the relaxation of session timeout policies or the activation of unauthorised integrations, providing an immediate visual breakdown of administrative activity.

3. Real-Time Event Monitoring and User Activity Auditing

While the Setup Audit Trail captures administrative metadata changes, it does not record user access to actual customer records. If a disgruntled employee exports thousands of client accounts or an API integration queries sensitive credit card data, the Setup Audit Trail will remain blank. To detect and track transactional user activities, organisations must deploy Salesforce Event Monitoring (part of Salesforce Shield).

Event Monitoring provides granular insight into the daily operations of the Salesforce platform. It captures over 50 unique event types, logging activities such as login attempts, API requests, report runs, dashboard executions, file downloads, search queries, and even individual Visualforce or LWC page loads. These events are compiled into Event Log Files, which are generated hourly or daily and stored as raw log data. To analyze these logs, architects typically ingest them into visualization tools (like CRM Analytics) or stream them into external SIEM engines. The most critical event types for data protection and compliance auditing include the following:

• ReportExportEvent / ReportEvent: Captures when a user runs, views, or exports a report, logging the specific report ID, the number of records retrieved, and whether the data was downloaded as a CSV or Excel file. This is the primary indicator of bulk data extraction.
• ApiEvent: Logs all inbound API queries executed via REST, SOAP, or Bulk API, including the query string, source IP address, execution time, and client application details.
• LoginEvent: Tracks every login transaction in detail, logging the authentication method (e.g., SSO, username/password), source IP address, device properties, and the TLS version utilised by the client.
• UriEvent: Records when users access specific records via the browser UI, enabling detailed tracking of "read" operations on sensitive custom records.

By actively analyzing these events, security teams can transition from a reactive logging posture to a proactive threat detection environment, establishing clear baselines for normal user behavior and immediately identifying spikes in data extraction or API usage.

The processing of Event Log Files requires a deep understanding of their schema and performance impact. For example, the RestApiEvent log contains precise metrics such as RUN_TIME (the total duration of the API transaction in milliseconds), CPU_TIME (the execution time spent in the CPU), URI (the exact REST endpoint called), and RECORD_ID (the specific record queried). By parsing these CSV fields, security tools can map out a record-level audit trail, showing exactly which user retrieved which record and how much system resource was consumed. Crucially, because Event Monitoring runs as an asynchronous, near-real-time logging pipeline, it incurs zero performance overhead on active user transactions. Unlike traditional synchronous database logging, which blocks threads and slows down transactions, Event Monitoring streams logs in the background, allowing organisations to capture millions of transactions per day without degrading platform response times.

4. Building Proactive Real-Time Transaction Security Policies

Standard Event Monitoring is historical; it records activity after it has occurred. While invaluable for forensics, historical logging cannot stop a security breach in progress. To prevent data leakage and enforce strict compliance rules in real-time, architects must configure Real-Time Transaction Security Policies. This feature (part of Salesforce Shield) allows organisations to intercept user actions as they occur and apply immediate security mitigations, such as blocking the transaction, requiring Multi-Factor Authentication, or alerting security administrators.

Transaction Security Policies are built using the Event Condition Builder (declarative) or programmatically via custom Apex classes that implement the TxnSecurity.EventCondition interface. When a monitored action occurs (such as a user exporting a report, logging in from an unusual device, or executing a high-volume API query), Salesforce evaluates the policy. If the condition is met, Salesforce triggers the defined action. The following Apex class demonstrates a robust transaction security policy that evaluates report exports. If a user attempts to export a report containing more than 2,000 rows, the policy blocks the export immediately and triggers a high-priority system alert:

global class BlockMassiveReportExportPolicy implements TxnSecurity.EventCondition {
    public boolean evaluate(SObject event) {
        // Evaluate the event type, ensuring it is a ReportEvent
        if (event instanceof ReportEvent) {
            ReportEvent reportEvent = (ReportEvent) event;
            
            // Check if the operation is a report export
            if ('ReportExported'.equals(reportEvent.Operation)) {
                // If the number of rows exported exceeds 2000, block the transaction
                if (reportEvent.RowsProcessed > 2000) {
                    System.debug('Blocking massive report export by User ID: ' + reportEvent.UserId);
                    return true; // True indicates the policy condition has been met (Trigger action: Block)
                }
            }
        }
        return false; // Policy not triggered, allow the transaction to proceed
    }
}

This programmatic control allows architects to establish dynamic perimeters. For instance, you can construct a policy that permits standard account view operations but blocks any bulk API query that accesses more than 10,000 lead records, or forces the user to complete an MFA challenge if they attempt to export a client list outside corporate working hours. This dramatically reduces the risk of malicious internal exfiltration and external account compromise.

5. Field Audit Trail Governance and Enterprise SIEM Integrations

The final layer of the auditing ecosystem is record-level field tracking. Standard Salesforce Field History Tracking is highly restricted: it only permits tracking up to 20 fields per standard or custom object, and the historical records are deleted after 18 months. For regulated industries (such as healthcare, government, or finance), retaining audit logs for only 18 months is a major compliance violation. These sectors require permanent historical records of data changes, often lasting seven to ten years.

To meet these requirements, architects must deploy Shield Field Audit Trail. This utility increases the field tracking limit from 20 fields to 60 fields per object and allows organisations to define custom history retention policies using the Metadata API. With Field Audit Trail, historical logs are stored in a dedicated, high-performance big data storage container, preserving records for up to 10 years. Administrators define retention rules in XML configuration files, establishing when data should be archived and when it should be permanently deleted from the active tables.

In addition to long-term storage, enterprise governance requires consolidating Salesforce security logs with external Security Information and Event Management (SIEM) systems, such as Splunk, Microsoft Sentinel, or Datadog. Having security logs isolated inside Salesforce prevents a holistic view of corporate security. Security analysts must be able to correlate a suspicious Salesforce login with a simultaneous corporate VPN connection from a different geographic location. The following diagram visualizes the architecture of streaming Salesforce Event Log Files into an external enterprise SIEM platform:

+-----------------------------------------------------------------+
|                      Salesforce Platform                         |
|                                                                 |
| +------------------+   +------------------+   +---------------+ |
| | SetupAuditTrail  |   | Event Monitoring |   |  Field Audit  | |
| | (Metadata Logs)  |   | (Hourly/Daily)   |   | (10-Yr BigData)| |
| +--------+---------+   +--------+---------+   +-------+-------+ |
+----------|----------------------|---------------------|---------+
           |                      |                     |
           +                      +                     +
     +--------------------------------------------------------+
     |                  Salesforce REST / Pub/Sub APIs        |
     |                     (Secure Ingestion Channel)         |
     +----------------------------+---------------------------+
                                  |
                                  v
     +--------------------------------------------------------+
     |               Enterprise SIEM (e.g., Splunk)           |
     |  - Centralized Correlation   - Real-time Alerting      |
     |  - Forensic Analysis         - Dashboard Visualization |
     +--------------------------------------------------------+

To execute this integration, architects configure secure API connectors that periodically pull the EventLogFile data via the REST API or stream real-time events using the Pub/Sub API. Once ingested into the enterprise SIEM, Salesforce events are parsed, correlated, and visualised on security operations dashboards, ensuring that Salesforce is fully integrated into the corporate threat detection ecosystem.