Trafficinator

Pragmatic analytics traffic generator

analyticstestingtoolingmatomoga4

Why I built Trafficinator, how it works, and how to use it to safely generate realistic web traffic for analytics validation.

When you ship analytics implementations often, you eventually need a repeatable way to produce traffic that looks like the real world. Not “10,000 hits per second” load tests—just credible visits with varying sources, UTM params, user‑agents, paths, and pacing so you can validate event models, debug tagging, and demonstrate reports end‑to‑end.

That’s why I built Trafficinator.

It’s a small, scriptable traffic generator designed for analytics engineers: predictable when you want it, chaotic when you need it, and careful about not hurting anything. It helps me verify Matomo/MTM setups (my default), GA4/GTM fallbacks, and server‑side pipelines before and after releases.

Repository: https://github.com/Puttrix/Trafficinator

What follows is the thinking behind it, how it works at a high level, and practical usage patterns I reach for in day‑to‑day work.

Why this exists

  • Validate end‑to‑end: From tag firing → network requests → ingestion → reports/dashboards.
  • Reproduce bugs: Generate the exact path + source + device mix that triggered an issue.
  • Migration parity: UA/GA4 → Matomo event model mapping checks with the same traffic seed.
  • Consent and privacy: Verify consent gating, cookieless behavior, and data minimization.
  • Demos and training: Seed clean datasets for workshops without clicking through UIs for hours.

Design goals

  • Simple first: a single command generates realistic pageviews and optional events.
  • Scriptable: define scenarios as data, not code, so you can version them in Git.
  • Safe by default: polite pacing, random jitter, and guardrails to avoid hammering.
  • Transparent: logs with enough detail to debug what was sent and why.
  • Portable: works locally, in containers, or in CI/CD.

How Trafficinator works (conceptually) Trafficinator walks through a set of “visits”. Each visit simulates a user journey with:

  • A source profile: direct/referrer/UTM combinations (e.g., utm_source=linkedin).
  • A device profile: desktop/mobile/tablet via user‑agent rotation.
  • A path plan: a sequence of URLs with dwell time ranges and optional event hooks.
  • Optional geo hints: e.g., set Accept-Language or proxy headers if you control the edge.

Under the hood it issues HTTP requests (GET by default) to the specified URLs, applying your headers, query params, and delays. If your analytics is tag‑manager based (Matomo Tag Manager, GTM), the tracker payloads will naturally fire as the pages load; if you test server‑side or beacon endpoints directly, you can also send crafted hits to those endpoints as a dedicated step.

Basic setup

  1. Clone the repo and read the README Repo: https://github.com/Puttrix/Trafficinator

  2. Configure a scenario file Scenarios describe pages, pacing, and variability. A simple (illustrative) YAML might look like this:

    # examples/launch-check.yml
site: https://example.com
visits: 25                 # how many sessions to run
pace:
  minDelayMs: 800          # between pageviews
  maxDelayMs: 2500
sources:
  - type: direct
  - type: utm
    params:
      utm_source: linkedin
      utm_medium: social
      utm_campaign: q3_launch
  - type: referrer
    ref: https://news.ycombinator.com/
devices:
  - desktop
  - mobile
userAgents:
  desktop: ["Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)…"]
  mobile:  ["Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X)…"]
paths:
  - "/"
  - "/work"
  - "/about"
events:
  - when: path == "/work"
    send: click:cta

  3. Run it Depending on the tool’s exact interface (see the repo’s README for authoritative flags):

    # Run with a scenario file
trafficinator run examples/launch-check.yml

# Or via Docker if provided
docker run --rm -v "$PWD:/app" ghcr.io/puttrix/trafficinator run /app/examples/launch-check.yml

What the output looks like

  • Console summary showing each visit: source, device, pages hit, time on page.
  • Optional structured logs (JSON/CSV) for later analysis.
  • If enabled: a recap of response codes and basic timing for quick health checks.

Common scenarios I use

  1. Campaign QA before launch

    • Seed a few dozen sessions mixing utm_source/utm_medium variants.
    • Verify that sessions and conversions attribute properly in analytics reports.
    • Double‑check spelling, casing, and unintended overrides.

  2. Consent boundary checks

    • Run one batch with consent granted, one without.
    • Confirm data minimization, storage behavior, and event suppression are respected.

  3. Migration parity: GA4 → Matomo

    • Generate a fixed seed scenario and feed both pipelines.
    • Compare key metrics and event properties to validate mapping.

  4. Path‑based debugging

    • Target problematic flows (e.g., /checkout → /thank-you).
    • Use slower pacing and more verbose logs to catch intermittent issues.

Tips for credible traffic

  • Randomness with guardrails: jitter delays and rotate UAs, but within sensible bounds.
  • Keep volumes humane: dozens/hundreds, not thousands, unless you truly need load.
  • Separate staging vs prod: different scenarios, different API keys/containers if relevant.
  • Label your traffic: add a recognizable UTM like utm_campaign=qa_YYYYMMDD.

Matomo‑first details I typically validate Matomo by driving real pages that load the Matomo Tag Manager container (this site uses matomo.surputte.se). If I need to test specific event payloads or server‑side enrichers, I’ll pair pageviews with explicit requests to the Matomo Measurement API using the same visitor ID to keep sessions coherent.

Safety and etiquette

  • Respect robots and rate limits. Even on your own properties, stay polite.
  • Avoid hammering third‑party origins referenced by your pages.
  • If you must test at scale, coordinate with ops and observability first.

FAQ Q: Does Trafficinator execute JavaScript like a headless browser? A: It focuses on HTTP‑level requests and pragmatic realism. For SPA/DOM‑heavy journeys requiring JS execution, pair it with a headless browser suite for a few golden paths and use Trafficinator for the bulk, repeatable seeding.

Q: Can I point it at server‑side tagging endpoints? A: Yes—crafting direct hits is useful for low‑level testing. Just ensure you don’t poison production data and that consent rules are mirrored.

Q: Can I run it in CI? A: Yes. Commit scenario files and run small batches on PRs to catch regressions (e.g., missing routes, broken redirects, or tag conditions).

Roadmap thoughts

  • First‑class scenario templating and variables.
  • Built‑in report summaries (e.g., bounce rate, path distribution) from emitted logs.
  • Optional headless mode for SPA flows.

Wrap‑up Trafficinator exists to make analytics validation less tedious and more trustworthy. It’s small on purpose, plays nicely with Matomo‑first stacks (and GA4 when needed), and is easy to pick up for teammates.

Have a look at the code and examples here: https://github.com/Puttrix/Trafficinator

If you try it and have ideas, issues, or requests—open an issue in the repo or ping me on LinkedIn. Happy testing!