Code Standards to Live By: Part Two

In our last blog post, we talked about Pure Functions speeding up page rendering and logic execution along with Separation of Concern Patterns, where we break down responsibility between each aspect of the backend system, resulting in libraries of reusable code across the organization.

While we always strive to produce quality projects and regression tested code, no system is ever 100% foolproof. Here at Groundswell, we take pride in ensuring our client’s success, and we believe that while it is critical to reducing errors proactively, it is more crucial to create the tools required to react when problems arise.

Error Reporting and Handling Framework

When it comes to error handling, Salesforce provides a couple of options like Apex Debug Logs & Salesforce Shield. However, specific use cases need additional handling, where we also use a custom error-handling framework. Each of these solutions come with their own feature set and trade-offs, and sometimes we must leverage one or more solutions in parallel to suit our particular business requirements. With these 3 solutions, we will evaluate them based on the following 3 requirements:

1. Time-Criticality — How soon do I need to be notified when an error occurs?
2. Auditing & Data Persistence — How long do I need to retain logs? How are these logs analyzed?
3. Transaction Scope — Do I have transactions that span across systems? How can I capture all the logs in a central location?
4. Access Control — Who needs to access what kind of logs? Developer vs Support Team vs Infosec/Compliance?
5. Tooling Cost — How much does it cost to achieve the business requirements described above?

Apex Debug Logs

We are all familiar with the (in?)famous Apex debug statements. This is a fantastic tool that allows developers to log database operations, system processes, and try/catch errors during transactions. Debug logs can also contain non-code information, such as database changes, HTTP callouts, workflows, approval processes, and more. These logs are stored in the standard ApexLog objects inside Salesforce and require no additional customization. 

1. Time-Criticality — For debugging, these are the most reliable in all 3 solutions. Insert logs in real-time as transactions complete. For real-time error logging, however, it is not at all reliable due to the cost and limits mentioned below. This solution is also not great for Org wide monitoring, as you cannot enable logging for every user in your org.
2. Auditing & Data Persistence — Limits such as <20MB per log limit, <24-hour retention impose a significant limitation as to its data persistence. Not only are the limits strict, but it also disables logging for some time once the limit is exceeded. ApexLog objects are not available for any form of reporting. 
3. Transaction Scope — ApexLogs will log everything within a single transaction, so long as it stays within the debug log size limit mentioned above. These logs will not be cross-system and will only capture the Salesforce side for a given transaction.
4. Access Control — These logs are available for any users with View All Data permission from within Salesforce.
5. Tooling Cost — Apex Debug Logs comes free with Performance, Unlimited, Developer, Enterprise, and Database.com Editions.

Salesforce Shield

Salesforce Shield is a set of security tools that Salesforce launched back in 2015. Within this set, Event Monitoring provides features for Admins and Developers to monitor the state of their Org. These logs are in the EventLogFile, and they can capture entire categories of events such as Logins, Visualforce page loads, Apex executions, API calls and more. Event Monitoring can be configured without any development effort and is a comprehensive monitoring tool that captures the significant use-cases.

1. Time-Criticality — Data time-criticality is not ideal, as the logs are only generated once per day during Salesforce non-peak hours. This makes Salesforce Shield not the best solution for real-time monitoring.
2. Auditing & Data Persistence — For Developer Editions and free accesses, all Event Monitoring logs come with one-day data retention for login and logout event types. For an extra cost, admins may access all log types with 30-day data retention. EventLogFile is entirely report enabled, and all the log files are available for admin reporting. These records can then also be pushed to external log management tools such as Splunk for further reporting and monitoring.
3. Transaction Scope — Data quality is very reliable. It monitors events that even custom solutions wouldn’t have access to, and it also captures information regarding the apex execution that failed for certain governor limits, which is otherwise not very convenient to track down.
4. Access Control — Salesforce provides 2 standard permissions sets for access to EventLogFile, allowing admins to lock down access for specific user groups. With the reporting capabilities of an SObject, as well as the full range of event types that it covers, Event Monitoring allows for the entire spectrum of users to find value in analyzing the logs generated, ranging from developer to compliance.
5. Tooling Cost — Unlike Apex Logs, the Salesforce Shield suite is not free, and a detailed pricing breakdown can be found here.

Custom Solution

Out-of-box solutions won’t cover all the use cases, to handle certain scenarios we’ve designed a custom framework that leverages Platform Event to logs errors to a Custom Object. With this approach, not only can we generate standard Salesforce Reports to understand the impact and the stability of our system better, but it also provides an endpoint for all external systems to listen to, allowing for further customizations and enhancements at the client’s discretion. 

As developers on the platform, we understand that all clients utilize the limits of their org differently. If Platform Events are not feasible due to existing implementations, we also recommend a similar approach but with Push-Topics or Future calls.

1. Time-Criticality — The approach is very reliable unless we’ve encountered an irrecoverable Salesforce error. Seeing as almost all aspects of Salesforce can be managed via Apex, we can capture logs and errors across these aspects.
2. Auditing & Data Persistence — Logs are stored as records onto a custom object, the data will persist for as long as the storage limit allows. Similar to Event Monitoring, as the central storage location is a Custom Object, all standard reporting methods are available.
3. Transaction Scope — Via Platform Events, this methodology will capture all Try/Catch’d exceptions within a single transaction. Although this currently stores error-logs within salesforce this can be easily extended to push data to an external system like Splunk that can hold transaction data across multiple systems.
4. Access Control — Access to the Custom Object can be managed very granularly via Custom Permissions. Third-party integration capturing these events have the flexibility to add in their own access control layer as required
5. Tooling Cost — There is no inherent monetary cost to this framework, but it does take up the limits in your org. This framework will consume 1 Custom Object usage, log storage bandwidth, and frequent platform events usage, which has its limits as well. 

We listed 3 different solutions, and as you can probably tell, they all come with their respective trade-offs. One solution is not necessarily better than the other, and no one solution will tick all the boxes. Apex debug logs are great, but they are not at all reliable for long term monitoring. Event monitoring is very reliable, but per its name, its core use case is for monitoring the Org, not handle errors. Our custom framework is very flexible, but it comes with specific resource usages that may be non-feasible for certain clients. 

private static Error_Log_Event__e createError(String description, String message, String source) {

   // make sure input length does not exceed field max length
   final Integer DESCRIPTION_MAX_LENGTH = Schema.SObjectType.Error_Log_Event__e.fields.Description__c.getLength();
   final Integer MESSAGE_MAX_LENGTH = Schema.SObjectType.Error_Log_Event__e.fields.Message__c.getLength();

   // populate log event object
   Error_Log_Event__e newLog = new Error_Log_Event__e();
   newLog.Description__c = description.length() <= DESCRIPTION_MAX_LENGTH ?
           description : description.substring(0,DESCRIPTION_MAX_LENGTH);
   newLog.Message__c = message.length() <= MESSAGE_MAX_LENGTH ?
           message : message.substring(0,MESSAGE_MAX_LENGTH);
   newLog.Source__c = source;

   return newLog;
}

public static void publishError(String description, String message, String source) {
   // create and publish error log event
   Error_Log_Event__e newLog = createError(description, message, source);
   EventBus.publish(newLog);
}

trigger ErrorLogEventTrigger on Error_Log_Event__e (after insert) {
   ErrorLogEventTriggerHandler.createErrorLogs(Trigger.new);
}

public static void createErrorLogs(List<Error_Log_Event__e> logEvents) {
   // Construct and inserts log record
   List<Error_Log__c> logs = new List<Error_Log__c>();
   for(Error_Log_Event__e logEvent : logEvents){
       Error_Log__c log = new Error_Log__c();
       log.Description__c = logEvent.Description__c;
       log.Message__c = logEvent.Message__c;
       log.Source__c = logEvent.Source__c;
       logs.add(log);
   }
   insert logs;
}

At Groundswell, we recommend the combination of Salesforce Shield + Custom Framework because it offers the maximum coverage and flexibility. Event monitoring allows DevOps and Admins alike to monitor the health and security of the entire org. At the same time, our custom framework ensures all apex exceptions are logged reliably with full traceability. While Salesforce Shield can be purchased and implemented with minimum effort, the Custom Framework comes with a few additional considerations.

Our methodology is precise to ensure fewer mistakes and helps our clients do less work in the future, with or without us. Coders are builders first. That’s why we need a steady foundation to build off of to solve complex problems. If you are interested in more details about our custom logging framework, feel free to contact us. If you share the same sense of responsibility and passion for the work that you do,  join our team.