> 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/methods-reference/apex-methods-reference/triton.md).

# Triton

The Triton class is the static entry point for all logging — builder creation, buffered and immediate logging, transaction management, and log-level filtering.

The `Triton` class exposes a fully **static** API. There is no instance to manage — every operation is a class method or property. A typical call chains a builder (created from a template) into one of the log methods:

{% code lineNumbers="true" %}

```apex
Triton.info(Triton.t
    .summary('Order placed')
    .details('Order 12345 processed'));
Triton.flush();
```

{% endcode %}

{% hint style="info" %}
**Logging never throws into your code.** `log`, the level methods, `logNow`, `flush`, `flushTop`, and the mark methods catch their own failures: a log that can't be built or published is dropped, and the failure is written to the Apex debug log at `ERROR`. A builder argument is evaluated in your code before Triton runs, so Triton can't catch what throws there, and `System.LimitException` can't be caught by any Apex. [`stopTransaction()`](#stoptransaction) can still throw when `withCache()` is enabled. See [When publishing fails](https://triton.pharos.ai/core-concepts/buffering-flushing.md#when-publishing-fails).
{% endhint %}

## Builder Creation

### makeBuilder()

{% code lineNumbers="true" %}

```apex
public static TritonBuilder makeBuilder()
```

{% endcode %}

Creates a new [`TritonBuilder`](https://triton.pharos.ai/methods-reference/apex-methods-reference/tritonbuilder.md) with the category defaulted to `Apex`.

**Returns:**

* A new `TritonBuilder` instance

### t

{% code lineNumbers="true" %}

```apex
public static TritonBuilder t { get; }
```

{% endcode %}

Shorthand property for [`fromTemplate()`](#fromtemplate). Returns a copy of the current template builder, stamped with the active transaction ID.

**Example:**

{% code lineNumbers="true" %}

```apex
Triton.log(Triton.t.summary('test').details('test'));
```

{% endcode %}

### fromTemplate()

{% code lineNumbers="true" %}

```apex
public static TritonBuilder fromTemplate()
```

{% endcode %}

Returns a clone of the currently saved template builder, with the active transaction ID applied. If no template was set, a default builder is used.

**Returns:**

* A `TritonBuilder` copy of the template

### setTemplate(TritonBuilder builder)

{% code lineNumbers="true" %}

```apex
public static void setTemplate(TritonBuilder builder)
```

{% endcode %}

Stores a builder to be reused as the base for [`fromTemplate()`](#fromtemplate) / [`Triton.t`](#t). Use this to set common attributes (category, area, post-processing) once per transaction.

**Parameters:**

* `builder` -- the `TritonBuilder` to use as a template

**Example:**

{% code lineNumbers="true" %}

```apex
Triton.setTemplate(Triton.makeBuilder()
    .area(TritonTypes.Area.OpportunityManagement)
    .level(TritonTypes.Level.INFO));
```

{% endcode %}

### makePostProcessingBuilder()

{% code lineNumbers="true" %}

```apex
public static TritonHelper.PostProcessingControlsBuilder makePostProcessingBuilder()
```

{% endcode %}

Creates a new [`PostProcessingControlsBuilder`](https://triton.pharos.ai/methods-reference/apex-methods-reference/tritonhelper/postprocessingcontrolsbuilder.md) for configuring Pharos post-processing flags.

**Returns:**

* A new `TritonHelper.PostProcessingControlsBuilder` instance

## Logging Methods

Logs are added to an internal buffer and persisted on [`flush()`](#flush). Each level method overrides the builder's level and then buffers the log.

### log(TritonBuilder builder)

{% code lineNumbers="true" %}

```apex
public static void log(TritonBuilder builder)
```

{% endcode %}

Adds a log to the buffer using the builder's own level. The log is skipped if it fails the current [log-level filter](https://triton.pharos.ai/core-concepts/log-levels.md) (see [`TritonHelper.Config.isLogAllowed`](https://triton.pharos.ai/methods-reference/apex-methods-reference/tritonhelper.md#islogallowed)). Stack trace, operation, tracepoint, and limit info are auto-captured at this point.

**Parameters:**

* `builder` -- a configured `TritonBuilder`

**Example:**

{% code lineNumbers="true" %}

```apex
Triton.log(Triton.t
    .type(TritonTypes.Type.Backend)
    .area(TritonTypes.Area.Accounts)
    .summary('Process completed')
    .level(TritonTypes.Level.INFO));
```

{% endcode %}

### logNow(TritonBuilder builder)

{% code lineNumbers="true" %}

```apex
public static void logNow(TritonBuilder builder)
```

{% endcode %}

Buffers the log and immediately flushes it (equivalent to `log()` followed by [`flushTop()`](#flushtop)). Use for critical logs that must persist right away. If a log-level rule filters the log out, nothing is published and the rest of the buffer is left untouched.

**Parameters:**

* `builder` -- a configured `TritonBuilder`

**Example:**

{% code lineNumbers="true" %}

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

{% endcode %}

### error / warning / info / debug / fine / finer / finest (TritonBuilder builder)

{% code lineNumbers="true" %}

```apex
public static void error(TritonBuilder builder)
public static void warning(TritonBuilder builder)
public static void info(TritonBuilder builder)
public static void debug(TritonBuilder builder)
public static void fine(TritonBuilder builder)
public static void finer(TritonBuilder builder)
public static void finest(TritonBuilder builder)
```

{% endcode %}

Convenience methods that override the builder's level to the corresponding [`Level`](https://triton.pharos.ai/core-concepts/log-levels.md) and buffer the log. `error()` also flags the log to create an issue. An issue implied by an error — from `error()`, `.exception(e)`, or a failed `.dmlResults(...)` — is withdrawn when the final level is below ERROR, so `Triton.warning(Triton.t.exception(e))` records the exception at WARNING with no issue. An explicit `.createIssue()` always stands.

**Parameters:**

* `builder` -- a configured `TritonBuilder`

**Example:**

{% code lineNumbers="true" %}

```apex
Triton.info(Triton.t.summary('Fetching items'));
Triton.error(Triton.t.summary('Failed').exception(e));
```

{% endcode %}

## Buffer Management

### flush()

{% code lineNumbers="true" %}

```apex
public static void flush()
```

{% endcode %}

Publishes every buffered log in one flush and clears the buffer. No-op when the buffer is empty. Never throws: if publishing fails, the buffered logs are dropped (not re-queued) and the failure is written to the Apex debug log at `ERROR`.

### flushTop()

{% code lineNumbers="true" %}

```apex
public static void flushTop()
```

{% endcode %}

Publishes only the most recently buffered log and removes it from the buffer. No-op when the buffer is empty. Never throws; a failed publish drops that one log and leaves the older ones buffered.

### drain()

{% code lineNumbers="true" %}

```apex
public static List<pharos__Log__c> drain()
```

{% endcode %}

Returns all buffered logs and clears the internal buffer **without** publishing them. Used by [`TritonFlow`](https://triton.pharos.ai/methods-reference/apex-methods-reference/tritonflow.md) to hand logs off to the deferred flush batch.

**Returns:**

* A `List<pharos__Log__c>` of the buffered log records

## Transaction Methods

A transaction ties together logs across multiple Salesforce contexts (Apex, LWC, Flow). It is identified by an auto-generated UUID stored in the static `Triton.TRANSACTION_ID`.

### startTransaction()

{% code lineNumbers="true" %}

```apex
public static String startTransaction()
```

{% endcode %}

Starts a new transaction with an auto-generated UUID. When platform cache is enabled, the ID is also cached. The span hierarchy resets to the request root **only when no** [**performance mark**](https://triton.pharos.ai/common-apex-usage-patters/performance-marks.md) **is open** — an open mark survives `startTransaction()`, so an LWC log save or a Flow **Log** action firing inside a mark can't destroy it or lose its unwritten completion record.

**Returns:**

* The new transaction ID

### resumeTransaction(String transactionId)

{% code lineNumbers="true" %}

```apex
public static void resumeTransaction(String transactionId)
```

{% endcode %}

Resumes an existing transaction. Use this to correlate logs across different Salesforce transactions.

**Parameters:**

* `transactionId` -- an existing transaction ID to resume

### stopTransaction()

{% code lineNumbers="true" %}

```apex
public static void stopTransaction()
```

{% endcode %}

Ends the current transaction and resets `Triton.TRANSACTION_ID`. Clears the cached ID when platform cache is enabled. Unlike the logging methods, this one is not guarded: with cache enabled, a failure clearing the cached ID is thrown to the caller.

### withCache()

{% code lineNumbers="true" %}

```apex
public static void withCache()
```

{% endcode %}

Enables Salesforce Platform Cache for transaction management. When available, the current transaction ID is resumed from (or written to) the Org cache so it survives across LWC/Apex/Flow round-trips and asynchronous jobs. Falls back to a plain in-memory transaction when cache is unavailable.

## Performance Marks

A **mark** times a stretch of Apex, emits a paired set of `Performance` records, and parents every log created inside it to that mark. Marks nest LIFO. See [Performance Marks in Apex](https://triton.pharos.ai/common-apex-usage-patters/performance-marks.md) for the full pattern.

Marks always log at `FINE` and always use the buffered path — no mark method flushes. There is no `level` parameter by design: verbosity is controlled by [`Log_Level__mdt`](https://triton.pharos.ai/core-concepts/log-levels.md), not by the call site.

### startMark()

{% code lineNumbers="true" %}

```apex
public static String startMark()
```

{% endcode %}

Opens a mark whose name is **derived from the stack trace** as `<Class>.<method>`, mints a span id, parents it to the enclosing span (the transaction when nothing else is open), and emits the opening record. Falls back to `AnonymousMark` plus a counter when a name can't be derived.

**Returns:**

* The derived mark name — pass it to [`endMark(String)`](#endmark-string-markname) if you need an out-of-order close

**Example:**

{% code lineNumbers="true" %}

```apex
Triton.startMark();
try {
    recalculate();
} finally {
    Triton.endMark();
}
```

{% endcode %}

### startMark(String markName)

{% code lineNumbers="true" %}

```apex
public static String startMark(String markName)
```

{% endcode %}

As [`startMark()`](#startmark), with the name supplied. Use it when the meaningful name isn't a method name, or to measure one method in several labelled segments. It is **not** a performance escape hatch — both forms cost effectively the same.

**Parameters:**

* `markName` -- the name for this mark

**Returns:**

* The mark name

**Example:**

{% code lineNumbers="true" %}

```apex
Triton.startMark('nightly-reconcile');
```

{% endcode %}

### endMark()

{% code lineNumbers="true" %}

```apex
public static void endMark()
```

{% endcode %}

Closes the innermost open mark, whatever it's called: computes the elapsed milliseconds, pops the span, and emits the completion record. Call it from a `finally` block. No-op when no mark is open.

### endMark(String markName)

{% code lineNumbers="true" %}

```apex
public static void endMark(String markName)
```

{% endcode %}

Closes the newest open mark with that name, for work that legitimately finishes out of order. A blank name, or one matching no open mark, is ignored — instrumentation never throws into business logic.

**Parameters:**

* `markName` -- the name of the mark to close

### clearMarks()

{% code lineNumbers="true" %}

```apex
public static void clearMarks()
```

{% endcode %}

Discards all open marks and resets the span stack to the request root. Call it explicitly when you want that reset: [`startTransaction()`](#starttransaction) does **not** clear marks while one is open. Not needed at the top of a batch chunk, `Queueable`, or `@future` — a fresh execution context already starts with an empty stack.

### startTriggerMark()

{% code lineNumbers="true" %}

```apex
public static String startTriggerMark()
```

{% endcode %}

Opens a mark named `<Handler>.<Trigger.operationType>` — for example `OpportunityHandler.BEFORE_UPDATE`. The handler class comes from the stack trace; the context comes from `Trigger.operationType`, which is the one naming detail a stack trace can't carry. Outside trigger context it behaves exactly like [`startMark()`](#startmark).

**Returns:**

* The mark name

**Example:**

{% code lineNumbers="true" %}

```apex
Triton.startTriggerMark();
try {
    dispatch();
} finally {
    Triton.endMark();
}
```

{% endcode %}

## Log-Level Filtering

Whether a log passes the `Log_Level__mdt` rules is decided by [`TritonHelper.Config.isLogAllowed(log)`](https://triton.pharos.ai/methods-reference/apex-methods-reference/tritonhelper.md#islogallowed), which `log()` calls before buffering. See [Log Levels](https://triton.pharos.ai/core-concepts/log-levels.md) for how rules are scoped and resolved.

## Constants

| Constant                | Description                                                                                                        |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------ |
| `Triton.TRANSACTION_ID` | The current transaction ID (`String`). Passed around to trace a process spanning multiple Salesforce transactions. |
| `Triton.SPACE_SEP`      | Separator (`'\n\n'`) used when concatenating details fragments.                                                    |
