Skip to content

docs: add scout_last_observed_version to ingestion troubleshooting section #3513

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
ericpretzel wants to merge 2 commits into
base: main
Choose a base branch
from
+17 −0
Open

docs: add scout_last_observed_version to ingestion troubleshooting section #3513

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
6b3ffda
docs: add scout version to ingestion troubleshooting
ericpretzel Jul 14, 2026
65b081b
fix whitespace
ericpretzel Jul 14, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 17 additions & 0 deletions docs/playbooks/stuck_objects/host_ingestion_failures.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -91,6 +91,23 @@ Look for:
- NIC or DPU pairing problems
- SKU or validation input mismatch

### Check the Scout version

NICo records the build version of Scout most recently observed during machine
discovery. Use this value to determine whether ingestion or validation failures
may correlate with a specific Scout release:

```bash
nico-admin-cli -a <api-url> -f json machine show <host-machine-id> \
| jq -r '.last_scout_observed_version // "unknown"'
```

The `last_scout_observed_version` value is updated whenever Scout registers the
host during discovery and remains associated with the machine after assignment.
It identifies the last discovery image, not necessarily a currently running agent.
The value is `null` for machines that have not completed discovery with a Scout
version that reports it, and a later Scout discovery replaces the stored value.
Comment on lines +105 to +109

@coderabbitai coderabbitai Bot Jul 14, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Align the update semantics with the producer contract.

The field is updated only when the discovery reporter is Scout and discovery_reporter_version is non-empty (crates/api-core/src/handlers/machine_discovery.rs:433-445). Therefore, “whenever Scout registers” overstates the behavior: a discovery without a version leaves the previous value unchanged. Please state that NICo updates it when it receives a non-empty Scout version, and clarify that the command renders stored null/missing values as unknown.

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/playbooks/stuck_objects/host_ingestion_failures.md` around lines 105 -
109, Update the documentation describing last_scout_observed_version to state
that NICo updates it only when discovery is reported by Scout with a non-empty
discovery_reporter_version; discoveries without a version leave the previous
value unchanged. Clarify that commands render stored null or missing values as
“unknown,” while preserving the existing explanation that later qualifying Scout
discoveries replace the stored value.

Source: Path instructions


## Validation and SKU

After discovery, ingestion may block on validation.
Expand Down
Loading