Home / Docs

Documentation

How DiffMon works across monitoring, alerts, security, and API integration.

Policy rules

Use post-diff rules to suppress noise, route important changes, and escalate notification severity.

Policy rules

Policy rules are deterministic, post-diff rules that run after Diffmon computes a diff.

Plan availability: Pro and above.

What policy rules can do

  • Suppress notifications for matched low-value changes.
  • Add destination routes for matched high-impact changes.
  • Escalate notification severity labels.
  • Add labels for downstream routing and triage.

What policy rules do not change

  • Diff computation.
  • Incident grouping.
  • Baseline logic.
  • Snapshot/diff persistence.

Suppression only stops notification event and delivery creation. Evidence and incidents still persist.

Matching inputs

Rules can match on:

  • classification_in: schema_change | value_change | mixed | content_change
  • min_severity: critical | high | medium | info
  • path_prefix_any: one or more JSON path prefixes

path_prefix_any is normalized to a slash-prefixed canonical form and deduped.

Rule schema (v1)

JSON
{
  "schemaVersion": "v1",
  "rules": [
    {
      "id": "breaking-payments",
      "enabled": true,
      "when": {
        "classification_in": ["schema_change", "mixed"],
        "min_severity": "high",
        "path_prefix_any": ["/v1/payments"]
      },
      "then": {
        "suppress_notifications": false,
        "route_destination_ids_add": ["dest_pagerduty"],
        "escalate_to": "critical",
        "labels_add": ["payments", "breaking"]
      }
    }
  ]
}

Evaluation behavior

  • Rules evaluate in persisted list order.
  • Disabled rules are skipped.
  • A rule matches only when all specified predicates match.
  • suppress_notifications accumulates with logical OR.
  • Routes and labels are unioned, deduped, and sorted.
  • Escalation uses highest matched severity and is monotonic against original severity.

Configure with API (v1)

Policy rules are stored on monitor settings.

  • GET /api/monitors/:id/settings returns policyRulesJson when entitled.
  • PATCH /api/monitors/:id/settings accepts policyRules using strict schema validation.
  • Replace-all semantics apply:
    • send rules: [] to clear
    • omit policyRules to leave unchanged

Example update:

JSON
{
  "policyRules": {
    "schemaVersion": "v1",
    "rules": [
      {
        "id": "ignore-timestamps",
        "enabled": true,
        "when": {
          "classification_in": ["value_change"],
          "path_prefix_any": ["/timestamp", "/generated_at"]
        },
        "then": {
          "suppress_notifications": true
        }
      }
    ]
  }
}

Validation and entitlement behavior

  • Unknown keys are rejected with 400 VALIDATION.
  • Invalid enums/ranges are rejected with 400 VALIDATION.
  • Rules over limit are rejected with 400 VALIDATION.
  • If not entitled, updates are rejected with 403 FORBIDDEN.

Best practices

  1. Start with one suppression rule for known noisy paths.
  2. Add one escalation rule for breaking schema paths.
  3. Keep rule IDs stable and descriptive.
  4. Prefer narrow path_prefix_any scopes over broad global suppression.