feat: add WIL-based TraceLogging ETW telemetry (experimental)

.azure-pipelines/templates/Rust.Build.Job.yml

@@ -83,6 +83,59 @@ jobs:
         condition: and(eq('${{ item.os }}','linux'), eq('${{ item.arch }}','arm64'))
 
       - ${{ if eq(parameters.isOfficialBuild, true) }}:
+
+        # --- Telemetry GUID substitution (official builds only, mirrors WinAppSDK) ---
+        # For internal builds, the real Microsoft telemetry group GUID is
+        # compiled in by overwriting WIL's public no-op traceloggingconfig.h
+        # with MicrosoftTelemetry.h from the private Microsoft.Telemetry.Inbox.Native
+        # NuGet package. Community/OSS builds skip these steps — build.rs
+        # compiles against the public stub and events fire as plain ETW.
+
+        # 1. Authenticate to the private NuGet feed hosting the telemetry package.
+        - task: NuGetAuthenticate@1
+          displayName: 'NuGet authenticate for telemetry config'
+          inputs:
+            nuGetServiceConnections: 'TelemetryInternal'
+          condition: and(succeeded(), eq('${{ item.os }}', 'windows'))
+
+        # 2. Restore Microsoft.Telemetry.Inbox.Native into build/telemetry/packages/.
+        - task: NuGetCommand@2
+          displayName: 'Restore Microsoft.Telemetry.Inbox.Native'
+          inputs:
+            command: 'custom'
+            arguments: >-
+              restore $(Build.SourcesDirectory)/build/telemetry/packages.config
+              -ConfigFile $(Build.SourcesDirectory)/build/telemetry/nuget.config
+              -PackagesDirectory $(Build.SourcesDirectory)/build/telemetry/packages
+          condition: and(succeeded(), eq('${{ item.os }}', 'windows'))
+
+        # 3. Find MicrosoftTelemetry.h and set the env var so build.rs picks it up.
+        - powershell: |
+            $srcPath = Get-ChildItem -Path '$(Build.SourcesDirectory)/build/telemetry/packages' `
+                       -File 'MicrosoftTelemetry.h' -Recurse -ErrorAction SilentlyContinue
+            if ($srcPath) {
+                Write-Host "Found telemetry config override: $($srcPath.FullName)"
+                Write-Host "##vso[task.setvariable variable=MXC_TELEMETRY_CONFIG_OVERRIDE]$($srcPath.FullName)"
+            } else {
+                Write-Host "MicrosoftTelemetry.h not found under $(Build.SourcesDirectory)/build/telemetry/packages/"
+                Get-ChildItem -Path '$(Build.SourcesDirectory)/build/telemetry/packages' -Recurse -ErrorAction SilentlyContinue
+            }
+          displayName: 'Set MXC_TELEMETRY_CONFIG_OVERRIDE'
+          condition: and(succeeded(), eq('${{ item.os }}', 'windows'))
+
+        # --- SDK license override (mirrors telemetry GUID substitution) ---
+        # For internal npm publishes, the public MIT-only LICENSE.md is replaced
+        # with a private EULA containing a Section 2 DATA clause (telemetry
+        # disclosure, GDPR). The private EULA is sourced from an internal
+        # artifact store and injected via the MXC_LICENSE_OVERRIDE env var.
+        # Community/OSS builds skip this step — the SDK ships MIT-only.
+
+        # 4. Apply private EULA if MXC_LICENSE_OVERRIDE is set.
+        - powershell: |
+            & '$(Build.SourcesDirectory)/scripts/apply-license-override.ps1'
+          displayName: 'Apply SDK license override'
+          condition: and(succeeded(), ne(variables['MXC_LICENSE_OVERRIDE'], ''))
+
         - template: Rust.Build.Steps.Official.yml@self
           parameters:
             targetTriple: $(triplet)

.gitignore

@@ -45,4 +45,16 @@ output
 pathrel_test.exe
 
 # Claude
-.claude/
+.claude/
+
+# Private telemetry config (restored from internal NuGet feed at build time).
+# The Microsoft.Telemetry.Inbox.Native package provides MicrosoftTelemetry.h
+# which contains the real Microsoft telemetry group GUID — must never be
+# committed. See docs/telemetry-wil-integration.md for details.
+build/telemetry/packages/
+
+# Private EULA override (injected at npm-publish time via MXC_LICENSE_OVERRIDE).
+# The private EULA includes the Section 2 DATA clause for telemetry disclosure
+# and must never be committed. See docs/telemetry-wil-integration.md for details.
+sdk/LICENSE.md.public
+build/eula/

README.md

@@ -219,6 +219,24 @@ wxc-exec.exe --debug config.json
 
 See [docs/diagnostics.md](docs/diagnostics.md) for full diagnostics reference.
 
+## Telemetry (Experimental)
+
+MXC supports optional TraceLogging ETW telemetry for execution observability. When enabled, structured events (`MXC.Execution` and `MXC.Error`) are emitted to the local ETW subsystem via a WIL (Windows Implementation Library) C++ shim — the same pattern used by WinAppSDK. Every event includes Part B common fields (Version, Channel, IsDebugging, `UTCReplace_AppSessionGuid`).
+
+Telemetry is **experimental** and requires:
+1. The `--experimental` CLI flag
+2. `"experimental": { "telemetry": { "enabled": true } }` in the JSON config
+
+On non-Windows platforms, all telemetry functions are no-ops. The WIL headers are automatically downloaded from NuGet at build time (Windows only).
+
+### Data collection
+
+This project may collect usage data and send it to Microsoft to help improve our products and services. Note, however, that **no data collection is performed when using your private builds** — the public source code ships with empty TraceLogging provider group macros that do not route events to any Microsoft collection pipeline.
+
+No PII is collected. Events contain only execution metrics (duration, backend type, exit code) and error context (phase, sanitized message). If you use the SDK to build applications, you are responsible for providing appropriate telemetry notices to your own users.
+
+Privacy information can be found at https://privacy.microsoft.com.
+
 ## Documentation
 
 | Document | Description |
@@ -235,11 +253,12 @@ See [docs/diagnostics.md](docs/diagnostics.md) for full diagnostics reference.
 | [docs/macos-support/seatbelt-backend.md](docs/macos-support/seatbelt-backend.md) | Seatbelt backend (macOS) |
 | [docs/windows-sandbox/windows-sandbox.md](docs/windows-sandbox/windows-sandbox.md) | Windows Sandbox backend |
 | [docs/state-aware-lifecycle/mxc-state-aware-sandbox-api.md](docs/state-aware-lifecycle/mxc-state-aware-sandbox-api.md) | State-aware sandbox lifecycle API |
+| [docs/telemetry-wil-integration.md](docs/telemetry-wil-integration.md) | WIL TraceLogging telemetry architecture |
 
 ## Contributing
 
 See [CONTRIBUTING.md](CONTRIBUTING.md) for contribution guidelines.
 
 ## License
 
-See [LICENSE.md](LICENSE.md) for details.
+See [LICENSE.md](LICENSE.md) for details.

build/telemetry/nuget.config

@@ -0,0 +1,10 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- Scoped NuGet config for restoring the private telemetry package.
+     The <clear/> ensures no unintended sources (e.g. nuget.org) are used.
+     NuGetAuthenticate@1 injects the feed URL and credentials from the
+     TelemetryInternal service connection at build time. -->
+<configuration>
+  <packageSources>
+    <clear />
+  </packageSources>
+</configuration>

build/telemetry/packages.config

@@ -0,0 +1,17 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- Telemetry configuration package for internal Microsoft builds.
+     Microsoft.Telemetry.Inbox.Native provides MicrosoftTelemetry.h which
+     redefines TraceLoggingOptionMicrosoftTelemetry() with the real Microsoft
+     telemetry group GUID. This is the same package and version used by
+     WinAppSDK (see dev/WindowsAppRuntime_Insights/packages.config in the
+     WindowsAppSDK repo).
+
+     The package itself is hosted on a private NuGet feed — see the
+     NuGetAuthenticate + NuGetCommand steps in Rust.Build.Job.yml.
+     Community/OSS builds do not need this package; the public WIL NuGet
+     already ships a no-op stub that compiles cleanly. -->
+<packages>
+  <package id="Microsoft.Telemetry.Inbox.Native"
+           version="10.0.19041.1-191206-1406.vb-release.x86fre"
+           targetFramework="native" />
+</packages>

docs/schema.md

@@ -80,6 +80,9 @@ production configs and the dev schema when working on experimental features:
             "launchMethod": "exec",        // "exec" or "open" (LaunchServices, for Apple-constrained apps)
             "nestedPty": true,             // Allow inner process to allocate its own pty (posix_openpt)
             "keychainAccess": false        // Allow Keychain via securityd / trustd / cfprefsd / lsd.*
+        },
+        "telemetry": {                // Telemetry (experimental, Windows only)
+            "enabled": true                // Emit TraceLogging ETW events via WIL C++ shim
         }
     }
 }