Enhanced Debug Overview

Enhanced Debug is a feature of Akamai delivery configurations which replaces and enhances the existing Pragma debugging, providing a numbeer of benefits:

1. Secure debugging: Each debug request must pass a SHA256-HMAC of a secret Debug Key (known as an Auth Token) in a special debug request header. Only you and Akamai know the value of the underlying Debug Key, so hackers cannot debug requests to your site and discover details which might otherwise be leaked using Pragma debugging.
2. Time-limited debugging: The Auth Token can be generated so that it can be used for a specified duration, from a few seconds to one day. Within this time period, it can be used to make multiple debug requests, but after it has expired, it can no longer be used.
3. Per-URL debugging: The Auth Token can include a list of specified URLs or hostnames that can be debugged; other hostnames or URLs cannot be debugged using that Auth Token.
4. More information: Enhanced Debug allows you to specify a greater variety of details about the request which are not available when using Pragma debugging.
5. Simplified interface: The various Enhanced Debug options are simple to specify and easy to understand.

Implementing Enhanced Debug in your Akamai configuration(s)

(This is a one-time-only step to update your configuration(s) to use Enhanced Debug)

Add the Enhanced Debug behavior in your Akamai delivery configuration(s) - it can be added in the Default Rule or in any other top-level rule which does not include any Matches. It will automatically generate a 64-byte hexadecimal Debug Key when you add it:

(if you have multiple configurations, you can add the Enhanced Debug behavior to each configuration and copy the same Debug Key to all of them - this makes debugging your configurations easier)

Optionally you can disable Pragma Debugging for the specified configuration - this is the default and is strongly suggested. However, if you have developed your own in-house tools or scripts that assume that Pragma debugging is enabled, you can leave Pragma debugging enabled until you have updated your systems to all use Enhanced Debug.

Optionally you can choose to always return a Global Request Number (GRN) response header with every request, or only with requests that you debug. More details of the GRN can be found in Akamai's Tech Docs. If you choose to return a GRN with every request (this is the default), you can remove any instances of the Global Request Number behavior you may have already added to Property Manager

Save the Debug Key somewhere safe! You will use it when generating Auth Tokens to debug requests.

Generating an Enhanced Debug Auth Token

You can generate an Enhanced Debug Auth Token at debug.akamai.com, which includes full details about the Auth Token format and how to specify Enhanced Debug options. You specify your Debug Key and the duration for which you want the Auth Token to be valid.

The generated Auth Token will have a format something like the following:

exp=1717791526~acl=%2f*~hmac=7790a6bb170713c46081dd6d45db422db577888d802ece32b0fa6c249f611130

(this is just an example Auth Token and will not work with your site or Debug Key)

Debugging a customer configuration using an Enhanced Debug Auth Token

Once you have generated an Auth Token, you pass it in the Akamai-Debug request header along with one or more specific Enhanced Debug options, like this:

curl -vvvv "https://www.akamai.com" -H "Akamai-Debug: {auth-token} {enhanced-debug-options}"

Examples

In these examples, you are specifying the cache and vars Enhanced Debug options (see below for a list of all options) and using the example Auth Token shown above:

Akamai-Debug: exp=1717791526~acl=%2f*~hmac=7790a6bb170713c46081dd6d45db422db577888d802ece32b0fa6c249f611130 cache vars

Note that the order of the specified Enhanced Debug options does not matter - the following will have the exact same functionality as the above:

Akamai-Debug: exp=1717791526~acl=%2f*~hmac=7790a6bb170713c46081dd6d45db422db577888d802ece32b0fa6c249f611130 vars cache

It also does not matter if an option is duplicated - the following will have the exact same functionality as the above:

Akamai-Debug: exp=1717791526~acl=%2f*~hmac=7790a6bb170713c46081dd6d45db422db577888d802ece32b0fa6c249f611130 vars cache vars vars cache vars

Enhanced Debug Options

Below is a list of the valid Enhanced Debug options. You can pass one or more options in any order. In general, each option corresponds to one or more Pragma header values and results in the same response headers being returned. Specifying any option will result in the X-Akamai-Request-ID response header being returned (as if the akamai-x-get-request-id Pragma value was passed).

• cache: This is the equivalent of passing all the following Pragma header values: 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-cache-tags.
• ssl or tls: This is the equivalent of passing the akamai-x-get-ssl-client-session-id Pragma header value.
• vars: This is the equivalent of passing the akamai-x-get-extracted values Pragma header value.
• client: This is the equivalent of passing the akamai-x-get-client-ip Pragma header value.
• brotli: This is the equivalent of passing the akamai-x-get-brotli-status Pragma header value.
• tags: This is the equivalent of passing the akamai-x-get-cache-tags Pragma header value.
• a2: This is the equivalent of passing the x-akamai-a2-trace Pragma header value.
• ro or im: This is the equivalent of passing the akamai-x-ro-trace Pragma header value.

Certain options will also return additional response headers that are not returned when Pragma debugging is used, as follows:

• cache: This will also return the Akamai-Cache-Status response header.
• ssl or tls: This will return a response header called Akamai-Connection-Info which contains the connection information used between the client and Akamai.
• client: This will return a response header called Akamai-Client-Info which contains the client information used, such as Ip address, round trip time and more.

The special all value will return all of the above values - this can result in a lot of response headers, so should generally be avoided.