Clusters

When a Signal has fired across thousands of traces, reading the event list by hand stops working. Clusters group similar events so you see patterns instead of scrolling.

​

What a cluster is

A cluster is a group of signal events whose summaries are semantically similar. Laminar groups events by meaning rather than exact wording, so “timeout calling the payments API” and “payments request exceeded deadline” land in the same cluster. Clustering is scoped to a single Signal: events from different Signals never share a cluster. Read top-down when you want the shape of the problem (“most failures are tool loops”). Read bottom-up when you want the specific example (“this one loop is the config-validation tool calling itself twelve times”).

​

Where to find them

On any Signal detail page, open the Events tab. The clusters view sits above the events table:

• The icicle strip. One row per level of the hierarchy, broadest at the top and most specific at the bottom, with each band’s width proportional to its event count. A band sitting under another is one of its sub-clusters, so the whole tree is readable at a glance without expanding anything. When a row has more clusters than it has width for, the smallest fold into a +N counter you can open to see the rest.
• The frequency chart. Each cluster is a stacked series over time, with a Signal runs overlay so you can read cluster volume against how often the Signal ran.
• The readout, pinned over the top-left of the chart. It names whatever cluster is in focus and gives its event count, its share of traces, and its sub-cluster count. With nothing in focus it shows the total cluster count for the range instead.

Hover a band to highlight its branch and see its details. Click the band to pin that cluster in the readout and filter the events table to its members; click it again to clear the selection. From any event you can jump to the trace that produced it. Everything respects the page-level time range.

​

How the hierarchy works

Clusters form a tree, up to three levels deep:

• Leaf clusters are the most specific named groups: events that describe near-identical behavior, like “config-validation tool retries in a loop”.
• Parent clusters group similar leaf clusters into broader patterns, like “tool call loops”. A parent’s events are the union of its children’s events, so counts add up as you move up the tree.
• The top level is a handful of broad categories that cover most of the Signal’s events. This is the view to start from during triage.

The hierarchy is not fixed upfront. It grows organically as events arrive: the first events of a new pattern form a leaf cluster, and when several related leaf clusters accumulate, a parent forms above them. Cluster names are generated by Laminar’s AI from representative sample events. Naming runs bottom-up: sub-clusters are named first, and each parent is then named with its children’s names in view, so a parent reads one abstraction level above its children instead of duplicating the name of its largest child. As new events shift what a cluster contains, its name is refreshed so it keeps describing the current members.

​

When events get clustered

Clustering runs asynchronously, after events are created:

1. Every new signal event is queued for clustering together with its summary.
2. Queued events for the same Signal are processed in batches. A batch runs once enough events accumulate, or shortly after the first event arrives, typically within a minute.
3. Each event in the batch either joins the closest existing group or starts a new one. As related events accumulate, named clusters appear in the UI; events that have not joined a named cluster sit in the Unclustered bucket.
4. If the batch created new clusters or meaningfully changed existing ones, names are generated or refreshed.

Two consequences worth knowing:

• An event shows up in the events table immediately but can take a minute or two to land in a cluster. During a live incident, expect cluster counts to trail the event count slightly.

Clusters are a view over the underlying events, not a copy. Deleting a Signal or purging events removes cluster membership automatically.

​

When clusters earn their keep

Clusters pay off when you have hundreds or thousands of events and an open-ended question:

• Triage: “Of the 4,000 traces flagged by agent_failure this week, which handful of failure modes account for most of them?”
• Regression detection: a cluster that was empty yesterday and full today is a new failure mode.
• Prompt tuning: if a cluster contains events you don’t consider matches, your prompt is too broad. If expected events split across unrelated clusters, your payload schema isn’t capturing the discriminating fields.

If your Signal has a small, well-defined set of payload fields (say, a category enum with five values), grouping in the SQL Editor or a custom dashboard is usually enough. Reach for clusters when the events are free-form or when you don’t yet know what categories exist.

​

Querying clusters with SQL

Clusters are queryable in the SQL Editor:

• The clusters table has one row per named cluster, including name, level, parent_id, and num_signal_events, so you can reconstruct the hierarchy or trend cluster sizes over time.
• The signal_events table has a clusters column: the IDs of every cluster an event belongs to, from its most specific cluster up through its parents.

​

Next steps