Docs

Log Formats

Overview

The WAF produces log data in two places: the WAF dashboard log viewer and the Logs API endpoint. Both use the same underlying data and field format, but they differ in how you access them and what they are best suited for.

Dashboard Log Viewer

The WAF dashboard includes a built-in log viewer that displays recent blocked requests. This is the quickest way to check what the WAF is blocking in real time.

  • Accessible from the Block Logs page in your dashboard
  • Shows the most recent blocked requests
  • Filterable by date, IP address, and block reason
  • Best for quick investigations and spot-checking

Logs API

The Logs API endpoint provides programmatic access to blocked request data for compliance, auditing, and advanced analysis. Logs are returned as JSON and can be paged through using a scroll cursor.

  • Returns up to 10,000 entries per request
  • Supports date range queries up to 90 days
  • Best for exporting to external systems (SIEM, log aggregators, spreadsheets)

Log Entry Fields

Every log entry — whether viewed in the dashboard or retrieved via the API — contains these fields:

Field Type Description
timestamp ISO 8601 string When the request was received (UTC)
client_ip String IP address of the requesting client. May be IPv4 (203.0.113.42) or IPv6 (2001:db8::1) depending on how the client connected.
http_method String HTTP method used (GET, POST, PUT, etc.)
request_path String The URL path requested (e.g., /wp-login.php)
http_status Integer HTTP response status code (typically 403 for blocks)
response_size Integer Response body size in bytes
referrer String or null HTTP Referer header value, if present
user_agent String Client User-Agent string
block_reason String WAF block reason code (e.g., BLOCK 1). See the Block Codes Reference for what each code means.
country String Two-letter ISO country code of the client (e.g., US, DE, CN)
cache_hit Boolean Whether the response was served from cache

IP Address Format

The client_ip field contains whichever IP version the client used to connect:

  • IPv4 addresses appear as dotted-quad notation: 203.0.113.42
  • IPv6 addresses appear in standard colon notation: 2001:db8::1

If you are filtering or parsing logs, ensure your tooling handles both formats. Most clients connect via IPv4, but IPv6 connections are becoming more common.

What Is Logged

Only blocked requests appear in the logs. Requests that the WAF allowed through to your application are not logged by the WAF. If you need logs for allowed traffic, use your Heroku application’s own request logging.

Need Help?

If you need help interpreting log data or setting up log exports: