project-health-alert-authoring

Define a new alert in a configuration file within `health.d/` using the `template` or `alarm` syntax. Ensure you establish an alert contract covering incident ownership, signal intent, and lifecycle behavior before finalizing the configuration.

Prevent flapping by using a combination of stable lookup windows, separate raise/clear thresholds, and `delay` settings. Start by selecting the smallest truthful lookup window, then apply threshold hysteresis if the signal continues to hover near boundaries.

Netdata does not use a Prometheus-style pending state machine. Instead, adapt persistence intent using Netdata-native observation windows and evaluation cadences, ensuring the configuration reflects the actual numeric state space of the monitored signal.

Use a helper alert (with `to: silent`) when an alert requires complex database lookups or multi-stage calculations that cannot be expressed in a single expression. This allows consuming alerts to reference the helper's published value.

Cross-chart variables rely on label-score matching to identify the correct instance. If labels are not sufficiently unique across instances, the variable may resolve to an incorrect chart, leading to inaccurate alert evaluations.