Anonymous Heartbeat Telemetry

What is sent

The gateway POSTs to the heartbeat endpoint every two hours, starting two minutes after startup. The first POST is delayed so rapid local-dev restarts do not generate traffic. The body is exactly four fields:

{
  "instance_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
  "version": "1.0.26",
  "rps_bucket": "1k-10k",
  "uptime_seconds": 86400
}

That is the entire payload. There is no IP address, no User-Agent, no location, no model name, no provider name, no customer identifier, no user_path, and no telemetry about the content of any request.

What is stored

The receiving worker is a Cloudflare Worker backed by Postgres. Per the worker README:

• Raw heartbeat rows are stored for deduplication for at most 48 hours, then deleted.
• Only daily unique counts are retained permanently (for example date, version, rps_bucket -> count).
• No PII is collected. IP addresses, User-Agents, and locations are discarded and never logged.

The retention is what the upstream worker README states. Aurora OSS does not control that worker. If you need a stronger privacy guarantee, disable the heartbeat or point it at your own endpoint.

How the heartbeat is generated

1. InitHeartbeat is called at gateway startup with the binary version.
2. If AURORA_TELEMETRY_DISABLE=true is set, the loop is a no-op and the function returns.
3. Otherwise, a goroutine waits two minutes, sends the first heartbeat, then sends one every two hours.
4. IncrementRequestCount is called once per model-interaction request. The total and the uptime are used to compute the RPS bucket.
5. The POST goes to AURORA_TELEMETRY_URL if set, otherwise to the default https://aurora-heartbeat.cortexx.workers.dev/api/v1/heartbeat.
6. The HTTP client has a 10-second timeout. Failures are logged at slog.Debug and never affect the gateway.

Opt out

To turn off the heartbeat entirely:

AURORA_TELEMETRY_DISABLE=true

Restart the gateway. The goroutine returns early and no requests are made. The IncrementRequestCount calls become cheap no-ops.

Point at a custom endpoint

AURORA_TELEMETRY_URL=https://your-internal-telemetry.example.com/api/v1/heartbeat

This is useful for:

• Air-gapped deployments that should not reach out to the public worker.
• Self-hosted telemetry aggregators that record the same instance_id / version / rps_bucket fields into your own data warehouse.
• Compliance reviews that want telemetry to stay in a specific region.

The remote endpoint must accept a JSON POST with the four fields above and return 200 to be treated as a success. A non-200 response or a connection failure is logged at debug and ignored.

Self-host the worker

The heartbeat-worker/ directory in the OSS repo is a Cloudflare Worker you can deploy yourself. It uses:

• A Postgres-compatible database (the OSS worker expects a Hyperdrive binding, but the SQL is plain Postgres).
• An ADMIN_KEY Wrangler secret for the admin endpoints.

Deploy:

cd heartbeat-worker
npm install
npx wrangler secret put ADMIN_KEY
npm run deploy

Set AURORA_TELEMETRY_URL=https://your-worker.your-domain.workers.dev/api/v1/heartbeat on every gateway that should phone home to you.

The worker exposes admin endpoints for live and historical stats:

curl -H "Authorization: Bearer $ADMIN_KEY" \
  https://your-worker.your-domain.workers.dev/api/v1/stats/live

Verify it is working

After the gateway has been up for more than two minutes, look for the debug log line:

telemetry heartbeat sent successfully

Increase log verbosity with LOG_LEVEL=debug if you do not see it at info.

The default worker also exposes a live stats endpoint (admin only) you can call to confirm receipt from the public endpoint:

curl -H "Authorization: Bearer $ADMIN_KEY" \
  https://aurora-heartbeat.cortexx.workers.dev/api/v1/stats/live

Gotchas

• AURORA_TELEMETRY_DISABLE is read at startup. Restart the gateway after changing it.
• The rps_bucket resets on restart. A gateway that restarts every hour will always report a low bucket even at high actual throughput. That is intentional — the metric measures sustained load, not bursts.
• The instance.id file persists across gateway restarts. It is what makes the 1k-10k bucket useful as a daily-unique counter on the server side.
• The worker is a separate deployment from the gateway. It is the project's own telemetry, not a third-party service.
• You can rotate the instance ID by deleting ~/.aurora/instance.id (or whichever of the three paths your install used) and restarting. A new UUID is generated.
• The heartbeat goroutine never blocks the gateway. All HTTP calls go through a client with a 10-second timeout. Failures are logged at slog.Debug and have no effect on request handling.

Related

• Our Values — the values behind Aurora's approach to telemetry
• Configuration — full env-var reference
• Observability — the gateway's own metrics, audit, and dashboard