Proposal to add telemetry data to xLights

[focusedonsound]

Proposal: Anonymous Telemetry & Usage Analytics for XLights

Discussion Type: Feature Proposal
Author: Nick Scilingo - Focusedonsound
Date: May 2026
Status: Open for Community Feedback

---

Overview

This proposal suggests adding an opt-in anonymous telemetry system to XLights to help the development team better understand how the software is being used in the real world. The data collected would be entirely anonymous, never contain personally identifiable information, and would be controlled by the user at all times via a clear opt-in/opt-out preference.

The goal is simple: make better development decisions backed by real usage data rather than assumptions. Knowing which features are most used, what hardware the community runs, how large shows are getting, and where pain points exist will help prioritize the roadmap more effectively.

I am volunteering to do the full implementation work for this feature.

---

Motivation

Right now, the XLights development team has limited visibility into how the software is actually being used across the community. We rely on forum posts, GitHub issues, and anecdotal feedback — which skews toward users who are vocal about problems and underrepresents the silent majority.

Anonymous telemetry would allow us to answer questions like:

• What percentage of users are still on Windows 10 vs Windows 11? (Informs OS support decisions)
• How large are shows getting in terms of pixel count and controller count?
• Which effects and features are actually being used vs. which are rarely touched?
• Are users upgrading promptly, or staying on older versions for extended periods?
• How many users rely on xScheduler vs FPP for show playback?

This is standard practice for open source projects of this scale. Examples include VS Code, Firefox, KiCad, and many others — all of which are transparent about what they collect and why.

---

Privacy & Consent Principles

These are non-negotiable foundations of the implementation:

1. Opt-in only. Telemetry will be disabled by default on first install. A clear, plain-language dialog will be shown once on first launch asking the user to opt in. No silent collection ever.
2. No personal data, ever. No names, email addresses, IP addresses, file paths, sequence names, show folder paths, or machine names will be collected.
3. No network activity without consent. If the user declines or has not yet been asked, zero network requests are made.
4. Persistent preference. The opt-in/opt-out choice is stored in XLights preferences and respected on every launch, forever.
5. Easy opt-out. A toggle will be available under Preferences → General labeled "Send anonymous usage data to help improve XLights" and can be changed at any time.
6. Public schema. The exact list of data fields collected will be documented publicly in this repo so anyone can audit what is and isn't sent.
7. "Show me what would be sent" button. A button in Preferences will display the exact JSON payload that would be transmitted, so no user ever has to trust blindly.
8. Anonymous install ID. A random UUID is generated on first launch and stored locally. It is never linked to a person, machine name, or any other identifier.

---

Proposed Backend

PostHog Cloud (Free Tier)

PostHog is an open-source analytics platform with a generous free cloud tier (1 million events/month, no credit card required). It supports anonymous event tracking by design, has a clean dashboard for visualizing data, and the XLights project would retain full control of the data.

• Free tier: 1M events/month, unlimited team members
• Data hosted in the US or EU (configurable)
• Open source (MIT licensed) — can be self-hosted if the project ever wants full control
• Integration requires only a simple HTTP POST using libcurl, which XLights already depends on
• No new library dependencies needed

If the community prefers a fully self-hosted solution, this can be migrated to a self-hosted PostHog instance or a lightweight custom endpoint at any time.

---

Technical Implementation

Language/Framework: C++ / wxWidgets (matching the existing XLights codebase)

New files:

• TelemetryManager.h / TelemetryManager.cpp — singleton class managing the event queue and HTTP dispatch
• TelemetryOptInDialog.h / TelemetryOptInDialog.cpp — first-launch consent dialog

Existing files modified (minimally):

• xLightsMain.cpp — init call on startup, flush call on shutdown
• xLightsXmlFile.cpp — hook for sequence open events
• Feature-specific files — lightweight TelemetryManager::TrackEvent() calls at key points

Transport: libcurl (already a dependency) posting JSON to PostHog's /capture/ endpoint on a background thread. Never blocks the UI.

Estimated effort: ~2 weeks for a single developer (me).

---

Proposed Data Points

The following sections describe every data point under consideration. I have organized these into a phased rollout to allow the community to review and approve each phase before implementation proceeds. Alternatively, all phases can ship together in a single release — I have listed both options below.

---

Option A — Phased Rollout (Recommended)

Phase 1 — System Environment & Version (Low sensitivity, high value)

These are the safest, least intrusive data points and provide immediate value for infrastructure decisions.

Data Point	Type	Example Value	Purpose
XLights version	String	2024.14	Track adoption of new releases
Operating system	String	Windows 11	Inform OS support decisions
OS version/build	String	22H2	Know when to drop legacy OS support
CPU architecture	String	x64 / ARM64	Platform support planning
RAM range	Bucket	16–32 GB	Performance expectation baselines
GPU type	String	Integrated / Dedicated	3D preview performance context
Primary screen resolution	String	1920x1080	UI layout and scaling decisions
Monitor count	Integer	2	Multi-monitor feature prioritization
Computer type	String	Desktop / Laptop / Mini PC	Hardware profile context
Anonymous install ID	UUID	a3f2c...	Deduplicate installs, count unique users
Session start timestamp (UTC date only, no time)	Date	2026-05	Monthly active user trends

Phase 2 — Show Scale & Hardware

Data Point	Type	Example Value	Purpose
Pixel count bucket	Enum	10,000–25,000	Understand show scale distribution
Controller count bucket	Enum	4–6	Scale awareness, UI complexity decisions
Controller types used	Array	["Falcon", "WLED"]	Controller support prioritization
Output protocols used	Array	["E1.31", "DDP"]	Protocol support prioritization
Universe count bucket	Enum	10–25	Network/output scaling context
Uses xScheduler	Boolean	true	xScheduler investment decisions
Show player used	Enum	xScheduler / FPP / Manual	Ecosystem awareness

Phase 3 — Sequencing & Feature Usage

Data Point	Type	Example Value	Purpose
Sequence count per season bucket	Enum	6–15	Understand workflow scale
Average sequence duration bucket	Enum	3–5 min	Performance planning
Sequencing method	Enum	Own / Purchased / Mix	Community ecosystem insight
Features used (checklist)	Array	["3D Preview", "SuperStar"]	Feature prioritization
Effects used (top N by count)	Array	["Chase", "ColorWash"]	Effect development prioritization
Years using XLights bucket	Enum	3–5 years	New vs veteran user ratio
Years in lighting hobby bucket	Enum	6–10 years	Community tenure context
Upgrade behavior	Enum	Immediate / Wait weeks	Release cadence planning

Phase 4 — Stability & Performance (Optional, most sensitive)

Data Point	Type	Example Value	Purpose
Crash occurred this session	Boolean	false	Stability tracking over time
Render time category	Enum	Fast / Slow	Performance regression detection
Session duration bucket	Enum	30–60 min	Engagement measurement

---

Option B — All Data Points at Once (Single Release)

All data points from Phases 1–4 above are collected from day one in a single implementation. This is simpler to ship but means the community reviews and approves the full scope upfront. The same privacy guarantees apply regardless of approach.

---

What Will NOT Be Collected (Ever)

To be absolutely explicit, the following will never be collected under any circumstances:

• Names, usernames, or email addresses
• IP addresses (stripped server-side by PostHog)
• File paths, folder names, or sequence names
• Show content, effect settings, or sequence data
• Controller IP addresses or network topology
• Machine names or hostnames
• Any information about files on the user's computer
• Audio file names or metadata
• License keys or registration data

---

Data Management & Governance

• All collected data will be owned by the XLights project (not by me personally)
• Access to the PostHog dashboard will be shared with core maintainers
• Aggregated, anonymized summary reports will be published periodically to the community (e.g. quarterly)
• Data retention will be set to 1 year, after which events are automatically deleted
• If the project ever wants to move off PostHog, the data is fully exportable and the backend is swappable with no code changes to XLights

---

My Commitment

I am volunteering to:

• Write the full TelemetryManager C++ implementation
• Build the opt-in consent dialog UI
• Wire up all event tracking calls across the codebase
• Set up and maintain the PostHog Cloud project
• Document the full data schema publicly in the repo
• Write the Preferences UI toggle and "show me what would be sent" feature
• Respond to all community feedback and iterate on the implementation
• Submit a clean PR with full test coverage for review by maintainers

I am not asking the core maintainers to do the work — only to review, give feedback, and merge if the community is supportive.

---

Open Questions for the Community

1. Opt-in or opt-out? I've proposed opt-in (disabled by default) as the safest approach. Would the community prefer opt-out (enabled by default with a clear notice)?
2. Phased or all-at-once? Do you prefer a gradual rollout of data points or a single comprehensive implementation?
3. PostHog Cloud or self-hosted? Are you comfortable with PostHog Cloud hosting, or would the project prefer a fully self-hosted solution?
4. Which data points should be excluded? Are there any fields in the list above that you feel are too sensitive even with anonymization?
5. Who should have dashboard access? Core maintainers only, or a broader group of contributors?

---

I welcome all feedback, concerns, and suggestions. My goal is to build something the community trusts and that genuinely helps make XLights better for everyone.

Thank you!

[cybercop23]

I think it needs to be OptOut so we get actual data. If opting out, we should have a prompt and a persistent banner to remind them why it is important. We should also collect a one-time opt-out "hit" (needs to be serialized - see below)
We do need some sort of show network topology. Home network or proxy, multiple proxies.
Need a way to identify the same user across multiple installs, be local, nightlies, or desktop/laptop.
Given how people upgrade, I think we should try to get as much gathered from the start - or better yet, have a way to update what gets collected without requiring a new version install; and when that happens, prompt and show the user there's new information being gathered.

[focusedonsound]

@cybercop23 great feedback, thank you — a few quick responses:
Opt-out — I agree. Opt-in will just capture enthusiasts and skew everything. Make it opt-out with a clear first-launch prompt and a persistent but unobtrusive indicator in the UI. The serialized opt-out hit is a genuinely clever addition — even a decline gives us a useful signal.

Network topology — Good catch, missed that entirely. Adding it to Phase 2. Proposed buckets: Direct, Single proxy, Multiple proxies — does that cover it?

Cross-install identity — Rather than any hardware fingerprinting, I'd propose an opt-in user-generated sync code the user can copy across installs. Keeps it voluntary with no device identification. Open to other ideas here.

Dynamic schema — 100% agree and will design for it from day one. Schema lives in a versioned manifest file in the repo, changes go through a PR, and XLights prompts the user when new fields are added. No install required to expand collection.

One more idea to throw in — since this is an open source project, would there be any objection to publishing an aggregated, read-only public dashboard of the results? Raw events stay private but the community gets to see the trends. Feels like it fits the spirit of xLights and would build a lot of trust around the telemetry itself.

[cybercop23]

I think some level of dashboard back to the community would be awesome