Query-Parameter (UTM/Tracking) Caching on Nginx

8 min read

Introduction

Lua query-parameter caching lets campaign visitors arriving from ads, emails and social posts get your fast, cached pages. It’s available on Nginx servers through the GridPane CLI, and is supported on Ubuntu 22.04 and newer.

What query-paramter caching does

Links from ads, emails and social posts add tracking codes to the end of your page addresses, like ?utm_source=newsletter or ?fbclid=.... By default, nginx skips the page cache for any address with these codes, so every campaign visitor gets a page built from scratch. During a big campaign, that can slow your site down.

Lua query-parameter caching fixes this. nginx recognises known tracking codes, ignores them when looking up the cache, and serves those visitors the same fast, cached page as everyone else.

Your tracking still works. The visitor’s browser keeps the full address, so Google Analytics, Meta Pixel, Klaviyo and similar tools still see every parameter.

It’s also safe by default. If an address contains anything the feature doesn’t recognise (a search term, a product filter, a page number), the cache is skipped exactly as it was before.

Before you start

Your site needs Redis or FastCGI page caching switched on. 

This is an Nginx specific page caching feature. It isn’t available on OpenLiteSpeed servers, or on sites with no page cache.

All commands below are run over SSH as root. If this is your first time connecting to a server over SSH, please see the following guides to get started:

Step 1: Set up your server (once per server)

Run these three commands, in order:

gp stack nginx -lua enable
gp stack nginx -lua packages-path set
gp stack nginx -lua query-param-cache regen

The last command installs the default list of tracking parameters. When it finishes you’ll see a line starting with query-param-cache policy deployed.

You only need to do this once. Every site on the server can then be switched on individually.

Step 2: Turn it on for a site

gp site example.com -lua-query-param-cache on

You should see:

lua-query-param-cache set to 'on' (no-fill) for example.com

The command tests the change before keeping it. If anything fails, it puts the site back the way it was and tells you why. It also clears the site’s page cache in the background.

This turns the site on in no-fill mode, which is the recommended setting for almost every site (see below).

Step 3. Choosing a mode (optional)

Use no-fill (the default) unless you have a specific reason not to.

no-fill

no-fill never changes the request, so nothing can break. Its only gap: a page that only campaign traffic visits (like an ad-only landing page) won’t get cached until something else loads it. A scheduled cache warm fixes this (see below).

Clean-Url

clean-url caches every page after its first visit, but it removes tracking codes before your site sees the request. If your site redirects visitors to another domain or alias, or redirects using JavaScript, those tracking codes can be lost. Only choose it if your campaign links land directly on your site’s own pages.

What it affectsno-fill (recommended)clean-url
Campaign visitors get cached pagesYes, once the page is cachedYes
Campaign visitors can fill the cacheNoYes
Changes what your site's code receivesNoYes, tracking codes are removed
Risk of losing tracking on redirectsNoneSome (see below)
Works with alt-domain sitesYesNo

Switching Modes

To switch modes on a site that’s already on (swap out example.com with your website’s URL):

gp site example.com -lua-query-param-cache regenerate -mode clean-url

You can change it back to the default no-fill mode with:

gp site example.com -lua-query-param-cache regenerate -mode no-fill

Step 4. Check it’s working

Check the site’s status:

gp site example.com -lua-query-param-cache status

Look for state : in-sync at the bottom. If it says DRIFT, run the repair command it prints.
To test a real request, run this on the server:

curl -sk -o /dev/null -D - "https://example.com/?utm_source=test" --resolve example.com:443:127.0.0.1 | grep -i x-grid

On a Redis site, a working setup shows:

x-grid-srcache-skip: ignored_query_string
x-grid-srcache-fetch: HIT

ignored_query_string means the tracking code was recognised. HIT means the visitor got the cached page. FastCGI sites show the same values in x-grid-cache-skip and x-grid-cache.

If you see MISS, the page simply isn’t cached yet. Load it once without the ?utm_source=test part, then test again.

Tracking parameters included by default

The default list covers 76 tracking parameters. Each one is read by a tracking script in the visitor’s browser, so it keeps working on cached pages. Where a row says “anything starting with”, every parameter beginning with those letters is covered.

PlatformParameters
UTM campaign codes (all platforms)anything starting with utm_ (e.g. utm_source, utm_medium, utm_campaign)
Google Ads and Analyticsanything starting with gad_, plus gclid, gclsrc, gbraid, wbraid, dclid, _ga, _gl, gtm_debug, srsltid
Meta (Facebook and Instagram)fbclid, fb_action_ids, fb_action_types, fb_source
Microsoft Advertisingmsclkid
X (Twitter)twclid
LinkedInli_fat_id
Redditrdt_cid
Pinterestepik
SnapchatScCid, ScCID
Yandexyclid, ysclid, _openstat
PixelYourSitegadid, fbadid
HubSpotanything starting with hsa_, plus __hstc, __hssc, __hsfp, _hsenc, _hsmi, hsCtaTracking
Klaviyo_kx
Adobe Marketo Engagemkt_tok
Drip__s
ActiveCampaignvgo_ee
dotdigitaldm_i
Listraktrk_contact, trk_msg, trk_module
Salesforce Marketing Cloudsfmc_id
Brevo_sc, _se
Omedaoly_anon_id, oly_enc_id
Verovero_id, vero_conv
Adobe Advertisingef_id, s_kwcid
Marin Softwaremkwid, pcrid
ShareASale (Awin)sscid
Matomo (and Piwik)mtm_campaign, mtm_cpn, mtm_source, mtm_medium, mtm_keyword, mtm_kwd, mtm_content, mtm_cid, mtm_group, mtm_placement, pk_campaign, pk_cpn, pk_source, pk_medium, pk_keyword, pk_kwd, pk_content, pk_cid, matomo_campaign, matomo_kwd, piwik_campaign, piwik_kwd

The list also includes 35 more parameters that are switched off by default, because they may need checking against your site first.

The default list is only installed on servers that don’t have a list yet. If your server already has one, it’s kept exactly as it is. To see your server’s current list:
cat

/etc/nginx/gridpane/cache-key-query-params.list

Adding your own tracking parameters

Most sites never need to change the default list. The list is shared by every site on the server. Here’s the step by step:

1. Back up the list

Create a copy of the list so you can restore it if needed:

cp -a /etc/nginx/gridpane/cache-key-query-params.list /root/cache-key-query-params.list.bak

2. Open the list

Open the list with the nano editor with the following:

nano /etc/nginx/gridpane/cache-key-query-params.list

3. Add your custom parameter

We recommend you add your edit at the bottom of the file. Add one parameter per line, and then save the file with XTRL+O followed by Enter. Exit nano with CTRL+D.

For a parameter called agency_click:

exact agency_click

4. Apply the change

Reload Lua to implement your changes:

gp stack nginx -lua query-param-cache regen

If you’ve made a typo, regen stops, names the line number, and changes nothing on your live sites. Fix the line and run it again.

Names are case-sensitive, so ScCid and sccid are different parameters.

Only add tracking codes read by JavaScript

Only add a parameter if it’s read in the visitor’s browser by a tracking script, and nothing on your site reads it in PHP. Never add parameters that change what the page shows, for example:

  • search, pagination and language parameters (s, page, paged, lang)
  • WooCommerce parameters (add-to-cart, coupon, orderby, min_price, v)
  • affiliate and login parameters (ref, aff, cid, awc, cjevent)
  • Mailchimp parameters (mc_cid, mc_eid, mc_cart_id)

Adding one of these makes every visitor see the same cached page, whatever the parameter says. If you’re not sure about a parameter, leave it off and the page will just skip the cache, as it always has.

Disabling query-parameter caching

Switch the site off, then clear its page cache:

gp site example.com -lua-query-param-cache off
gp fix -page-cache example.com

The site remembers its mode, so turning it back on later restores the same setting.

To remove the feature from the whole server, turn it off on every site first, then run:

gp stack nginx -lua disable

Troubleshooting

Tracking links show BYPASS and -query_string

The feature isn’t switched on for the site. Check its status, then turn it on:

gp site example.com -lua-query-param-cache status
gp site example.com -lua-query-param-cache on

Tracking links show BYPASS and -query_param

The address contains a parameter that isn’t on the list, so the cache is skipped. This is safe. Check the address for unexpected parameters, or refresh the server’s list:

gp stack nginx -lua query-param-cache regen

“applies to a redis/fastcgi page cache only”

The site has no page cache. Turn on Redis or FastCGI page caching for the site first, then run the on command again.

regen fails and mentions a line number

There’s a typo on that line of the list. Nothing on your live sites has changed. Open the list, fix the line, and run regen again:
nano /etc/nginx/gridpane/cache-key-query-params.list
gp stack nginx -lua query-param-cache regen

status says DRIFT

The site’s settings are out of sync. Run the repair command that status prints, usually:
gp site example.com -lua-query-param-cache regenerate

Campaign tracking is lost after switching to clean-url

A redirect on your site is dropping the tracking codes. Switch back to no-fill:

gp site example.com -lua-query-param-cache regenerate -mode no-fill

“ROLLBACK UNCONFIRMED”

Don’t change anything else on the site. Contact support with the command’s full output, and the output of these commands:

gp stack nginx -lua query-param-cache show
gp site example.com -lua-query-param-cache status