MetaLens360Help Center

Investigate async Apex failures with Runtime Forensics

Pull failed batch, queueable, future and scheduled Apex jobs from an org, grouped by root cause, with a daily trend, the classes involved and where to look for each cause.

Updated in Monitoring & runtime

Overview

Runtime Forensics answers "why are our background jobs failing?" It reads Salesforce's async job records (batch, queueable, future and scheduled Apex), groups the failures by cause, and shows you how often each cause happens, which classes are involved and where to look first.

Instead of reading hundreds of raw error messages, you see a handful of distinct causes, ranked, with the raw messages one click away.

Before you start

  • Connect the org. Runtime Forensics queries Salesforce live, so the connection must be working.
  • Your Salesforce connection user needs access to view async Apex jobs.

Steps

  1. Open Runtime Forensics under Monitoring, Runtime & Logs.
  2. Set the filters:
    • Org — the org to investigate.
    • Status — defaults to "Failed". Choose All statuses to include other outcomes.
    • Apex class — one class, or All classes.
    • From and To — From defaults to 7 days ago. Times are in your local time zone.
    • Row cap — 200, 2k, 10k or 50k.
  3. Click Fetch.
  4. Read the tiles: Failures, Critical, High, Distinct causes, Apex classes, Peak and Since last failure.
  5. Check Failures per day to see whether a cause started on a specific day — often the day of a deployment.
  6. In Causes (N) — click one to filter, click a cause. Read Where to look and the raw messages behind it.
  7. Click a failure to open its detail: Job id, Status, Ran as, Created and the Raw error, which you can copy.
  8. Read What this cannot tell you before drawing conclusions.
  9. To ignore stored history and query Salesforce again, click Force refresh.

Example

Priya, a release manager, fetches failures for acme-prod over the last 7 days. Distinct causes is 3, and one cause — a row lock on Account — accounts for most failures, all starting the day AccountRollupBatch was deployed. Where to look points at concurrent updates to the same parent records. She copies the raw error into ACME-142 and the team reduces the batch's scope size.

FAQs

Why are times shown in my local time zone?

Every time on the page, including the day buckets, is in your local time zone. Salesforce stores times in UTC, so the failure detail shows the raw UTC timestamp alongside.

What does "Ran as" tell me?

The user who ran the job. Failures concentrated on one user usually point at that person's permissions or data; failures spread across many point at shared configuration or the code.

Does this replace debug logs?

No. It tells you what failed and how often. Use Debug Log Analyzer to see the detail of a single transaction.

Troubleshooting

A warning says the row cap was reached

You hit the Row cap, so every count on the page is a floor, not a total. Narrow the date range or raise the cap and fetch again.

"No async jobs matched these filters…"

That is a clean result for the window you chose. Widen the date range or add statuses if you expected failures.

Recent failures are missing

Click Force refresh to re-query Salesforce instead of relying on stored history.

Fetch fails with an authentication error

The org's credentials may have expired. Reconnect it from Connections and try again.

Was this article helpful?

Related articles