> 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/triton-best-practices/log-levels-and-usage.md).

# Log Levels: When to Use What

Choosing the right log level for each situation — and using Log\_Level\_\_mdt to turn the volume up in a sandbox and down in production without touching code.

The mechanics of levels — the seven-value scale and how `Log_Level__mdt` filters them at runtime — live in [Core Concepts → Log Levels](https://triton.pharos.ai/core-concepts/log-levels.md). This page is about the judgment call: given a specific thing that just happened in your code, which level does it deserve?

Get this wrong in one direction and you drown real problems in trivia. Get it wrong in the other and the log you needed at 2am was filtered out in production. So it's worth being deliberate.

## The decision, in one table

| Level                     | Reach for it when…                           | Real examples                                                                               | Don't use it for…                                        |
| ------------------------- | -------------------------------------------- | ------------------------------------------------------------------------------------------- | -------------------------------------------------------- |
| **ERROR**                 | Something failed that a human should look at | Uncaught exception, failed callout, broken invariant, DML that lost data                    | Expected/benign conditions ("no records to process")     |
| **WARNING**               | Something recoverable or suspicious happened | Retry after a timeout, partial DML failure, fallback path taken, governor limit approaching | Every retry attempt — one warning per *distinct* problem |
| **INFO**                  | A notable business event completed           | "Order placed", "Batch finished: 240 processed", "12 leads converted"                       | Per-record chatter inside a loop                         |
| **DEBUG**                 | Developer detail useful while diagnosing     | Branch decisions, query shapes, intermediate state                                          | Anything you'd be embarrassed to leave on in prod        |
| **FINE / FINER / FINEST** | Increasingly verbose tracing                 | Loop-body detail, payload snippets, micro-timing                                            | The signal you actually want in production               |

{% hint style="info" %}
**The one-sentence heuristic:** if you'd want to see it in production, it's `INFO` or higher; if it only helps while you're actively debugging, it's `DEBUG` or below. `ERROR` is reserved for "wake someone up" — if everything is an error, nothing is.
{% endhint %}

## A worked example: a processing batch

Notice how one method spans four levels — routine progress buffered at `INFO`, a per-record diagnostic at `FINE` (invisible in prod, available on demand), and the failure published immediately at `ERROR`.

{% code lineNumbers="true" %}

```apex
public class OrderProcessingBatch implements Database.Batchable<SObject> {
    public void execute(Database.BatchableContext bc, List<Order> scope) {
        Long startTime = System.now().getTime();

        Triton.setTemplate(Triton.makeBuilder()
            .category(TritonTypes.Category.Apex)
            .area(TritonTypes.Area.OpportunityManagement));

        // INFO — a business milestone worth seeing in production
        Triton.info(Triton.t.summary('Processing order batch').details('batchSize=' + scope.size()));

        try {
            for (Order ord : scope) {
                // FINE — per-record trace, filtered out in prod, switch on when investigating
                Triton.fine(Triton.t
                    .summary('Processing order')
                    .details('status=' + ord.Status)
                    .relatedObject(ord.Id));
                processOrder(ord);
            }

            // INFO — completion with a duration you can trend
            Triton.info(Triton.t
                .summary('Order batch completed')
                .details('processed=' + scope.size())
                .duration(System.now().getTime() - startTime));

        } catch (Exception e) {
            // ERROR — publish immediately so a mid-batch failure is never lost
            Triton.logNow(Triton.t
                .exception(e)
                .relatedObjects(new Map<Id, Order>(scope).keySet()));
            throw e;
        } finally {
            Triton.flush();   // publish the buffered INFO/FINE logs together
        }
    }
}
```

{% endcode %}

A few things to note about the 2.0 API here: `Triton.info(...)` and `Triton.fine(...)` **buffer** — they don't publish until `flush()`. `.exception(e)` sets the level to `ERROR` for you (no `.error()` needed), and `Triton.logNow(...)` gets that failure out immediately. See [Buffering & Flushing](https://triton.pharos.ai/triton-best-practices/buffering-and-flushing.md) for why the split matters.

## Level, by intent

If you're unsure, match the *intent* of the log to a level:

* **"A person needs to act on this."** → `ERROR`. Exceptions, integration failures that break a process, data integrity problems.
* **"This is off, but we handled it."** → `WARNING`. Fallbacks, retries, partial failures, nearing a governor limit. One warning per distinct condition — don't spam.
* **"This is the story of what the system did."** → `INFO`. Lifecycle events and business milestones: jobs started/finished, records created, conversions completed. This is your production baseline.
* **"I'm explaining a decision to my future self."** → `DEBUG`. Which branch ran, what a query returned, why a value was chosen.
* **"I need the firehose."** → `FINE` / `FINER` / `FINEST`. Loop bodies, payload dumps, step-by-step traces. Cheap to leave in code because filtering keeps them out of prod.

## Tuning by environment — through metadata, not code

Because `Log_Level__mdt` sets thresholds per environment, you don't hard-code environment behavior — you deploy different metadata. A practical baseline:

| Environment              | Typical threshold                             | Why                                                                     |
| ------------------------ | --------------------------------------------- | ----------------------------------------------------------------------- |
| Dev / scratch            | `FINE` or `FINEST`                            | See everything while you build.                                         |
| QA / staging             | `INFO`                                        | Production-like signal, still enough to investigate.                    |
| Production               | `INFO` (or `WARNING` for very chatty areas)   | Business events and problems, minimal noise.                            |
| Production, mid-incident | temporarily `FINE` for one Category/Type/Area | Turn the firehose on for *just* the flaky area, then turn it back down. |

That last row is the payoff of doing this right: when an integration starts misbehaving, you bump the threshold for that integration's Area to `FINE`, capture a few detailed traces, and drop it back — all without a deploy of Apex. For the full precedence rules, see [Core Concepts → Log Levels](https://triton.pharos.ai/core-concepts/log-levels.md).

{% hint style="warning" %}
**`ERROR` should never be filtered out.** Don't configure a `Log_Level__mdt` threshold below `ERROR` for a slice of logs that can actually fail — you'd be dropping the exact records you'll wish you had. When in doubt, keep the floor at `ERROR`/`WARNING` in production.
{% endhint %}

## Related reading

* The filtering mechanics and precedence order: [Core Concepts → Log Levels](https://triton.pharos.ai/core-concepts/log-levels.md).
* How level ties into the classification fields: [Taxonomy & Standards](https://triton.pharos.ai/triton-best-practices/taxonomy-and-standards.md).
