> For the complete documentation index, see [llms.txt](https://triton.pharos.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://triton.pharos.ai/core-concepts/buffering-flushing.md).

# Buffering, Flushing & Deferred Publishing

How Triton buffers logs and publishes them as platform events — flush, flushTop, and drain, and why bulkification matters for platform-event limits.

Triton logs are published as **platform events**, and Salesforce puts a ceiling on how many of those you can fire. Buffering is how Triton respects that ceiling: instead of publishing each log the moment you create it, it queues logs in memory and publishes them together. This page explains the buffer, the methods that drain it, and how to buffer without ever losing a log that mattered.

## The buffer

Every `Triton.log(...)` (and every level method like `Triton.info(...)`) adds a log to an in-memory **buffer** — a static queue that lives for the duration of the transaction. Nothing leaves your org until you flush.

{% code lineNumbers="true" %}

```apex
Triton.info(Triton.t.summary('Step 1'));   // buffered
Triton.info(Triton.t.summary('Step 2'));   // buffered
Triton.info(Triton.t.summary('Step 3'));   // buffered
Triton.flush();                            // all three published together
```

{% endcode %}

Publishing three logs as one batch instead of three separate events is the entire game. In a trigger firing across 200 records, the difference between buffering and not buffering can be the difference between one platform event and hundreds.

## The three ways logs leave the buffer

| Method              | Publishes                                                    | Use when                                                                             |
| ------------------- | ------------------------------------------------------------ | ------------------------------------------------------------------------------------ |
| `Triton.flush()`    | **Everything** in the buffer, then clears it                 | You've reached a safe checkpoint and want your queued logs persisted.                |
| `Triton.flushTop()` | Only the **most recent** buffered log                        | You just logged something critical and want *it* out now, without flushing the rest. |
| `Triton.drain()`    | **Nothing** — returns the buffered logs and clears the queue | You want to hand logs off for someone else to publish later (e.g. a Flow batch).     |

`Triton.logNow(...)` is just sugar for "buffer this one, then `flushTop()`" — the convenient way to publish a single log immediately. If a log-level rule filters the log out, nothing is published and the rest of the buffer is left alone:

{% code lineNumbers="true" %}

```apex
Triton.logNow(Triton.t.summary('Critical failure').exception(e));
```

{% endcode %}

### `drain()` and deferred publishing

`drain()` is the newest of the three and exists for a specific problem: high-volume producers (Flows especially) that would otherwise burn platform-event allocations inline. Instead of publishing, they **drain** the buffer and hand the records to a batch that publishes them later, off the hot path. You rarely call `drain()` yourself in Apex — it powers the Flow flush batch. See [Logging in Flow → Deferred Flush & Batching](https://triton.pharos.ai/flows.md) and [End-to-End Logging](https://triton.pharos.ai/end-to-end.md).

## Buffer the routine, publish the critical

Buffering has one catch: **a buffered log only exists in memory until you flush it.** If the transaction throws (or hits a governor limit) before the flush, those queued logs are gone. That leads to a simple, reliable discipline:

* **Buffer the routine.** Progress logs, info, debug — queue them and flush at the end.
* **Publish the critical immediately.** For an exception you must not lose, use `Triton.logNow(...)` so it's persisted before anything else can go wrong.
* **Flush at boundaries.** End of a trigger handler, end of a batch `execute`, before a callout, in `finally` blocks — these are natural flush points.

{% code lineNumbers="true" %}

```apex
try {
    for (Account a : scope) {
        // ... work ...
        Triton.info(Triton.t.summary('Processed ' + a.Id));   // buffered, cheap
    }
    Triton.flush();                                            // publish the batch
} catch (Exception e) {
    Triton.logNow(Triton.t.summary('Batch failed').exception(e));   // never lose this one
}
```

{% endcode %}

{% hint style="warning" %}
**Watch the `finally`.** If there's meaningful risk of an exception between a log and its flush, either move the flush into a `finally` block or publish the important log immediately with `logNow`. A buffered log that never flushes is a log you'll wish you had.
{% endhint %}

## When publishing fails

Logging should never be the reason your code fails, so `Triton.log(...)`, the level methods, `Triton.logNow(...)`, `Triton.flush()`, `Triton.flushTop()`, and the performance-mark methods never throw into the caller. If Pharos can't accept a publish — the running user lacks a license or a permission, for example — the logs in that publish are **dropped**, not retried, and one `ERROR` line naming the failure and the number of logs lost is written to the Apex debug log. Your transaction carries on.

Three things are still yours to handle:

* **Builder arguments run in your code.** Everything inside the parentheses of `Triton.log(...)` is evaluated before Triton is called, so a null dereference there — `Trigger.newMap.keySet()` in a before-insert trigger, say — throws in your code. Keep builder arguments null-safe.
* **Governor limits.** `System.LimitException` can't be caught by any Apex. In bulk code, buffer and flush once at a boundary rather than calling `logNow` in a loop.
* **`Triton.stopTransaction()` with `withCache()` enabled** can still throw, if clearing the cached transaction id fails.

Triton doesn't throttle publishing on its own, so the discipline above — buffer, then flush in bulk at boundaries — is also what keeps you inside your platform-event allocation. For trigger handlers, see [Instrument Apex → Trigger handlers](https://triton.pharos.ai/instrumentation-skills/instrument-apex.md#trigger-handlers-logging-never-fails-the-write).

## Bulk & async notes

* **The buffer is per-transaction.** Because it's static, each Apex transaction starts with an empty buffer and clears at the end — no bleed between transactions.
* **In Batch and Queueable**, each `execute` is its own transaction. Flush within each execution (typically at the end) rather than assuming logs carry across chunks.
* **The same discipline as DML applies.** Think of `flush()` like a DML statement: do it in bulk, at boundaries, and out of loops.

## Related reading

* The methods in context: [The Static Logging API](https://triton.pharos.ai/core-concepts/static-logging-api.md).
* Real patterns for triggers, batches, and queueables: [Logging in Apex](https://triton.pharos.ai/common-apex-usage-patters.md).
* Correlating buffered logs across contexts: [End-to-End Logging](https://triton.pharos.ai/end-to-end.md).
