App telemetry

For client-hosted applications rather than public websites: a one-way, key-authenticated pipe for operational events — navigation, admin actions, API latency and failures, and runtime errors — so HLD can see how a client's suite is behaving without needing access to their database.

When to use this instead of the tracker

Website analytics answers marketing questions about anonymous visitors on a public site. It runs in the browser and needs no server work.
App telemetry answers operational questions about a known application: which routes are slow, what is failing, what administrators are actually doing. It is posted from the application, browser or server, with a bearer key.

Ingest

bash

POST /api/monitoring/telemetry/ingest
Authorization: Bearer <telemetry key>
Content-Type: application/json

json

{
  "events": [
    {
      "id": "01J8…",
      "occurred_at": "2026-09-05T04:11:22.001Z",
      "category": "api",
      "name": "tickets.list",
      "severity": "info",
      "actor": "admin@example.com.au",
      "session_id": "sess_01J8…",
      "surface": "admin-portal",
      "route": "/api/tickets",
      "method": "GET",
      "status_code": 200,
      "duration_ms": 184,
      "metadata": { "page": 2 }
    }
  ]
}

Name	Type	Required	Description
id	string	Yes	Your event id. Ingest is idempotent on it — a client that times out mid-flush will resend the same batch, and this is what stops that becoming duplicates.
category	string	Yes	session \| navigation \| action \| api \| error \| vitals.
severity	string	No	debug \| info \| warning \| error \| critical. Defaults to info.
route / method / status_code / duration_ms	mixed	No	For API events. This is what the latency and error-rate rollups are built from.
error_message	string	No	For error events.
metadata	object	No	Free-form detail, bounded.

Up to 200 events per batch, 512 KB per request.

Two rules that shape everything

The key determines the tenant. A payload cannot name its own tenant, so a leaked key can only ever write to the tenant it was issued for.
Only a hash of the key is stored. A read of the source table never yields a usable key, and a lost key is replaced rather than recovered.

Clock skew

Note:A client clock can be wrong in both directions. Anything outside a sane window is pulled back to arrival time, so one bad machine cannot park events in 2087 where no dashboard query would ever surface them.

Reading it back

bash

GET /api/monitoring/telemetry?tenant=<uuid|slug>&hours=24&category=api

HLD administrators only. Returns a summary — totals, error rate, slowest routes — computed over the whole window rather than the returned page, so a small limit does not silently understate the error count, plus the raw tail.

Retention

Telemetry is pruned on a schedule; it is an operational signal, not an audit log. If you need something kept permanently, write it to your own audit trail as well.

Privacy & retention Introduction