CLI Telemetry Alignment

Status · 2025-11-21

• Telemetry strictly opt-in via the --telemetry switch; no background usage channel runs by default.
• When telemetry is enabled, the CLI writes scoped JSON documents (for example cli-command-*.json, snapshot-*.json, build-*.json, and run summaries) that remain local-only.
• Automated coverage under tests/Xtraq.Tests/CliTelemetryServiceTests.cs verifies the opt-in persistence path and schema.

Decision · Remain Local-Only

After reviewing the official .NET CLI telemetry guidance we have decided to keep Xtraq's CLI telemetry local-only for the time being.

• No anonymised aggregates are uploaded or transmitted off-device. The opt-in JSON reports exist solely for manual diagnostics when teams decide to capture them.
• Remote publishing would require an ingestion endpoint, retention policy, encryption in transit, and a privacy review. None of those pieces are in place yet, so we are deferring remote collection until the infrastructure exists.
• This page documents every artifact that --telemetry produces so teams can review the footprint before enabling it.

Design Principles

1. Explicit intent. Telemetry only runs when the user provides --telemetry; no hidden environment toggles.
2. Hash sensitive data. Paths, procedure filters, and other potentially identifying values are hashed before touching disk.
3. Document the schema. CliTelemetryService persists command metadata in the same envelope described in the source comments so downstream tooling can reason about the files.

Next Steps

1. Revisit remote aggregation once we can host a privacy-reviewed ingestion endpoint (earliest Q2 2026).
2. Add a short CLI command (xtraq telemetry export) that redacts and packages local telemetry when users explicitly share diagnostics.
3. Publish a schema diagram for the telemetry envelope in the reference docs so downstream tooling can parse the JSON files when needed.

References

• .NET CLI telemetry guidance