Generated file. Source: docs/telemetry_worker.md Edit the source document and run npm run docs:sync to refresh this published copy.

Telemetry Worker¶

Goal¶

This worker collects only ten anonymous technical events:

password_gate_unlocked
page_view_calculator
page_view_how_it_works
page_view_product_roadmap
click_how_it_works_nav
click_product_roadmap_nav
click_technical_documentation
calculator_inputs_changed
results_rendered
yearly_analysis_mode_changed

It is designed to be:

removable
cookie-free
free of user identifiers
free of form data
limited to simple event counts, last-seen timestamps, and a short rolling history of recent events

Does the app have to be hosted on Cloudflare?¶

No.

Only the worker needs to be deployed to Cloudflare.

The frontend can be:

running locally on localhost
deployed anywhere else
hosted on a completely different provider

The browser will simply send a request from the page to the Cloudflare Worker over the network.

What matters is:

the Worker must be publicly reachable
the Worker must allow the frontend origin in CORS
the frontend must use the Worker URL as VITE_TELEMETRY_ENDPOINT

Important:

the allowed origin must match the browser URL exactly
http://localhost:5173 and http://127.0.0.1:5173 are different origins
if Vite starts on 5174 instead of 5173, the Worker must also allow 5174
after changing ALLOWED_ORIGINS, you must redeploy the Worker

Example:

local frontend: http://localhost:5173
deployed Worker: https://bond-calculator-telemetry.<your-subdomain>.workers.dev/events

This setup works fine as long as http://localhost:5173 is listed in ALLOWED_ORIGINS.

What the worker stores¶

The worker stores only:

total event counters
per-event counters
last seen timestamp per event
a rolling buffer of the most recent events with timestamps

Implementation note:

yearly_analysis_mode_changed is emitted by the shared global analysis-mode interactions exposed in the chart and detailed yearly-table sections

It does not need cookies, local storage, or a user identifier.

Current implementation notes:

the frontend sends telemetry with a regular fetch
the frontend does not use cookies for telemetry
the Worker accepts only a fixed allowlist of event names
the recent event buffer currently stores up to 200 events total

Endpoints¶

`POST /events`¶

Accepts a payload like:

{
  "event": "page_view_calculator",
  "ts": "2026-03-23T12:34:56.000Z"
}

Allowed events are hardcoded in the worker.

`GET /stats`¶

Returns counters and last seen timestamps.

This endpoint requires the request header:

x-telemetry-token: your-secret-token

`GET /events`¶

Returns the most recent stored events.

Optional query param:

?limit=20

Maximum stored history is currently 200 events. The limit query parameter controls only how many of the already stored events are returned in the response.

Examples:

?limit=20 -> return up to 20 newest events
?limit=100 -> return up to 100 newest events
?limit=200 -> return up to the full stored buffer

This does not change how many events the Worker stores internally.

This endpoint also requires:

x-telemetry-token: your-secret-token

`POST /reset`¶

Resets:

all counters
all lastSeen values
the recent event history

This endpoint also requires:

x-telemetry-token: your-secret-token

`GET /health`¶

Simple health check.

Files¶

Worker code: index.ts: cloudflare/telemetry-worker/src/index.ts
Worker config: wrangler.toml: cloudflare/telemetry-worker/wrangler.toml

Setup Step by Step¶

1. Install Wrangler¶

If you do not have it yet:

npm install -g wrangler

or use npx wrangler.

wrangler login

3. Create a KV namespace¶

Run:

wrangler kv namespace create TELEMETRY_KV
wrangler kv namespace create TELEMETRY_KV --preview

Copy the returned IDs into:

id
preview_id

inside wrangler.toml: cloudflare/telemetry-worker/wrangler.toml

4. Configure allowed origins¶

In wrangler.toml: cloudflare/telemetry-worker/wrangler.toml, set:

ALLOWED_ORIGINS = "http://localhost:5173,http://127.0.0.1:5173,http://localhost:5174,http://127.0.0.1:5174,https://bondprofitabilitycalculator.niwciu.workers.dev"

Use a comma-separated list.

For local development only, http://localhost:5173 is enough. If you sometimes use 127.0.0.1 or Vite switches to 5174, add those variants too. If you later expose the app on a LAN IP, for example http://192.168.1.10:5173, that exact origin must also be added. For the current deployed app, add:

https://bondprofitabilitycalculator.niwciu.workers.dev

5. Configure a token for reading stats¶

Set a Worker secret:

wrangler secret put STATS_READ_TOKEN

Enter a long random token.

This token is only for reading /stats. It is not used by the frontend.

6. Run the worker locally¶

From the repo root:

wrangler dev --config cloudflare/telemetry-worker/wrangler.toml

You should get a local Worker URL.

7. Point the frontend to the worker¶

In your frontend .env.local:

VITE_ENABLE_TELEMETRY=true
VITE_TELEMETRY_ENDPOINT=http://127.0.0.1:8787/events

or for deployed worker:

VITE_ENABLE_TELEMETRY=true
VITE_TELEMETRY_ENDPOINT=https://bond-calculator-telemetry.niwciu.workers.dev/events

Then restart Vite.

8. Deploy the worker¶

wrangler deploy --config cloudflare/telemetry-worker/wrangler.toml

After deploy, use the returned workers.dev URL in the frontend env.

Important:

redeploy is required not only after changing ALLOWED_ORIGINS
redeploy is also required after any change to Worker code or wrangler.toml
restarting Vite is required after changing frontend env values

How to read stats¶

Example:

curl -H "x-telemetry-token: YOUR_SECRET_TOKEN" \
  https://bond-calculator-telemetry.niwciu.workers.dev/stats

You can also use the lightweight helper script from the repo root:

python3 scripts/telemetry_cli.py stats --token YOUR_SECRET_TOKEN

or with an environment variable:

export TELEMETRY_TOKEN=YOUR_SECRET_TOKEN
python3 scripts/telemetry_cli.py stats

How to read recent events / logs¶

Example with curl:

curl -H "x-telemetry-token: YOUR_SECRET_TOKEN" \
  "https://bond-calculator-telemetry.niwciu.workers.dev/events?limit=20"

Example with the helper script:

python3 scripts/telemetry_cli.py events --token YOUR_SECRET_TOKEN --limit 20

This prints a compact log-like view:

2026-03-23 19:12:01+00:00  page_view_calculator
2026-03-23 19:12:04+00:00  page_view_how_it_works

Useful variants:

python3 scripts/telemetry_cli.py event-types
python3 scripts/telemetry_cli.py health
python3 scripts/telemetry_cli.py stats --json --token YOUR_SECRET_TOKEN
python3 scripts/telemetry_cli.py events --json --token YOUR_SECRET_TOKEN --limit 100
python3 scripts/telemetry_cli.py reset --token YOUR_SECRET_TOKEN

If Cloudflare returns Error 1010: Access denied for the Python script, it usually means the default script signature was blocked. The helper now sends its own User-Agent, and you can override it if needed:

python3 scripts/telemetry_cli.py stats --token YOUR_SECRET_TOKEN \
  --user-agent "BondTelemetryCLI/1.0"

Example response:

{
  "totalEvents": 12,
  "lastEventAt": "2026-03-23T12:34:56.000Z",
  "stats": [
    {
      "event": "password_gate_unlocked",
      "count": 2,
      "lastSeen": "2026-03-23T10:10:10.000Z"
    },
    {
      "event": "page_view_calculator",
      "count": 6,
      "lastSeen": "2026-03-23T12:00:00.000Z"
    }
  ]
}

How to read recent events¶

Example:

curl -H "x-telemetry-token: YOUR_SECRET_TOKEN" \
  "https://bond-calculator-telemetry.niwciu.workers.dev/events?limit=20"

Example response:

{
  "totalStored": 12,
  "limit": 20,
  "events": [
    {
      "event": "page_view_product_roadmap",
      "ts": "2026-03-23T12:34:56.000Z",
      "recordedAt": "2026-03-23T12:34:56.321Z"
    },
    {
      "event": "password_gate_unlocked",
      "ts": "2026-03-23T12:30:00.000Z",
      "recordedAt": "2026-03-23T12:30:00.111Z"
    }
  ]
}

Notes:

ts is the timestamp sent by the frontend
recordedAt is when the Worker stored the event

How to reset telemetry¶

Example:

curl -X POST \
  -H "x-telemetry-token: YOUR_SECRET_TOKEN" \
  https://bond-calculator-telemetry.niwciu.workers.dev/reset

Troubleshooting¶

If stats stay at zero:

confirm the frontend is open under an origin allowed by the Worker
confirm .env.local contains:

VITE_ENABLE_TELEMETRY=true
VITE_TELEMETRY_ENDPOINT=https://bond-calculator-telemetry.niwciu.workers.dev/events

restart Vite after env changes
redeploy the Worker after any Worker-side config or code change
in browser DevTools -> Network, check the request to /events

Typical signals:

202 -> event accepted by the Worker
403 -> origin not allowed
404 -> wrong endpoint URL
no request at all -> frontend telemetry is not firing or env is not active

Example response:

{
  "ok": true,
  "reset": true
}

Privacy Notes¶

Recommended operating rules:

do not add cookies
do not add user IDs
do not add IP-based analysis in your own reporting layer
do not send form inputs
do not expand the event catalog without a clear reason

This keeps the telemetry minimal and easier to justify as a lightweight operational signal.

Telemetry Worker¶

Goal¶

Does the app have to be hosted on Cloudflare?¶

What the worker stores¶

Endpoints¶

POST /events¶

GET /stats¶

GET /events¶

POST /reset¶

GET /health¶

Files¶

Setup Step by Step¶

1. Install Wrangler¶

2. Login to Cloudflare¶

3. Create a KV namespace¶

4. Configure allowed origins¶

5. Configure a token for reading stats¶

6. Run the worker locally¶

7. Point the frontend to the worker¶

8. Deploy the worker¶

How to read stats¶

How to read recent events / logs¶

How to read recent events¶

How to reset telemetry¶

Troubleshooting¶

Privacy Notes¶

`POST /events`¶

`GET /stats`¶

`GET /events`¶

`POST /reset`¶

`GET /health`¶