Enhanced Debug
Enhanced Debug is a method for debugging requests that go through Akamai's servers. It includes all the functionality provided by the existing Pragma debugging, but is more secure and provides additional information.
All Enhanced Debugging requests pass an authentication token in the Akamai-Debug request header – this auth token is generated by you using a secret debug key. Only you and Akamai have access to the debug key used to generate the token.
Before you begin
Review your configuration and perform the following steps if necessary:
- Remove any Pragma debugging-specific code, such as the Remove Debug Info rule.
- Remove any code related to passing a specific header to enable Pragma debugging.
- If you are using WAF, disable Rule 699989 to strip Pragma request headers.
Implementation
Add the behavior and set the Enable slider to On. You can add it to these rules in your property:
- The Default Rule. All requests processed by this property will support Enhanced Debug.
- A custom top-level rule. You can add it in a custom rule that doesn’t have any parents.
Features and options
Option | Description |
---|---|
Debugging Enabled | Enables enhanced debugging using the Akamai-Debug request header. |
Debug Key | Specify the debug key to validate the debugging auth token when Akamai processes the request. The same debug key is also used to generate the auth token. The debug key value needs to be a 64-byte hex string. You can auto-generate a valid random string with the refresh button. You can generate a debug key in one property and reuse it in other configurations. |
Disable Pragma Debugging | Whether you want to allow Pragma-based debugging. The default value is Disabled, meaning that the standard debugging with the Pragma request header is no longer available. Pragma debugging should only be enabled during a transition period, when you’re still configuring the Enhanced Debugging functionality. |
Global Request Number | Specify whether you want to return the Global Request Number (GRN) in the Akamai-GRN response header for all requests, even if the Akamai-Debug request header is not passed. For example:Akamai-GRN: 0.25313217.1562625611.27bb4bb The Akamai-GRN header is useful for log extraction. |
Generate the authentication token
To make an Enhanced Debugging request, you need to generate an auth token. You can use the same token to debug multiple requests until it expires.
To generate the token, you need to provide these values:
- The Debug Key value specified in the Enhanced Debug behavior.
- A duration for which the token should be valid. This can range from 30 seconds to 1 day.
You can use Akamai Token Auth software development kits (SDK) to generate this token. They are available for multiple programming languages, and they account for all required and optional fields:
- Python: https://github.com/akamai/EdgeAuth-Token-Python
- Java: https://github.com/akamai/EdgeAuth-Token-Java
- Ruby: https://github.com/akamai/EdgeAuth-Token-Ruby
- NodeJS: https://github.com/akamai/EdgeAuth-Token-Node
See the README section on these pages for details on how to use the SDKs. Alternatively you can use the Akamai Debug Utilities page to generate the token.
Debug your requests
To debug your requests and receive enhanced debugging information with the response, you need to pass the Akamai-Debug request header (elements in square-brackets are optional):
Akamai-Debug: [auth-token] option [option…]
There are multiple options you can specify in the Akamai-Debug header depending on the results you want to receive in the response headers. If you want to specify multiple option values, separate them with blanks or commas. The order of any specified option values is not important. However, if you are passing an auth-token, place it before any option values.
Specify the auth token
The auth token can be passed in two ways - either within the Akamai-Debug header itself or in a separate header or cookie. The debugging functionality is exactly the same, whichever method you use.
- Passing the auth token in the Akamai-Debug header itself. You can pass the auth token as the first value in the Akamai-Debug header:
Akamai-Debug: [auth-token] option [option...]
For example, when passing the vars and cache options:
Akamai-Debug: exp=1562789819~acl=%2f*~hmac=06b2aaac06fc420b172cfdaf227459dc2176f5d64e4b6f2648f01980768837cf vars cache
- Passing the auth token in the akamaidebugtoken header. You can pass the auth token in the akamaidebugtoken header, and pass only the debugging values in the Akamai-Debug header, as in the following example showing the two headers:
Akamai-Debug: vars cache akamaidebugtoken: exp=1562789819~acl=%2f*~hmac=06b2aaac06fc420b172cfdaf227459dc2176f5d64e4b6f2648f01980768837cf
- Passing the auth token in the akamaidebugtoken cookie. You pass the auth token in the akamaidebugtoken cookie, and pass only the debugging values in the Akamai-Debug header, as in the following example showing the Akamai-Debug header and the Cookie header:
Akamai-Debug: vars cache Cookie: akamaidebugtoken=exp=1562789819~acl=%2f*~hmac=06b2aaac06fc420b172cfdaf227459dc2176f5d64e4b6f2648f01980768837cf
Note that theakamaidebugtoken
cookie name is case-sensitive, and must be specified as lower-case.
If you pass an invalid or expired auth token, whether inline within the Akamai-Debug
header, or separately in the akamaidebugtoken
header or cookie, a Akamai-Debug-Status
response header is returned, indicating the specific auth token error. No other debugging response headers are returned.
Specify the Akamai-Debug header options
The Akamai-Debug header is a shorter, simpler way to get the same response, instead of passing a long sequence of Pragma values. In other words, the Akamai-Debug header is an 'alias' for the Pragma header. Compare the values of both header types:
Akamai-Debug value | Pragma values generated The examples below do not include the auth token. |
---|---|
[any value] | akamai-x-get-request-id |
cache | akamai-x-cache-on, akamai-x-cache-remote-on, akamai-x-check-cacheable, akamai-x-get-cache-key, akamai-x-get-true-cache-key |
ssl or tls | akamai-x-get-ssl-client-session-id |
vars | akamai-x-get-extracted-values |
client | akamai-x-get-client-ip |
feo | akamai-x-feo-trace |
im or ro | akamai-x-ro-trace |
tags | akamai-x-get-cache-tags |
all | All the above values |
a2 | x-akamai-a2-trace (not included with all) |
brotli | akamai-x-get-brotli-status (not included with all) |
As an example, specifying the following Akamai-Debug request header:
Akamai-Debug: cache vars
results in the same debug response headers being returned as if you passed this Pragma request header:
Pragma: akamai-x-get-request-id, akamai-x-cache-on, akamai-x-cache-remote-on, akamai-x-check-cacheable, akamai-x-get-cache-key, akamai-x-get-true-cache-key, akamai-x-get-extracted-values
Updated 13 days ago