The tracking script

One script records page views, Web Vitals, and JavaScript errors, without cookies or browser storage. See Data kogut collects.

Add a site

1. Open Settings → Sites → Add site and enter acme.com.

2. Copy the script tag into the <head> of every page:

   <script defer src="https://kogut.acme.com/b.js" data-site="acme.com"></script>

3. Open your site and check Analytics for the visit.

Use the same tag on subdomains such as www.acme.com and shop.acme.com. kogut rejects pages outside the site’s domain and subdomains.

Next.js

Render this component in your root layout:

import Script from "next/script";

<Script
	src="https://kogut.acme.com/b.js"
	data-site="acme.com"
	strategy="afterInteractive"
/>;

Astro

Use is:inline to keep Astro from bundling the script:

<head>
	<script is:inline defer src="https://kogut.acme.com/b.js" data-site="acme.com"></script>
</head>

Client-side navigation needs no extra setup. For an app on Vercel, Netlify, or Cloudflare Pages, see Hosted apps.

Analytics history

Analytics covers up to one year (1y). Days older than the retained raw page views come from daily rollups. A metric is left out when its data is not kept for the whole range, such as JavaScript errors in 1y with the default retention. A metric has no comparison when the previous period extends beyond its retention.

Link the site to a service

To show errors on a service and use its traffic in incidents, add the site to that service’s sites list:

[[service]]
name = "website"
sites = ["acme.com"]

Create the site in the panel first. kogut links existing sites at startup and when the file changes.

Change the script’s settings

To send events to another endpoint, add data-api="https://kogut.acme.com/e" to the tag. Without it, events go to /e on the script’s origin.

To test on local addresses, add data-local. The script otherwise skips localhost, 127.*, 0.0.0.0, [::1], *.localhost, and file: pages. The server still requires an HTTP or HTTPS page URL on a registered domain.

Without data-site or a data-website-id (see the migration guides), the script does not track.

The app version

To tell which build of your app each visitor runs, add data-version with your release:

<script defer src="https://kogut.acme.com/b.js" data-site="acme.com" data-version="1.4.2"></script>

Page views, Web Vitals, and JavaScript errors then carry the version, and deploy reports compare the deployed version with the previous one. Set it at build time from your release tag or commit, such as git describe --tags, and send the same version to the Deploy API. A visitor whose browser still runs an older cached build reports that build’s version.

A version has up to 64 characters: ASCII letters, digits, ., _, +, and -. kogut stores events with a longer version or other characters, but without the version.

Each site keeps up to 20 versions. A new version takes the place of the one seen least recently, but only after that one has had no events for an hour, so requests that make up versions cannot push out the ones your visitors run. Events with a version that was not kept are stored without one. The list starts empty when the server restarts.

Exclude your own visits

Block the script in your browser. For uBlock Origin, add these lines under My filters:

||kogut.acme.com/b.js
||kogut.acme.com/script.js

There is no per-visitor opt-out stored in the browser.

Consent

If your site requires consent, load the script only after the visitor agrees:

<script>
	function loadKogut() {
		const script = document.createElement("script");
		script.src = "https://kogut.acme.com/b.js";
		script.dataset.site = "acme.com";
		document.head.append(script);
	}
</script>

Call loadKogut() from your consent tool. Until then, the script sends no requests.

Allow the script in your content security policy

Add kogut’s origin to both directives:

script-src 'self' https://kogut.acme.com;
connect-src 'self' https://kogut.acme.com;

Serve the script through your site

To use your site’s origin, proxy both /b.js and /e. With Caddy:

acme.com {
	handle /b.js {
		reverse_proxy https://kogut.acme.com {
			header_up Host kogut.acme.com
		}
	}
	handle /e {
		reverse_proxy https://kogut.acme.com {
			header_up Host kogut.acme.com
		}
	}
	# Keep your site's other handlers here.
}

Then use a relative script URL:

<script defer src="/b.js" data-site="acme.com"></script>

If the proxy runs on another machine or in another container, add its address to trusted_proxies. kogut trusts loopback proxies by default.

If Analytics warns that most visits come from one address, check proxy trust and Docker port forwarding: kogut counts everyone as one visitor and applies one rate limit to them all. When that address is private and sends X-Forwarded-For, such as a proxy on Docker’s bridge network, the Overview shows the trusted_proxies line to add. See Client addresses behind a proxy.