Feature: Nebula Logger Plugin

.github/workflows/ci.yml

@@ -6,6 +6,7 @@ on:
       - main
     paths:
       - "source/**"
+      - "plugins/nebula-logger/source/**"
     types: [opened, ready_for_review, reopened, synchronize]
 
 concurrency:

plugins/nebula-logger/README.md

@@ -0,0 +1,95 @@
+This plugin leverages the [Plugin Framework](https://github.com/jasonsiders/apex-database-layer/wiki/The-Plugin-Framework) to automatically logs details about your DML and SOQL operations, via _Nebula Logger_.
+
+[Nebula Logger](https://github.com/jongpie/NebulaLogger/tree/main) is a popular logging framework for Salesforce. Like Apex Database Layer, it's free, and open-source. 
+
+## Getting Started
+
+### Prerequisites
+To use this plugin, you must have the most recent version of [Apex Database Layer](https://github.com/jasonsiders/apex-database-layer) and [Nebula Logger](https://github.com/jongpie/NebulaLogger/tree/main) installed.
+
+### Installation
+
+If you're using both the latest & unmanaged versions of _Apex Database Layer_ and _Nebula Logger_ installed, you may install this plugin as an unlocked package.
+
+First, locate the latest version of the plugin package, called `nebula-logger-plugin@latest` in [`sfdx-project.json`](https://github.com/jasonsiders/apex-database-layer/blob/main/sfdx-project.json):
+
+```sh
+sf package install --package <<package_version_id>> --wait 10
+```
+
+> :warning: **Note:** If you are using a managed version of _Apex Database Layer_ and/or _Nebula Logger_, you won't be able to formally install the package. Instead, manually copy the contents of these two Apex Classes in your desired environment:
+>
+>- [`DatabaseLayerNebulaLoggerAdapter.cls`](https://github.com/jasonsiders/apex-database-layer/blob/main/plugins/nebula-logger/source/classes/DatabaseLayerNebulaLoggerAdapter.cls)
+>- [`DatabaseLayerNebulaLoggerAdapterTest.cls`](https://github.com/jasonsiders/apex-database-layer/blob/main/plugins/nebula-logger/source/classes/DatabaseLayerNebulaLoggerAdapterTest.cls))
+
+### Setup
+
+Once installed, navigate to `Setup > Custom Metadata > Database Layer Settings`. If a record already exists, use that record. Else, create a new record, called "Default". 
+
+Set the Custom Metadata record's _DML: Pre & Post Processor_ and _SOQL: Pre & Post Processor_ fields to be the name of the Apex class: `DatabaseLayerNebulaLoggerAdapter`:
+
+<img width="1178" alt="image" src="https://github.com/user-attachments/assets/db8a5ed1-453f-4c91-bf88-d4c911579669" />
+
+**Note:** Once configured, this custom metadata record won't be altered by upgrading the _Apex Database Layer_ package, or the plugin package itself. 
+
+---
+
+## Usage
+
+Whenever a DML or SOQL operation runs, the plugin will log the details of those operations to Nebula Logger. This results in log entries with the `apex-database-layer` _Log Entry Tag_. 
+
+### DML Logging
+Just before a DML operation is processed, the plugin will issue a `FINEST` log entry summarizing the action that's about to take place. 
+- The [`Dml.Request`](https://github.com/jasonsiders/apex-database-layer/wiki/The-Dml.Request-Class) is serialized and shown in the message body
+- The records being operated on are shown in the `Related Records` tab
+
+<img width="1400" alt="image" src="https://github.com/user-attachments/assets/d9e8cfd1-5f87-4a0e-ad60-abe0593902fe" />
+<img width="1400" alt="image" src="https://github.com/user-attachments/assets/04beeed6-ddbf-476e-84ee-2aaf3a029a9a" />
+
+After a DML operation is processed, the plugin issues another `FINEST` log entry summarizing the action that took place. 
+
+- The [`Dml.Request`](https://github.com/jasonsiders/apex-database-layer/wiki/The-Dml.Request-Class) is serialized and shown in the message body
+- The records that were operated on are shown in the `Related Records` tab
+- The relevant database result objects (ex., `Database.SaveResult`) are shown in the `Related Records` tab
+
+<img width="1400" alt="image" src="https://github.com/user-attachments/assets/f4f18658-2021-4d14-941d-30394a984ba3" />
+<img width="1402" alt="image" src="https://github.com/user-attachments/assets/975e8713-9300-41f3-be4d-0b8b276f2e89" />
+
+If an exception is thrown during a DML operation, an `ERROR` log entry is issued:
+
+- The `Exception` message is shown in the message body
+- The [`Dml.Request`](https://github.com/jasonsiders/apex-database-layer/wiki/The-Dml.Request-Class) is serialized and shown in the message body
+- The records that were operated on are shown in the `Related Records` tab
+
+<img width="1403" alt="image" src="https://github.com/user-attachments/assets/9c3ff70f-e955-4b5c-bd49-b8cabdf3a5dd" />
+
+### SOQL Logging
+
+Just before a SOQL operation is processed, the plugin issues a `FINEST` log entry summarizing the query about to take place:
+
+- The text of the query is available in the message body
+
+<img width="1429" alt="image" src="https://github.com/user-attachments/assets/fa66b1a5-3aea-41e3-b27d-abe183694548" />
+
+After a SOQL operation is processed, the plugin issues another `FINEST` log entry summarizing the query and its results:
+
+- The text of the query is available in the message body
+- The resulting SObject records are available in the `Related Records` tab
+  - Note: Other query operations (ex., `getCursor`, `countQuery`) that do _not_ output SObjects will be printed in the message body instead
+
+<img width="1431" alt="image" src="https://github.com/user-attachments/assets/51b574ed-ef2f-42ef-b97d-96f965290982" />
+<img width="1406" alt="image" src="https://github.com/user-attachments/assets/e37a5a19-72b0-4701-aa17-06c16343b034" />
+
+If an exception is thrown during a SOQL operation, an `ERROR` log entry is issued:
+
+- The text of the query is available in the message body
+- The `Exception` message is shown in the message body
+
+<img width="1402" alt="image" src="https://github.com/user-attachments/assets/2e879830-1a85-4e7f-881b-dc8f154aeb0b" />
+
+### Considerations
+
+#### `MockSoql`: Additional query logs for non-standard SOQL operations
+Many `MockSoql` query operations use the `query` method as the basis for building mock results. This may result in additional logs being issued. 
+
+For example, `MockSoql.getQueryLocator` calls `MockSoql.query` to generate the list of records to be returned, and then wraps the results in a `Soql.QueryLocator`. In this scenario, the plugin issues 4 `FINEST` logs: one before/after `MockSoql.getQueryLocator`, and one before/after `MockSoql.query`. 

plugins/nebula-logger/source/classes/DatabaseLayerNebulaLoggerAdapter.cls

@@ -0,0 +1,206 @@
+/**
+ * @description Adapter class that integrates Nebula Logger with the Apex Database Layer framework.
+ *              Implements both DML and SOQL pre/post processors to log database operations.
+ */
+@SuppressWarnings('PMD.AvoidGlobalModifier')
+global class DatabaseLayerNebulaLoggerAdapter implements Dml.PreAndPostProcessor, Soql.PreAndPostProcessor {
+	@TestVisible
+	private static final String TAG_NAME = 'apex-database-layer';
+	private static final String DELIMITER = '\n---\n';
+	private static final Boolean ORIGINAL_DEBUG_FLAG_VALUE;
+	private static final LoggerSettings__c SETTINGS;
+
+	static {
+		SETTINGS = Logger.getUserSettings();
+		ORIGINAL_DEBUG_FLAG_VALUE = SETTINGS?.IsApexSystemDebugLoggingEnabled__c ?? false;
+	}
+
+	/**
+	 * @description Configure Nebula Logger to ignore this framework's internal classes in log stack traces
+	 */
+	global DatabaseLayerNebulaLoggerAdapter() {
+		Logger.ignoreOrigin(DatabaseLayerNebulaLoggerAdapter.class);
+		Logger.ignoreOrigin(DatabaseLayer.class);
+		Logger.ignoreOrigin(DatabaseLayerUtils.class);
+		Logger.ignoreOrigin(DatabaseLayerTestUtils.class);
+		Logger.ignoreOrigin(Dml.class);
+		Logger.ignoreOrigin(MockDml.class);
+		Logger.ignoreOrigin(MockRecord.class);
+		Logger.ignoreOrigin(MockSoql.class);
+		Logger.ignoreOrigin(Soql.class);
+	}
+
+	/**
+	 * @description Logs DML requests before execution
+	 * @param request The DML request to be processed
+	 */
+	global void processPreDml(Dml.Request request) {
+		String op = this.getDmlOperationName(request?.operation);
+		this.log(System.LoggingLevel.FINEST)
+			?.addLine('⏳ DML: Processing ' + op + '...')
+			?.addLine('Request:\n' + JSON.serialize(request))
+			?.setRecords(request?.records)
+			?.build();
+	}
+
+	/**
+	 * @description Logs a successful DML operation
+	 * @param request The DML request that was processed
+	 * @param results The Database.*Results returned from the DML operation
+	 */
+	global void processPostDml(Dml.Request request, List<Object> results) {
+		String op = this.getDmlOperationName(request?.operation);
+		this.log(System.LoggingLevel.FINEST)
+			?.addLine('✅ DML: Processed ' + op)
+			?.addLine('Request: ' + JSON.serialize(request))
+			?.setDatabaseResults(results)
+			?.setRecords(request?.records)
+			?.build();
+	}
+
+	/**
+	 * @description Logs DML errors
+	 * @param request The DML request that encountered an error
+	 * @param error The exception that was thrown
+	 */
+	global void processDmlError(Dml.Request request, Exception error) {
+		String op = this.getDmlOperationName(request?.operation);
+		this.log(System.LoggingLevel.ERROR)
+			?.addLine('🚨 DML: Error processing ' + op)
+			?.addLine(error?.toString())
+			?.addLine('Request:\n' + JSON.serialize(request))
+			?.setRecords(request?.records)
+			?.build();
+	}
+
+	/**
+	 * @description Logs SOQL requests before execution.
+	 * @param request The SOQL request being processed
+	 */
+	global void processPreSoql(Soql.Request request) {
+		this.log(System.LoggingLevel.FINEST)
+			?.addLine('⏳ SOQL: Processing ' + request?.operation + '...')
+			?.addLine(request?.queryString)
+			?.build();
+	}
+
+	/**
+	 * @description Logs SOQL requests after execution.
+	 * @param request The SOQL request that was processed
+	 * @param results The results from the SOQL operation
+	 */
+	global void processPostSoql(Soql.Request request, Object results) {
+		this.log(System.LoggingLevel.FINEST)
+			?.addLine('✅ SOQL: Processed ' + request?.operation)
+			?.addLine(request?.queryString)
+			?.setRecords(results)
+			?.build();
+	}
+
+	/**
+	 * @description Logs SOQL errors.
+	 * @param request The SOQL request that failed
+	 * @param error The exception that occurred
+	 */
+	global void processSoqlError(Soql.Request request, Exception error) {
+		this.log(System.LoggingLevel.ERROR)
+			?.addLine('🚨 SOQL: Error processing ' + request?.operation)
+			?.addLine(request?.queryString)
+			?.addLine(error?.toString())
+			?.build();
+	}
+
+	// **** PRIVATE **** //
+	private String getDmlOperationName(Dml.Operation operation) {
+		return operation?.name()?.removeStart('DO_');
+	}
+
+	private LogBuilder log(System.LoggingLevel level) {
+		return new DatabaseLayerNebulaLoggerAdapter.LogBuilder(level);
+	}
+
+	// **** INNER **** //
+	private class LogBuilder {
+		private LogEntryEventBuilder entry;
+		private List<String> lines;
+
+		/**
+		 * @description Creates a new LogBuilder instance with the specified logging level
+		 * @param level The logging level for this log entry
+		 */
+		public LogBuilder(System.LoggingLevel level) {
+			this.createLogEntry(level);
+			this.lines = new List<String>{};
+		}
+
+		/**
+		 * @description Adds a line to the log message
+		 * @param line The line to add to the log message
+		 * @return This LogBuilder instance for method chaining
+		 */
+		public LogBuilder addLine(String line) {
+			this.lines?.add(line);
+			return this;
+		}
+
+		/**
+		 * @description Builds the final log entry with all accumulated lines
+		 * @return The LogEntryEventBuilder with the complete log message
+		 */
+		public LogEntryEventBuilder build() {
+			String msg = String.join(this.lines, DELIMITER);
+			return this.entry?.setMessage(msg);
+		}
+
+		/**
+		 * @description Sets database operation results on the log entry
+		 * @param obj List of database results (DeleteResult, SaveResult, etc.)
+		 * @return This LogBuilder instance for method chaining
+		 */
+		public LogBuilder setDatabaseResults(List<Object> obj) {
+			if (obj instanceof List<Database.DeleteResult>) {
+				List<Database.DeleteResult> databaseResults = (List<Database.DeleteResult>) obj;
+				this.entry?.setDatabaseResult(databaseResults);
+			} else if (obj instanceof List<Database.LeadConvertResult>) {
+				List<Database.LeadConvertResult> databaseResults = (List<Database.LeadConvertResult>) obj;
+				this.entry?.setDatabaseResult(databaseResults);
+			} else if (obj instanceof List<Database.SaveResult>) {
+				List<Database.SaveResult> databaseResults = (List<Database.SaveResult>) obj;
+				this.entry?.setDatabaseResult(databaseResults);
+			} else if (obj instanceof List<Database.UndeleteResult>) {
+				List<Database.UndeleteResult> databaseResults = (List<Database.UndeleteResult>) obj;
+				this.entry?.setDatabaseResult(databaseResults);
+			} else if (obj instanceof List<Database.UpsertResult>) {
+				List<Database.UpsertResult> databaseResults = (List<Database.UpsertResult>) obj;
+				this.entry?.setDatabaseResult(databaseResults);
+			}
+			return this;
+		}
+
+		/**
+		 * @description Sets records or query results on the log entry
+		 * @param obj Records to log (SObject list, QueryLocator, or other results)
+		 * @return This LogBuilder instance for method chaining
+		 */
+		public LogBuilder setRecords(Object obj) {
+			if (obj instanceof List<SObject>) {
+				List<SObject> records = (List<SObject>) obj;
+				this.entry?.setRecord(records);
+			} else if (obj instanceof Soql.QueryLocator) {
+				Soql.QueryLocator locator = (Soql.QueryLocator) obj;
+				this.lines?.add('Results:\n' + locator);
+			} else {
+				this.lines?.add('Results:\n' + JSON.serialize(obj));
+			}
+			return this;
+		}
+
+		private void createLogEntry(System.LoggingLevel level) {
+			// Create a basic/empty log entry object for the builder to hydrate with log lines & other information
+			// Special care must be taken to prevent committing unnecessary '' log lines to System.debug logs:
+			SETTINGS.IsApexSystemDebugLoggingEnabled__c = false;
+			this.entry = Logger.newEntry(level, '')?.addTag(TAG_NAME);
+			SETTINGS.IsApexSystemDebugLoggingEnabled__c = ORIGINAL_DEBUG_FLAG_VALUE;
+		}
+	}
+}

plugins/nebula-logger/source/classes/DatabaseLayerNebulaLoggerAdapter.cls-meta.xml

@@ -0,0 +1,5 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<ApexClass xmlns="http://soap.sforce.com/2006/04/metadata">
+    <apiVersion>64.0</apiVersion>
+    <status>Active</status>
+</ApexClass>