Debug rules created with Rules Engine
Turn on Debug Rules for an application and read the rules each request ran in the GraphQL API, Data Stream, or Real-Time Events.
You can turn on Debug Rules for an application in Azion Console, then read which Rules Engine rules each request ran. The GraphQL API, Data Stream, and Real-Time Events all return that record. A rule that is missing from the record did not run on the request.
A firewall has its own Debug Rules setting, in the Main Settings tab of the firewall. Its rules reach the same record only while the firewall is active.
Prerequisites
- An application with at least one active rule, served by a workload. To create both, refer to Applications quickstart.
- Access to Azion Console. To sign in, refer to Access Azion Console.
- For the GraphQL API, a personal token. To create one, refer to Manage a personal token.
Turn on Debug Rules
Debug Rules is off when you create an application. In the API, the setting is the debug boolean of the application. In Azion Console, the Debug Rules toggle of the Main Settings tab sets it.
To turn on Debug Rules in Azion Console:
Access Azion Console > Applications, and select the application.
In the Debug Rules section, turn on the Debug Rules toggle.
The debug field of the application reads true, and the application records the rules that each request runs. For the other settings of the tab, refer to Main Settings.
Query the record with the GraphQL API
The GraphQL API of Real-Time Events returns the record of executed rules in the stacktrace field of the workloadEvents dataset. That dataset holds the events of the HTTP requests to your applications. This query reads 10 events from the time window in tsRange, in ascending order of ts. Set begin and end to the window you want to read:
From Postman or another GraphQL client, send the query in a POST request to https://api.azion.com/v4/events/graphql. The request carries the Authorization: Token [TOKEN VALUE] header and a JSON body with the query in its query key.
Each event in the response carries the four fields that the query selects:
| Field | What it holds |
|---|---|
ts | The time the request started |
remoteAddress | The IP address of the client that sent the request |
requestUri | The URI of the request |
stacktrace | The rules that ran on the request |
The response lists the events under data.workloadEvents. Each stacktrace is a JSON string that groups rule names by where the rules ran. edge_application_request holds the Request Phase rules of the application, and edge_application_response holds its Response Phase rules. edge_firewall holds the rules of the firewall. A request that passed through a firewall and an application can carry all three keys in one string.
Stream the record with Data Stream
Data Stream sends the record of executed rules to an endpoint you own, in the $traceback variable of the events it collects from applications. Create a stream whose source is your applications, with a custom template whose data set holds $traceback, as this data set does:
| Variable | What it holds |
|---|---|
$time | The date and time of the request, such as Oct. 31st, 2022 - 19:30:41 |
$traceback | The names of the Rules Engine rules, of the application and of the firewall, that ran on the request |
A stream collects the events of the workloads it is associated with. In an account that still uses legacy Domains, it collects the events of the domains it names instead. The stream delivers the events to the connector set as its destination, while the stream is active. To confirm that the stream reaches your endpoint, query its deliveries in Real-Time Events.
Find the record in Real-Time Events
Real-Time Events shows the record of executed rules in Azion Console, with no stream and no query. Each event of an HTTP request carries the record in $traceback, with the same keys as stacktrace in the GraphQL API.
To find the record in Azion Console:
Access Azion Console > Real-Time Events.
The $traceback field of the event lists, per key, the names of the rules that ran on that request.
A firewall rule that applies WAF lets the other rules of the firewall run alongside it. The record can therefore list more firewall rules for a request that WAF blocked, and the block still applies. For every field of an HTTP request event, refer to Real-Time Events.