Describe how to approach debugging system issues and monitoring flows, processes, and asynchronous and batch jobs, etc.

After studying this topic, you should be able to:

  • Identify the features available for debugging system issues in Salesforce.
  • Describe the use of Debug Logs for debugging system issues including how to activate, configure and access them.
  • Explain how the Log Inspector can be used to inspect various types of operations.
  • Explain the use of checkpoints to debug Apex classes and triggers.

Table of Contents

  • Introduction
  • Debug Logs
  • Log Categories
  • Log Levels
  • Event Types
  • Debug Log Examples
  • Trace Flags
  • Log Inspector
  • Checkpoints
  • Exception Handling
  • Debug Flows & Processes
  • Debug Lightning Components
  • Monitor Flows, Processes, and Jobs

Introduction

  • Salesforce provides tools that can be used to inspect and debug system issues related to operations like automated workflow processes, database changes, execution of Apex code, etc
    • Debug Logs, Log Inspector, Checkpoint Inspector, and exception handling can all be used for debugging
    • Debug logs are used to track events that occur in an org
  • Overview
    • Debug Logs: can be generated by setting a user trace flag. Can be used to track system events like record database operations, system processes, and errors that occur when executing an Apex transaction or running unit tests
    • Log Inspector: can be used to inspect debug logs including database events, Apex processing, workflow, and validation logic. Logs tab in the Developer Console can be used to open debug logs in the Log Inspector, which shows the source of an operation, what triggered it, and what occurred next.
    • Checkpoints: up to five checkpoints can be set to debug Apex classes and triggers. Checkpoints tab in Developer Console can be used to investigate the objects in memory at a specific point of execution and see other objects with references to them.
    • Troubleshooting: error email can be analyzed to troubleshoot failed flow interviews and processes. Debug log can also be used for analysis
    • Monitoring: paused flow interviews, scheduled actions from processes, and asynchronous Apex jobs can be monitored in Salesforce
    • Exception Handling: try, catch and finally statements can be used to gracefully recover from exceptions in Apex. Exceptions can be generated using throw statements

Debug Logs

  • A debug log can be inspected to identify database operations, system processes, and errors
    • Debug Log Info: can contain info such as database changes, HTTP callouts, Apex errors, resources used by Apex, and automated workflow processes (workflow rules, assignment rules, approval processes, validation rules)
    • Generating Debug Logs: generated when there are active user-based trace flags, when running Apex tests and when executed code or API requests include debugging parameters or headers
    • Trace Flags: debug logs can be set up for specific users, classes and triggers
      • Set them up by navigating to debug logs in Setup
      • Trace flags consist of a debug level, start time, end time, and log type
      • Add or remove trace flags from the Developer Console by going to Debug > Change Log Levels
    • Trace Flag Considerations: Class and trigger trace flags do not cause debug logs to be generated or saved. They are created to override logging levels that are set by other debug levels such as ones defined by user trace flags.
    • Debug Log Details: each log consists of a header, execution units, code units, log lines, and other log data.
      • Header: consists of API version, log categories, and levels
      • Execution unit: everything that occurred in a transaction
      • Code unit: discrete unit of work, like a trigger or workflow invocation
      • Log line: contains a timestamp and an event identifier that indicate which code or rules were executed
      • Also contains cumulative resource usage and cumulative profiling info
    • Debug Levels: determines the amount of information contained in a debug log. can be configured by navigating to ‘Debug Levels’ in Setup or Debug > Change Log Levels in Developer Console. Include the following categories: None, Error, Warn, Info, Debug, Fine, Finer, Finest
    • Log Categories: each debug level consists of a log level for the following log categories: Database, Workflow, NBA, Validation, Callout, Apex Code, Profiling, Visualforce, and System
    • Event Types: indicate which events are logged. Consiste of two parts, timestamp and event identifier. Ex event types: USER_DEBUG, CALLOUT_RESPONSE, and VALIDATION_PASS
  • Debug Log Sections: include the following
    • Header: contains API version used, the log category, and level used to generate the log
    • Execution Unit: equivalent to a transaction and contain everything that occurred within the transaction. EXECUTION_STARTED and EXECUTION_FINISHED delimit an execution unit
    • Code Unit: discrete unit of work within a transaction, such as a trigger, webService method, or validation rule
    • Log Lines: included inside units of code and indicate which code or rules are being executed. Can also contain messages written to the debug log
    • Cumulative Resource Usage: logged at the end of many code units such as triggers, executeAnonymous and webService methods
    • Cumulative Profiling Info: logged at the end of a transaction for DML invocations and expensive queries
  • Debug Log: a debug log is a tool that allows developers to keep track of all actions that the Salesforce org instance is processing
    • Log Sources: generated when there is an active user trace flag, when Apex tests are run, and when executed code or API requests included debugging parameters or headers
    • Activate Logging: to activate debug logging for users, Apex classes and Apex triggers, trace flags and debug levels are configured in Setup or Developer Console
    • Log Details: debug logs contain information of database operations, system processes, and errors that occur when a transaction is executed or unit tests are run
    • Log Types: debug logs can contain information about database changes, HTTP callouts, Apex errors, resources used by Apex, and automated workflow processes (workflow rules, assignment rules, approval processes, validation rules)
    • Log Exclusion: debug log does not include information from actions triggered by time-based workflows
    • Manage Logs: debug logs may be viewed, downloaded and deleted from Setup
    • Log File Size: debug logs should not exceed 20 MB size. Older log lines are deleted to reduce size of larger logs
    • Log Storage Limit: an org cannot retain more than 1000 MB of debug logs

Log Categories

  • Following briefly describes the types of info logged by each log category:
    • Database: includes info about activities related to the database such as DML, SOQL, and SOSL calls
    • Workflow: includes info about workflow rules, flows, and processes
    • Visualforce: includes events generated from Visualforce such as the view state, etc
    • Apex Profiling: includes cumulative profiling info such as namespace limits, emails sent, etc
    • Validation: includes info about validation rules that fired and their results
    • Apex Code: includes info about Apex code such as trigger, method, queries, etc
    • System: includes info about executed system methods such as System.debug()
    • Callout: includes info about requests and responses from a web service
    • NBA: logs activities generated by Einstein Next Best Action and Strategy Builder

Log Levels

  • A log level is specified for each log category in a debug level
    • Salesforce user interface: can be configured in Setup by entering Debug Levels using the quick find
    • Log Level Override: debug levels can be overridden for an Apex class or trigger by using Apex class or trigger trace flags
    • Developer Console: debug levels can be configured in the Developer Console by navigating to Debug > Change Log Levels
    • Inherited Log Level: A class or trigger inherits log settings of its caller if no log level is defined for the specific class or trigger that is being called
  • Log levels are cumulative and range in verbosity, from low to high, from:
    • None, Error, Warn, Info, Debug, Fine, Finer, Finest

Event Types

  • An event type is a combination of log category and log level and specifies which events are logged
    • Event Details: consists of info such as line and character number where the event started, fields associated with the event, and duration of the event
    • Event Parts: consists of two parts: a timestamp and an event identifier
    • Event Examples: USER_DEBUG, CALLOUT_RESPONSE, VALIDATION_PASS

Debug Log Examples

  • This example shows a debug log that was generated after the execution of anonymous Apex code

  • An execution unit in a debug log represents a transaction. EXECUTION_STARTED represents the beginning of the execution unit.

  • A code unit in a debug log represents a discrete unit of work within a transaction. It is delimited by CODE_UNIT_STARTED and CODE_UNIT_FINISHED

  • Each log line contains a timestamp and an event identifier that indicate which code or rules have been executed

  • Cumulative profiling information is logged at the end of the transaction and shows information about usage of DML statements, SOQL queries, callouts, CPU time, etc

  • Following approach can be used to debug issues using debug logs:
    1. Set up debug level and user trace flag
    2. Add debug statements to code if required
    3. Execute the transaction as the traced user
    4. Identify the issue by analyzing the debug log
    5. If the issue is not found, use the rule of elimination

Trace Flags

  • Trace Flags are used to activate debug logs for specified entities in the org
    • Trace Flag Details: consists of a debug level, start time, end time, and log type
    • Trace Flag in Developer Console: trace flags can be added and changed in the Developer Console by navigating to Debug > Change Log Levels
    • Debug Log Entities: debug logs can be setup for specific users, classes, and triggers
    • Trace Flag in Setup: new trace flags can be created in Setup by searching for debug logs
    • Logging Level Override: other logging levels, such as logging levels set by user trace flags, are overridden by class and trigger trace flags
    • Apex Class and Trigger: class/trigger trace flags do not cause logs to be generated and are used to override other logging levels
  • Creating Trace Flags: trace flags set log levels for a user, Apex class or Apex trigger for up to 24 hours
    • Create Trace Flag: trace flag for Debug Logs can be created by going to Setup > Debug Logs > New
    • About Entity Types: user trace flags can be created to generate and monitor user logs, while class and trigger trace flags are used to override logging levels
    • Configure Trace Flag: the entity to trace is selected, the time period during which logs should be generated, and a debug level

  • Debug Log Order of Precedence: The next logging logic is used if the preceding logic is not available
    1. Active trace flags override all other logging logic until the expiration date
    2. Default logging levels are used for synchronous and asynchronous tests
    3. Logging levels are defined by the API header
    4. Log levels are defined by entry points
  • Platform Integration User: many internal Salesforce applications automatically run their business processes as the Platform Integration User
    • User Fields: “Platform Integration User” appears in the Created By, Last Modified By, or Owner fields on certain records in the organization
    • Debug Logs: Debug Logs can be used to trace the business processes performed by the Platform Integration User
    • Trace Flags: A user trace flag can be created and “Platform Integration” can be selected from the Trace Entity Type dropdown list
    • Audit Fields: For example, “Platform Integration User” is displayed in audit fields when data is synchronized using the Salesforce Integration Cloud

Log Inspector

  • Log Inspector is a tool in the Developer Console that can be used to inspect debug logs
    • Log Panels on the Log Inspector contain various panels including Stack Tree, Execution Stack, Execution Log, Source, Variables and Execution Overview
    • Custom Perspectives can be designed, saved, and later selected, by selecting Debug > View Log Panels in the Developer Console
    • Lots tab can be used to open a log in the Log Inspector for troubleshooting and debugging

  • Log Panels:
    • Stack Tree: Two views, Execution Tree and Performance Tree. Show information in a top-down manner from the initiating calls to the next level down. The Execution Tree displays each operation while the Performance Tree aggregates operations to provide a better look at the performance of an operation as a whole.
    • Execution Stack: The Execution Stack displays a bottom-up view of the currently selected item in the debug log from the lowest level call to the next level up.
    • Execution Log: The Execution Log contains the debug log that shows every operation that occurred in the transaction. For each operation, the panel shows the timestamp, event, and details pertaining to the event. It can be used to retrace steps through a process. The following options are available for filtering the log: This Frame, Executable, Debug Only, and Filter
    • Source: The Source panel shows the executed source code or the metadata definitions of entities used during the process, and lists how many times a line of code was executed.
    • Variables: The Variables panel can be used to identify when a variable is assigned a value and what the value of the variable is. A ‘Variable’ event can be clicked to populate the section.
    • Execution Overview: The Execution Overview panel contains four tabs, namely, Save Order, Limits, Timeline, and Executed Units. The Save Order tab shows save order elements for each DML action. The Limits tab shows overall system limits by name and amount used. The Timeline tab shows a visual representation of the time taken by each process. The Executed Units tab shows the system resources used by each item in the process.
  • Executed Units: display metrics of the different types of operations in a transaction. Following shows the runtime duration of each function.

  • Following describes the steps that can be taken to use the Log Inspector for debugging
    • Display Executables: Select Executable in the Execution Log panel to filter all the non-executable steps and trace path of execution
    • View Debug Statements: Enter “Debug” keyword in the Filter of the Execution Log panel to view System.Debug statements
    • Update Source Code: Update the source code using the Source panel after the cause and fix of a bug or issue has been identified
    • View Executed Units: Use the Executed Units tab of the Execution Overview panel to view all the DML statements in a transaction

Checkpoints

  • Checkpoints can be added to specific lines in Apex source code to provide additional information related to the lines of code when they are executed in a transaction
    • Setting Checkpoints: up to five checkpoints can be set by opening the class or filter in a source code editor and clicking in the margin to the left of the line number
    • Checkpoints Tab: Checkpoints preserve a snapshot of the state of objects in memory at the time the checkpoint was reached. Can be used to access a list of saved checkpoints.
    • Checkpoint Inspector: checkpoint can be double-clicked to view the results of the Checkpoint inspector. Two tabs: Heap and Symbols:
      • Heap: displays all objects in memory at the time the line of code was executed
      • Symbols: displays a tree view of all symbols in memory at the checkpoint
    • Overlaying Apex Code and SOQL: A checkpoint’s properties can be edited to overly Apex code and SOQL statements that run when code executes at a particular checkpoint. This can be used to create a specific condition in which the code should be tested. Results of the overlayed code appear on a separate Query Results or Apex Execution Results tab in the Checkpoint Inspector
  • Steps to Using Checkpoints
    1. Apex Class or Trigger that needs to be checked is opened in the Developer Console
    2. Click in the margin to the left of the line number where the checkpoint must be set
    3. Execute the code with the Developer Console open
    4. Checkpoints and results can be viewed on the Checkpoints tab
  • Checkpoints can be set in Apex classes and triggers. Below shows checkpoints that are being added on specific lines in an Apex class

  • Considerations regarding using checkpoints:
    • Capture Once: results for a checkpoint are captured only once, regardless of the number of times they are executed
    • Set Iteration: iteration for the capture can be changed from the Checkpoint Locations list on the Checkpoints tab
    • Future Methods: If a checkpoint is set in a method that uses the @future annotation, the Developer Console must be kept open until the asynchronous method completes

  • Checkpoint Inspector has two main tabs:
    1. Symbols Tab: displays a tree view of all the symbols in memory at the checkpoint
    2. Heap Tab: displays all objects in memory when the checkpoint was executed, including the following columns:
      • Types: show info about all the classes of instantiated objects in memory at the checkpoint, their count, and their total size
      • Instances: column shows a list of all the instantiated objects of a particular type, with their address in the heap and memory size
      • State: shows the fields and values in a particular object selected in the Instances column

Exception Handling

  • Salesforce comes with a comprehensive exception handling framework for identifying and handling different types of errors on the platform
    • Built-in Exceptions: there are several built-in exception types that the Apex runtime engine throws depending on the type of error
      • Ex: DmlException, QueryException, and NullPointerException
      • Exception methods like getCause() can be used in the catch block to get more information about the exception
    • Using Exception Handling for Debugging: if a block of Apex is likely to cause an error, exception handling can be used to catch the error
      • System.debug statements can be used in catch blocks to log the errors

Debug Flows & Processes

  • Troubleshooting Flows & Processes: when a flow or process fails, steps can be taken to troubleshoot and resolve the issue
    • Process Failures: when a process fails, the end user sees an error message that contains the process name, error ID, and sometimes technical information. Detailed error email is also sent to the system administrator.
    • Flow Failures: when a flow fails, an email is sent, which includes the error message from the failure and **details about each flow element, including user-entered data
    • Troubleshooting Processes: debug logs can be used to find detailed information about processes after they finish running. They appear as flows and workflow rules in debug logs. Log level should be set to finer for the workflow log category
    • Debugging Flows: debug option in a flow can be used to test the flow and observe what happens as it runs
  • Example Troubleshooting a Failed Process
    • Email received after the failure of the process can be analyzed
    • If a user trace flag has been set, the error can also be viewed in the generated debug log

  • Tracking a Flow’s Resource Usage: debug logs can track resource consumption of flows and provide information which can be used for troubleshooting or optimizing flows

Debug Lightning Components

  • Different methods are available for debugging Lightning Components
    • Browser Developer Tools: browser’s web development tools can be used to debug JavaScript client-side code for Lightning components. For example, Chrome Developer Tools can be used for client-side debugging of Lightning components.
    • Debugger Statements: a breakpoint can be set by inserting a debugger statement in the line of JavaScript code where it needs to be stopped during debugging
    • Salesforce Lightning Inspector: The Salesforce Lightning Inspector is a Google Chrome Developer Tools extension that can be installed for navigating the component tree, inspecting component attributes, and profiling component performance
    • Developer Console: The Developer Console can be used for server-side debugging of Lightning components. A debugger can look for logs that have contain “/aura” in their Operation column
  • Debug Mode for Lightning Components: Enabling Debug Mode helps debug JavaScript code contained in Lightning components
    • Production Mode (Default): In the production mode, the framework code is optimized, minified, and obfuscated, which reduces the size of the JavaScript code. Custom component code is not minified or obfuscated
    • Selective Debug Mode: It is possible to enable debug mode only for users who are involved in debugging activity to not affect the performance of Salesforce for other users in the org
    • Debug Mode Enabled: When the debug mode is enabled, framework JavaScript code is not minified and is easier to read and debug. However, Salesforce is slower for any user who has debug mode enabled
    • Debug Mode Users: Debug mode can be enabled for specific users by navigating to ‘Debug Mode’ under the ‘Lightning Components’ section in Setup. Users who have debug mode enabled see a banner notification once a week while it is enabled
  • Below shows a configuration where Debug Mode is enabled only for one user in the org

  • Web developer tools such as Chrome DevTools can be used to debug JavaScript code client-side controllers of custom Lightning components

  • The Salesforce Lightning Inspector is a browser extension offered by Salesforce for analysing and debugging Lightning components

  • Debug logs generated by Lightning componennts shows "/aura" in the Operation column

Monitor Flows, Processes, and Jobs

  • Flows, Processes, and asynchronous Apex can be monitored in Salesforce
    • Monitoring Flows & Processes: paused flow interviews and scheduled actions from processes can be monitored on the ‘Paused and Failed Flow Interviews’ page in Setup
    • Apex Jobs: Apex jobs page in Setup can be used to monitor the status of all asynchronous Apex jobs in Salesforce. Apex Flex Queue in Setup can be used to monitor and reorder the jobs.
    • Batch Jobs: Batch jobs page can be used to view only batch jobs. It is useful when there are many batch jobs. A slider can be used to select a specific date range and narrow down the list of batch jobs
    • Scheduled Jobs: The “Scheduled Jobs” page in Setup can bbe used to view all reporting snapshots, scheduled Apex jobs, and dashboards scheduled to refresh
    • Using SOQL for Monitoring Jobs: A SOQL query on AsyncApexJob can be used to obtain information about a submitted job. Info about scheduled jobs can be obtained by running a SOQL query on CronTrigger
  • The Apex Jobs Page in Setup can be used to view all the asynchronous Apex jobs, including batch, future, and scheduled jobs

  • The AsyncApexJob and CronTrigger objects contain data related to asynchronous operations