Telemetry beacon
Records client update telemetry for statistics collection.
This endpoint stores telemetry in the same way as /checkVersion, but it is optimized for speed by keeping a snapshot of parameters in RAM.
On metadata changes, the API rebuilds a compact allow-list index (owner, app, channel, platform, architecture names) and serves beacon validation from that in-memory snapshot instead of reading full apps_meta documents per request.
Performance (development benchmarks)
Measured on a local Mac (not production). Absolute numbers will differ on servers, but the comparison shows why this endpoint exists for edge-heavy traffic.
| Metric | Previous /checkVersion-style path | /telemetry/beacon |
|---|---|---|
| Avg time until persistence step | ~20.8 ms | ~0.15 ms |
wrk throughput (4 threads, 100 conn, 30s) | ~359 req/s | ~1,192 req/s |
wrk avg latency | ~287 ms | ~88 ms |
For architecture context (edge mode, allow-list lifecycle, and caveats), see Edge and S3 Response Cache.
Endpoint
GET /telemetry/beacon?app_name=<app_name>&version=<version>&channel=<channel>&platform=<platform>&arch=<arch>&owner=<owner>
Authentication
No auth token is required.
Required Header
| Header | Type | Required | Description |
|---|---|---|---|
X-Device-ID | string | ✅ | Unique client device identifier used for telemetry deduplication and tracking |
Query Parameters
All query parameters are required.
| Parameter | Type | Required | Description |
|---|---|---|---|
app_name | string | ✅ | Application name |
version | string | ✅ | Current client version |
channel | string | ✅ | Release channel (for example, stable or beta) |
platform | string | ✅ | Client platform (for example, linux, windows, darwin) |
arch | string | ✅ | Client architecture (for example, amd64, arm64) |
owner | string | ✅ | Application owner username |
Example Request
curl --location 'http://localhost:9000/telemetry/beacon?app_name=secondapp&version=0.0.1&channel=stable&platform=linux&arch=amd64&owner=admin' \
--header 'X-Device-ID: ncjskbfhbhjs473tdah'
Response
Success Response (204 No Content)
This endpoint always returns 204 No Content on success and does not include a response body.
Usage Notes
- This endpoint is intended for telemetry collection when
/checkVersionis not used. - If your client already calls
/checkVersion, you do not need to call/telemetry/beacon. - This endpoint is designed for
faynosync-sdkflows where updates are received from edge infrastructure and/checkVersionis skipped. - Missing
X-Device-IDor missing query parameters should be treated as invalid requests. - Reported
versionis stored for statistics but is not required to match the in-memory allow-list (clients may report versions no longer present in the admin UI).