View Setup Audit Trail
View Setup Audit Trail is the Salesforce feature that records administrative changes made through the Setup UI and the Metadata API, and exposes them in a chronological log.
Definition
View Setup Audit Trail is the Salesforce feature that records administrative changes made through the Setup UI and the Metadata API, and exposes them in a chronological log. The log captures who made the change, what was changed, when it happened, and the source IP address of the user. It covers configuration changes (creating a custom field, modifying a permission set, deploying a managed package) but not record-level data changes (which are handled by Field History Tracking, Field Audit Trail, and Event Monitoring).
The Setup Audit Trail is the lightest-weight compliance and forensics tool in the Salesforce admin toolkit. It retains the last 180 days of changes by default, with longer retention available through the paid Field Audit Trail add-on. It is accessible from Setup, Security, View Setup Audit Trail, or downloadable as CSV for offline analysis. For any org subject to SOC 2, ISO 27001, HIPAA, or similar compliance regimes, the Setup Audit Trail is the first stop when an auditor asks who changed a profile, who deployed metadata last Tuesday, or who turned off password expiration policies in 2024.
How the Setup Audit Trail actually records configuration changes
What Setup Audit Trail captures (and what it does not)
Setup Audit Trail logs configuration changes: new custom fields, permission set assignments, profile changes, user creation, password resets, login IP range edits, Apex class deployments, Flow activations, managed package installs. It does not log record-level changes to standard or custom data (those need Field History Tracking) and does not log read access or query history (Event Monitoring does that). The boundary between configuration and data is the right mental model. If a change is administrative in nature, Setup Audit Trail probably catches it. If it touches a customer record's field value, it does not.
Retention: 180 days standard, 10 years with Field Audit Trail
The default retention is 180 days. After that, older entries are purged from the in-app view. Salesforce keeps a copy in the platform's internal logs, but the customer cannot self-serve historical entries beyond 180 days. Customers who need longer retention buy the Field Audit Trail add-on, which extends Setup Audit Trail (and several other tracking products) to up to 10 years of retention. Compliance-heavy industries (financial services, healthcare, government) typically need the extension. The default is sufficient for most general business orgs.
The data shape: user, action, section, IP, time
Each Setup Audit Trail entry has six core fields. Date is the timestamp in the org's time zone. User is the Salesforce user who made the change. Action is the textual description of the change ("Created custom object Order_Item__c", "Activated Flow CaseEscalation"). Section is the category (Customize Accounts, Manage Users, Apex Classes). Display is a free-text detail field with the component name and ID. Source Namespace identifies whether the change came from a managed package install. Two more fields not always shown in the UI but available in the download: Login Source IP (the originating IP address) and User Type. Together these support most "who did this" forensics.
Downloading the audit trail as CSV
The Setup Audit Trail UI shows recent entries with filter and search. For deeper analysis, click Download Setup Audit Trail. The platform generates a CSV of the last 180 days. This is the canonical export for compliance audits and for feeding into SIEM platforms. Many security-conscious orgs schedule a monthly export and archive it externally, so when a 2-year-old compliance question arrives, the historical record is preserved beyond the 180-day in-app retention.
Metadata API and CI/CD impact
The audit trail captures changes made through the Metadata API as well as through the Setup UI. A CI pipeline deploying a managed package shows up in the trail with the deploying user, the deployment timestamp, and a Display field listing the components. This is how you trace a production incident back to a specific deployment: filter on the date range, filter on the user who ran the deployment, identify which components were touched. The same applies to Workbench deployments, Salesforce CLI deploys, and Workbench-style ad-hoc metadata changes.
Limitations: no record changes, no read access, no fine-grained queries
Setup Audit Trail has clear boundaries. It does not show what record data was viewed, queried, or exported. For that, you need Event Monitoring, which is a paid add-on with much finer granularity (per-API call, per-report-export, per-Apex-execution event types). The trail also does not show pre-change vs post-change values for configuration changes. It tells you Flow X was activated, not what the Flow looked like before vs after. For pre/post tracking of configuration metadata, you need Change Sets, source control, or a third-party tool like Salto or Gearset.
Common forensics scenarios
Three common questions the Setup Audit Trail answers. First, "Who deployed metadata to production on date X?" Filter by date, scan for Apex Class, Visualforce, Flow, Permission Set, or Metadata API entries. Second, "Who changed the IT user's permissions last quarter?" Filter on user IT_System_User, look for Manage Users section entries. Third, "When did password policy get weakened?" Filter on Security Controls or Password Policies section. Each answer typically takes 5 minutes if the change is within 180 days, and is impossible without the audit trail or a SIEM-archived equivalent.
Using the Setup Audit Trail for compliance and forensics
The Setup Audit Trail does not need to be turned on. It records by default. The configuration work is on the consumption side: accessing it, filtering it, downloading it, and archiving it for long-term retention.
- Open Setup Audit Trail
Setup, in the Quick Find type Setup Audit Trail, click the link under Security. The default view shows the most recent 20 entries.
- Filter by date, user, or section
Above the entries list, filter by date range, by user, or by section (Apex Classes, Manage Users, Security Controls). Filters combine with AND logic. Use them to narrow large logs.
- Search the Display field
For specific changes (a particular custom field, a named Apex class), use the search box on the Display field. Pattern matching is substring, not regex, but adequate for most queries.
- Download the full 180-day log
Click Download Setup Audit Trail. The platform generates a CSV with all entries from the past 180 days. Save the file with a date stamp. The CSV is the canonical export for compliance audits.
- Schedule monthly external archive
For longer retention than 180 days, schedule a monthly extract through a CI job or a scheduled Apex export. Push the file to an external archive (S3, on-prem SIEM). This preserves the audit history beyond Salesforce's default retention.
- Buy Field Audit Trail for compliance-heavy orgs
For 10-year retention without manual archiving, purchase the Field Audit Trail add-on. It extends Setup Audit Trail (and Field History) to up to 10 years and adds queryable history tables.
Top-of-page filter that narrows entries to a specific window. Useful for compliance "what changed in Q3" questions.
Narrow to changes made by a specific user. Critical for forensic investigations.
Narrow to a category (Apex Classes, Manage Users, Security Controls). Each category has its own audit log filter.
Generates the past 180 days as a CSV. The download is the source of truth for offline analysis and external archival.
Paid extension that grows retention from 180 days to up to 10 years and adds queryable history tables for Setup, Field History, and Big Object archives.
- Setup Audit Trail retention is 180 days by default. Older entries are gone unless you exported them. Schedule monthly CSV archives if your compliance regime requires longer history.
- The trail does not show pre-change vs post-change values. It tells you a Flow was edited, not what changed inside the Flow. For pre/post comparisons, use source control or a change-tracking tool.
- Record-level data changes are not in the audit trail. Field History Tracking captures field-value changes on standard and custom objects, but it has its own retention and selection rules.
- Reads, queries, and exports of record data are not in the audit trail. Event Monitoring is the right tool for those, and it is a paid add-on with much finer granularity.
- Managed package install events appear in the trail with the package's namespace in the Source field. Use this to confirm which version of a package is installed at a given point in time.
Trust & references
Straight from the source - Salesforce's reference material on View Setup Audit Trail.
- View Setup Audit TrailSalesforce Help
- Field Audit TrailSalesforce Help
- SetupAuditTrail Object ReferenceSalesforce Developers
About the Author
Dipojjal Chakrabarti is a B2C Solution Architect with 29 Salesforce certifications and over 13 years in the Salesforce ecosystem. He runs salesforcedictionary.com to help admins, developers, architects, and cert/interview candidates sharpen their fundamentals. More about Dipojjal.
Test your knowledge
Q1. What is the primary benefit of View Setup Audit Trail for Salesforce administrators?
Q2. Why is understanding View Setup Audit Trail important for Salesforce admins?
Q3. Can a Salesforce admin configure View Setup Audit Trail without writing code?
Discussion
Loading discussion…