> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fusioncore.us/llms.txt
> Use this file to discover all available pages before exploring further.

# Logging

> Structured logging with FCORE_BASE.Logger: log levels, the commit-by-DML vs commit-by-platform-event choice, and the canonical try/catch pattern.

`FCORE_BASE.Logger` is the Platform package's structured logger, available to every package under the `FCORE_BASE` namespace. It provides structured logging for exceptions, custom messages, and HTTP callouts. Each log persists to the `Log__c` object.

A log is collected in memory and then committed in one of two ways:

* **By DML** — written directly to `Log__c` in the current transaction.
* **By platform event** — published as a `Log_Event__e` platform event, which a subscriber persists. Because the platform event is delivered independently of the current transaction, this option survives a rollback. Use it whenever the surrounding transaction may roll back (for example, when you log an exception and then rethrow it).

Most commit-style methods take a final `Boolean shouldCommitByDML` argument: pass `true` to commit by DML, or `false` to commit by platform event.

## Log Levels

The level is the `FCORE_BASE.Logger.LogLevel` enum:

| Level    | Use for                                                         |
| -------- | --------------------------------------------------------------- |
| `ERROR`  | Caught exceptions and failures.                                 |
| `WARN`   | Recoverable problems or unexpected-but-handled states.          |
| `INFO`   | Notable, expected milestones.                                   |
| `DEBUG`  | Verbose diagnostic detail.                                      |
| `ACTION` | A user- or system-initiated action you want an audit trail for. |

## Always Set the Execution Context First

Call `FCORE_BASE.Logger.setApexExecutionContext(Type classType, String methodName)` before you log so that the originating class and method are recorded on the log:

```java theme={null}
FCORE_BASE.Logger.setApexExecutionContext(MyClass.class, 'doWork');
```

## Methods

All `Logger` methods are `global static`.

| Purpose                                                         | Signature                                                                                                                |
| --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| Set the class/method recorded on subsequent logs                | `setApexExecutionContext(Type classType, String methodName)`                                                             |
| Log an exception and commit                                     | `logAndCommit(Exception ex, LogLevel logLevel, List<Id> recordIds, Boolean shouldCommitByDML)`                           |
| Log a callout and commit                                        | `logAndCommit(CalloutLogWrapper calloutLogWrapper, LogLevel logLevel, List<Id> recordIds, Boolean shouldCommitByDML)`    |
| Log a message (collect only)                                    | `log(String message, LogLevel logLevel, List<Id> recordIds, String action)`                                              |
| Log an exception (collect only)                                 | `log(Exception ex, LogLevel logLevel, List<Id> recordIds)`                                                               |
| Log an HTTP callout (collect only)                              | `log(CalloutLogWrapper calloutLogWrapper, LogLevel logLevel, List<Id> recordIds)`                                        |
| Log an action with a message                                    | `logAction(String action, String message, List<Id> recordIds)`                                                           |
| Log an exception, return a correlation context                  | `logWithContext(Exception ex, LogLevel logLevel, List<Id> recordIds)` → `LogContext`                                     |
| Log an exception, commit, return a correlation context          | `logAndCommitWithContext(Exception ex, LogLevel logLevel, List<Id> recordIds, Boolean shouldCommitByDML)` → `LogContext` |
| Flush logs collected by the non-committing `log(...)` overloads | `commitLogs(Boolean shouldCommitByDML)`                                                                                  |

<Note>
  The message overload of `log` requires the fourth `action` argument — there is no three-argument message overload. The `logWithContext` correlation variant exists only for an `Exception` (there is no message or callout overload).
</Note>

## Collect Versus Commit

The plain `log(...)` overloads only collect a log in memory; nothing is written until you call `commitLogs(Boolean shouldCommitByDML)`. This lets you batch several logs and flush them once. The `logAndCommit(...)` overloads collect and commit in a single call.

## Inner Classes

* `Logger.CalloutLogWrapper` wraps an HTTP request/response pair so you can log the request and response bodies and the status. Construct it with `CalloutLogWrapper(HttpRequest request, HttpResponse response)`, then pass it to a callout `log` or `logAndCommit` overload.
* `Logger.LogContext` is returned by the `...WithContext` methods. It carries a `uuid` String you can hand back to a user or to another system so they can correlate that reference with the stored `Log__c` record.

## Canonical Try/Catch Pattern

When you catch an exception, log it by platform event (so the entry survives the rollback) and then rethrow:

```java theme={null}
public void doWork(List<Id> recordIds) {
    FCORE_BASE.Logger.setApexExecutionContext(MyClass.class, 'doWork');
    try {
        // ... business logic ...
    } catch (Exception ex) {
        // shouldCommitByDML = false → commit by platform event, survives rollback
        FCORE_BASE.Logger.logAndCommit(
            ex,
            FCORE_BASE.Logger.LogLevel.ERROR,
            recordIds,
            false
        );
        throw ex;
    }
}
```

## Logging an HTTP Callout

```java theme={null}
HttpRequest request = new HttpRequest();
// ... configure request ...
HttpResponse response = new Http().send(request);

FCORE_BASE.Logger.CalloutLogWrapper calloutLog =
    new FCORE_BASE.Logger.CalloutLogWrapper(request, response);

FCORE_BASE.Logger.logAndCommit(
    calloutLog,
    FCORE_BASE.Logger.LogLevel.INFO,
    new List<Id>(),
    false
);
```