Easily Debug Salesforce Using Nebula Logger

Share this article...

There is a regular requirement and a big use case for both admins and developers, as they need to easily debug and surface issues in an app that is accessible for end users. Robust logging functionality is an essential part of the puzzle – even better if it can be customized to meet the needs of your specific org.

I spoke with Jonathan Gillespie, a Senior Software Engineer at Salesforce and a member of SFXD, to gain some additional insight. Jonathan is also the creator of the most popular open-source logging framework in the Salesforce ecosystem. This framework is being widely adopted by both FAANG (Big Tech) companies as well as internal Salesforce teams.

Why Is Advanced Logging Important?

For anyone implementing or supporting an application, you’ve probably realized that no system is perfect. At some point, errors or issues can (and likely will) occur – this could be due to bugs, user errors, or issues with external integrations, among other things.

READ MORE: 17 Free Ways to Monitor Your Salesforce Org

We can use a robust logging solution to help monitor and look out for these situations; by logging system errors, warnings, and other information-level details, we can keep an eye on what is happening within the system. This empowers us to proactively find and resolve any issues, instead of relying on users to report the issues themselves.

Debugging in Salesforce

The Salesforce platform provides some out-of-the-box functionality for basic logging. This is available to admins via the Salesforce Developer Console, and provides information about exceptions, database operations, callouts, and more:

  • System-generated debug information for Apex and Flow is automatically added to the debug log. This includes information about what Apex class or Flow is running.
  • Apex developers can add custom debug messages to the debug log by using the method System.debug() within their code. This is a great way for developers to monitor that a certain block of code is executing, to see the values of parameters and variables, etc.
  • System limits for the current transaction – given that Salesforce has several transactional limits (for example, you cannot have more than 150 DML statements per transaction), this is critical information to monitor, especially as you are adding your own automations to your Salesforce org.

However, there are some major considerations when using the Salesforce platform:

  • Only Apex can directly add debug statements – in Flow and Lightning Components, admins/devs do not have an equivalent option to using System.debug() in Apex.
  • You must enable logs for each user, which has a limit of 24 hours (maximum).
  • Debug logs can be truncated.
  • Old debug logs are auto-purged by the platform.
  • Each debug log must be 20 MB or smaller.
  • System debug logs are retained for 24 hours. Debug logs are retained for seven days.
  • Reporting and monitoring of logs is very limited. Paid add-ons (like Salesforce Shield) or third-party tools are typically needed for more detailed reporting and monitoring.

These limits can make it difficult to rely solely on Salesforce’s logging to troubleshoot issues, especially if it’s an inconsistent issue, or if the user does not know how to recreate the issue.

Enter Nebula Logger

Nebula Logger is a project I started working on 4-5 years ago with my friend and colleague, James Simone. The aim was to provide a better free logging solution for Salesforce. Originally, logging was part of a larger project we collaborated on called the Nebula Framework. The framework was trying to do “a little bit of everything” – it provided logging, a trigger framework, a query builder engine, DML management and mocking, and more.

As time went by, and other open-source projects became more popular in Salesforce, I stopped investing as much time on some features. This included the trigger handler code, as there were already so many well-designed trigger frameworks available for Apex.

However, it still felt like the Salesforce ecosystem needed better logging solutions. Years ago, there were very few options available – a few open-source projects, and a couple of paid AppExchange packages – but I wasn’t super happy with the features they provided. Since James and I had already developed the foundation for a logging solution, I decided to split that portion of Nebula Framework into its own project back in 2018. Nebula Logger was born.

Since then, we’ve put countless hours into the project in an attempt to make it the most robust logging solution for Salesforce. It’s designed for any Salesforce professional (admin, developer, architect, etc.) either implementing or supporting a Salesforce org, and it provides a huge set of features. There are too many to list here, but some of the main features include:

Provides unified logging for Salesforce:

You can easily add log entries via Apex, Lightning Components (both LWC and Aura), and Flow and Process Builder to generate one consolidated log per platform transaction.

Enables reporting on log data by storing data in custom objects:

Log__c and LogEntry__c are the core objects, but two new objects, LogEntryTag__c and LoggerTag__c, have recently been added as part of the tagging system – these can be used in reports/dashboards. Optional pre-built reports and dashboards are also available via GitHub.

Manage logs by tracking the log owner, status, priority, and more: 

This feature is optional, but can be very helpful in production orgs as a way of tracking which logs are important. It also provides custom fields for you to track details such as the “Issue” of an error when you are trying to do root-cause analysis (RCA) for production errors.

Automatically delete old logs with the included batch and schedulable job: 

Storing data in custom objects lets you leverage Salesforce’s features for things like reporting and dashboards, but at the expense of consuming your org’s data storage. Nebula Logger includes a schedulable batch job that you can run in your org to automatically delete old logs (and minimize the storage space used). This is done based on the field Log__c.LogRetentionDate__c, which is automatically set based on the custom setting LoggerSettings__c, and can be manually changed by admins or automatically set in your org using your own automations.

Automatically mask sensitive data by configuring rules in the custom metadata type LogEntryDataMaskRule__mdt:

Even when logging data, you won’t want to log some sensitive information due to privacy concerns, security concerns, and so on. This custom metadata type uses RegEx (or “regular expressions”) to provide advanced data masking – any sensitive data in your logs can be automatically masked simply by configuring a new rule in your org, with no code changes required. Out of the box, Nebula Logger includes data masking rules for US social security numbers, Visa credit card numbers, and Mastercard credit card numbers.

Leverage a pub/sub model with platform events:

Platform events are an absolutely critical part of how Nebula Logger works when logging errors. If you try to store data in a custom object directly, and an error occurs, then the data in your custom object is automatically rolled back by the platform.

Using the LogEntryEvent__e platform event not only solves this issue on-platform, but also allows external systems subscribe to any logging-related events. This is a great way to have your Salesforce logs pulled into an external system if you want to do more advanced reporting and storing of logs off-platform. With the newly added “Log Entry Event Stream” tab, you can also use platform events within Salesforce to monitor and filter log entries in real-time.

Easily add new functionality via the plug-in framework (in beta): 

Over the years, several people have made their own customizations to Nebula Logger by directly modifying the code, but this makes upgrading to new versions more challenging, as those customizations are lost when upgrading.

Earlier this year, I started working on a “plugin framework” for Nebula Logger – now you can create or install plug-ins that add new functionality without needing to directly modify Nebula Logger’s code. This can be done using Apex or Flow, and it is a fantastic way to add org-specific functionality that may not make sense to include directly into Nebula Logger.

For example, I have a plug-in to integrate with Slack – not every org uses Slack, so I didn’t want to include some of this metadata in the core package. But for anyone who does use Slack, you can simply install the plug-in’s package (on top of Nebula Logger) to add Slack notifications for critical logs.

To install Nebula Logger in your org, you have three options:

  • Install the unlocked package: This is the recommended approach, as it makes upgrading (and uninstalling) much easier, and it provides features that are not available in the managed package.
  • Install the managed package: This has the same metadata as the unlocked package, but due to some platform limitations with how managed packages work, several features are not available in the managed package edition.
  • Deploy the metadata directly to your org: This is very similar to installing the unlocked package (in terms of functionality) – you lose some of the capabilities of easily upgrading or uninstalling, but some orgs prefer to not use packages, so I try to make sure that the unpackaged metadata is always deployable to orgs.

The latest versions of the unlocked and managed packages are available via Nebula Logger’s README — you can also see the full list of package versions in the wiki.

Contribute to the Nebula Logger Project 

Over the last year or so, Nebula Logger has turned into a very community-driven project – we receive feedback about features and bugs via GitHub, LinkedIn, SFXD (the amazing Salesforce discord channel that everyone should check out!), emails, and more. I love the community’s engagement, and welcome any contributions.

If you’re interested in contributing to Nebula Logger, there are several ways you can help:

  • Request new features or bugfixes: Even if you don’t want to be the person to implement a new feature or bugfix, simply reporting it on GitHub is a huge help – as I mentioned, it’s become a very community-driven project, so if there is a new feature you’d like to be added, just let me know!
  • Code/implement a new feature: If you have an idea for a new feature (or bugfix), you can submit a pull request via GitHub.
  • Help with documentation: Several months ago, I finally started a wiki for the project on GitHub to help document the ever-growing list of features, but it’s an ongoing task to document everything.

A Developer’s Trailblazer Journey

I spoke with Jonathan Gillespie (Senior Software Engineer at Salesforce) to find out more about his professional journey as a developer and Trailblazer, as well as his experience of open-source logging projects.

Atlas: How did you get started in Salesforce and what is the one thing you wish you’d known when you were starting out? Any recommendations to those who are taking their first steps in their journey?

Jonathan: I first started working with Salesforce in 2011/2012 when I was working at a nonprofit organization. The organization was working to replace a legacy CRM system across different business units, with different modules being migrated to new systems as separate projects.

I joined a project team that was focussed on implementing a donation system for employees and volunteers to use for entering and managing donations across the US at fundraising events. We ended up using a combination of:

  • Sales Cloud and AppExchange packages, used by internal employees to manage fundraising events and donations.
  • Heroku to host a custom Java app, used by volunteers at fundraising events to capture donor/donation information – this integrated with our Salesforce org in real-time.

It was a fascinating project, and I learned so much about the Salesforce platform along the way. Since then, I’ve worked at several other organizations and companies – all of my positions over the last 10 years have involved implementing Salesforce in various ways. Around 6-7 months ago, I officially became a Salesforce employee, which has been an amazing experience so far!

There are so many things I wish I’d known when I first started out! For me, one of the biggest things I wish I’d known (or at least given more credit to) is that, with this type of work, you’ll never stop learning. Technology is ever-changing, and Salesforce is no exception. 

As the platform continues to evolve with each release, there are always new and improved ways for us to implement features. For example, if you were starting a new Salesforce implementation…

  • 6+ years ago, then you probably would have used workflow rules for declarative automations, and Apex and Visualforce for custom development.
  • 3-5 years ago, then you would probably have used Process Builder for simple declarative automations, perhaps Flow for some more complex declarative automations, and Apex and Aura components for custom development.
  • Within the last 1-2 years, you probably would use Flow for all declarative work (including both screen flows for user inputs, and screenless flows for pure backend automations), and Apex and Lightning Web Components for custom development.

Similarly, Salesforce has acquired a long list of companies over the years, and with each new acquisition comes the possibility of new features and products being added to the ecosystem.

So, for anyone who is just starting their journey in the Salesforce ecosystem, I think it’s incredibly helpful to learn how the platform works today – learning things like when to use ‘clicks, not code’ or when to build your own solution versus using an AppExchange package – are key details to understand when working with the platform. 

But don’t just learn about how the platform works today – keep learning, keep reading release notes, keep playing in sandboxes, keep completing Trailhead modules. You may not always go back and change how you previously implemented a feature in your org – but the next time you have a similar requirement, it’ll help if you know that the platform offers new & improved ways to implement your requirements.

Atlas: You’re helping to solve a very important issue in Salesforce, and helping a lot of people in the process. What do you think about open-source content in general?

Jonathan: I think we all benefit from supporting open-source content – a project could be just a small script that solves one simple issue, or it could be a huge project as complex as an entire operating system. Regardless of the scope, by creating (or supporting) an open-source project, you’re helping others to solve the same issue, while also sharing knowledge that encourages learning. The project can then continue to evolve – other experts from around the world can contribute their knowledge and feedback to the project, improving it for everyone.

In my own experience, I started working on open-source projects as a way to learn and improve my skills. I had seen and used some popular open-source projects for Salesforce – projects like Kevin O’Hara’s trigger framework, and the never ending list of repos that Andrew Fawcett has created over the years. But I’ve found that I learn best from hands-on experience, so actually writing my own code has been a great way for me to learn about platform limits, coding best practices, and more.

Eventually, others became interested in a couple of my projects on GitHub, so I happily continue to work on them – it’s one way that I try to give back to the Salesforce community, and I encourage everyone to support open-source projects whenever (or however) they can!

Atlas: What do you think about online communities, especially given the pandemic is still in effect. What do you think about SFXD?

Jonathan: I think that online communities have been an incredible way for people everywhere to stay in touch and interact, especially over the last few years when it’s been much harder and riskier to socialize in person.

James Simone invited me to join SFXD in August 2020. In my opinion, SFXD in particular is one of the best resources for fellow Salesforce ‘nerds’ and I’ve really enjoyed chatting with people there. It’s full of knowledgeable Salesforce experts who always try to help each other solve issues and talk through different possible approaches – they come up with some incredibly clever solutions. It’s also another way that I get feedback on some of my open-source projects, like Nebula Logger. 

It’s an amazing community, and a fantastic way to collaborate with other Salesforce professionals. I highly recommend it for anyone working with the Salesforce platform.

Atlas: Thanks so much for the interview. I’ll see you at the next one!

Final Thoughts

Logging is an important part of the day-to-day functioning of a Salesforce org. Most enterprise systems use event monitoring and have a logging framework designed for their specific use. However, you can use Nebula Logger to quickly solve your logging needs – it’s customizable and built around best practices. You can also add additional functionality on your own. 

If you’re a Salesforce enthusiast like me, you will probably enjoy my newest project, Blue Canvas – we build modern CI, source control, and no-nonsense release management for Salesforce. We are aiming for a single unified platform that makes the whole team happy, including admins, developers, and release managers!

Also check out the Salesforce CPQ deployer tool that lets you ship a whole CPQ project without any SOQL knowledge.

Add Comment