Fast Start - Logging
Framework: KernDX | Total time: ~30 minutes
- What this is: a way to write logs that you can search, report on, and keep. Salesforce's built-in
System.debug()output expires and can't be queried. - Why it matters: when something fails in production, the evidence is still there days later, linked to the records and the single user action that triggered it.
- Who should follow this: developers capturing errors, plus tech leads and DevOps who need traceability in live systems.
- When to use it: any time you'd otherwise use
System.debug(). For a one-off value you only need while developing, plainSystem.debug()is still fine. Switch to persistent logging when you need the evidence to survive into production. - What you'll get working: persistent, queryable logging that adds no database writes to your own transaction and survives rollbacks.
- What you'll build: a service class that logs every step of order processing (start, per-record progress, errors, and completion), with all entries from one run sharing a Transaction ID.
- Success looks like: log entries visible in App Launcher > Kern > Log Entries, showing info/debug/error messages linked to specific Account records, and your test class showing 2/2 passing.
- Coverage: the two tests cover the happy path. The defensive per-record error handler isn't exercised, so
SVC_OrderProcessorlands at ~82% coverage. Add a test that forces a failure inside the loop to take it to 100%. - In one line:
kern.LOG_Builder.build().info('Payment processed').forRecord(accountId).emitAt('SVC.charge');persists via platform event and survives rollbacks.
Namespaces in code samples:
kern.on a class andkern__on an object, field, or metadata type mark the managed package's namespace. On the managed package, framework references need those prefixes even where a sample omits them; repackaged under your own namespace, replacekern/kern__with your prefix; on an unmanaged deploy, drop them. See How to read the code samples.
Before you start
- Open your terminal in your project's top folder, the one that holds
sfdx-project.json. On Windows that terminal is Command Prompt. - Run the four-line check on Set Up Your Computer once: it proves your terminal, the CLI, your login and the KernDX package, and answers what goes wrong. Done that today? Carry on.
- Work in a sandbox or a scratch org, never production.
- Every command below writes
YourOrgAliaswhere your org's alias goes: the name you gave it when you logged in.
Tier 1: See It Work (~2 minutes)
Run these blocks in Execute Anonymous (Developer Console or VS Code) to see logging in action.
Log at every level
In Salesforce, open the Developer Console (the gear icon, then Developer Console), then Debug, then Open Execute Anonymous Window, and run:
kern.LOG_Builder.LogScope scope = kern.LOG_Builder.scope();
try
{
kern.LOG_Builder.build().info('Application started').emitAt('MyApp.initialize');
kern.LOG_Builder.build().debug('Loading configuration').emitAt('MyApp.loadConfig');
kern.LOG_Builder.build().warn('Configuration missing, using defaults').emitAt('MyApp.loadConfig');
kern.LOG_Builder.build().error('Failed to connect').emitAt('MyApp.connect');
}
finally
{
scope.close();
}Open App Launcher > Kern > Log Entries to see your four entries:
- Each has a log level, message, and class/method context.
- All four share the same Transaction ID, because they were written in one transaction, so you can filter the four entries as a group.
- A Correlation ID follows one user action across triggers, callouts and jobs when you start one with
kern.LOG_Builder.startCorrelation()(see the Logging Developer Guide).
Once you have real volume, open the Log Console instead, from the launcher card on the Kern app's home page, or search "Log Console" in the App Launcher. It:
- groups recurring problems with occurrence counts
- ranks the writers producing the most entries, with their origin
- filters by severity and searches past entries
- opens a drawer that walks one operation end to end
The Logging Developer Guide covers it in full.
Why the scope wrapper? Each
.emit()publishes a platform event, and Salesforce caps a single transaction at 150 such immediate publishes (thePublishImmediategovernor). The scope wrapper keeps you safely under that cap:LOG_Builder.scope()collects every emission inside the try/finally and sends them as one batch whenscope.close()runs.
Log an exception with full stack trace
In Salesforce, in the same Execute Anonymous window, run:
try
{
Integer result = 1 / 0;
}
catch(Exception error)
{
kern.LOG_Builder.build().error(error).emitAt('MyApp.calculate');
}Open the log entry. You'll see the exception type (MathException) and the full stack trace, both captured automatically.
Correlate logs to a record
In Salesforce, in the same Execute Anonymous window, run:
Account newAccount = new Account(Name = 'Logging Demo Corp', Phone = '555-0100');
insert newAccount;
kern.LOG_Builder.build().info('Account created successfully')
.at('MyApp.createAccount')
.forRecord(newAccount.Id)
.emit();
kern.LOG_Builder.build().info('Ready for processing')
.at('MyApp.createAccount')
.forRecord(newAccount.Id)
.withContext('industry', 'Technology')
.emit();Both log entries link to the Account record. Click View Record on any log entry to jump directly to it.
When to move to Tier 2: When you want structured logging inside your own classes with automated test coverage.
Tier 2: Build Your Own (~20 minutes)
No local project? You can create classes directly in the Developer Console (Gear Icon > Developer Console > File > New > Apex Class) and run tests from there too (Test > New Run). Paste the code, save, and skip the terminal commands.
Step 1: Create the service class
This service processes Account records and logs every step (start, per-record progress, errors, and completion), batched under one scope. You create an empty class with one command, paste the code into it, then send it to your org.
1. In the terminal, from your project's top folder, create the empty class:
sf apex generate class --name SVC_OrderProcessor --output-dir force-app/main/default/classesYou should see two files created in force-app/main/default/classes, both named SVC_OrderProcessor: the class, ending in .cls, and its companion, ending in .cls-meta.xml.
The second file tells Salesforce which API version the class uses. You never edit it, but a deploy fails without it.
2. In your editor, open this file, delete what is there, paste the code below in, and save:
force-app/main/default/classes/SVC_OrderProcessor.cls/**
* @description Processes Account records with correlated, structured logging at every step.
*
* @see SVC_OrderProcessor_TEST
*
* @author your.name@company.com
*
* @group Order Management
*
* @date February 2026
*/
public with sharing class SVC_OrderProcessor
{
/** @description Context key for the record count. */
@TestVisible private static final String CONTEXT_COUNT = 'count';
/**
* @description Processes a list of Account records with full correlated logging.
*
* @param accounts The Account records to process.
*/
public void processOrders(List<Account> accounts)
{
kern.LOG_Builder.LogScope scope = kern.LOG_Builder.scope();
try
{
kern.LOG_Builder.build()
.info('Order processing started')
.withContext(CONTEXT_COUNT, accounts.size())
.emitAt('SVC_OrderProcessor.processOrders');
for(Account account : accounts)
{
try
{
kern.LOG_Builder.build()
.debug('Processing account')
.forRecord(account.Id)
.emitAt('SVC_OrderProcessor.processOrders');
}
catch(Exception error)
{
kern.LOG_Builder.build()
.error(error)
.forRecord(account.Id)
.emitAt('SVC_OrderProcessor.processOrders');
}
}
kern.LOG_Builder.build()
.info('Order processing completed')
.withContext(CONTEXT_COUNT, accounts.size())
.emitAt('SVC_OrderProcessor.processOrders');
}
finally
{
scope.close();
}
}
/**
* @description Emits a single ERROR-level alert.
*
* @param message The alert message to persist.
*/
public void criticalAlert(String message)
{
kern.LOG_Builder.build()
.error(message)
.emitAt('SVC_OrderProcessor.criticalAlert');
}
}What this code does:
LOG_Builder.scope()opens a batch scope: every.emit()call inside the try/finally is held back and published together atscope.close(), staying well under the 150-event limit.info()/.debug()/.warn()/.error()set the log level.at('ClassName.methodName')records where the log came from.forRecord(account.Id)links the log entry to the Account being processed.withContext(key, value)adds structured key-value data to the entry.emitAt('Class.method')shorthand for.at(...).emit()
Every entry also records two facts you never have to set: who wrote it (Framework, Apex, Flow or Component) and the plain name of the class, Flow or component that did. The Log Console shows them on its Top sources card, and your own reports can group by them. The Logging Developer Guide explains both.
3. In the terminal, send the class to your org:
sf project deploy start -o YourOrgAlias -m "ApexClass:SVC_OrderProcessor"You should see Status: Succeeded, with SVC_OrderProcessor listed as created.
Something went wrong? See Common Issues, Step 1.
Step 2: Try the service
Create one Account and hand it to the service, then look at the entries it wrote.
In Salesforce, in the Developer Console's Execute Anonymous window, run:
Account newAccount = new Account(Name = 'Order Demo Corp', Phone = '555-0200', BillingCity = 'Melbourne');
insert newAccount;
new SVC_OrderProcessor().processOrders(new List<Account>{ newAccount });
System.debug('Done — check App Launcher > Kern > Log Entries');You should see this line in the log:
Done — check App Launcher > Kern > Log EntriesThen, in App Launcher > Kern > Log Entries, you should see three new entries: an INFO Order processing started, a DEBUG Processing account linked to the Account, and an INFO Order processing completed, all sharing the same Transaction ID.
Something went wrong? See Common Issues, Step 2.
Step 3: Write and run the test
The test class checks both methods: the order run writes INFO entries, and the alert writes one ERROR entry with its message. It reads the saved log entries through SEL_LogEntries, the short selector of your own shown in Testing with logs. You create the two empty classes, paste the code into them, send them to your org, then run the test.
1. In the terminal, from your project's top folder, create the empty test class and the empty selector:
sf apex generate class --name SVC_OrderProcessor_TEST --output-dir force-app/main/default/classes
sf apex generate class --name SEL_LogEntries --output-dir force-app/main/default/classesYou should see four files created in force-app/main/default/classes: two named SVC_OrderProcessor_TEST and two named SEL_LogEntries. Each pair is the class, ending in .cls, and its companion, ending in .cls-meta.xml.
2. In your editor, open force-app/main/default/classes/SEL_LogEntries.cls, delete what is there, paste in the selector from Testing with logs, and save.
3. In your editor, open this file, delete what is there, paste the code below in, and save:
force-app/main/default/classes/SVC_OrderProcessor_TEST.cls/**
* @description Unit tests for SVC_OrderProcessor.
*
* @see SVC_OrderProcessor
*
* @author your.name@company.com
*
* @group Order Management
*
* @date February 2026
*/
@SuppressWarnings('PMD.ApexUnitTestClassShouldHaveRunAs')
@IsTest(seeAllData=false isParallel=true)
private class SVC_OrderProcessor_TEST
{
/** @description Log level string for INFO entries. */
private static final String LOG_LEVEL_INFO = 'INFO';
/** @description Log level string for ERROR entries. */
private static final String LOG_LEVEL_ERROR = 'ERROR';
/** @description Alert message used in the error path test. */
private static final String ALERT_MESSAGE = 'Critical system failure';
/**
* @description Verifies that processOrders() creates correlated log entries
* queryable by kern__UserId__c after platform event delivery.
*/
@IsTest
private static void shouldCreateScopedLogEntriesForProcessedAccounts()
{
Account account = (Account)kern.TST_Builder.of(Account.SObjectType).build();
kern.LOG_Builder.ignoreTestMode = true;
Test.startTest();
new SVC_OrderProcessor().processOrders(new List<Account>{ account });
Test.getEventBus().deliver();
Test.stopTest();
// Query by kern__UserId__c — NOT CreatedById.
// TRG_PersistLogEntry runs as the Automated Process user, so CreatedById returns zero rows.
Id currentUserId = UserInfo.getUserId();
List<kern__LogEntry__c> entries = new SEL_LogEntries().query
.condition(kern__LogEntry__c.kern__UserId__c).equals(currentUserId)
.toList();
Assert.isFalse(entries.isEmpty(), 'Expected correlated log entries after event delivery');
Boolean foundInfo = false;
for(kern__LogEntry__c entry : entries)
{
if(entry.kern__LogLevel__c == LOG_LEVEL_INFO)
{
foundInfo = true;
}
}
Assert.isTrue(foundInfo, 'Expected at least one INFO entry from processOrders()');
}
/**
* @description Verifies that criticalAlert() persists an ERROR entry with the correct message.
*/
@IsTest
private static void shouldPersistErrorEntryForCriticalAlert()
{
kern.LOG_Builder.ignoreTestMode = true;
Test.startTest();
new SVC_OrderProcessor().criticalAlert(ALERT_MESSAGE);
Test.getEventBus().deliver();
Test.stopTest();
// Query by kern__UserId__c — NOT CreatedById (see note in test above)
Id currentUserId = UserInfo.getUserId();
List<kern__LogEntry__c> entries = new SEL_LogEntries().query
.condition(kern__LogEntry__c.kern__UserId__c).equals(currentUserId)
.andCondition(kern__LogEntry__c.kern__LogLevel__c).equals(LOG_LEVEL_ERROR)
.toList();
Assert.isFalse(entries.isEmpty(), 'Expected one ERROR entry from criticalAlert()');
Assert.areEqual(ALERT_MESSAGE, entries[0].kern__Message__c, 'Message should match the alert text');
}
}About the query filter: Tests must filter
kern__LogEntry__cbykern__UserId__c, not byCreatedById. The trigger action that saves log entries (TRG_PersistLogEntry, run by theTRG_LogEntryEventtrigger) runs as the Automated Process user, so aCreatedByIdfilter returns zero rows. Thekern__UserId__cfield, by contrast, holds the ID of the user who emitted the log.
About the annotations:
@IsTest(seeAllData=false isParallel=true)keeps tests isolated and enables parallel execution.@SuppressWarnings('PMD.ApexUnitTestClassShouldHaveRunAs')suppresses a code analysis rule. In production tests, consider wrapping logic inSystem.runAs(testUser)to verify profile and permission set access.
4. In the terminal, send the test class and the selector to your org:
sf project deploy start -o YourOrgAlias -m "ApexClass:SEL_LogEntries" -m "ApexClass:SVC_OrderProcessor_TEST"You should see Status: Succeeded, with SEL_LogEntries and SVC_OrderProcessor_TEST listed as created.
5. In the terminal, run the test:
sf apex run test -o YourOrgAlias -t SVC_OrderProcessor_TEST --code-coverage --synchronous --result-format humanYou should see 2 tests passing: both tests show Pass, the summary line Outcome reads Passed, and the coverage table shows SVC_OrderProcessor at around 82%. The lines left uncovered are the per-record error handler, which neither test reaches.
Something went wrong? See Common Issues, Step 3.
Key Patterns
| Pattern | Example | Why |
|---|---|---|
| Scope batching | LOG_Builder.scope() + try/finally | Keeps you under the platform-event publish limit |
| Log at method boundaries | .info('started') + .info('completed') | Trace execution flow in production |
| Per-record context | .forRecord(account.Id) | All logs for one record queryable together |
| Debug inside loops | .debug('Processing account') | Drop it in production by raising LogLevelThreshold__c above DEBUG; the default keeps it |
| Catch-log-continue | .error(error) in catch, no rethrow | Persistent record; processing continues for remaining items |
| Single-shot alert | .error('message').emitAt(...) | One-liner for config/startup errors |
| Query by UserId | kern__UserId__c = UserInfo.getUserId() | Not CreatedById (TRG_PersistLogEntry runs as Automated Process user) |
Tier 3: Production Patterns (~5-10 minutes)
Log levels
See the Logging Guide for the complete log level reference, and How do I configure this? for the filtering configuration.
| Level | Method | When to use |
|---|---|---|
| ERROR | .error(exception) or .error('message') | Failures, exceptions, data corruption |
| WARN | .warn('message') | Business rule violations, missing optional data, degraded performance |
| INFO | .info('message') | Key business events, state transitions, completion messages |
| DEBUG | .debug('message') | Implementation details, variable values (kept unless LogLevelThreshold__c is set above DEBUG) |
Flood control for repeated events
When the same event fires repeatedly in a hot loop, you don't want thousands of near-identical rows drowning the log table. Tag the event with a fingerprint instead: the first occurrence keeps a full entry, and repeats roll up into a daily counter.
In your editor, in your own class:
kern.LOG_Builder.build()
.warn('Payment gateway retry failed')
.withFingerprint('payment-gateway-retry')
.emitAt('PaymentSync.run');Pick a fingerprint that identifies the kind of event, and keep it stable (never use a record Id or timestamp, or every occurrence looks unique and the rollup never kicks in). See Log Grouping & Flood Control in the Logging Guide for reading grouped logs and reporting on occurrence counts.
Shorthand: .emitAt()
When you don't need .forRecord() or .withContext(), use .emitAt() as shorthand for .at().emit().
In your editor, in your own class:
// These are equivalent:
kern.LOG_Builder.build().info('Done').at('MyClass.myMethod').emit();
kern.LOG_Builder.build().info('Done').emitAt('MyClass.myMethod');Use .emitAt() for simple messages. Use .at() + chain + .emit() when adding .forRecord() or .withContext().
Exception logging
Always pass the Exception object, never .getMessage().
In your editor, in a catch block of your own class:
catch(Exception error)
{
// Captures exception type, message, AND full stack trace
kern.LOG_Builder.build().error(error).at('MyClass.myMethod').forRecord(recordId).emit();
throw error;
}Testing with logs
To assert on log entries in a test, you need them to actually be written, and by default they aren't: logs are suppressed in @IsTest context. Two steps turn them on:
- Set
kern.LOG_Builder.ignoreTestMode = truebefore your log call to enable logging in tests. - Call
Test.getEventBus().deliver()to deliver the platform events synchronously before you assert.
In your editor, in a test method:
kern.LOG_Builder.ignoreTestMode = true;
Test.startTest();
new SVC_OrderProcessor().processOrders(accounts);
Test.getEventBus().deliver();
Test.stopTest();
// Query by kern__UserId__c — NOT CreatedById
Id currentUserId = UserInfo.getUserId();
List<kern__LogEntry__c> entries = new SEL_LogEntries().findByField(kern__LogEntry__c.kern__UserId__c, currentUserId);
Assert.isFalse(entries.isEmpty(), 'Should have log entries');The test reads through a short selector of your own, in its own class file. The Step 3 test uses the same selector:
force-app/main/default/classes/SEL_LogEntries.clspublic with sharing class SEL_LogEntries extends kern.SEL_Base
{
public SEL_LogEntries()
{
super(kern__LogEntry__c.SObjectType);
}
public override List<SObjectField> getFields()
{
return new List<SObjectField>
{
kern__LogEntry__c.kern__Message__c,
kern__LogEntry__c.kern__LogLevel__c,
kern__LogEntry__c.kern__CorrelationId__c
};
}
}The selector reads in user mode. Log entries are owned by the Automated Process user and their sharing is Private, so the user running the test needs to see all log entries: a System Administrator can, and any other user needs the kern.Administrator permission set. Keep this read outside System.runAs: inside it, kern__UserId__c still holds the user who started the test, so the filter finds nothing.
Key steps:
ignoreTestMode = true→ emit logs →Test.getEventBus().deliver()→ query bykern__UserId__c→ assert.
Why a selector for
kern__LogEntry__c? Every read goes through a selector, in tests too: the Kern scanner ruleKernNoInlineSOQLflags inline SOQL in test classes as well. The package does not give you a log selector to call, so write a short one of your own.
Scoped logging
When one operation emits many logs, a scope keeps you under the platform event publish cap:
LOG_Builder.scope()holds back every log entry emitted inside a try/finally block.- It publishes them in one flush at
scope.close(). That single flush keeps you well clear of the 150-eventPublishImmediategovernor limit. - You don't need a scope for grouping: the entries of one transaction already share a Transaction ID.
In your editor, in your own class:
kern.LOG_Builder.LogScope scope = kern.LOG_Builder.scope();
try
{
kern.LOG_Builder.build().info('Batch started').emitAt('BATCH_ProcessAccounts.execute');
// ... process records ...
kern.LOG_Builder.build().info('Batch completed').emitAt('BATCH_ProcessAccounts.execute');
}
finally
{
scope.close();
}To see scoped entries, try it out.
In Salesforce, in the Developer Console's Execute Anonymous window, run:
kern.LOG_Builder.LogScope scope = kern.LOG_Builder.scope();
try
{
kern.LOG_Builder.build().info('Step 1: Loading data').emitAt('MyApp.processRecords');
kern.LOG_Builder.build().info('Step 2: Validating').emitAt('MyApp.processRecords');
kern.LOG_Builder.build().info('Step 3: Complete').emitAt('MyApp.processRecords');
}
finally
{
scope.close();
}
System.debug('Check App Launcher > Kern > Log Entries — all three entries share the same Transaction ID.');Logging from Flows
Use invocable actions to log from Flows. This creates correlated log entries visible in the same Log Entries tab as Apex logs.
- Open Setup > Flows and edit your Flow (or create a new one)
- Add an Action element:
- Search for Start Flow Correlation
- Set Label to
Start Logging - Set flowName to the name of your Flow (e.g.,
Account_Onboarding) - Set recordId to the record ID variable (e.g.,
{!recordId}) - Store the output correlationId in a text variable (e.g.,
{!correlationId})
- At key steps, add Action elements:
- Search for Log Flow Event
- Set correlationId to
{!correlationId} - Set message to a description (e.g.,
Account created successfully) - Set Log Level (input name
logLevel) toINFO,WARN, orERROR - Optionally set Record ID (input name
recordId) to the record this log is about (e.g.,{!$Record.Id}) so every log for that record can be filtered together - Optionally set Flow Name (input name
flowName) to the same Flow name used in step 2, so the entry is filed under the Flow rather than the step
- At the end of the Flow, add an Action element:
- Search for End Flow Correlation
- Set flowName to the same Flow name used in step 2
- Set correlationId to
{!correlationId} - Set Success (input name
success) to{!$GlobalConstant.True}(orFalsefor failure paths)
- Save and Activate
All log entries from the Flow share the same Correlation ID, so you can filter them together in App Launcher > Kern > Log Entries.
Logging from LWC
From a Lightning Web Component, pick the way that fits:
- Simple messages and errors: use the built-in
consoleLog()andconsoleError()methods on ComponentBuilder (the KernDX base class that gives your components their common wiring, such as toasts, Apex calls, and navigation, already built in).- These route through the framework's client logger: the entries are buffered, flushed to Apex automatically, and saved as
kern__LogEntry__crows. - They echo to the browser console only if you turn mirroring on with
setConsoleMirroring(true)fromkern/utilityLogger, which is handy while debugging.
- These route through the framework's client logger: the entries are buffered, flushed to Apex automatically, and saved as
- Correlation tracking, timers, and explicit log levels: import the
kern/utilityLoggermodule directly.- Its
debug()/info()/warn()/error()calls are flushed to Apex automatically and saved askern__LogEntry__crows. - Pass an
Errorobject toerror()and its JavaScript stack trace is kept on the entry, along with any context data you pass, so you can read later exactly what the client saw.
- Its
- Your Apex controller methods themselves: use
LOG_Builder.
Access: a user who is not a System Administrator needs access to the Apex class the client logger writes through. Assign the Kern Component Access permission set (it also grants the Flow logging actions), or add Apex class access for
kern.CTRL_Loggerto a permission set they already have.
In your editor, in your component's JavaScript file:
// In any ComponentBuilder LWC:
this.consoleLog('User clicked save');
this.consoleError(error, 'MyComponent.handleSave'); // the error object comes firstSee the LWC Guide for the full ComponentBuilder reference, or the Logging Guide for server-side logging patterns.
Sensitive data is masked by default
You don't have to remember to scrub secrets out of your logs: every entry passes through the data masking framework before it is saved. Out of the box, two rules fire:
MaskSecretKeysredacts common secret JSON keys (password,token,apiKey,authorization,bearer,client_secret,private_key,access_token,refresh_token) anywhere they appear in a field value.MaskPaymentCardredacts 13–19 digit sequences that pass the Luhn (mod-10) checksum, covering all major card brands (digits may be separated by spaces or hyphens). The Luhn check filters out most transaction IDs, order numbers, and other long digit runs that would otherwise false-positive as card data. (It replaces the originalMaskCreditCardrule, which still ships, switched off. If you switch it on, switch its four targets on with it.)
So LOG_Builder.build().info('Payload: ' + JSON.serialize(payload)).emitAt(...) is safe even if payload contains a password or card number: the persisted LogEntry__c.Message__c will have them redacted.
The other rules:
- Fourteen more rules ship as inactive templates: SSN, IBAN, SWIFT/BIC, MBI, health keywords, email, US phone, AWS access key, URL basic auth, authorization header, private IPv4, postal address, free text, international phone. To switch one on, flip
kern__MaskingRule__mdt.IsActive__c = trueand add akern__MaskingTarget__mdtrecord wiring the rule to the fields that need it. - A third active rule,
MaskJwt, redacts JSON Web Tokens on API call records and API issues, not on log entries.
Wiring gotcha. Wiring a rule to a field doesn't guarantee it fires: a rule carries two optional filters that can quietly veto a target. If a
MaskingTarget__mdtpoints at aField__cwhose type or value length the filter rejects, the rule will not run on that field.
ApplicableFieldTypes__crestricts whichDisplayTypes the rule applies to. AnApplicableFieldTypes__cmismatch is at least visible: the framework logs a one-timewarnLogEntry to surface the misconfiguration.MinInputLength__csets a minimum value length. AMinInputLength__cmismatch is silent.The fix in either case is to widen the rule filter or remove the target.
Masking performance telemetry. If you ever suspect masking is slowing down a trigger, you can measure it. Masking runs inside trigger dispatch.
- Enable
LogSetting__c.EnableMaskerPerformanceLogging__c(default off) to emit one aggregateLogEntry__cper trigger batch, not per record.- The log fires only when total masking time for that batch meets or exceeds
LogSetting__c.MaskerPerformanceThresholdMs__c(default 100ms), so it stays quiet until there's something worth seeing.
Clean up
If you built this example only to try the framework, run this command when you have finished the guide. The Accounts the Tier 1 and Step 2 blocks created (Logging Demo Corp and Order Demo Corp) and the log entries stay; delete them in the app, or leave them.
In the terminal, delete the two classes:
sf project delete source -o YourOrgAlias -m "ApexClass:SVC_OrderProcessor_TEST" -m "ApexClass:SVC_OrderProcessor" --no-promptYou should see Status: Succeeded, then a Deleted Source table listing the two classes. The command deletes the files from your project too.
Something went wrong? See Common Issues.
Common Issues
Trouble with your computer rather than this guide (sf is not recognised, scripts are disabled, you are not logged in, the wrong folder)? Those are answered once, in Set Up Your Computer.
Step 1: Create the service class
The deploy says there is nothing to deploy
The deploy stops with No source-backed components present in the package. The command ran inside another project's folder, so the CLI looked for the class there and found nothing. Open the terminal in your own project's top folder, the one that holds sfdx-project.json, and run the command again.
Step 2: Try the service
No entries appear
The entries arrive by platform event, a moment after the block finishes, so the list can still be empty when you first open it. Wait a few seconds and refresh Log Entries.
Step 3: Write and run the test
Invalid type: LogEntry__c
The test class's deploy fails with this message when the code names the log object without its namespace prefix.
- On the managed package, use
kern__LogEntry__candkern__FieldName__c(double underscore) for the object and its fields, as the test class in this step does. - If you installed KernDX under your own namespace or without one, change the
kern__prefix in the code as the namespace note at the top of this guide explains.
Tier 3: Production Patterns (~5-10 minutes)
Your own test's query finds no log entries
A test you write yourself asserts on log entries and its query returns zero rows. The test class in Step 3 shows the three things that must all be in place, as Testing with logs explains:
- Logs are suppressed in test context. Set
kern.LOG_Builder.ignoreTestMode = truebefore logging. - The platform events must be delivered before you assert. Call
Test.getEventBus().deliver()after emitting, or assert afterTest.stopTest(). - The query must filter by
kern__UserId__c, notCreatedById. Usekern__LogEntry__c.kern__UserId__c = UserInfo.getUserId().TRG_PersistLogEntryruns as the Automated Process user, soCreatedByIdnever matches the running user.
The log entry has no stack trace
The code passed a String instead of the Exception: .error(error.getMessage()) loses the stack trace. Use .error(error) to pass the Exception object directly, as Exception logging shows.
The log entries have no method context
The call is missing .at() or .emitAt(). Always include .emitAt('Class.method') or .at('Class.method').
A platform-event limit error after many emits
Your org allows 150 immediate event publishes in one transaction.
- Each emit outside a scope is its own publish, so a long loop of emits can use them all up.
- A later publish in the same transaction then fails: a scope's flush, the flush of an error entry, or your own
EventBus.publish. - A scope keeps its entries in one publish. Wrap the emit calls in
kern.LOG_Builder.scope()plus try/finally, as Scoped logging shows.
Test.getEventBus() can only be called from test methods
The line ran outside an @IsTest context, for example in the Execute Anonymous window. Test.getEventBus().deliver() only works inside test methods.
Sensitive data is masked by default
A sensitive value appears raw in a log
The field is not covered by a masking target, or the rule is inactive. Add a kern__MaskingTarget__mdt record with the rule, SObjectType, and field (blank Field__c for a wildcard). See Logging Guide.
Still stuck? Tell us which step and what you saw.
What You Now Know
| Concept | What it does |
|---|---|
kern.LOG_Builder.build() | Starts a log entry you configure with short chained calls |
.info() / .warn() / .error() / .debug() | Sets the log level |
.at('Class.method') | Records where the log came from |
.forRecord(Id) | Links the log entry to a specific record |
.withContext(key, value) | Adds structured key-value data |
.withSummary(message) | Sets a short searchable summary on the entry |
.emitAt('Class.method') | Shorthand for .at().emit() |
.emit() | Publishes the log as a platform event |
LOG_Builder.scope() | Publishes all emits in one batch; keeps you under the platform-event publish limit |
ignoreTestMode = true | Enables logging in test context |
Test.getEventBus().deliver() | Delivers platform events synchronously in tests |
kern__UserId__c | The field to filter on when querying log entries (not CreatedById) |
Key patterns:
- Wrap bulk logging in
LOG_Builder.scope()+ try/finally (batches emits, keeps you under the platform-event publish limit) - Log at method boundaries (entry + exit) for execution tracing
- Always pass
Exceptionobjects, not.getMessage()strings - Use
.forRecord()on every log call to enable record-level filtering - Add
.withContext()for structured data instead of string concatenation - In tests:
ignoreTestMode = true→ emit →Test.getEventBus().deliver()→ query bykern__UserId__c→ assert