How to Implement and Interpret Debug Headers

January 29, 2019

Debug headers are a valuable tool for understanding what is happening with content on a webpage so you can make informed decisions in your performance optimization efforts. In this article, we will look at how to set up and interpret debug headers and provide best practices for implementing them on the Section platform. First off, however, let’s review what response and request headers are and how to read them.

Chrome Developer Tools provide information on how the browser is interacting with a particular application or website. These tools help you assess performance and debug certain aspects of the page load by allowing you to see how a website is built, where its content is served from, its page load times, and so on.

Response and Request Headers

Response and request headers provide information on where a request is being served from, in addition to further data such as whether it was served from a cache or a Content Delivery Network (CDN).

Traditionally, almost all response and request headers will give you information linked to the cache status of an object, in addition to where that object is being served from (in multi-tiered CDNs). Critical information that is normally provided includes cache state, cache location, cache key, and transaction ID. All of this information helps in determining how to debug request headers.

Within Chrome DevTools, receiving and viewing the debug headers is relatively straightforward; however, knowing how to interpret the information returned in the response can be rather complex. Sometimes, single characters can provide a host of data that can be interpreted only by referring to particular Internet specifications; in other instances, a detailed CDN guide may be needed to break down what each header specifically means.

The response headers tell you how the web server or CDN is returning each HTTP request to the browser. Each header has a unique request even if they share the same server; for instance, Section assigns a unique ID under section-io-id to each request; Varnish Cache also gives each request its own identifier using x-varnish. The response headers tell you if the request was a cache hit or cache miss; a cache hit will be labeled x-cache: Hit. You can also determine the cached age of the requested item from a response header, in addition to the time of the last modification and the content type, such as image (png) or text (HTML).

The request headers are those sent by the browser when it first initiates a connection to your remote address. They provide information on how the request was made, such as browser type, operating system, IP address of the issuing computer, etc. Request headers can help you identify whether or not your web application is having challenges with particular operating systems and identify potential solutions, such as performing redirects in response to the device type or setting new caching rules.

Benefits of Debug Headers

Debug headers help to provide a deeper understanding (at a granular level) of where and how specific objects are being cached, so you can troubleshoot, define an optimal debugging strategy, and optimize content delivery.

They also let you spot check what’s happening with newly published files, updated features, or configuration changes. Transaction IDs are particularly helpful for this as they provide a unique string, helpful for identifying a transaction within logs. This allows you to find out exactly what happened in a specific request for a single asset and see how a specific object behaves within the entire content delivery workflow.

Furthermore, debug headers allow you to see individual requests coming into the browser in real-time. By clicking on each individual request, you are able to access the headers, cookies, timing, and content of each response.

Implementation Best Practices at Section

While every CDN typically provides debug headers, each has their own unique take on how they deliver the information. Section’s Edge CDN services also follow a defined structure.

As mentioned above, a section-io-id is assigned by default to each request that moves through the Section platform. As all requests are logged, this allows you to track down issues related to each individual request. We ensure that access to headers is secure for each customer.

Some examples of these include:

  • x-varnish: assigned by Varnish to every request
  • x-cache: as indicated above, this is marked as hit or miss, which helps you identify whether a request has been served from cache or not.

We can also tell you:

  • Which edge server handled the request
  • In addition to hit/miss, other information related to cache can be obtained, including cache location, hierarchical tiering and origin shield information
  • Time to serve
  • Time to fetch from origin

The transaction ID can be used for further troubleshooting on the CDN side. The section-io-tag can be set by any edge module and the section-io-cache-tag can be set in Varnish Cache. This can be used to debug/capture all information related to the request/response.

Unlike many traditional CDNs that lock configurations in a black box, Section gives developers full control to customize headers according to your choice of modules. Headers can be added, which are unique to the modules deployed on the Section stack. For instance, the Kraken-optimized header will let you know if the image has been optimized by Kraken or not.

In the logs, you can track patterns across requests/responses for all indexed headers.

An example of response headers for an HTML request:

accept-ranges: bytes
access-control-allow-credentials: true
access-control-allow-headers: DNT,X-Mx-ReqToken,Keep-Alive,User-Agent,XRequested-With,If-Modified-Since,Cache-Control,Content-Type
access-control-allow-methods: GET, POST, OPTIONS access-control-allow-origin: *
age: 33603
cache-control: no-store, no-cache, must-revalidate, max-age=0
content-encoding: gzip
content-length: 30291
content-type: text/html; charset=UTF-8
date: Sun, 20 Jan 2019 23:25:19 GMT
expires: -1
grace: none
pragma: no-cache
section-io-cache: Hit
section-io-id: 403514207947711548026719.492
section-visitors: 50
set-cookie: sqshowmaintenance.1479168057=false;Path=/; Expires=Mon, 21 Jan 2019 00:25:19 GMT;
status: 200
vary: Accept-Encoding
x-content-type-options: nosniff
x-frame-options: SAMEORIGIN
x-magento-cache-control: max-age=155520000, public, s-maxage=155520000
x-magento-cache-debug: HIT
x-xss-protection: 1; mode=block

An example of response headers for an image request:

accept-ranges: bytes
bytes-saved: 46631
cache-control: public, max-age=31622400
content-length: 13856
content-type: image/jpeg
date: Sun, 20 Jan 2019 23:25:20 GMT
kraken-optimized: true
kraken-size: 13856
original-size: 60487
section-io-cache: Hit
section-io-id: 4035142079477351548026720.027
section-visitors: 50
server: openresty
status: 200
via: 1.1 varnish-v4
x-varnish: 55546054 9713805

For more guidance around the technical implementation of Section’s debug headers, see our Custom Logging Documentation.