fission-ai__openspec/openspec/changes/archive/2026-01-09-add-posthog-analytics/proposal.md at dependabot/github_actions/github-actions-03d71bef4d

mirror of https://github.com/Fission-AI/OpenSpec.git synced 2026-09-14 20:16:53 +08:00

Files

T

Tabish Bidiwale 940898c1c5 Add optional anonymous usage statistics (#468 )

* chore: add proposal for PostHog analytics integration

Introduces the proposal artifact for adding opt-in telemetry to OpenSpec
using PostHog. Covers command tracking, feature adoption metrics, and
privacy-respecting consent management.

* feat: add optional anonymous usage statistics

Introduces privacy-first usage analytics to help understand how OpenSpec
is being used. Key privacy protections:

- Only tracks command names and version (no arguments, paths, or content)
- Opt-out via OPENSPEC_TELEMETRY=0 or DO_NOT_TRACK=1
- Auto-disabled in CI environments
- No IP address collection (explicitly disabled)
- Anonymous ID is a random UUID with no PII

Uses PostHog with a reverse proxy to avoid ad blockers. First-run shows
a one-line notice informing users about the collection.

* docs: make telemetry section collapsible and concise

2026-01-09 23:10:31 -08:00

1.4 KiB

Raw Permalink Blame History

Why

OpenSpec currently has no visibility into how the tool is being used. Without analytics, we cannot:

Understand which commands and features are most valuable to users
Measure adoption and usage patterns
Make data-driven decisions about product development

Adding PostHog analytics enables product insights while respecting user privacy through transparent, opt-out telemetry.

What Changes

Add PostHog Node.js SDK as a dependency
Implement telemetry system with environment variable opt-out
Track command usage (command name and version only)
Show first-run notice informing users about telemetry
Store anonymous ID in global config (~/.config/openspec/config.json)
Respect DO_NOT_TRACK and OPENSPEC_TELEMETRY=0 environment variables
Auto-disable in CI environments

Capabilities

New Capabilities

telemetry: Anonymous usage analytics using PostHog. Covers command tracking, opt-out controls, and first-run disclosure notice.

Modified Capabilities

global-config: Add telemetry state storage (anonymous ID, notice seen flag)

Impact

Dependencies: Add posthog-node package
Privacy: Opt-out via env var, no personal data collected, clear disclosure
Configuration: New global config fields for telemetry state
Network: Async event sending with flush on exit (~100-300ms added)
CI/CD: Telemetry auto-disabled when CI=true
Documentation: Update README with telemetry disclosure

1.4 KiB Raw Permalink Blame History

Why