> ## Documentation Index
> Fetch the complete documentation index at: https://docs.upmetr.com/llms.txt
> Use this file to discover all available pages before exploring further.

# WAF Monitoring

> Monitor AWS WAFv2 Web ACLs with CloudWatch metrics and alert rules

Upmetr automatically discovers **AWS WAFv2 Web ACLs** and polls CloudWatch metrics for request traffic analysis. See allowed, blocked, and counted requests in real-time charts alongside your other cloud resources.

## How It Works

1. Upmetr discovers WAF Web ACLs during **resource sync** (both regional and CloudFront-scoped)
2. CloudWatch metrics are polled every **5 minutes** via the CloudWatch virtual agent
3. Metrics appear in the **Infrastructure** detail page under the WAF section
4. You can create **alert rules** for WAF metrics (e.g., spike in blocked requests)

<Note>
  WAF monitoring is read-only — it observes metrics from CloudWatch without modifying your WAF configuration. Your Web ACL rules, IP sets, and rate-based rules are not affected.
</Note>

## Prerequisites

Your AWS IAM role or user needs the following permissions:

```json theme={null}
{
  "Effect": "Allow",
  "Action": [
    "wafv2:ListWebACLs",
    "wafv2:GetWebACL"
  ],
  "Resource": "*"
}
```

<Tip>
  If your account doesn't have WAF or lacks these permissions, Upmetr silently skips WAF discovery — no errors, no configuration needed.
</Tip>

## Metrics

Upmetr collects three CloudWatch metrics per Web ACL:

| Metric               | Description                         | CloudWatch Name   |
| -------------------- | ----------------------------------- | ----------------- |
| **Allowed Requests** | Requests that matched an Allow rule | `AllowedRequests` |
| **Blocked Requests** | Requests that matched a Block rule  | `BlockedRequests` |
| **Counted Requests** | Requests that matched a Count rule  | `CountedRequests` |

All metrics use the `AWS/WAFV2` namespace with three dimensions: `WebACL`, `Region`, and `Rule` (aggregated as "ALL").

## Regional vs Global WAFs

WAFv2 Web ACLs can be scoped as:

* **REGIONAL** — associated with ALBs, API Gateways, or other regional resources. Discovered per-region.
* **CLOUDFRONT** — associated with CloudFront distributions. Always discovered in `us-east-1` regardless of your configured regions.

Upmetr handles both scopes automatically. CloudFront-scoped WAFs appear with region `global` in the resource list.

## Viewing WAF Metrics

1. Go to **Infrastructure** in the sidebar
2. Click on a **CloudWatch agent** card (the one associated with your AWS account)
3. Scroll to the **WAF Web ACLs** section (pink-themed charts)

If your account has multiple Web ACLs, each metric chart shows overlaid lines per ACL. Use the resource name in the tooltip to distinguish them.

## Setting Up Alert Rules

WAF metrics support the same alert rules as other CloudWatch metrics. Recommended thresholds:

| Rule                      | Metric                     | Operator | Threshold     | Severity |
| ------------------------- | -------------------------- | -------- | ------------- | -------- |
| High blocked requests     | `aws.waf.blocked_requests` | >        | 500 (10 min)  | Warning  |
| Critical blocked requests | `aws.waf.blocked_requests` | >        | 2000 (10 min) | Critical |

To create an alert rule:

1. Go to **Alerts** in the sidebar
2. Click **Create Rule**
3. Select resource type **WAF**
4. Choose the metric (e.g., `aws.waf.blocked_requests`)
5. Set the threshold, duration (minimum 600s for CloudWatch), and severity
6. Configure notification channels

<Warning>
  CloudWatch metrics have a minimum resolution of 5 minutes. Set alert duration to at least **600 seconds** (2 data points) to avoid false positives.
</Warning>

## Troubleshooting

<AccordionGroup>
  <Accordion title="No WAF resources discovered">
    * Verify your IAM role has `wafv2:ListWebACLs` permission
    * Ensure you have at least one WAF Web ACL in your account
    * Check the Celery worker logs for WAF discovery messages
  </Accordion>

  <Accordion title="WAF section not showing in Infrastructure page">
    * WAF charts only appear for CloudWatch agents with discovered WAF resources
    * Trigger a resource sync from **Settings > Cloud Accounts** and wait for the next CloudWatch poll (5 min)
  </Accordion>

  <Accordion title="Metrics show zero values">
    * This is normal if your WAF is not receiving traffic
    * CloudWatch reports zero when there are no matching requests in the 5-minute window
    * For CloudFront-scoped WAFs, verify the distribution is active and receiving requests
  </Accordion>
</AccordionGroup>