export: align reanimator contract v2.7
This commit is contained in:
Mikhail Chusavitin
@@ -455,3 +455,129 @@ live collection and raw snapshot replay still underreported component health fie
|
||||
component record.
|
||||
|
||||
<!-- Add new decisions below this line using the format above -->
|
||||
|
||||
## ADL-025 — Missing serial numbers must remain absent in Reanimator export
|
||||
|
||||
**Date:** 2026-03-15
|
||||
**Context:**
|
||||
LOGPile previously generated synthetic serial numbers for components that had no real serial in
|
||||
source data, especially CPUs and PCIe-class devices. This made the payload look richer, but the
|
||||
serials were not authoritative and could mislead downstream consumers. Reanimator can already
|
||||
accept missing serials and generate its own internal fallback identifiers when needed.
|
||||
|
||||
**Decision:**
|
||||
- Do not synthesize fake serial numbers in LOGPile's Reanimator export.
|
||||
- If a component has no real serial in parsed source data, export the serial field as absent.
|
||||
- This applies to CPUs, PCIe devices, GPUs, NICs, and any other component class unless an
|
||||
upstream contract explicitly requires a deterministic exporter-generated identifier.
|
||||
- Any fallback serial generation defined by the upstream contract is ingest-side Reanimator behavior,
|
||||
not LOGPile exporter behavior.
|
||||
|
||||
**Consequences:**
|
||||
- Exported payloads carry only source-backed serial numbers.
|
||||
- Fake identifiers such as `BOARD-...-CPU-...` or synthetic PCIe serials are no longer considered
|
||||
acceptable exporter behavior.
|
||||
- Any future attempt to reintroduce generated serials requires an explicit contract review and a
|
||||
new ADL entry.
|
||||
|
||||
---
|
||||
|
||||
## ADL-026 — Live Redfish collection uses explicit preflight host-power confirmation
|
||||
|
||||
**Date:** 2026-03-15
|
||||
**Context:**
|
||||
Live Redfish inventory can be incomplete when the managed host is powered off. At the same time,
|
||||
LOGPile must not silently power on a host without explicit user choice. The collection workflow
|
||||
therefore needs a preflight step that verifies connectivity, shows current host power state to the
|
||||
user, and only powers on the host when the user explicitly chose that path.
|
||||
|
||||
**Decision:**
|
||||
- Add a dedicated live preflight API step before collection starts.
|
||||
- UI first runs connectivity and power-state check, then offers:
|
||||
- collect as-is
|
||||
- power on and collect
|
||||
- if the host is off and the user does not answer within 5 seconds, default to collecting without
|
||||
powering the host on
|
||||
- Redfish collection may power on the host only when the request explicitly sets
|
||||
`power_on_if_host_off=true`
|
||||
- when LOGPile powers on the host for collection, it must try to power the host back off after
|
||||
collection completes
|
||||
- if LOGPile did not power the host on itself, it must never power the host off
|
||||
- all preflight and power-control steps must be logged into the collection log and therefore into
|
||||
the raw-export bundle
|
||||
|
||||
**Consequences:**
|
||||
- Live collection becomes a two-step UX: probe first, collect second.
|
||||
- Raw bundles preserve operator-visible evidence of power-state decisions and power-control attempts.
|
||||
- Power-on failures do not block collection entirely; they only downgrade completeness expectations.
|
||||
|
||||
---
|
||||
|
||||
## ADL-027 — Sensors without numeric readings are not exported
|
||||
|
||||
**Date:** 2026-03-15
|
||||
**Context:**
|
||||
Some parsed sensor records carry only a name, unit, or status, but no actual numeric reading. Such
|
||||
records are not useful as telemetry in Reanimator export and create noisy, low-value sensor lists.
|
||||
|
||||
**Decision:**
|
||||
- Do not export temperature, power, fan, or other sensor records unless they carry a real numeric
|
||||
measurement value.
|
||||
- Presence of a sensor name or health/status alone is not sufficient for export.
|
||||
|
||||
**Consequences:**
|
||||
- Exported sensor groups contain only actionable telemetry.
|
||||
- Parsers and collectors may still keep non-numeric sensor artifacts internally for diagnostics, but
|
||||
Reanimator export must filter them out.
|
||||
|
||||
---
|
||||
|
||||
## ADL-028 — Reanimator PCIe export excludes storage endpoints and synthetic serials
|
||||
|
||||
**Date:** 2026-03-15
|
||||
**Context:**
|
||||
Some Redfish and archive sources expose NVMe drives both as storage inventory and as PCIe-visible
|
||||
endpoints. Exporting such drives in both `hardware.storage` and `hardware.pcie_devices` creates
|
||||
duplicates without adding useful topology value. At the same time, PCIe-class export still had old
|
||||
fallback behavior that generated synthetic serial numbers when source serials were absent.
|
||||
|
||||
**Decision:**
|
||||
- Export disks and NVMe drives only through `hardware.storage`.
|
||||
- Do not export storage endpoints as `hardware.pcie_devices`, even if the source inventory exposes
|
||||
them as PCIe/NVMe devices.
|
||||
- Keep real PCIe storage controllers such as RAID and HBA adapters in `hardware.pcie_devices`.
|
||||
- Do not synthesize PCIe/GPU/NIC serial numbers in LOGPile; missing serials stay absent.
|
||||
- Treat placeholder names such as `Network Device View` as non-authoritative and prefer resolved
|
||||
device names when stronger data exists.
|
||||
|
||||
**Consequences:**
|
||||
- Reanimator payloads no longer duplicate NVMe drives between storage and PCIe sections.
|
||||
- PCIe export remains topology-focused while storage export remains component-focused.
|
||||
- Missing PCIe-class serials no longer produce fake `BOARD-...-PCIE-...` identifiers.
|
||||
|
||||
---
|
||||
|
||||
## ADL-029 — Local exporter guidance tracks upstream contract v2.7 terminology
|
||||
|
||||
**Date:** 2026-03-15
|
||||
**Context:**
|
||||
The upstream Reanimator hardware ingest contract moved to `v2.7` and clarified several points that
|
||||
matter for LOGPile documentation: ingest-side serial fallback rules, canonical PCIe addressing via
|
||||
`slot`, the optional `event_logs` section, and the shared `manufactured_year_week` field.
|
||||
|
||||
**Decision:**
|
||||
- Keep the local mirrored contract file as an exact copy of the upstream `v2.7` document.
|
||||
- Describe CPU/PCIe serial fallback as Reanimator ingest behavior, not LOGPile exporter behavior.
|
||||
- Treat `pcie_devices.slot` as the canonical address on the LOGPile side as well; `bdf` may remain
|
||||
an internal fallback/dedupe key but is not serialized in the payload.
|
||||
- Export `event_logs` only from normalized parser/collector events that can be mapped to contract
|
||||
sources `host` / `bmc` / `redfish` without synthesizing message content.
|
||||
- Export `manufactured_year_week` only as a reliable passthrough when a parser/collector already
|
||||
extracted a valid `YYYY-Www` value.
|
||||
|
||||
**Consequences:**
|
||||
- Local bible wording no longer conflicts with upstream contract terminology.
|
||||
- Reanimator payloads use contract-native PCIe addressing and no longer expose `bdf` as a parallel
|
||||
coordinate.
|
||||
- LOGPile event export remains strictly source-derived; internal warnings such as LOGPile analysis
|
||||
notes do not leak into Reanimator `event_logs`.
|
||||
|
||||
Reference in New Issue
Block a user