feat(firmware): count artifacts unavailable before download

[chet]

DownloadFinished runs only after a firmware download starts. A missing URL and a stale cached artifact that cannot be removed both return earlier, which meant neither blocker appeared in the download metrics.

So, the two existing error branches now emit sibling Events backed by carbide_firmware_artifact_unavailable_total, with a bounded reason={missing_url,stale_cache_removal_failed} label. Separate Event types keep each branch's existing log fields intact without adding empty context, while every false return and the recoverable checksum warning stay the same.

The table-driven Event contract checks both reasons and exact log fields, and callsite tests exercise an empty URL and a deterministic stale-cache removal failure.

Tests added!

Related issues

This supports #4078

Part of #3169

Type of Change

• Add - New feature or capability
• Change - Changes in existing functionality
• Fix - Bug fixes
• Remove - Removed features or deprecated functionality
• Internal - Internal changes (refactoring, tests, docs, etc.)

Breaking Changes

• This PR contains breaking changes

Testing

• Unit tests added/updated

• Integration tests added/updated

• Manual testing performed

• No testing required (docs, internal refactor, etc.)

• cargo test -p carbide-firmware --lib

• cargo make format-nightly

• cargo make clippy

• cargo make carbide-lints

• cargo xtask check-event-names

• cargo xtask check-metric-docs

• cargo xtask check-workspace-deps

• cargo make check-licenses

• cargo make check-bans

Additional Notes

Closes #4078

[chet]

@coderabbitai full_review, thanks!

[coderabbitai]

@chet: Starting a full review of #4085, including the new metric-event paths and their test coverage.

🐇🔍

✅ Action performed

Full review finished.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 3b73f5f4-d6bf-4a3b-bec4-a1aff1d2de7e

📥 Commits

Reviewing files that changed from the base of the PR and between 4f36238 and 4401406.

⛔ Files ignored due to path filters (1)

• Cargo.lock is excluded by !**/*.lock

📒 Files selected for processing (4)

• crates/firmware/Cargo.toml
• crates/firmware/src/downloader.rs
• crates/firmware/src/tests/downloader.rs
• docs/observability/core_metrics.md

---

Summary by CodeRabbit

• Observability
  • Added structured reporting for unavailable firmware artifacts, including missing download URLs and failures removing stale cached artifacts.
  • Added the carbide_firmware_artifact_unavailable_total metric, broken down by failure reason.
• Documentation
  • Documented the new firmware artifact availability metric.
• Tests
  • Added coverage for error reporting, event details, and metric increments in both scenarios.

Walkthrough

Firmware downloader artifact-unavailable paths now emit structured events for missing URLs and stale cached artifact removal failures. Tests validate event fields and reason-scoped metrics, and observability documentation records the new counter.

Changes

Firmware artifact telemetry

Layer / File(s)	Summary
Telemetry contracts and downloader emission crates/firmware/src/downloader.rs	Defines bounded unavailable reasons and emits structured events with firmware path, filename, and removal error context.
Telemetry validation and documentation crates/firmware/Cargo.toml, crates/firmware/src/tests/downloader.rs, docs/observability/core_metrics.md	Adds test support, validates structured logs and reason-labeled counter increments, and documents carbide_firmware_artifact_unavailable_total.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Sequence Diagram(s)

sequenceDiagram
  participant FirmwareDownloaderActual
  participant emit
  participant Metrics
  participant ErrorLogs
  FirmwareDownloaderActual->>emit: Emit artifact-unavailable event
  emit->>Metrics: Increment counter by reason
  emit->>ErrorLogs: Record structured error fields

Loading

Possibly related issues

• feat(firmware): count artifacts unavailable before download #4078 — Directly covers the firmware artifact-unavailable events, metric, logging, and tests added here.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main change: counting firmware artifacts unavailable before download.
Description check	✅ Passed	The description matches the implemented metric, event changes, and tests.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

🌿 Preview your docs: https://nvidia-preview-pull-request-4085.docs.buildwithfern.com/infra-controller