Alerting Rules

ObsrvHQ suppression rules give you explicit control over how individual services and metrics are handled. Most teams find the default envelope-based behavior handles 90% of their noise without any custom rules. Rules are for the cases where the default sensitivity is wrong for a specific service: user-facing checkout APIs that need tight monitoring, or background job queues that are inherently noisy and should be suppressed unconditionally.

Rules are evaluated in order. The first matching rule determines the suppression decision for an alert. If no rule matches, the default suppression behavior applies: envelope-based comparison at sensitivity 1.5x.

Rule schema

Rules are defined in YAML and can be managed via the dashboard or the API. A full rules file looks like this:

rules:
  - name: checkout-api-error-rate-strict
    service: checkout-api
    metric: error_rate
    sensitivity: 1.0   # tighter: page sooner
    enabled: true

  - name: db-replica-replication-lag-lenient
    service: db-replica-2
    metric: replication_lag
    sensitivity: 2.5   # wider: suppress more
    deploy_window_min: 30
    enabled: true

  - name: cdn-miss-rate-ignore
    service: cdn-edge
    metric: miss_rate
    action: suppress_always
    enabled: true

defaults:
  sensitivity: 1.5
  deploy_window_min: 15

Rule fields

Field	Type	Required	Description
`name`	string	Yes	Unique identifier for this rule
`service`	string	Yes	Service label value to match
`metric`	string	No	Metric name to match (omit to match all metrics for service)
`sensitivity`	float	No	Envelope width multiplier. 1.0 = tight, 3.0 = very wide. Default 1.5
`action`	string	No	`default`, `suppress_always`, or `page_always`
`deploy_window_min`	integer	No	Minutes to widen envelope after deployment event. Default 15
`enabled`	boolean	No	Set false to disable without deleting. Default true

Sensitivity multiplier

The sensitivity multiplier controls how wide the learned envelope is before triggering a page. A multiplier of 1.0 means: page exactly when the metric exceeds the learned statistical boundary. A multiplier of 2.0 means: the metric must deviate twice as far before a page is triggered.

0.5x to 1.0x: aggressive, catches small deviations. Use for critical user-facing services.
1.5x (default): balanced. Suppresses clear noise, pages on genuine outliers.
2.0x to 3.0x: lenient. Use for noisy services where false positives are common and tolerance for missed alerts is higher.

Special actions

suppress_always: The metric is never paged regardless of its value. Use for known noisy metrics that provide no actionable signal (e.g., CDN cache miss rates, non-critical background job queues).

page_always: The metric always pages regardless of baseline. Use for metrics where any deviation is critical, bypassing the envelope logic entirely.

Deployment event windows

When a deployment event is received via the API or webhook, ObsrvHQ widens the sensitivity multiplier by widen_multiplier (default 2.0x) for deploy_window_min minutes. After the window expires, the envelope returns to the configured sensitivity.

This eliminates the classic post-deploy alert storm: 15 minutes of silence, then normal operation resumes.

Validation

Validate your rules file locally before applying:

curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/yaml" \
  --data-binary @obsrvhq-rules.yaml \
  https://api.obsrvhq.com/v1/rules/validate