Integrate stable telemetry into MXC runtime

[RamonArjona4]

• I have signed the Contributor License Agreement.
• This pull request is related to an issue.
• If this PR changes build commands, project architecture, or key conventions, I have updated .github/copilot-instructions.md.

---

Summary

Promotes telemetry to the stable top-level configuration and integrates the reviewed consent and policy foundation with the engine and executors. Adds typed maintenance requests, live authorization checks, generated schemas, migration handling, and Windows consent/ETW smoke coverage.

This is PR 3 of 5 and depends on the consent/policy foundation in PR 2.

Stack

Order	Change	PR
1	Normative privacy and telemetry documentation	#818
2	Consent and policy foundation	#819
3	Stable config and executor integration	#820
4	Rust SDK and C ABI	#821
5	Node.js and .NET SDKs	#822

Review only this PR's diff; prerequisite behavior is in the PR above.

[azure-pipelines]

Azure Pipelines:
There may be pipelines that require an authorized user to comment /azp run to run.

[azure-pipelines]

Azure Pipelines:
There may be pipelines that require an authorized user to comment /azp run to run.

[Jeff Whiteside (jsidewhite)]

[Copilot]

Pull request overview

Promotes telemetry into MXC’s stable runtime configuration and integrates consent-aware emission across executors and the engine.

Changes:

• Adds stable telemetry parsing, authorization gates, and state-aware correlation.
• Introduces typed consent-maintenance requests and generated schemas.
• Adds Windows consent/ETW smoke tests and updates documentation.

Reviewed changes

Copilot reviewed 27 out of 27 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
.github/workflows/Build.Windows.Job.yml	Adds telemetry tests and smoke coverage.
docs/schema.md	Documents stable telemetry configuration.
docs/state-aware-lifecycle/mxc-state-aware-sandbox-api.md	Updates telemetry correlation guidance.
docs/telemetry/telemetry-consent-design.md	Marks consent design as implemented.
docs/telemetry/telemetry-consent-privacy-review.md	Updates implementation status.
docs/telemetry/telemetry-policy.md	Marks policy integration as implemented.
docs/telemetry/telemetry.md	Updates telemetry implementation status.
schemas/dev/mxc-config.schema.0.8.0-dev.json	Promotes telemetry to the schema root.
schemas/dev/mxc-telemetry-consent.schema.1.json	Adds the maintenance-request schema.
src/core/lxc/src/main.rs	Adds consent maintenance and stable telemetry wiring.
src/core/mxc_darwin/src/main.rs	Adds equivalent macOS maintenance handling.
src/core/mxc_engine/src/lib.rs	Adds telemetry-aware streaming wrappers.
src/core/mxc_engine/src/policy.rs	Adds per-request telemetry enablement.
src/core/mxc_engine/src/state_aware.rs	Adds state-aware telemetry and correlation.
src/core/wxc/src/main.rs	Integrates maintenance commands and runtime emission.
src/core/wxc_common/Cargo.toml	Clarifies telemetry test-support behavior.
src/core/wxc_common/src/config_parser.rs	Parses stable telemetry and migration cases.
src/core/wxc_common/src/models.rs	Moves telemetry into ExecutionRequest.
src/core/wxc_common/src/telemetry/consent_cli.rs	Implements shared consent maintenance handling.
src/core/wxc_common/src/telemetry/events.rs	Updates ETW event documentation.
src/core/wxc_common/src/telemetry/mod.rs	Adds live authorization and SDK emission paths.
src/core/wxc_common/src/wire.rs	Defines telemetry maintenance wire contracts.
src/testing/wxc_e2e_tests/tests/e2e_windows.rs	Updates telemetry E2E invocation.
src/tools/mxc_schema_gen/src/main.rs	Adds consent schema/type generation modes.
tests/examples/28_telemetry_enabled.json	Uses stable top-level telemetry.
tests/scripts/run_telemetry_consent_smoke_test.ps1	Adds isolated consent smoke coverage.
tests/scripts/run_telemetry_etw_smoke_test.ps1	Strengthens isolated ETW smoke coverage.

Suppressed comments (1)

src/core/wxc_common/src/telemetry/events.rs:106

• The provider emits MXC.Error, not Error; preserving this exact identity is part of the ETW smoke assertion. Keep the public function documentation aligned with the actual event contract.

/// Log an Error ETW event.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Pull request overview

Copilot reviewed 28 out of 28 changed files in this pull request and generated no new comments.

Suppressed comments (3)

docs/telemetry/telemetry-consent-design.md:2

• Removing the implementation-status notice makes this document claim that the Rust/C ABI and Node/.NET consent APIs described later are available now, but this PR's own stack assigns those surfaces to follow-up PRs #821 and #822. Keep a partial-implementation notice until those PRs land so readers are not directed to APIs absent from this branch.

# Telemetry consent design

src/core/mxc_engine/src/lib.rs:195

• A timed-out state-aware streaming exec is converted to a generic BackendError, so classify_mxc_error reports process_error instead of the existing timeout telemetry category. Preserve ErrorKind::TimedOut when constructing the state-aware telemetry outcome (or add a state-aware emit path that accepts FailureReason::Timeout) so one-shot and state-aware timeout events agree.

                let outcome = match result {
                    Ok(exit_code) => Ok(
                        wxc_common::state_aware_dispatch::DispatchOutcome::ExecCompleted {
                            exit_code: *exit_code,
                        },
                    ),
                    Err(error) => Err(wxc_common::mxc_error::MxcError::backend_error(
                        error.to_string(),
                    )),

src/core/mxc_engine/src/policy.rs:787

• SandboxRequest is re-exported by mxc-sdk, so this method immediately adds a public Rust SDK API. The repository's SDK-change convention requires updating the Rust SDK crate docs and src/core/mxc-sdk/README.md in the same PR; neither currently documents this method. Please add those updates, or keep the method non-public until the SDK-exposure PR.

    /// Enable or disable telemetry for this invocation.
    ///
    /// Enabling this per-request switch is necessary but not sufficient:
    /// telemetry still requires persisted user consent and an administrative
    /// policy that permits collection. It is independent of experimental mode.
    pub fn set_telemetry_enabled(&mut self, enabled: bool) -> &mut Self {

[Copilot]

Pull request overview

Copilot reviewed 36 out of 38 changed files in this pull request and generated 2 comments.

Suppressed comments (6)

src/core/mxc_engine/src/state_aware.rs:86

• WSLc has been dropped from the state-aware dispatcher here. resolve_backend still returns Wslc, and wslc_common::WslcStateAwareRunner still implements the backend, but this request now falls through to wxc_common::state_aware_dispatch::run_state_aware, which unconditionally returns unsupported_phase. Restore the feature-gated WSLc arm and its experimental opt-in behavior.

    if matches!(
        backend,
        wxc_common::models::ContainmentBackend::WindowsSandbox
            | wxc_common::models::ContainmentBackend::IsolationSession
    ) && !parsed.request.experimental_enabled

src/core/mxc_engine/src/lib.rs:351

• A try_wait error does not establish that the sandbox has terminated; implementations can return a transient OS/transport error while the workload remains live. Emitting here releases the provider and suppresses the later real completion from wait, producing an inaccurate terminal event. Leave telemetry active on Err so a later terminal operation (or Drop) accounts for the invocation.

            // Poll-error branch — emit a synthesised terminal event so the
            // provider reference isn't released without accounting for the
            // run, then return the error unchanged to the caller.
            Err(_) => self.emit_synthetic(SyntheticTerminal::PollError),

src/core/mxc_engine/src/lib.rs:367

• This records a successful cancellation even when the underlying kill() returns an error and the process may still be running. That consumes the exactly-once telemetry slot, so a subsequent successful wait() cannot report the actual outcome. Emit Killed only after a successful kill.

        let result = self.inner.kill();
        self.emit_synthetic(SyntheticTerminal::Killed);
        result

src/core/mxc_engine/src/lib.rs:250

• State-aware streaming timeouts are converted to MxcError::backend_error here, so classify_mxc_error emits process_error instead of the documented timeout. SandboxProcess::wait explicitly reports timeouts as ErrorKind::TimedOut; preserve that distinction when constructing the state-aware telemetry outcome.

                let outcome = match result {
                    Ok(exit_code) => Ok(
                        wxc_common::state_aware_dispatch::DispatchOutcome::ExecCompleted {
                            exit_code: *exit_code,
                        },
                    ),
                    Err(error) => Err(wxc_common::mxc_error::MxcError::backend_error(
                        error.to_string(),
                    )),

src/core/mxc_engine/src/lib.rs:280

• Killed is encoded as a generic Interrupted I/O error, but emit only special-cases TimedOut: one-shot mode therefore classifies this as init_error, and state-aware mode as process_error. The public event contract includes cancelled, so successful caller cancellation is currently misreported. Route this terminal kind through a cancellation-specific emission path.

            SyntheticTerminal::Killed => (
                std::io::ErrorKind::Interrupted,
                "sandbox handle was killed before completion",
            ),

src/core/mxc_engine/src/state_aware.rs:123

• The WSLc streaming path has lost both its experimental gate and backend-specific dispatch. A wslc: exec without opt-in now reports generic unsupported_phase instead of backend_unavailable, and an opted-in request no longer reaches WslcStateAwareRunner's deliberate library-consumer validation. Restore the feature-gated WSLc arm so the established error contract remains intact.

    if matches!(
        backend,
        wxc_common::models::ContainmentBackend::WindowsSandbox
            | wxc_common::models::ContainmentBackend::IsolationSession
    ) && !parsed.request.experimental_enabled

[Copilot]

Pull request overview

Copilot reviewed 43 out of 45 changed files in this pull request and generated 1 comment.

Suppressed comments (3)

src/core/wxc_common/src/telemetry/events.rs:120

• The updated public event inventory removes mxc.sandbox_kind from MXC.Error, but this changed call still passes a value and mxc_telemetry::log_error emits that field (src/mxc_telemetry/src/lib.rs:263). Align the provider payload and documentation before treating this as a stable contract.
  sdk/node/src/types.ts:286
• This public SDK documentation still describes enabled: true as “force on,” although the promoted stable behavior also requires persisted user consent and permissive administrative policy. Update the interface docs so consumers do not expect this option to bypass those gates.

/** Telemetry configuration for TraceLogging ETW support. */
export interface TelemetryConfig {
  /**
   * Explicit telemetry override. `true` = force on, `false` = force off,

tests/scripts/run_telemetry_etw_smoke_test.ps1:221

• This CI smoke test now validates only that an event with the expected identity exists; it deleted the prior checks for mxc.backend, mxc.exit_code, mxc.outcome, and mxc.duration_ms. The new Rust field-level ETW test is #[ignore] and is not invoked by this workflow, so payload regressions can pass CI. Retain field-level validation in the non-ignored smoke path.

[Copilot]

Pull request overview

Copilot reviewed 43 out of 45 changed files in this pull request and generated no new comments.

Suppressed comments (5)

src/core/mxc_engine/src/lib.rs:366

• This emits cancelled even when inner.kill() returns an error and the child remains running. It also consumes the terminal slot, so a subsequent successful wait() cannot report the real outcome. Only finalize cancellation after termination is known to have succeeded; otherwise leave telemetry pending.

        let result = self.inner.kill();
        self.emit_synthetic(SyntheticTerminal::Killed);

src/core/wxc_common/src/wire.rs:105

• Promoting this field to the stable top level also requires updating the public schema reference. docs/schema.md:127-129 still presents experimental.telemetry, but the parser now rejects that legacy location, so users copying the documented example receive a migration error. Move the example and field documentation to the top-level telemetry section in this PR.
  src/core/mxc_engine/src/lib.rs:351
• A try_wait error does not mean the child has terminated, so consuming the one-shot telemetry slot here can record a terminal internal_error while the process continues. If a later wait() succeeds, its real exit outcome is then suppressed. Keep the slot live on polling errors so a later terminal operation can report the actual outcome.

            // Poll-error branch — emit a synthesised terminal event so the
            // provider reference isn't released without accounting for the
            // run, then return the error unchanged to the caller.
            Err(_) => self.emit_synthetic(SyntheticTerminal::PollError),

src/core/mxc_engine/src/policy.rs:794

• Enabling telemetry after build_request* creates a fresh TelemetryConfig without the caller-requested containment kind. Consequently Rust SDK requests built with abstract Containment::Process report the resolved backend (processcontainer, bubblewrap, or seatbelt) as mxc.sandbox_kind, contrary to the documented caller-intent field. Preserve the builder's requested containment when constructing this config.

    pub fn set_telemetry_enabled(&mut self, enabled: bool) -> &mut Self {
        self.inner.telemetry = Some(TelemetryConfig {
            enabled: Some(enabled),
            ..Default::default()
        });

docs/telemetry/telemetry.md:96

• The updated event contract removes mxc.sandbox_kind from MXC.Error, but mxc_telemetry::log_error still emits that field and event_names_preserve_collector_contract explicitly requires it. Align the provider/test and documentation so consumers have one authoritative payload contract.

| `mxc.backend` | string | Containment backend name |

[Copilot]

Pull request overview

Copilot reviewed 43 out of 45 changed files in this pull request and generated no new comments.

Suppressed comments (3)

docs/telemetry/telemetry.md:123

• The table now omits mxc.sandbox_kind, but MXC.Error still emits that field: events.rs:116-122 passes a sandbox kind to mxc_telemetry::log_error, and the provider contract test in mxc_telemetry/src/lib.rs:350-376 requires it. Keep the public event documentation aligned with the actual payload, or remove the field from the provider and its contract test.

| Field | Type | Description |
|-------|------|-------------|
| `mxc.backend` | string | Containment backend name |
| `mxc.error_type` | string | Error category (`config_error`, `policy_error`, `process_error`, `timeout`, `init_error`, `internal_error`, `cancelled`, `unknown`) |
| `mxc.exit_code` | int32 | Process exit code |
| `mxc.phase` | string | State-aware lifecycle phase; empty for one-shot executions |

src/core/mxc_engine/src/lib.rs:252

• State-aware streaming timeouts are misclassified here. ExecSandboxProcess explicitly returns io::ErrorKind::TimedOut (wxc_common/src/exec_stream.rs:545-551), but this branch converts every error to MxcError::backend_error, so emit_sdk_state_aware_with_kind records process_error instead of the documented timeout. Preserve the timeout category when constructing the state-aware telemetry outcome.

                    Err(error) => Err(wxc_common::mxc_error::MxcError::backend_error(
                        error.to_string(),
                    )),

src/core/wxc/src/main.rs:1341

• This completion path drops the caller-requested containment kind captured in request.telemetry.requested_sandbox_kind. Because parsing resolves abstract process/vm into a concrete ContainmentBackend first (models.rs:89-119), emit_completion falls back to that backend and emits the same value for mxc.sandbox_kind and mxc.backend, contrary to the event contract in docs/telemetry/telemetry.md:104-108. Pass the retained requested kind through the executor emission path, as the SDK path already does.

    telemetry::emit_completion(
        telemetry_active,
        &request.containment,
        &response,
        run_elapsed,

[Copilot]

Pull request overview

Copilot reviewed 52 out of 54 changed files in this pull request and generated no new comments.

Suppressed comments (6)

src/core/mxc_engine/src/state_aware.rs:340

• The exec envelope cannot carry containment, so the parser records the missing value as the one-shot default Some("process"). Using it here labels streaming exec telemetry for every state-aware VM/container backend as process, despite resolving the actual backend from sandboxId below. Non-provision state-aware requests should leave this attribution unset so emission uses the resolved backend.

    let requested_sandbox_kind = parsed
        .request
        .telemetry
        .as_ref()
        .and_then(|config| config.requested_sandbox_kind);

sdk/node/src/types.ts:287

• This public description says true forces telemetry on, but the promoted stable contract only requests collection; persisted consent and administrative policy still gate emission. That wording can lead SDK users to believe this option bypasses consent. Match the generated wire documentation's opt-in semantics.

/** Telemetry configuration for TraceLogging ETW support. */
export interface TelemetryConfig {
  /**
   * Explicit telemetry override. `true` = force on, `false` = force off,
   * `undefined` = off (default).

src/core/wxc_common/src/telemetry/events.rs:120

• This reconstructs mxc.sandbox_kind from the resolved backend, so every MXC.Error loses the caller's abstract request (process or vm) even when its paired MXC.Execution preserves it via *_with_kind. The two events then disagree about the same invocation. Carry the request-scoped sandbox kind into the error emission instead of forcing the backend fallback.
  src/core/mxc_engine/src/policy.rs:794
• set_telemetry_enabled creates telemetry after the wire config has already been parsed, so requested_sandbox_kind remains None. For requests built with abstract Containment::Process or Containment::Vm, telemetry therefore reports the resolved concrete backend rather than the caller-requested kind documented for mxc.sandbox_kind. Preserve the original containment intent when building SandboxRequest and copy it into this config.

    pub fn set_telemetry_enabled(&mut self, enabled: bool) -> &mut Self {
        self.inner.telemetry = Some(TelemetryConfig {
            enabled: Some(enabled),
            ..Default::default()
        });

src/core/mxc_engine/src/state_aware.rs:252

• For every non-provision phase, containment is intentionally absent, and the shared parser consequently stores requested_sandbox_kind = Some("process"). Passing that value here misattributes start/stop/deprovision telemetry for Windows Sandbox, IsolationSession, and WSLC as process instead of falling back to the backend resolved from sandboxId. Treat the requested kind as absent on non-provision envelopes.

This issue also appears on line 336 of the same file.

    let requested_sandbox_kind = parsed
        .request
        .telemetry
        .as_ref()
        .and_then(|config| config.requested_sandbox_kind);

docs/telemetry/telemetry.md:120

• The MXC.Error provider still emits mxc.sandbox_kind (src/mxc_telemetry/src/lib.rs:280), so removing it from this payload table makes the telemetry data inventory incomplete. Restore the field to keep the privacy-facing documentation aligned with the actual event contract.

| `mxc.backend` | string | Containment backend name |

[Copilot]

Pull request overview

Copilot reviewed 52 out of 54 changed files in this pull request and generated no new comments.

Suppressed comments (3)

src/core/mxc_engine/src/lib.rs:386

• A try_wait() error does not prove that the sandbox terminated. For example, the Windows implementations return Err when WaitForSingleObject or GetExitCodeProcess fails while the process may still be running. Consuming active here releases the provider and prevents a later successful wait() from reporting the real outcome, which is the same lifecycle problem already avoided for a failed kill(). Keep the telemetry slot active after polling errors unless termination is known.

            // Poll-error branch — emit a synthesised terminal event so the
            // provider reference isn't released without accounting for the
            // run, then return the error unchanged to the caller.
            Err(_) => self.emit_synthetic(SyntheticTerminal::PollError),

src/core/mxc_engine/src/lib.rs:252

• This state-aware branch converts every wait error to BackendError, including ErrorKind::TimedOut; classify_mxc_error then reports process_error instead of the defined timeout category. The one-shot branch immediately above preserves FailurePhase::Timeout, so streaming state-aware executions currently produce inconsistent and inaccurate telemetry. Preserve the timeout distinction in the state-aware emission path as well.

                let outcome = match result {
                    Ok(exit_code) => Ok(
                        wxc_common::state_aware_dispatch::DispatchOutcome::ExecCompleted {
                            exit_code: *exit_code,
                        },
                    ),
                    Err(error) => Err(wxc_common::mxc_error::MxcError::backend_error(
                        error.to_string(),
                    )),

src/testing/wxc_e2e_tests/tests/e2e_telemetry_etw.rs:222

• The instrumented child redirects only the consent store, so it still reads the host's real administrative policy. On a managed machine with AllowTelemetry=0, assert_effective_consent still sees "granted", but telemetry::init correctly suppresses emission and the granted trace assertion fails. Redirect policy to an isolated allowed HKCU test key (as the PowerShell smoke test does) for both status and execution commands.