WAF Logging & Sampled Requests

Tuning a Web ACL means answering "what did this rule actually match?" repeatedly, and AWS gives two different tools for that depending on whether you need a quick look or a durable trail. GetSampledRequests needs no setup and answers "what happened recently." PutLoggingConfiguration sets up a real pipeline and answers "what happened, ever, queryable later."

This page covers both, and when each is the right call.

Recipe

GetSampledRequests is the fastest way to see what a rule is doing right now, with zero infrastructure. It returns up to 500 matched requests from the last 3 hours for one rule.

# --- Python (boto3) ---
import boto3
from datetime import datetime, timedelta, timezone
 
wafv2 = boto3.client("wafv2", region_name="us-east-1")
 
now = datetime.now(timezone.utc)
resp = wafv2.get_sampled_requests(
    WebAclArn="arn:aws:wafv2:us-east-1:111111111111:regional/webacl/app-web-acl/abc123",
    RuleMetricName="blockBadHeader",
    Scope="REGIONAL",
    TimeWindow={"StartTime": now - timedelta(hours=3), "EndTime": now},
    MaxItems=100,
)
for item in resp["SampledRequests"]:
    req = item["Request"]
    print(item["Action"], req["ClientIP"], req["URI"])

// --- TypeScript (AWS SDK v3) ---
import { WAFV2Client, GetSampledRequestsCommand } from "@aws-sdk/client-wafv2";
 
const wafv2 = new WAFV2Client({ region: "us-east-1" });
 
const now = new Date();
const threeHoursAgo = new Date(now.getTime() - 3 * 60 * 60 * 1000);
 
const resp = await wafv2.send(new GetSampledRequestsCommand({
  WebAclArn: "arn:aws:wafv2:us-east-1:111111111111:regional/webacl/app-web-acl/abc123",
  RuleMetricName: "blockBadHeader",
  Scope: "REGIONAL",
  TimeWindow: { StartTime: threeHoursAgo, EndTime: now },
  MaxItems: 100,
}));
for (const item of resp.SampledRequests ?? []) {
  console.log(item.Action, item.Request?.ClientIP, item.Request?.URI);
}

RuleMetricName must match the VisibilityConfig.MetricName you gave that specific rule when creating it - the sample is per-rule, not per-ACL. Three hours is the maximum lookback; there is no way to query further back through this API.

Working Example

Set up durable logging to a Kinesis Data Firehose delivery stream, and redact the Authorization header so tokens never land in the logs.

# --- Python (boto3) ---
import boto3
 
wafv2 = boto3.client("wafv2", region_name="us-east-1")
web_acl_arn = "arn:aws:wafv2:us-east-1:111111111111:regional/webacl/app-web-acl/abc123"
firehose_arn = "arn:aws:firehose:us-east-1:111111111111:deliverystream/aws-waf-logs-app"
 
wafv2.put_logging_configuration(
    LoggingConfiguration={
        "ResourceArn": web_acl_arn,
        "LogDestinationConfigs": [firehose_arn],
        "RedactedFields": [
            {"SingleHeader": {"Name": "authorization"}},
        ],
        "LoggingFilter": {
            "DefaultBehavior": "KEEP",
            "Filters": [{
                "Behavior": "KEEP",
                "Conditions": [{"ActionCondition": {"Action": "BLOCK"}}],
                "Requirement": "MEETS_ANY",
            }],
        },
    },
)

// --- TypeScript (AWS SDK v3) ---
import { PutLoggingConfigurationCommand } from "@aws-sdk/client-wafv2";
 
const webAclArn = "arn:aws:wafv2:us-east-1:111111111111:regional/webacl/app-web-acl/abc123";
const firehoseArn = "arn:aws:firehose:us-east-1:111111111111:deliverystream/aws-waf-logs-app";
 
await wafv2.send(new PutLoggingConfigurationCommand({
  LoggingConfiguration: {
    ResourceArn: webAclArn,
    LogDestinationConfigs: [firehoseArn],
    RedactedFields: [
      { SingleHeader: { Name: "authorization" } },
    ],
    LoggingFilter: {
      DefaultBehavior: "KEEP",
      Filters: [{
        Behavior: "KEEP",
        Conditions: [{ ActionCondition: { Action: "BLOCK" } }],
        Requirement: "MEETS_ANY",
      }],
    },
  },
}));

The Firehose delivery stream name must start with aws-waf-logs- - WAF enforces this naming convention on the destination. RedactedFields removes the field's value from the log entry entirely (replaced with a redaction marker) rather than just masking part of it. The LoggingFilter here keeps only BLOCK-action entries, which cuts volume dramatically on a busy ACL where most traffic is allowed.

Deep Dive

Three Destination Types, One Call

PutLoggingConfiguration accepts a Kinesis Data Firehose ARN, a CloudWatch Logs log group ARN, or an S3 bucket ARN in LogDestinationConfigs - the same call, just a different ARN shape. Firehose is the most common choice because it can fan out to S3 (for querying with Athena) and to an analytics tool simultaneously. CloudWatch Logs is simplest for teams already living in CloudWatch. Direct-to-S3 logging skips Firehose entirely for the lowest-latency, simplest pipeline when you do not need real-time forwarding elsewhere.

Sampling vs Logging Are Not Mutually Exclusive

GetSampledRequests works whether or not PutLoggingConfiguration is set up - it reads from WAF's own internal sampling, not from your log destination. Many teams use sampling exclusively during initial rule development (fast iteration, no infrastructure) and only turn on full logging once a rule is stable enough to be worth long-term retention and querying.

LoggingFilter Controls Both Cost and Signal

Without a LoggingFilter, every evaluated request that matches at least one rule gets logged - including ALLOW matches from managed rule groups running in normal operation, which on busy traffic can be the overwhelming majority of log volume. A filter keeping only BLOCK and COUNT actions focuses the log on what actually needs review, while cutting storage and Firehose/CloudWatch costs proportionally.

Redaction Happens Before the Log Is Written

RedactedFields operates at the point of log generation, not as an after-the-fact scrub. Once a field is configured for redaction, its value never appears in any destination - there is no way to retroactively "unredact" older log entries, so get the redaction list right before sensitive fields ever ship to a destination you do not fully control.

Gotchas

• Firehose stream name without the required prefix. PutLoggingConfiguration rejects a Firehose ARN whose delivery stream name does not start with aws-waf-logs-.
• Expecting GetSampledRequests to cover more than 3 hours. It cannot; anything older needs a logging destination set up in advance.
• Logging everything on a high-traffic ACL. Without a LoggingFilter, logging every ALLOW from a busy managed rule group can generate enormous log volume and cost; filter to BLOCK/COUNT unless you specifically need full traffic logs.
• Forgetting to redact sensitive headers. Authorization headers, session cookies, and API keys land in plaintext logs unless explicitly listed in RedactedFields.
• Assuming one logging configuration covers multiple Web ACLs. PutLoggingConfiguration is set per Web ACL's ResourceArn; each ACL needs its own call.
• Not checking CloudWatch Logs resource policy. A CloudWatch Logs destination needs a resource policy granting WAF permission to write to it, or PutLoggingConfiguration fails silently on delivery even though the API call itself succeeds.

Alternatives

• GetSampledRequests only, no persistent logging, suits early rule tuning and low-traffic applications where recent-traffic visibility is enough.
• Direct-to-S3 logging skips Firehose when you only need raw log files for periodic batch analysis (Athena, QuickSight) and do not need a real-time stream elsewhere.
• CloudWatch Logs is the simplest destination to wire up for teams already using CloudWatch dashboards and alarms, at the cost of CloudWatch's own ingestion and storage pricing.
• Kinesis Data Firehose to multiple destinations (S3 plus an analytics or SIEM integration) is the most flexible option and the one most production security teams land on.

FAQs

Related

• Web ACLs, Rules & Rule Groups - the rules whose matches this page reviews.
• Rate-Based Rules & Bot Control - rules commonly staged with Count and reviewed via logging before enforcement.
• WAF & Shield via SDK Best Practices - the tuning workflow this page's tools support.

Stack versions: This page was written for boto3 1.43.x (Python 3.10+) and the AWS SDK for JavaScript v3 (Node.js 18+).