Fingerprint Rules

Fingerprint rules let you override the default error grouping algorithm. Define custom rules to group errors by business context rather than stack trace similarity.

Rule format

Rules are defined as JSON objects with a name, a custom fingerprint string, and a list of conditions. When all conditions match an incoming error, the custom fingerprint is applied instead of the auto-generated one.

fingerprint-rule.json

{
  "rules": [
    {
      "name": "Stripe payment errors",
      "fingerprint": "stripe-payment-error",
      "conditions": [
        { "field": "error.message", "operator": "contains", "value": "Stripe" },
        { "field": "error.type", "operator": "equals", "value": "PaymentError" }
      ]
    }
  ]
}

Operators

Each condition uses an operator to match against a field value:

equals -- exact string match
contains -- substring match (case-insensitive)
regex -- regular expression match
startsWith -- prefix match
endsWith -- suffix match
not_equals -- negated exact match

Available fields

error.message -- the error message string
error.type -- the error class name (e.g. TypeError, RangeError)
error.stack -- the full stack trace text
error.url -- the page URL where the error occurred
error.tags.* -- custom tags attached via captureError

Rule templates

Common patterns you can use as starting points:

chunk-load-rule.json

{
  "name": "Chunk load failures",
  "fingerprint": "chunk-load-failure",
  "conditions": [
    {
      "field": "error.message",
      "operator": "regex",
      "value": "Loading chunk \\d+ failed"
    }
  ]
}

network-timeout-rule.json

{
  "name": "API timeouts",
  "fingerprint": "api-timeout",
  "conditions": [
    { "field": "error.message", "operator": "contains", "value": "timeout" },
    { "field": "error.url", "operator": "startsWith", "value": "/api/" }
  ]
}

Priority ordering

Rules are evaluated in priority order (lowest number first). The first matching rule wins. Use low priority numbers for specific rules and high numbers for catch-all rules.

{
  "rules": [
    { "priority": 1, "name": "Payment errors", "fingerprint": "payment", "conditions": [...] },
    { "priority": 2, "name": "Network errors", "fingerprint": "network", "conditions": [...] },
    { "priority": 99, "name": "Catch-all scripts", "fingerprint": "third-party", "conditions": [...] }
  ]
}

If no custom rule matches, the default fingerprinting algorithm is used (message + stack trace hash).

CLI management

# Upload fingerprint rules
gurulu fingerprints upload --site-id YOUR_SITE_ID --file rules.json

# List active rules
gurulu fingerprints list --site-id YOUR_SITE_ID

# Test a rule against recent errors
gurulu fingerprints test --site-id YOUR_SITE_ID --rule-name "Payment errors"

Edit this page