Extension: implement VS Code telemetry signals (#17721)

extension/README.md

@@ -223,6 +223,25 @@ Found a bug or have an idea? File it on the [microsoft/aspire](https://github.co
 
 ---
 
+## Data and telemetry
+
+The Aspire extension collects anonymous usage data and sends it to Microsoft to help improve our products and services. Telemetry is gated by the global [`telemetry.telemetryLevel`](https://code.visualstudio.com/docs/getstarted/telemetry) VS Code setting — disable it there to opt out. Read our [privacy statement](https://privacy.microsoft.com/privacystatement) to learn more.
+
+Events the extension reports include:
+
+- **`command/invoked`** — whenever a user runs an Aspire command, with the command name, where it was invoked from (command palette, tree view, code lens, walkthrough, or editor), outcome, and duration.
+- **`engagement/active`** — fired once per session the first time we detect meaningful engagement (an AppHost in the workspace, a command invocation, or a debug session start).
+- **`runningAppHostsView/shown`** — when the Aspire side panel becomes visible, along with how many AppHosts are running.
+- **`debug/appHost/start`** and **`debug/appHost/end`** — when an Aspire AppHost debug session begins and ends, including the AppHost language family (C# / TypeScript) and aggregate counts of child resource sessions to help us understand multi-language debugging usage.
+- **`debug/runSession/start`** and **`debug/runSession/end`** — per-resource debug-session lifecycle events with the resource type (clamped to the set of types the extension recognizes — anything else is bucketed as `unsupported`) and duration.
+- **Dashboard telemetry passthrough** — when the extension hosts the Aspire dashboard, telemetry events emitted by the dashboard are forwarded through the extension's reporter under a small fixed set of event names (`dashboard/operation`, `dashboard/userTask`, `dashboard/fault`, `dashboard/asset`, `dashboard/scope/start`, `dashboard/scope/end`, `dashboard/property/set`, `dashboard/property/recurring`, `dashboard/commandLineFlags`). The original dashboard-side event name is carried as a `dashboard_event_name` property, and the per-event property/metric bag is JSON-encoded into two stable properties (`dashboard_properties`, `dashboard_measurements`) capped at 100 entries and 8 KB each — so the upstream dashboard adding new events or properties does not silently grow the extension's classification surface. Properties the dashboard explicitly tags as personally identifiable are dropped before forwarding. In addition, the known free-form diagnostic fields that the dashboard composes from runtime data — exception messages and stack traces (the `Aspire.Dashboard.Exception.Message` / `Aspire.Dashboard.Exception.StackTrace` bundle properties), the exception-derived operation error messages on failure end events, fault descriptions, and operation/user-task result summaries — are dropped entirely rather than forwarded, because they can embed resource names and workspace paths; the non-sensitive structured `Aspire.Dashboard.Exception.Type` and `Aspire.Dashboard.Exception.RuntimeVersion`, the failure `result` label, and `fault_severity` are retained so the failure signal survives. Command-line flag prefixes are reduced to the flag *name* only (anything after the first `=`, `:`, or whitespace is stripped) so a flag value such as a token or password cannot ride along. Every remaining string value in the bundle is capped per-entry at ~1 KB before bundling so that a single property cannot serve as a side channel for multi-KB workspace content, and bundle keys and other dashboard-supplied identifiers forwarded as first-class fields (event names, property names, asset ids, command-line flag prefixes) are clamped to 256 characters as defense-in-depth against an upstream regression that puts user-controlled strings into identifier positions. Anything still routed through VS Code's telemetry reporter additionally receives the reporter's pattern-based scrubbing for common PII shapes (home-directory paths, emails, well-known tokens). If this concerns you, disable telemetry at the VS Code level.
+
+The full set of event names the extension is allowed to emit is enumerated in [`src/utils/telemetryRegistry.ts`](./src/utils/telemetryRegistry.ts); the TypeScript type system rejects telemetry calls that introduce new event names or new property names without an entry there.
+
+Events the extension originates do not include source code, file paths, environment variable values, resource names, or other workspace contents.
+
+---
+
 ## License
 
 See [LICENSE.TXT](./LICENSE.TXT) for details.