> 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/static-logging-api.md).

# The Static Logging API

How Triton 2.0's static, builder-first API works — log methods, immediate vs buffered logging, level shorthands, and the transaction state kept for you.

In Triton 2.0 you talk to the logger through the `Triton` class directly. There's no logger to instantiate, no instance to pass around, and no singleton to fetch — you just call `Triton`:

{% code lineNumbers="true" %}

```apex
Triton.error(Triton.t.summary('Payment capture failed').exception(e));
```

{% endcode %}

This page covers the whole surface: how logs get built and sent, the difference between buffered and immediate logging, the convenience level methods, and — importantly — where all the state actually lives now that there's no instance.

## Building and sending a log

Every log follows the same shape: **build a description, hand it to a `Triton` method.** The builder describes *what* to log; the `Triton` method decides *how* (which level, buffered or immediate).

{% code lineNumbers="true" %}

```apex
Triton.log(Triton.makeBuilder()
    .type(TritonTypes.Type.Backend)
    .area(TritonTypes.Area.OpportunityManagement)
    .summary('Synced opportunity to ERP')
    .level(TritonTypes.Level.INFO));
```

{% endcode %}

You'll almost always start the builder with `Triton.makeBuilder()` (a fresh builder, pre-set to the `Apex` category) or `Triton.t` (a builder cloned from your [template](https://triton.pharos.ai/core-concepts/builder-and-templates.md)). More on both below.

## Buffered vs immediate

This is the one distinction worth internalizing. Triton can either **queue** a log for later or **publish** it right now.

| You want to…                          | Call                     | What happens                                                   |
| ------------------------------------- | ------------------------ | -------------------------------------------------------------- |
| Queue a log to publish later, in bulk | `Triton.log(builder)`    | Added to the buffer. Nothing is published until you `flush()`. |
| Publish a log right now               | `Triton.logNow(builder)` | Added to the buffer **and** flushed immediately.               |

{% code lineNumbers="true" %}

```apex
// Buffered — cheap, batched, published on flush()
Triton.log(Triton.t.summary('Step 1 complete'));
Triton.log(Triton.t.summary('Step 2 complete'));
Triton.flush();               // both published together, one platform event batch

// Immediate — published on the spot
Triton.logNow(Triton.t.summary('Critical failure').exception(e));
```

{% endcode %}

Why does this matter? Salesforce caps how many platform events you can publish, and every published log consumes an allocation. Buffering lets you publish many logs in one batch instead of one at a time. The trade-off: buffered logs are only in memory until you flush, so if the transaction dies first, they're lost. The rule of thumb — **buffer the routine, publish the critical immediately** — is covered in depth in [Buffering, Flushing & Deferred Publishing](https://triton.pharos.ai/core-concepts/buffering-flushing.md).

## The convenience level methods

Setting `.level(TritonTypes.Level.ERROR)` on every builder gets old fast, so `Triton` gives you a method per level. Each one applies the level for you and buffers the log:

{% code lineNumbers="true" %}

```apex
Triton.error(builder);     // same as Triton.log(builder.error())
Triton.warning(builder);
Triton.info(builder);
Triton.debug(builder);
Triton.fine(builder);
Triton.finer(builder);
Triton.finest(builder);
```

{% endcode %}

So these two lines are identical:

{% code lineNumbers="true" %}

```apex
Triton.log(Triton.t.summary('Retrying').level(TritonTypes.Level.WARNING));
Triton.warning(Triton.t.summary('Retrying'));
```

{% endcode %}

There's no `Triton.errorNow(...)` — for immediate publishing at a specific level, set the level on the builder and call `logNow`:

{% code lineNumbers="true" %}

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

{% endcode %}

## Where the state lives now

If there's no instance, where does the buffer live? Where does the transaction id live? On the `Triton` class itself, as **static state that persists for the entire Apex transaction**. Everything you log during a transaction accumulates in the same place — one buffer, one transaction id, one template — held as `static` members:

* **The buffer** — a static list of pending logs, shared by every `Triton.log(...)` call in the transaction.
* **The transaction id** — a static `Triton.TRANSACTION_ID`, so all your logs correlate automatically.
* **The template** — a static builder you set once and reuse via `Triton.t`.
* **The underlying Pharos logger** — lazily initialized and reused.
* **Log-level config** — loaded once from `Log_Level__mdt` custom metadata.

Because Apex statics live for the duration of a single transaction, this gives you a "one logger, shared context" model with nothing to pass around. When the transaction ends, the statics reset, so there's no bleed between transactions.

{% hint style="info" %}
**Bulk / async note:** because the buffer is static per-transaction, the usual bulkification discipline applies — buffer as much as you can, then flush at safe boundaries. In async contexts (Batch, Queueable) each execution is its own transaction with its own fresh statics. See [Logging in Apex → Batch Logging](https://triton.pharos.ai/common-apex-usage-patters/batch-logging.md).
{% endhint %}

{% hint style="info" %}
Upgrading existing code that used `Triton.instance`? See the [Migrating from 1.x](https://triton.pharos.ai/migration.md) guide.
{% endhint %}

## Quick reference

{% code lineNumbers="true" %}

```apex
// Build
Triton.makeBuilder()            // fresh builder, category = Apex
Triton.t                        // builder cloned from the template (+ current transaction id)

// Buffer
Triton.log(builder)             // buffer at the builder's level
Triton.error(builder)           // buffer at ERROR  (also: warning/info/debug/fine/finer/finest)

// Publish
Triton.logNow(builder)          // buffer + flush this log now
Triton.flush()                  // publish everything buffered
Triton.flushTop()               // publish only the most recent buffered log
Triton.drain()                  // hand off the buffer without publishing (for batching)
// log, the level methods, logNow, flush, and flushTop never throw:
// a log that can't be published is dropped and noted in the Apex debug log

// Marks (buffered, logged at FINE)
Triton.startMark()              // open a timed span named <Class>.<method> from the stack trace
Triton.startTriggerMark()       // same, named <Handler>.<Trigger.operationType>
Triton.endMark()                // close the innermost open mark (call it in a finally)
Triton.clearMarks()             // discard open marks and reset to the request root

// Transactions
Triton.startTransaction()       // begin a correlation id
Triton.resumeTransaction(id)    // adopt an existing id
Triton.stopTransaction()        // clear it
Triton.withCache()              // back transaction state with platform cache
```

{% endcode %}
