sneak
dfb44c5546
check / check (push) Waiting to run
The old README opened with project history and one list of a hundred settings. The new one leads with what smallwebwaf is, what it protects against, how to build and deploy it, how it sits in front of the app, what happens to a request, the settings most deployments touch, how to check it works and how to develop it. The reference material, every setting, bans, rule files, the Core Rule Set, the admin endpoints, the request log, alerts, metrics, state files, lookups, reputation sources, the image and gitea, moves to files under docs/, each linked from the README. Every statement was checked against the code on next. Model: fable-5-1
84 lines
3.1 KiB
Markdown
84 lines
3.1 KiB
Markdown
# The metrics
|
|
|
|
`GET /_smallwebwaf/metrics` answers in the Prometheus text format. The
|
|
requirements are under "Metrics endpoint" in [`SPEC.md`](../SPEC.md); this file
|
|
lists the metrics. Every metric carries the label `instance`, set to
|
|
`SWWAF_INSTANCE_NAME`; Prometheus keeps it as `exported_instance` unless the
|
|
scrape sets `honor_labels: true`. No metric carries a client's address.
|
|
|
|
## Traffic
|
|
|
|
- `smallwebwaf_requests_total`, `smallwebwaf_request_bytes_total` and
|
|
`smallwebwaf_response_bytes_total`, by `status_class` such as `2xx` and by
|
|
`action`;
|
|
- `smallwebwaf_request_duration_seconds` and
|
|
`smallwebwaf_upstream_duration_seconds`, as histograms;
|
|
- `smallwebwaf_requests_in_flight`.
|
|
|
|
## Limits and bans
|
|
|
|
- `smallwebwaf_rate_limit_hits_total`, by `window` and by `kind` (`requests`,
|
|
`bytes` or `refusals`);
|
|
- `smallwebwaf_size_and_time_limit_hits_total`, by `limit`, the setting passed;
|
|
- `smallwebwaf_offences_total`, by `kind`;
|
|
- `smallwebwaf_bans_made_total`, by `cause`;
|
|
- `smallwebwaf_active_bans` and `smallwebwaf_permanent_bans`.
|
|
|
|
## Attack detection
|
|
|
|
- `smallwebwaf_rule_matches_total`, by `rule_id` and `action`, and
|
|
`smallwebwaf_rules_loaded`;
|
|
- `smallwebwaf_waf_matches_total`, by `mode` and `rule_id`, for the rules that
|
|
fired.
|
|
|
|
## Countries and AS numbers
|
|
|
|
For the `SWWAF_METRICS_TOP_N` busiest of each, the rest as `other`:
|
|
|
|
- `smallwebwaf_country_requests_total`,
|
|
`smallwebwaf_country_request_bytes_total`,
|
|
`smallwebwaf_country_response_bytes_total` and
|
|
`smallwebwaf_country_list_refusals_total`, by `country`;
|
|
- `smallwebwaf_asn_requests_total`, `smallwebwaf_asn_request_bytes_total` and
|
|
`smallwebwaf_asn_response_bytes_total`, by `asn`.
|
|
|
|
## Lookups
|
|
|
|
- `smallwebwaf_geojs_requests_total` and `smallwebwaf_geojs_failures_total`;
|
|
- `smallwebwaf_geojs_unanswered_total`: the requests that needed an answer and
|
|
went on without it;
|
|
- with the file source,
|
|
`smallwebwaf_lookup_database_last_read_timestamp_seconds` and
|
|
`smallwebwaf_lookup_database_read_failures_total`.
|
|
|
|
## Reputation sources
|
|
|
|
By `source`: each list's URL, each zone, and `abuseipdb`:
|
|
|
|
- `smallwebwaf_reputation_hits_total`, `smallwebwaf_reputation_queries_total`
|
|
and `smallwebwaf_reputation_failures_total`;
|
|
- `smallwebwaf_reputation_last_fetch_timestamp_seconds`, for a list;
|
|
- `smallwebwaf_reputation_daily_budget_remaining`, for AbuseIPDB.
|
|
|
|
## State files
|
|
|
|
By `file`:
|
|
|
|
- `smallwebwaf_state_file_writes_total`,
|
|
`smallwebwaf_state_file_write_failures_total`,
|
|
`smallwebwaf_state_file_last_write_timestamp_seconds` and
|
|
`smallwebwaf_state_file_size_bytes`;
|
|
- `smallwebwaf_state_file_edits_taken_in_total` and
|
|
`smallwebwaf_state_file_edits_set_aside_total`;
|
|
- `smallwebwaf_tracked_clients`: the clients in the table.
|
|
|
|
## Remote log, alerts and the process
|
|
|
|
- while a syslog server is set, `smallwebwaf_remote_log_lines_sent_total`,
|
|
`smallwebwaf_remote_log_lines_dropped_total` and
|
|
`smallwebwaf_remote_log_buffer_depth`;
|
|
- by `destination`, `smallwebwaf_alerts_sent_total`,
|
|
`smallwebwaf_alerts_failed_total`, `smallwebwaf_alerts_suppressed_total` and
|
|
`smallwebwaf_alerts_dropped_total`;
|
|
- Go's own `go_` metrics and the process's `process_` metrics.
|