Enhanced Debug is a default, secure, and feature-rich method for diagnosing requests that replaces legacy Pragma debugging. It uses a time-limited authentication token generated from a customer-defined secret key to prevent unauthorized access.

See also the Debug Mode match. It explains how you can control other functionality in your property based on whether a specific request is being debugged using enhanced debugging.

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 any functionality to strip Pragma request headers.

Implementation

Add the behavior and make sure that the Enable slider is 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 and match criteria.

🚧

By default, Enhanced Debug functionality is applied to all requests. If you add this behavior in a rule that has match criteria defined, all match criteria are ignored for Enhanced Debug.

Features and options

Generate the authentication token

To make an enhanced debugging request, generate an auth token with either:

• Akamai Debug application.
• Akamai's EdgeAuth software development kits (SDKs), available for multiple programming languages. See the README section for details on how to use the SDKs.

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 the same token to debug multiple requests until it expires. A generated token will look like this:

exp=1562789819~acl=%2f_~hmac=06b2aaac06fc420b172cfdaf227459dc2176f5d64e4b6f2648f01980768837cf

The debug examples in this guide abbreviate this to exp=1562789819~acl=%2f_~hmac=06b2...37cf for display purposes only.

Debug your requests

To start debugging and receive comprehensive details in the response, pass the auth token and one or more debugging options with your request.

Specify the auth token

You can pass the auth token either within the header or in a separate header or cookie. The debugging functionality is exactly the same in each method.

Akamai-Debug header. You can pass the auth token as the first value in the Akamai-Debug header, followed by one or more debugging options, separated by blanks:

Akamai-Debug: auth-token option [option...]

See this example with the cache and vars debugging options:

Akamai-Debug: exp=1562789819~acl=%2f*~hmac=06b2...37cf vars cache

akamaidebugtoken cookie. You can pass the auth token in the akamaidebugtoken cookie, and pass only the debugging options in the Akamai-Debug header.

Akamai-Debug: option [option...]

Cookie: akamaidebugtoken=auth-token

See this example with the cache and vars debugging options:

Akamai-Debug: vars cache

Cookie: akamaidebugtoken=exp=1562789819~acl=%2f*~hmac=06b2...37cf

Note that the akamaidebugtoken cookie name is case-sensitive, and must be specified as lower-case.

📘

If you pass an invalid or expired auth token, the Akamai-Debug-Status response header is returned, indicating the specific auth token error. No other debugging response headers are returned.

Example curl request

An example curl request may look like this:

curl "https://www.akamaicustomer.com/abc/def" -H "Akamai-Debug: exp=1562789819~acl=%2f*~hmac=06b2...37cf vars cache"

Or this:

curl "https://www.akamaicustomer.com/abc/def" -H "Cookie: akamaidebugtoken=exp=1562789819~acl=%2f*~hmac=06b2...37cf" -H "Akamai-Debug: vars cache"

Enhanced Debug options

Enhanced debugging offers a modern alternative to the legacy Pragma header debugging method. Instead of passing a long sequence of comma-separated Pragma values, Enhanced Debug provides a concise, simpler alias using "debugging options" which are passed in the Akamai-Debug header. A single debugging option may equate to multiple Pragma values. In addition, Enhanced Debug returns information that is not available using Pragma debugging. Note the following:

• Multiple debugging options may be specified in the Akamai-Debug header.
• The order of debugging options in the Akamai-Debug header is ignored.
• The same debugging option may be specified multiple times in the Akamai-Debug header.

This table shows how the two debugging approaches compare:

🚧

Unsupported debug options

All debug options denoted with an asterisk (*) are currently not supported.

The none debugging option

If you specify the none debugging option with a valid auth token, no debugging response headers will be returned, but the Debug Mode match will evaluate to true in your delivery property. This allows you to define processing in your delivery property which should only occur when a request is debugged.

For example, you could define an alternate testing origin which is only used when the Debug Mode match is true. If you specify the none debugging option, all other debugging options are ignored.

Example

If you specify the Akamai-Debug request header:

Akamai-Debug: cache vars

The same debug response headers are 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

It will also return multiple Debug information headers.

Debug information headers

You can use information found in response headers to help during the debugging process. See the table below for details returned in Akamai-specific, debug information headers.

For information specific to returned Pragma headers, see our Pragma headers documentation.

📘

Headers marked with (multiple) such as Akamai-Cache-Info-* (multiple) may have several variants returned for a single request. For example, a request that traverses a child server and a parent server would return both the Akamai-Cache-Info-Child response header and the Akamai-Cache-Info-Parent response header.