Debug Log
A debug log is the time-stamped trace of everything that happened during a Salesforce transaction: Apex execution, SOQL queries, DML operations, validation rules, workflow actions, callouts, and the governor-limit running totals.
Definition
A debug log is the time-stamped trace of everything that happened during a Salesforce transaction: Apex execution, SOQL queries, DML operations, validation rules, workflow actions, callouts, and the governor-limit running totals. The platform captures one when a Trace Flag is active for the running user or for the entity that triggered the transaction. Debug logs are the primary diagnostic surface in Salesforce, used by developers and admins to figure out why a process behaved the way it did.
A log is a structured text file divided into event lines, each carrying a category (APEX_CODE, DB, SYSTEM, and so on) and a level (DEBUG, FINE, FINEST, and others). You configure which categories and levels are captured through Debug Levels and which users or transactions produce logs through Trace Flags. Logs live in the ApexLog table for up to 7 days and are accessible through the Developer Console, Setup, or the Tooling API.
Reading and configuring Salesforce debug logs
Trace Flags: who, what, and how long to log
A Trace Flag binds a Debug Level to a target (a User, an Apex Class, a Flow, or an Apex Trigger) for a window of time. Without a Trace Flag, the system captures only system-level entries on errors. User Trace Flags are the most common: an admin or developer turns one on for their own user, runs the transaction, and reads the resulting log. Apex Class Trace Flags override the user's debug level for specific classes, which is how you turn FINEST verbosity on a single class without flooding the rest of the log.
Debug Levels and category granularity
A Debug Level is a named set of log levels per category. Out of the box, you get SFDC_DevConsole and various ApexDebugLevel records. Each category (APEX_CODE, APEX_PROFILING, CALLOUT, DB, NBA, SYSTEM, VALIDATION, VISUALFORCE, WAVE, WORKFLOW) gets a level (NONE through FINEST), and the union of those settings drives what the log contains. FINE on DB plus DEBUG on APEX_CODE is a good default for most debugging; FINEST on everything fills the log quickly.
What a log entry actually looks like
Each line in a debug log is pipe-delimited: timestamp, event, identifier, and event-specific payload. SOQL_EXECUTE_BEGIN lines show the query and bind variables; SOQL_EXECUTE_END shows the row count and elapsed time. METHOD_ENTRY and METHOD_EXIT bracket Apex method calls. USER_DEBUG lines show your System.debug() output. CUMULATIVE_LIMIT_USAGE at the end of the log summarizes governor consumption for the whole transaction.
The 50 MB per-log and 250 MB rolling cap
Each log can grow to 50 MB. When you hit the cap, the platform truncates from the top, replacing earlier entries with SKIPPED_BYTES markers. This is why a long-running batch with FINEST on APEX_CODE often loses the start of the transaction. The org also has a 250 MB total cap across logs in a 15-minute rolling window. Above that, new logs are suppressed until older ones expire.
Storage and retention
Debug logs are stored as ApexLog records, queryable via SOQL (SELECT Id, Operation, Status, DurationMilliseconds, LogLength FROM ApexLog WHERE LogUserId = :userId). They live for 7 days and then get deleted. Logs are downloadable as text from the Developer Console, the Setup UI, or the Tooling API. A common pattern is to query ApexLog for a recent timeframe, identify the failing log by Operation and Status, and download just that one.
Cumulative Limits and where to read them
At the bottom of every log, the CUMULATIVE_LIMIT_USAGE block shows how much of each governor limit the transaction consumed: SOQL queries, DML rows, CPU time, heap, future calls, callouts, and so on. This is your fastest path to spotting a soon-to-fail transaction: if SOQL queries used reads 95 out of 100, you have a query loop. Always scan the cumulative limits before assuming a transaction is healthy.
Heap dumps versus debug logs
Heap dumps are a separate diagnostic surface, captured when a Checkpoint is hit during execution. The dump records every variable's value at that instant, where a debug log records the sequence of events. Use a debug log to see what happened; use a heap dump to see what was in memory when something happened. The Apex Replay Debugger in VS Code stitches the two together for stepwise debugging.
How to capture a debug log for a specific user or transaction
Debug logs require a Trace Flag and a Debug Level. Once both are in place, any transaction the targeted user runs (or any transaction that touches the targeted entity) produces a log. The fastest path is through the Developer Console; production-grade debugging uses the Setup UI or the Tooling API.
- Open Setup, then Debug Logs
Setup, then Debug Logs. The page lists active Trace Flags and recent logs. Click New to add a Trace Flag.
- Pick the target user
For most debugging, set the Tracked Entity Type to User and the Tracked Entity Name to your own user. For multi-user troubleshooting, target the user who is hitting the bug.
- Pick or create a Debug Level
Choose an existing Debug Level (SFDC_DevConsole is a good default) or create a new one with the categories and levels you want. APEX_CODE: FINE and DB: FINEST are common starting points; raise individual categories as needed.
- Set the start and expiration time
Trace Flags expire automatically. Default duration is 30 minutes; max is 24 hours. Pick a window that covers your testing without burning storage.
- Reproduce the transaction
Run the failing process: hit a button, save a record, run an Apex job. Each transaction the user runs in the window produces a new log entry.
- Open and analyze the log
From the Debug Logs page or the Developer Console (Debug, then View Log), open the log. Search for USER_DEBUG, EXCEPTION_THROWN, or CUMULATIVE_LIMIT_USAGE to jump to the interesting parts. Download the file if you need to grep it offline.
Logs every transaction the user runs. Most common starting point for general debugging.
Logs only transactions that execute the named Apex class. Useful for narrowing high-volume logs to one component.
Logs only transactions that fire the named trigger.
Controls Apex execution detail. FINE shows method entry/exit; FINEST adds variable values and SOQL bind details.
Controls SOQL and DML detail. FINEST shows query plans and row counts.
- Logs are capped at 50 MB each. A FINEST log on a batch with 200 records can hit the cap and lose the start of the transaction. Lower the level or narrow the trace flag to a specific class.
- User Trace Flags expire automatically. If you opened a 30-minute window and the failing transaction runs at minute 31, you get no log. Check the expiration before reproducing.
- The 250 MB rolling org-wide cap is shared across all users. A noisy demo org with multiple developers logging at FINEST can suppress new logs until older ones age out.
- Logs are stored for 7 days. Anything older is gone. Download or query into Apex what you need to preserve before that window closes.
Trust & references
Straight from the source - Salesforce's reference material on Debug Log.
- Debug Log Levels and FiltersSalesforce Help
- View Debug LogsSalesforce Help
- Apex Debug LogsSalesforce 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 does a Debug Log capture?
Q2. Where can you view debug logs?
Q3. Why is reading debug logs a core developer skill?
Discussion
Loading discussion…