For the complete documentation index, see llms.txt. This page is also available as Markdown.

Performance Marks

Time any stretch of Apex with startMark / endMark — names derived from the stack trace, automatic nesting, and every log inside the mark parented to it.

Timing a piece of Apex used to mean a stopwatch you wrote yourself: a Long before, a subtraction after, and a .duration(...) on the log. Marks replace that with two calls that also build a span tree — and they don't ask you to type a name.

public void recalculateForecast() {
    Triton.startMark();
    try {
        // ... the work being measured ...
    } finally {
        Triton.endMark();
    }
}

That's the whole idiom. The mark is named ForecastService.recalculateForecast — derived from the stack trace Triton already captures — and it emits a pair of records: one when it opens, one when it closes carrying the elapsed milliseconds.

This is the Apex counterpart of the LWC Custom Performance Marks. Same concept, same record shape, so a trace that starts in the browser and lands in Apex reads as one tree.

Naming: derived by default

startMark() takes no arguments on purpose. The class and method are already in the stack trace, so making you retype them just creates strings that drift — a renamed method leaves a mark (and any Log_Level__mdt rule pointing at it) quietly stale. A derived name cannot drift.

It returns the derived name, which is handy when you need to close out of order:

String mark = Triton.startMark();     // → 'ForecastService.recalculateForecast'

When the meaningful name simply isn't a method name, supply one:

Triton.startMark('nightly-reconcile');
Triton.startMark('chunk-3-of-40');

Use the explicit form for a name the framework can't know, or when you want to measure one method in several labelled segments.

startMark(String) is not a performance escape hatch. Both forms capture the stack once — the records need a trace regardless — so supplying a name skips only a short string parse, not the capture. Pick whichever reads better; they cost effectively the same. If derivation can't produce a name, the mark falls back to AnonymousMark plus a counter, so it still nests and is still identifiable.

Nesting

Marks form a stack. endMark() closes the innermost open mark, whatever it's called — which is why the finally block never has to name anything, and can't silently no-op on a typo:

For work that legitimately finishes out of order — opened in one method, closed in another — close by name with endMark(String); it closes the newest open mark carrying that name.

clearMarks() discards every open mark and resets to the request root. Call it when you want that reset explicitly — startTransaction() does not clear marks while one is open, and you do not need clearMarks() at the top of a batch chunk or a queueable (see Async and batch). It's there for deliberate recovery to a known-good state.

Trigger handlers

startTriggerMark() is the one shorthand, and it exists for one reason: Trigger.operationType is the single piece of naming information a stack trace cannot carry. BEFORE_UPDATE and AFTER_UPDATE run the same method from the same frame, so without it a trigger cascade collapses into one indistinguishable span.

Zero arguments — the handler class comes from the stack trace, the context from Trigger.operationType. Put it in your base handler's dispatch method and every handler in the org is instrumented without touching one of them. Called outside trigger context, there's no operation to append, so it produces the same <Class>.<method> name startMark() would — it is exactly startMark() at that point, safe to leave in a method that's also reachable outside a trigger.

There is no boundary method and no batch method. A request boundary is startMark() at the top of the endpoint; a batch phase is startMark() at the top of execute(). Depth is a fact the framework already knows, not something you declare — the outermost mark parents to the transaction automatically.

What gets logged

A mark emits two records — one on open, one on close — so a transaction that dies mid-mark still shows the work having started.

Field
Opening record
Completion record

Summary

Performance started: <mark>

Performance: <mark>

Details

(unset)

Duration: <n>ms

Type

Performance

Performance

Action

<mark>

<mark>

Duration

(unset)

the elapsed milliseconds

Span_Id__c

the mark's span

the same span

Parent_Span_Id__c

the enclosing span

the same enclosing span

Stack trace

the startMark() call site

the same trace, not endMark()'s frame

Level

FINE

FINE

Category / Area

inherited from Triton.t

inherited from Triton.t

Both halves are built from your template, so an entry point that sets an Area gets it on its marks for free. Both carry the opening call site's stack trace: they describe the same span, and where the two genuinely differ — an out-of-order close from another method — the opening frame is the more useful one, because that's where the measured work began.

The opening record omits governor-limit info (it has no duration and no deltas worth having); the completion record keeps it.

Levels are a rule, not an argument

Marks always log at FINE. There is deliberately no level parameter, because a level baked into a call site overrides the Log_Level__mdt rule an admin is supposed to control without a deploy — the opposite of how the rest of Triton works. To turn marks on for one class, write the rule:

Field
Value

Component

ForecastService

Level

FINE

Every other field left blank is a wildcard, so that record targets ForecastService logs in any category, type, or area. See Log Levels (resolution rules) for how competing rules resolve.

Logs inside a mark become children of it

This is the part that turns marks from a stopwatch into a trace. While a mark is open, every ordinary log you emit is parented to it:

You write nothing extra. The outermost mark parents to the transaction span; a nested mark parents to the mark enclosing it; ordinary logs become leaves under whichever mark is innermost. Full model in Spans & Distributed Tracing.

An id you set yourself always wins. If you call .spanId(...) or .parentSpanId(...) on a builder, marks never overwrite it. That's what keeps an LWC → Apex trace intact: the ids the browser forwarded stay exactly as they arrived.

Filtered-out marks stay transparent

If a Log_Level__mdt rule rejects a mark's opening record, the mark doesn't leave a hole behind it. Its children re-parent to the nearest surviving ancestor instead of pointing at a span that was never published — so dialling a class down thins the tree rather than orphaning it.

Marks never flush

startMark() and endMark() use the buffered path, exactly like Triton.log(). No mark method ever publishes a platform event, so a mark opened and closed inside a loop adds two buffered records per iteration and nothing else. Your existing flush points stay yours.

Async and batch

Apex statics don't survive a batch chunk, a Queueable, or a @future, and the mark stack is a static. That's fine — each async unit starts clean and becomes its own subtree under the shared transaction, which is what you want anyway.

The whole batch idiom is two calls you already have:

The phase is the method name, so startMark() derives LeadsBatch.execute for free — there's no batch-specific method to learn. clearMarks() isn't needed here: a fresh execution context already starts with an empty stack. Carrying the transaction id across chunks is still Database.Stateful plus an instance field, unchanged — see Batch Logging.

Opting in

Marks change nothing until you add one. A transaction with no open mark produces byte-identical span fields to before.

Do / Don't

Last updated