Migrating

The safe order

1. Add trckable's script alongside your current tool. Two scripts for a week costs your visitors about 2 KB and tells you more than any comparison table.
2. Import your history.
3. Compare the week where both ran. They will not match exactly — nobody's do — and the differences are explainable, which is the next section.
4. Remove the old script.

Importing

trckabled import tkb_a1b2c3d4 export.ndjson
trckabled import tkb_a1b2c3d4 export.csv
cat export.ndjson | trckabled import tkb_a1b2c3d4 -

One row per pageview or goal. trckable reads Plausible's and Umami's column names as well as its own, and GA4's BigQuery export as BigQuery writes it, so an export usually imports without being touched. The import goes through the same write-ahead log and writer as live traffic, so the result is a real dataset and not a special case.

The site is its id or its domain. Importing the same file again stores it once. Each row gets an id from its contents and its place in the file, and a row whose id is already stored is skipped, so a second run of the same file changes nothing.

If most of a file's rows cannot be read (fewer than one in five usable), the import stops and lists the columns it expects. An import that cheerfully reports "0 rows" is worse than an error.

Stop the server first

An import writes to the same write-ahead log the server does, so it needs the server stopped. Run against a data directory in use, it refuses and says so. When it is done, start the server again: the writer applies the imported rows.

With Docker, stop the container, run the import in a one-off container on the same volume, and start it again:

docker stop trckable
docker run --rm -v trckable-data:/data -v "$PWD":/import \
  ghcr.io/trckable/trckable:latest import tkb_a1b2c3d4 /import/export.ndjson
docker start trckable

To stream a file in instead, give the one-off container -i and use -:

docker run --rm -i -v trckable-data:/data \
  ghcr.io/trckable/trckable:latest import tkb_a1b2c3d4 - < export.ndjson

Why the numbers will differ

• Sessions. trckable ends a session after 30 minutes of inactivity, server-side. A tool that closes sessions at midnight, or on a fixed timer, counts differently.
• Bounces. Here a bounce is one pageview and no interaction. Some tools use a time threshold, which makes a slow reader a bounce.
• Channels. trckable checks paid before search and AI before search, so an ad on Google is Paid and a visit from Gemini is an AI assistant. Tools that classify differently will show a different split of the same traffic.
• Bots. Filtering is not standardised anywhere. Stricter filtering means fewer visits and truer ones.
• Blocking. If you move from a hosted tool on its own domain to a same-origin proxy, trckable will see visits the old one never did. Your traffic did not grow; your measurement did.

Step by step, per tool

• From Google Analytics 4: through GA4's BigQuery export.
• From Plausible: raw events out of Community Edition's ClickHouse.
• From Umami: one query against Umami's PostgreSQL database.

Leaving trckable

The same way you arrived: your data is on your disk, in your own instance. The CSV export and the API give you any range as totals (per source, page, country and so on, not one row per visit: there is no raw export of single events yet). trckabled backup writes everything as one encrypted archive: the analytics inside it are Parquet files, readable once the archive is decrypted by a restore with your key (Backups).

Nothing about trckable is designed to make leaving hard. A tool you cannot leave is a tool you did not choose.