logpile/bible-local/docs/hardware-ingest-contract.md

Hardware Ingest Contract

Version: 2.4 Updated: 2026-03-15 Source: Reanimator Core hardware-ingest-contract.md

This file mirrors the external Reanimator hardware-ingest contract that LOGPile targets. The Reanimator endpoint uses strict JSON decoding. Any field not listed here must not be emitted.

Endpoint

POST /ingest/hardware
Content-Type: application/json

The ingest request is asynchronous. Accepted response:

{
  "status": "accepted",
  "job_id": "job_01J..."
}

Final result is available from:

GET /ingest/hardware/jobs/{job_id}

Top-level payload

{
  "filename": "redfish://10.10.10.103",
  "source_type": "api",
  "protocol": "redfish",
  "target_host": "10.10.10.103",
  "collected_at": "2026-02-10T15:30:00Z",
  "hardware": {
    "board": {},
    "firmware": [],
    "cpus": [],
    "memory": [],
    "storage": [],
    "pcie_devices": [],
    "power_supplies": [],
    "sensors": {}
  }
}

Top-level rules

• collected_at is required and must be RFC3339
• hardware.board.serial_number is required
• source_type allowed values: api, logfile, manual
• protocol allowed values: redfish, ipmi, snmp, ssh
• Unknown JSON keys are rejected by Reanimator

Shared component status fields

Allowed on cpus, memory, storage, pcie_devices, power_supplies:

• status
• status_checked_at
• status_changed_at
• status_history
• error_description

status_history[] items:

• status
• changed_at
• details

Do not emit status_at_collection; it is not part of the current strict ingest schema.

hardware.board

Allowed fields:

• serial_number required
• manufacturer
• product_name
• part_number
• uuid

String values equal to "NULL" should be omitted.

hardware.firmware

Allowed fields:

• device_name
• version

Only system-level firmware belongs here. Device-bound firmware must stay on the relevant device record and must not be duplicated at the top level.

hardware.cpus

Allowed fields:

• socket
• model
• manufacturer
• cores
• threads
• frequency_mhz
• max_frequency_mhz
• temperature_c
• power_w
• throttled
• correctable_error_count
• uncorrectable_error_count
• life_remaining_pct
• life_used_pct
• serial_number
• firmware
• present
• shared status fields

Exporter rule:

• if CPU serial is missing, generate {board_serial}-CPU-{socket}

hardware.memory

Allowed fields:

• slot
• location
• present
• serial_number
• part_number
• manufacturer
• size_mb
• type
• max_speed_mhz
• current_speed_mhz
• temperature_c
• correctable_ecc_error_count
• uncorrectable_ecc_error_count
• life_remaining_pct
• life_used_pct
• spare_blocks_remaining_pct
• performance_degraded
• data_loss_detected
• shared status fields

Exporter rules:

• skip memory items with missing serial_number
• skip memory items with present=false
• skip memory items with status=Empty

hardware.storage

Allowed fields:

• slot
• serial_number
• model
• manufacturer
• type
• interface
• size_gb
• temperature_c
• power_on_hours
• power_cycles
• unsafe_shutdowns
• media_errors
• error_log_entries
• written_bytes
• read_bytes
• life_used_pct
• firmware
• present
• remaining_endurance_pct
• life_remaining_pct
• available_spare_pct
• reallocated_sectors
• current_pending_sectors
• offline_uncorrectable
• shared status fields

Exporter rule:

• skip storage items with missing serial_number

hardware.pcie_devices

Allowed fields:

• slot
• vendor_id
• device_id
• numa_node
• temperature_c
• power_w
• life_remaining_pct
• life_used_pct
• ecc_corrected_total
• ecc_uncorrected_total
• hw_slowdown
• battery_charge_pct
• battery_health_pct
• battery_temperature_c
• battery_voltage_v
• battery_replace_required
• sfp_temperature_c
• sfp_tx_power_dbm
• sfp_rx_power_dbm
• sfp_voltage_v
• sfp_bias_ma
• bdf
• device_class
• manufacturer
• model
• serial_number
• firmware
• link_width
• link_speed
• max_link_width
• max_link_speed
• mac_addresses
• present
• shared status fields

Known device_class values:

• MassStorageController
• StorageController
• NetworkController
• EthernetController
• FibreChannelController
• VideoController
• ProcessingAccelerator
• DisplayController

Exporter rules:

• if PCIe serial is missing or placeholder-like, generate {board_serial}-PCIE-{slot}
• numa_node is allowed again in the upstream contract
• network adapters should emit mac_addresses when available
• do not emit fields outside the upstream contract

hardware.power_supplies

Allowed fields:

• slot
• present
• serial_number
• part_number
• model
• vendor
• wattage_w
• firmware
• input_type
• input_voltage
• input_power_w
• output_power_w
• temperature_c
• life_remaining_pct
• life_used_pct
• shared status fields

Exporter rule:

• skip PSUs with missing serial_number

hardware.sensors

Shape:

{
  "fans": [],
  "power": [],
  "temperatures": [],
  "other": []
}

sensors.fans

Allowed fields:

• name required
• location
• rpm
• status

sensors.power

Allowed fields:

• name required
• location
• voltage_v
• current_a
• power_w
• status

sensors.temperatures

Allowed fields:

• name required
• location
• celsius
• threshold_warning_celsius
• threshold_critical_celsius
• status

sensors.other

Allowed fields:

• name required
• location
• value
• unit
• status

Sensor rules:

• dedupe within one payload by (section, name), keeping the first item
• skip sensors without name
• the current LOGPile exporter maps generic SensorReading values into these four groups heuristically