Skip to content

Bucketing settings

DV Forge's built-in normalization removes the common run-specific values (times, addresses, data, seeds, paths) before it fingerprints a failure. Your testbench may print values it doesn't recognize, such as a transaction tag or a lane number that changes from seed to seed, and each new value creates a new signature for the same bug. Masks fix that for one project. This page explains what masks are, how to preview their effect, and how re-bucketing applies them without losing your triage work.

Open Bucketing in the sidebar. Everyone in the project can view the page. Editing masks, previewing and re-bucketing need the project_admin role; for everyone else the masks are read-only.

The Engine card

Field What it shows
Engine version The bucketing version DV Forge currently keys signatures under (for example v3)
Masks last changed When the masks were last saved, or never (defaults)
Re-bucket The re-bucket status: idle, queued, running or failed, with when the last one finished. A failed re-bucket shows its error underneath.

Re-bucket now queues a re-bucket of the whole project with the current masks and engine version. You rarely need it: saving masks and engine upgrades both re-bucket on their own.

Masks

A mask is a regular expression. Before DV Forge normalizes a failure's headline, it replaces every match of every mask with <mask>. Masks apply to the message text and to the message id.

For example, without masks these two headlines are two signatures:

error | axi_mon | unexpected bresp on channel w for txn tag qx19 (lane l7) | axi_monitor.sv
error | axi_mon | unexpected bresp on channel w for txn tag rb02 (lane l3) | axi_monitor.sv

With the masks tag \w+ and lane L\d+, both reduce to one template:

error | axi_mon | unexpected bresp on channel w for txn <mask> (<mask>) | axi_monitor.sv

Syntax and limits

  • One mask per line. Blank lines, surrounding spaces and exact duplicates are ignored.
  • Matching is case-insensitive.
  • Masks use RE2 regular-expression syntax: the familiar character classes, groups, alternation and repetition work, but backreferences (\1), lookahead and lookbehind ((?=…), (?<=…)) and possessive quantifiers don't.
  • At most 20 masks per project, each 1–256 characters.
  • A mask can't match empty text (x* is rejected).

Patterns are evaluated safely: a mask runs in time proportional to the text it scans, whatever the pattern, so no mask can stall bucketing.

If a mask is invalid, saving or previewing fails and the page shows why, for example:

invalid mask: '(?=x)y': invalid perl operator: (?= (masks use RE2 syntax: no backreferences, lookahead/lookbehind or possessive quantifiers)

Tip

Mask only what varies from run to run. Assertion names, check names and signal names are what tell bugs apart; masking them merges different bugs into one signature. The built-in rules already handle hex values, Verilog literals, numbers, sim times and seeds, so you don't need masks for those.

Preview the effect

Before you save, check what the masks would do.

  1. Edit the masks in the Masks box.
  2. Select Preview.

The preview re-keys the project's most recent failures (up to 20,000) with the masks in the box and changes nothing. It shows:

  • Scanned N failures (with "the most recent 20,000" when the project has more), and the number of signatures before and after, with the difference.
  • Would merge (n): groups of existing signatures that would become one signature.
  • Would split (n): existing signatures whose failures would spread over several signatures (→ k signatures).
  • "No existing signature would merge or split." when nothing changes.

Each list shows up to 25 entries, then "…and N more". Every title links to its signature. If you edit the masks after previewing, the old preview fades and says "Masks changed since this preview — run Preview again."

Save and re-bucket

Select Save & re-bucket. The button is enabled only when the masks differ from the saved ones. DV Forge saves the masks, shows "Saved — re-bucket queued.", and queues a re-bucket. Failures that arrive from then on are bucketed with the new masks.

Re-bucketing

Re-bucketing re-keys every failure in the project under the current masks and engine version, then regroups them.

When it happens

  • When someone with the project_admin role saves masks (Save & re-bucket).
  • When someone with the project_admin role selects Re-bucket now.
  • Automatically after DV Forge upgrades its bucketing engine: any project with live signatures keyed under an older version is queued. Without this, every known bug would fork into a new signature at its next hit.

If a re-bucket is already queued, another request doesn't queue a second one; the queued run picks up the latest masks.

What's preserved

Re-bucketing keeps your signatures' identity:

  • Signatures keep their ids, and with them their triage status, assignee, labels, comments, attachments, activity and root-cause runs. Each signature follows "its" bug: it takes the new fingerprint that most of its failures now have.
  • Manual merges survive. A signature you merged stays merged.
  • Split rules survive, and keep routing matching failures to their child signatures.
  • Running a re-bucket twice in a row changes nothing the second time.

What can change

  • Signatures can merge. If several signatures now share one fingerprint, the oldest keeps it and the others are merged into it. These merges show as merged by re-bucketing and can't be unmerged; split the survivor if you need them apart again.
  • Signatures can split. Failures whose new fingerprint no signature owns go to a new signature. New signatures start Untriaged with DV Forge's first classification guess, and DV Forge looks for possible duplicates among them.
  • Counts are recomputed: hits, regressions, first and last seen, and recurrence.

Status and progress

The Re-bucket line on the Engine card follows the job live: queued → running → idle when it's done, with last finished updated. There's no percentage; large projects take longer. Results you upload while a re-bucket runs wait and are bucketed as soon as it finishes; nothing is lost.

If the re-bucket hits a temporary database conflict, it goes back to queued and retries automatically (the error line starts with "retrying after:"). Any other error marks it failed with the error shown; fix the cause (for example, a mask) and save again, or select Re-bucket now.