Detection rules

Rules evaluate parsed, structured observations. Capture filters select input; where/when select events. Business observations can still contribute to observability statistics without matching an event rule.

Report a specific URL request

To emit when request headers arrive, instead of waiting for the response, enable this in the main configuration:

{"http":{"request_events":true}}

Merge this fragment into the configuration and restart the analyzer. Create a rule file and add it to the main rules list:

rule "export_request" do
  on "http.request"
  where service == "billing" and not incomplete
  when http.method == "POST" and http.path == "/admin/export"
  emit "http.export_requested" do
    severity = "info"
    message = "Export endpoint requested"
    method = http.method
  end
end

Each matching request produces an event without exporting the raw URL, body, or credentials. For response-based detection, use on "http.transaction" and include a response condition in when; request-stage events are then unnecessary. http.status is a three-character string, for example http.status >= "500".

Suppress repeated events

Add group_by service and cooldown "30s" to a non-window rule. It emits at most once per sensor/service within 30 seconds of event time. Omit cooldown when every matching visit must be reported.

Detect an error rate

rule "database_error_rate" do
  on "db.transaction"
  where not incomplete
  group_by service, db.system
  window "60s"
  when count() >= 20 and ratio(error) >= 0.10
  emit "database.error_rate" do
    severity = "warning"
    message = "Database request error rate exceeded 10 percent"
    requests = count()
    error_ratio = ratio(error)
  end
end

Windows align to event time, allow five seconds of disorder, and emit at most once per group after closing. Unknown error values are not successes. Missing samples, truncation, and missing context cannot establish health.

Test and reload

netflowscout rules test --config /etc/netflowscout/netflowscout.json \
  --input observations.ndjson --format ndjson --compare-rules ./candidate.nfs
sudo netflowscout check --config /etc/netflowscout/netflowscout.json
sudo systemctl reload netflowscout.service

Install the tested file at the configured path before the full check and reload. All rules must compile before switching; failures retain the previous engine. Unchanged rules retain compatible windows, cooldowns, and incidents. New or changed window rules warm up again. Confirm the active version and a real event after reloading.

Trigger and recover incidents

Use a window rule with lifecycle for firing / ongoing / resolved / closed events. Download the complete example. Recovery needs explicit healthy windows; idle time does not resolve incidents. Removing or replacing a rule emits closed, not business recovery. See the language reference.