Skip to main content

Telemetry Insights — Understand Your Users Better 📊

· 6 min read
Serhii Kuianov
Serhii Kuianov
DevOps

Once your app is in users' hands, the obvious questions follow: How many people actually run it? Which version are they on? Which platforms should you prioritize? Shipping updates blind is guesswork — faynoSync's built-in telemetry turns those questions into data.

The best part: it's privacy-first and you already have most of the plumbing. Telemetry is collected from the same /checkVersion calls your clients already make — you just add one header. This post covers what's tracked, the critical X-Device-ID header, how to enable it, the beacon endpoint for SDK/edge flows, and how to read the data.

What is Telemetry? 🤔​

Telemetry is faynoSync's built-in analytics layer that:

  • 📈 Tracks user engagement and active clients
  • 🔍 Monitors version distribution and adoption
  • 🌍 Analyzes platform and architecture usage
  • 📊 Aggregates it all into daily stats

It helps you make data-driven decisions about your application's future. Full reference: Telemetry System docs.

What You Can Track 🎯​

1. Client Analytics​

  • 👥 Unique clients and active users
  • 📱 Platform distribution
  • 💻 Architecture breakdown

2. Version Insights​

  • 📦 Version adoption rates
  • 🎯 Clients on the latest version vs. outdated clients
  • 📈 Version distribution trends

3. Channel Analytics​

  • 🎨 Channel popularity (stable, beta, nightly, alpha)
  • 📊 Per-channel client counts

How it works​

Telemetry data is collected automatically when clients call the /checkVersion endpoint — as long as they send the X-Device-ID header. For each request faynoSync records the device ID, app name, platform, channel, architecture, and reported version.

The data is stored in Redis with a 30-day retention period, aggregated daily, and organized by administrator → application → date → metric. No separate database, no extra service.

The X-Device-ID header — the part that matters most​

Telemetry is only collected when the client sends an X-Device-ID header. Without it, the request still works — but it won't count toward your stats. This ID is what lets faynoSync count unique devices instead of raw requests.

GET /checkVersion?app_name=myapp&version=1.0.0&channel=stable&platform=darwin&arch=arm64
X-Device-ID: 3f6c1a8e-9b2d-4c77-bc1e-2a9f0d5e7a11

Implementation guidelines​

  • Generate a UUID v4 (or similar) on first launch.
  • Persist it in secure, durable storage on the device.
  • Reuse the same ID across app restarts and updates.
  • Never change it for an existing installation, or you'll double-count that user.

Keep it anonymous​

The device ID must not contain any personal data:

  • ❌ No names, emails, or account identifiers
  • ❌ No IP addresses
  • ❌ No sensitive data

It's an opaque identifier and nothing more. This is what keeps faynoSync telemetry privacy-first by design — you control the ID, and a random UUID reveals nothing about the user.

How to Enable It 🔌​

Add this to your .env file:

ENABLE_TELEMETRY=true

That's the server side. Then make sure your clients send X-Device-ID on their /checkVersion calls, and stats start accumulating automatically.

Collecting telemetry without checkVersion: the beacon endpoint​

If your client doesn't call /checkVersion — for example, SDK or edge flows where updates come from edge infrastructure — use the dedicated /telemetry/beacon endpoint instead. It records the same data but is optimized for speed, validating requests against an in-memory snapshot rather than reading full metadata per call.

curl --location 'http://localhost:9000/telemetry/beacon?app_name=myapp&version=1.0.0&channel=stable&platform=linux&arch=amd64&owner=admin' \
--header 'X-Device-ID: 3f6c1a8e-9b2d-4c77-bc1e-2a9f0d5e7a11'
  • Requires no auth token, but all query parameters and X-Device-ID are required.
  • Returns 204 No Content on success.
  • If you already call /checkVersion, you do not need the beacon.

See Telemetry beacon and Edge and S3 Response Cache for the architecture behind it.

How to Access Insights 📊​

Dashboard​

Log in to your admin dashboard and open the Telemetry section to explore charts for clients, versions, platforms, and channels.

API​

GET /telemetry?range=week

Available query parameters:

ParameterDescription
dateSpecific date (YYYY-MM-DD)
rangeTime range: week or month
appsFilter by application(s)
channelsFilter by channel(s)
platformsFilter by platform(s)
architecturesFilter by architecture(s)

Reading the response​

The API returns aggregated stats. The summary block is where the headline numbers live:

{
  "date": "2026-06-16",
  "admin": "ku9n",
  "summary": {
    "total_requests": 1765,
    "unique_clients": 1751,
    "clients_using_latest_version": 167,
    "clients_outdated": 1584,
    "total_active_apps": 5
  },
  "platforms": [
    { "platform": "windows", "client_count": 229 },
    { "platform": "linux", "client_count": 215 },
    { "platform": "darwin", "client_count": 207 }
  ],
  "channels": [
    { "channel": "stable", "client_count": 448 },
    { "channel": "beta", "client_count": 446 },
    { "channel": "nightly", "client_count": 435 }
  ],
  "daily_stats": [
    { "date": "2026-06-15", "total_requests": 400, "unique_clients": 400, "clients_using_latest_version": 37, "clients_outdated": 363 }
  ]
}

What the key fields tell you:

  • unique_clients — real device count (thanks to X-Device-ID), not inflated by repeat polling.
  • clients_using_latest_version vs clients_outdated — your update adoption rate at a glance. In the example above, most clients are still on older builds — a clear signal to investigate why updates aren't landing.
  • platforms / architectures / channels — where to focus QA and build effort.
  • daily_stats — trends over time: growing user base, adoption after a release, lingering outdated clients.

The full response also includes a versions block with per-version client counts. See the complete example in the docs.

Access control & privacy 🔒​

  • Per-admin isolation — each administrator sees telemetry only for their own apps.
  • Team users — can view all statistics but can only filter/sort resources they have access to; access is verified by the API.
  • Anonymous by design — identification is via the opaque X-Device-ID you generate; no PII, no IP addresses.
  • 30-day retention — data ages out automatically.

Limitations 📝​

  1. Data is retained for 30 days.
  2. Statistics are only collected when X-Device-ID is provided.
  3. Team users have limited filtering capabilities.
  4. Data is aggregated daily (not real-time per request).

Best Practices 💡​

  • Enable from day one — telemetry is only as good as its history; you can't backfill.
  • Generate device IDs correctly — UUID v4, persistent, never reused or mutated.
  • Review trends weekly — watch adoption after each release and chase down outdated-client spikes.
  • Let the data drive the roadmap — prioritize the platforms and channels your users actually run.

How to try faynoSync?​

  1. Follow the Getting Started guide:
    👉 https://faynosync.com/docs/getting-started

  2. Create your app using the REST API or web dashboard:
    📦 API Docs: https://faynosync.com/docs/api
    🖥️ Dashboard UI: https://github.com/ku9nov/faynoSync-dashboard

  3. Set ENABLE_TELEMETRY=true and send X-Device-ID from your clients.

  4. Open the Telemetry dashboard and start collecting insights. 📊

If you find this project helpful, please consider subscribing, leaving a comment, or giving it a star, create an Issue or feature request on GitHub.
Your support keeps the project alive and growing 💚