Failure atlas
The Atlas view is a map of your failing sessions. Each dot is one session, placed by how similar its failure is to the others. Each cluster forms an island. Use it to see whether your clusters are really distinct, to find pairs that should be merged, and to spot failures too sparse to form a cluster yet.
At a glance
| Where it lives | Diagnose → Failure Modes → Atlas |
| Key API route | GET /clusters/atlas |
| What it needs | A completed clustering run. The map is drawn from the most recent one |
| Time window | None. The atlas shows the latest clustering run, whatever the page’s time picker says |
| Scope | Per agent |
Read the atlas
- Dots are failing sessions from the latest clustering run. A cluster’s dots are drawn inside an outline, which makes an island.
- Hollow dots are unclustered sessions: failures with no close neighbours. Clustering treats them as noise because there are too few similar sessions to form a cluster yet.
- Dashed links join two islands that are close enough to review for a merge.
- Colour follows the toggle at the top of the card: Colour: category (Tool failures, Timeouts and so on) or Colour: outcome (errored, silent failure, recovered, not confirmed; see outcome definitions).
- Hover a dot to see its cluster, outcome and session. Click an island or a dot, or focus an island with Tab and press Enter, to open that cluster in the side panel.
With nothing selected, the side panel explains how to read the map, lists the pairs flagged for review (Review for merge; click one to open it) and counts the Unclustered sessions.
With a cluster selected, the panel shows the same cluster panel as Triage: its sessions, share, wasted spend, trend, what the user got, its remediation, and actions to generate a remediation, start a fix run, build a regression set or open Where it breaks →. The numbers cover the last 7 days, or all time when the cluster had no sessions in the last 7 days. Below it, Close to lists the clusters it may duplicate.
What distance means
Closeness means the failures look alike: similar errors, at similar steps, with similar failed quality checks. It is the same similarity Neens uses to cluster sessions (see How it works).
- Two islands that touch usually describe the same problem in different words, for example “Final answer contradicts tool result” and “supervisor_synthesize drops tool facts”. Both may come from the step that writes the final answer.
- A tight island far from everything is a distinct, well-separated failure mode.
- A spread-out island is a loose cluster. Its sessions share less than its label suggests, so read a few before trusting the label.
The axes have no units, and only relative distance matters. The map flattens many dimensions of similarity into two, so two points can look closer than they are. Treat closeness as a lead and confirm it by reading sessions.
How merge candidates are chosen
Neens draws a dashed link between two active clusters when their centres are very similar (a similarity of 0.85 or higher on a 0 to 1 scale). It is a suggestion to review. Neens never merges clusters on its own.
Review two islands for merge
Find the pair
Look for a dashed link on the map, or check Review for merge in the side panel. It names the two clusters and how similar they are.
Compare their sessions
Click the pair to open the first cluster, then open the second from Close to. Use Where it breaks → on each to read their sessions and see where each one fails. Ask whether one fix would resolve both. If it would, they are the same failure mode. If the root causes differ (for example, one is a prompt problem and the other a tool timeout), keep them apart even if they look close.
Merge, or leave them
To merge, go to the Failure Modes view, open the actions on the card you want to fold in, and choose Merge (see Merge a failure mode). Its sessions move into the target, which keeps its own name. Merging works only within one bucket; if the two islands have different bucket colours, pick the one that fits and rename it instead. If they are different problems, leave them. The link is only a suggestion and has no effect on its own.
Check the triage view
After a merge the combined cluster shows its full reach in Triage. Its share, growth and fix-queue rank are recomputed from the combined sessions.
Unclustered sessions
Hollow dots are failures that did not join any cluster. A few are normal. Watch for:
- A small group of hollow dots close together. This is often a new failure starting. It becomes a cluster once enough similar sessions arrive, but you can look now: hover the dots to see their session ids, then open those sessions from the Sessions page.
- Many hollow dots everywhere. Your clustering settings may be too strict for this agent’s volume. See Clustering configurations.
When the atlas appears
The atlas is drawn when clustering runs. The toolbar shows which run it comes from and how many sessions it holds.
| You see | Why | What to do |
|---|---|---|
| ”Appears after the next clustering run” | No clustering run has finished since the atlas became available for this agent | Wait for the next scheduled run, or run clustering from the Failure Modes view |
| ”Not enough failing sessions to map yet” | The run had fewer than 20 failing sessions, which is not enough for a useful map | Use the Triage view, or Open sessions, until more failures arrive |
| Fewer dots than failing sessions | Very large runs are sampled to at most 3,000 dots, keeping some from every cluster | Nothing. Every cluster still has an island; the panel counts all sessions |
| Dots don’t change when you move the time picker | The atlas always shows the latest clustering run | Expected. Use Triage for windowed counts |
Each new clustering run replaces the map. The layout can shift between runs, so an island’s position today says nothing about its position yesterday.