Diagnose
cua.env.v1 Diagnose: the image self-test report `SystemService.Diagnose` streams.
cua.env.v1 Diagnose: the image self-test report `SystemService.Diagnose` streams.
The report of the image self-test (SystemService.Diagnose / DiagnoseOnce): checks, their evidence and the summary.
Source: libs/cua/proto/cua/env/v1/diagnose.proto.
cua/env/v1/diagnose.proto#Options shared by Diagnose and DiagnoseOnce.
| Field | # | Type | Description |
|---|---|---|---|
strict | 1 | bool | Treat warnings (and skips not allowed by the manifest) as failures. |
only | 2 | repeated string | Run only checks whose id equals, or starts with <entry>., one of these (for example "stream" or "auth.token_file"). Empty runs all. |
skip | 3 | repeated string | Skip checks matched the same way as only. |
effects | 4 | DiagnoseEffects | Which checks may change guest state. Unspecified means NONE. |
expect_manifest | 5 | bytes | A manifest (JSON, same schema as /etc/cua-image/manifest.json) to check against instead of the one baked into the image. Empty uses the image's own. |
timeout | 6 | google.protobuf.Duration | Overall budget. Unset means 120 seconds. Checks still running when it expires fail with a timeout. |
host_time | 7 | google.protobuf.Timestamp | The caller's wall clock, for the clock-skew check. Unset skips the comparison. |
Request for SystemService.Diagnose.
| Field | # | Type | Description |
|---|---|---|---|
options | 1 | DiagnoseOptions | What to run. |
One event of SystemService.Diagnose: started, then check, for each
check, and a final report.
| Field | # | Type | Description |
|---|---|---|---|
started | 1 | DiagnoseCheckStarted (oneof event) | A check began. |
check | 2 | DiagnoseCheck (oneof event) | A check finished. |
report | 3 | DiagnoseReport (oneof event) | The run finished. Always the last message. |
A check began.
| Field | # | Type | Description |
|---|---|---|---|
id | 1 | string | Check id, for example "stream.encode.openh264". |
group | 2 | string | Check group, the id's first segment. |
Request for SystemService.DiagnoseOnce.
| Field | # | Type | Description |
|---|---|---|---|
options | 1 | DiagnoseOptions | What to run. |
Response for SystemService.DiagnoseOnce.
| Field | # | Type | Description |
|---|---|---|---|
report | 1 | DiagnoseReport | The final report. |
The result of one check.
| Field | # | Type | Description |
|---|---|---|---|
id | 1 | string | Stable id, <group>.<name>[.<detail>]. |
group | 2 | string | Group, the id's first segment (for example "auth"). |
status | 3 | CheckStatus | Outcome after severity is applied. |
severity | 4 | CheckSeverity | Severity from the manifest. |
claimed_by | 5 | repeated string | Manifest claims that make this check matter, for example "feature:desktop_stream" or "auth_mode:local". |
message | 6 | string | What happened, in one line. |
remediation | 7 | string | What to do about a warning or failure. Empty on pass. |
duration_ms | 8 | uint32 | Wall time of the check in milliseconds. |
facts | 9 | map of string to string | Measured values (for example {"backend": "openh264", "psnr_db": "41.2"}). |
artifacts | 10 | repeated DiagnoseArtifact | Evidence files. |
Evidence produced by a check.
| Field | # | Type | Description |
|---|---|---|---|
name | 1 | string | File name, unique within the report (for example "screenshot.display0.png"). |
media_type | 2 | string | Media type, for example "image/png". |
data | 3 | bytes | Contents, when small enough to inline (at most 1 MiB). Empty otherwise. |
path | 4 | string | Where the full file was written in the guest. Empty when not written. |
The whole report.
| Field | # | Type | Description |
|---|---|---|---|
schema_version | 1 | uint32 | Report schema version. Always 1 for this message. |
spacesd | 2 | DiagnoseSpacesd | The daemon that ran the checks. Unset when a shim produced the report for an image without cua-spacesd. |
image | 3 | DiagnoseImage | The image under test. |
environment | 4 | DiagnoseEnvironment | Where the guest runs. |
summary | 5 | DiagnoseSummary | Totals. |
checks | 6 | repeated DiagnoseCheck | Every check, in run order. |
fidelity | 7 | DiagnoseFidelity | Facts that make a task behave differently between variants of one image. Compared key by key by the eval-parity lane. |
producer | 8 | string | What produced the report: "cua-spacesd", or "cua-doctor-shim/<target>". |
started_at | 9 | google.protobuf.Timestamp | When the run started. |
The daemon that ran the checks.
| Field | # | Type | Description |
|---|---|---|---|
version | 1 | string | cua-spacesd version. |
protocol_revision | 2 | uint32 | cua.env.v1 protocol revision it serves. |
git_sha | 3 | string | Source revision of the build, when known. |
cua_driver_version | 4 | string | Version of the linked cua-driver core. |
The image under test.
| Field | # | Type | Description |
|---|---|---|---|
name | 1 | string | Image name from the manifest, for example "linux". |
ref | 2 | string | Reference the image was built as, when the manifest records it. |
variant | 3 | string | "rootfs" (container) or "containerdisk" (VM). |
os | 4 | string | "linux", "windows" or "macos". |
manifest_sha256 | 5 | string | SHA-256 of the manifest the checks ran against. Empty without one. |
manifest_source | 6 | string | Where the manifest came from: a guest path, "request", or empty when there is none. |
Where the guest runs.
| Field | # | Type | Description |
|---|---|---|---|
runtime | 1 | string | Runtime: "container", "gvisor", "qemu", "kubevirt", "lume", "hyperv", "bare" or "unknown". |
runtime_detail | 2 | string | Free-form runtime detail, for example "runsc". |
arch | 3 | string | "x86_64" or "arm64". |
init | 4 | string | Init system: "systemd", "supervisord", "launchd", "scm" or "unknown". |
display_server | 5 | string | "x11", "wayland", "quartz", "win32" or "none". |
os | 6 | string | OS name and version, for example "Ubuntu 24.04". |
Totals of a report.
| Field | # | Type | Description |
|---|---|---|---|
status | 1 | CheckStatus | Worst outcome: fail if any check failed, warn if any warned (fail under strict), else pass. |
pass | 2 | uint32 | Passed checks. |
warn | 3 | uint32 | Warnings. |
fail | 4 | uint32 | Failures. |
skip | 5 | uint32 | Skipped checks. |
duration_ms | 6 | uint32 | Wall time of the whole run in milliseconds. |
strict | 7 | bool | True when the run used strict. |
Facts that change how a task behaves. Every key is always present; an unknown value is the empty string.
| Field | # | Type | Description |
|---|---|---|---|
display | 1 | string | Primary display, "<width>x<height>@<scale>". |
fonts_sha256 | 2 | string | SHA-256 over the sorted list of installed font files. |
tz | 3 | string | Time zone name. |
locale | 4 | string | Locale, for example "C.UTF-8". |
clock_skew_ms | 5 | int64 | Guest clock minus the caller's clock, in milliseconds. 0 when the caller sent no host_time. |
encoder | 6 | string | Video encoder the stream would use, for example "openh264". |
a11y_backend | 7 | string | Accessibility backend, for example "atspi". |
audio_backend | 8 | string | Audio backend, for example "pipewire". |
cpu_model | 9 | string | CPU model string. |
cpu_count | 10 | uint32 | Logical CPUs. |
memory_mib | 11 | uint64 | Total memory in MiB. |
gpu | 12 | string | GPU description, or "none". |
kernel | 13 | string | Kernel release. |
runtime | 14 | string | Runtime, as in DiagnoseEnvironment.runtime. |
init | 15 | string | Init system, as in DiagnoseEnvironment.init. |
packages_sha256 | 16 | string | SHA-256 over the installed package list (name and version). |
app_versions | 17 | map of string to string | Versions of the apps the manifest lists (for example {"firefox": "130.0"}). |
tool_versions | 18 | map of string to string | Versions of the tools the manifest lists (dev tiers, for example {"node": "v22.20.0"}). |
simulator_runtimes | 19 | repeated string | Available simulator runtimes, sorted (for example "iOS 26.0"). Empty unless the manifest claims some. |
Which checks may act on the guest.
| Value | # | Description |
|---|---|---|
DIAGNOSE_EFFECTS_UNSPECIFIED | 0 | Not set. Same as DIAGNOSE_EFFECTS_NONE. |
DIAGNOSE_EFFECTS_NONE | 1 | Read-only checks. Input, window and fixture checks are skipped. |
DIAGNOSE_EFFECTS_VIRTUAL_ONLY | 2 | Effectful checks run, but only against fixture windows the doctor itself launched on the guest's virtual display. Refused on bare hosts. |
Outcome of one check.
| Value | # | Description |
|---|---|---|
CHECK_STATUS_UNSPECIFIED | 0 | Not reported. |
CHECK_STATUS_PASS | 1 | Works as claimed. |
CHECK_STATUS_WARN | 2 | Works with a caveat, or something unclaimed is off. |
CHECK_STATUS_FAIL | 3 | Broken. |
CHECK_STATUS_SKIP | 4 | Not run; message says why. |
How much a check matters for this image, derived from the manifest.
| Value | # | Description |
|---|---|---|
CHECK_SEVERITY_UNSPECIFIED | 0 | Not reported. |
CHECK_SEVERITY_REQUIRED | 1 | The image claims it: a failure fails the report. |
CHECK_SEVERITY_RECOMMENDED | 2 | Optional in the manifest: a failure is reported as a warning. |
CHECK_SEVERITY_INFO | 3 | Not claimed: a failure is reported as a warning. |