Why ?utm_source links wake your Laravel container

Every ?ref= or ?utm_source= link is a new page to the edge cache, so it reaches your serverless Laravel container. How to keep one copy with edge.ignore_query.

In this post
  1. Why do links with a query string wake a cached Laravel page?
  2. Where these parameters come from
  3. Why not ignore the query string altogether?
  4. Naming the parameters that change nothing
  5. Only a query string of one parameter
  6. What your application no longer sees
  7. Finding the parameters that wake your container
  8. In short

A serverless Laravel container is supposed to sleep when nobody needs it. You let the edge keep your public pages, you take the session off them, the homepage comes back with cdn-cache: HIT, and still the container wakes several times a day. The list of addresses that reached it shows why: /?ref=SomeDirectory, /?utm_source=newsletter, /pricing?fbclid=…. Every one of them is a page your app answers exactly like the page without it.

This post explains why tracking parameters get past an edge cache, why the obvious fix is the wrong one for Laravel, and what edge.ignore_query in Brewless does about it.

Because an edge cache keeps a page per address, and the query string is part of the address. /?ref=SomeDirectory is a page bunny.net has never seen, so it asks your container, even though Laravel ignores ref and sends the same HTML as for /.

On Scaleway, a serverless container scales to zero after 15 minutes without a request, and every request that reaches it starts those 15 minutes again. So one link from a directory is enough to keep the container up for a quarter of an hour, and that happens once for every value the parameter takes.

Where these parameters come from

You rarely add them yourself. Other people put them on the links to your site:

Parameter Who adds it
utm_source, utm_medium, utm_campaign Newsletters, social posts and ad campaigns, often your own
ref Directories, launch sites and lists of tools that link to you
fbclid Facebook and Instagram, on every outgoing link
gclid Google Ads, on every click

fbclid and gclid carry a different value for every click. To the edge each of those is a new page, so a cache that keeps pages per address cannot help with them at all: every visitor who comes in through such a link reaches the container.

The values that repeat, such as ?ref=SomeDirectory, do get kept after the first request. But every release empties the edge, so after each deploy the first visitor through each of those links reaches the container again. On brewless.eu itself, links from directories alone came to a few dozen such requests a day.

Why not ignore the query string altogether?

bunny.net has a switch for it, and it would solve this in one go. It would also break your Laravel app.

Laravel reads the query string on more pages than you might think:

  • paginate() and simplePaginate() read ?page=2;
  • search pages read ?q= or ?search=;
  • filters and sorting read ?sort=price or ?category=shoes;
  • a signed URL carries its signature and expires in the query string.

A pull zone that ignores every query string serves page one of your blog for page two, and the first search result for every search. Behind a pull zone Brewless manages the query string stays part of the address. What changes is that you can name the parameters that make no difference to your pages.

Naming the parameters that change nothing

edge.ignore_query takes a list of parameter names per environment:

brewless.yml
environments:
  production:
    edge:
      ignore_query: [ref, utm_*, fbclid, gclid]

An address whose query string is one of those parameters alone is then kept once, as the address without it. /?ref=SomeDirectory gets the page the edge already keeps for /, and /pricing?fbclid=… gets the page of /pricing. The container is not asked.

A name stands for the parameter with any value: ref takes ref=SomeDirectory, and not referrer=…. With * after it, it stands for every parameter that starts that way: utm_* takes utm_source=…, utm_medium=… and utm_campaign=…. You can name at most 10.

The next deploy gives the pull zone the rules for it, and brewless plan shows that change before you deploy. A deploy puts the rules back when someone changed or switched them off in the bunny.net dashboard, and removes them when the file no longer names any parameter. A deploy without a brewless.yml keeps what the last one set.

Only a query string of one parameter

There is a limit, and it is deliberate. bunny.net matches a rule against the whole query string, with * as its only wildcard. A rule cannot say "every parameter here is one of these names". So Brewless folds an address into the page without its query string only when that query string is a single parameter you named.

Address Kept as
/?ref=SomeDirectory /
/blog?utm_source=mastodon /blog
/blog?utm_source=news&utm_medium=email its own copy
/blog?ref=x&page=2 its own copy
/blog?page=2 its own copy

?utm_source=news&utm_medium=email still reaches the container once per combination. That is the price of the other line: ?ref=x&page=2 keeps page two, because a rule that dropped the whole query string there would lose a parameter your application reads. Most links from directories and social networks carry one parameter, so the single-parameter case is the one that removes most of these requests.

What your application no longer sees

Folding a link into the cached page means the request never reaches Laravel. That is the point, and it is also the one thing to check before you name a parameter.

Warning

Name only parameters your application never reads on a page the edge keeps. A referral program that stores ?ref=CODE in the session or a cookie on the first visit would lose that code, because the visitor gets the cached page without your code running.

Two things keep working:

  • An analytics script in the browser still sees the whole address. The address bar holds ?utm_source=newsletter, so Plausible, Matomo or any other script that reads it from window.location counts the campaign as before.
  • Pages the edge does not keep are not affected. A page with a session, or one that sets Cache-Control: private itself, reaches your application with its query string as it always did.

What stops is server-side tracking of those parameters on cached pages: a middleware that logs utm_source to your database will not see visitors whose page came from the edge. If you rely on that, either leave the parameter out of the list or move the tracking to the browser.

Finding the parameters that wake your container

You do not have to guess which parameters to name. On the page of an environment behind bunny.net, What reaches the container lists the addresses of the last 24 hours that the edge did not answer itself, most first, with the cache status bunny.net logged. The same list is in a terminal:

brewless wakes production

The list shows only the names in a query string (/?utm_source=…), never their values, and next to each address the sites it was linked from. A row of MISS on /?ref=…, with a directory as the referrer, is exactly what edge.ignore_query is for. The Wake-ups next to it show which of those requests started a container that had been asleep for 15 minutes.

The list is read from the request log of your own pull zone when you open it. Reading it never asks anything of the container, in line with the rule that Brewless never sends requests to your application to measure it. More on what else keeps a container awake is in why your Laravel container never scales to zero, and on what that first request after a sleep costs in Laravel cold starts on serverless. The full reference is the edge cache documentation.

In short

  1. An edge cache keeps a page per address, query string included, so every tracking value is a new page to it.
  2. Ignoring every query string breaks pagination, search and signed URLs in Laravel.
  3. edge.ignore_query names the parameters that change nothing, and folds an address with one of them alone into the page without it.
  4. A query string with more than one parameter keeps its own copy, so a parameter your app reads is never dropped.
  5. Leave out any parameter your server reads, and check What reaches the container to see which ones are worth naming.

Frequently asked questions

Why does a link with ?utm_source= reach my Laravel container when the page is cached?

The edge keeps one copy per address, and the query string is part of the address. /?utm_source=newsletter is a page the edge has never seen, so it asks the container, even though Laravel answers it with the same HTML as /.

Can I just tell bunny.net to ignore every query string?

Not safely. Laravel paginates with ?page=2, and search and filter pages read their query string too. A pull zone that ignores the query string serves page one for every page. Brewless keeps the query string in the cache key and only folds away the parameters you name.

Does ignoring utm parameters at the edge break Google Analytics or Plausible?

Not for an analytics script in the browser. The visitor's address bar still holds the whole address, so a script that reads utm_source from it sees the value. Only your server never sees the request, so server-side tracking of those parameters stops on cached pages.

What happens to ?utm_source=news&utm_medium=email?

It keeps its own copy at the edge. bunny.net matches a rule against the whole query string with * as its only wildcard, so it cannot tell that every parameter of several is one you named. Brewless therefore only folds a query string of a single named parameter.

How do I see which addresses with a query string wake my container?

On the page of an environment behind bunny.net, under What reaches the container, or with brewless wakes production. It lists the addresses of the last 24 hours that the edge did not answer itself, with only the names of a query string, never its values.

All posts Read this post as markdown

Try it on your own app

Brewless deploys your Laravel app to Scaleway and bunny.net, in your own accounts. Start free with one application, production included.