Alerts

Attach threshold rules to any span via the alerts option. At ingest time, each rule is evaluated and its result stored with the trace. The dashboard flags breaching spans with a warning badge and, when you specify target values, highlights the exact items within multi-table output that caused the breach.

Basic usage

Pass a single check with a numeric value and a threshold. The span gets flagged if the value crosses it.

because.addSpan('json', 'Query time', {
  output: { durationMs: 1240 },
  alerts: [
    {
      label: 'query duration (ms)',
      level: 'warn',
      gt: 1000,
      checks: [{ value: 1240 }]
    }
  ]
});

Use error for higher severity:

alerts: [
  {
    label: 'query duration (ms)',
    level: 'warn',
    gt: 1000,
    checks: [{ value: 1240 }]
  },
  {
    label: 'query duration (ms)',
    level: 'error',
    gt: 5000,
    checks: [{ value: 1240 }]
  }
];

Multiple checks with targets

When a span outputs multiple tables, pass one check per table and set target to the table's title. Every check that breaches the threshold gets a warning icon on its table heading in the dashboard - not just the worst one.

const pcts = plans.map(
  (plan) => ((planCost(plan) - referencePrice) / referencePrice) * 100
);

because.addSpan('table', 'Cost breakdown', {
  alerts: [
    {
      label: '% vs reference price',
      level: 'warn',
      gt: 20,
      lt: -20,
      checks: plans.map((plan, i) => ({
        target: `${plan.company} - ${plan.name}`,
        value: +pcts[i].toFixed(1)
      }))
    }
  ],
  output: {
    tables: plans.map((plan) => because.table(`${plan.company} - ${plan.name}`)./* ... */.build())
  }
});

The target string must exactly match the title passed to because.table().

alerts options

* At least one of gt or lt must be provided.

checks options

Dashboard behaviour

• Collapsed span - a warn or error badge appears on the right of the span header if any check breached its threshold.
• Expanded span - a coloured banner appears for each triggered alert rule, showing the label and the breach detail (e.g. % vs reference price: 25.3 exceeded threshold of 20). Multiple rules each get their own row.
• Table headings - when target is set and matches a table group title, that table's heading shows a warning icon. All matching tables are marked, not just the most extreme.