Clarify no-synthesis ingest contract
This commit is contained in:
Mikhail Chusavitin
@@ -3,5 +3,5 @@
|
||||
- Date: `2026-03-15`
|
||||
- Decision: Host/BMC/Redfish event logs are accepted as a separate ingest payload (`event_logs`) and stored in a dedicated asset log read model with dedup/upsert semantics. They are not written to history events, snapshots, or timeline cards.
|
||||
- Context: Operational logs may contain useful diagnostics, but their semantics, duplication patterns, and lifecycle differ from canonical asset/component state mutations. Mixing them into history/timeline would pollute domain events and break history-first invariants.
|
||||
- Consequences: Hardware ingest contract must define `event_logs` as an optional raw/normalized log section. Persistence must use a separate table family (not `timeline_events`). UI must expose a dedicated asset log section/page with source/severity/date filters. Future derivations from logs into domain signals must be explicit secondary rules, not implicit by ingest.
|
||||
- Consequences: Hardware ingest contract must define `event_logs` as an optional raw/normalized log section. Persistence must use a separate table family (not `timeline_events`). UI must expose a dedicated asset log section/page with source/severity/date filters. Integrators must forward only source-derived values and must not synthesize log content or invent component serial numbers when collection fails. Future derivations from logs into domain signals must be explicit secondary rules, not implicit by ingest.
|
||||
- Supersedes: No prior explicit decision.
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
title: Hardware Ingest JSON Contract
|
||||
version: "2.6"
|
||||
version: "2.7"
|
||||
updated: "2026-03-15"
|
||||
maintainer: Reanimator Core
|
||||
audience: external-integrators, ai-agents
|
||||
@@ -9,7 +9,7 @@ language: ru
|
||||
|
||||
# Интеграция с Reanimator: контракт JSON-импорта аппаратного обеспечения
|
||||
|
||||
Версия: **2.6** · Дата: **2026-03-15**
|
||||
Версия: **2.7** · Дата: **2026-03-15**
|
||||
|
||||
Документ описывает формат JSON для передачи данных об аппаратном обеспечении серверов в систему **Reanimator** (управление жизненным циклом аппаратного обеспечения).
|
||||
Предназначен для разработчиков смежных систем (Redfish-коллекторов, агентов мониторинга, CMDB-экспортёров) и может быть включён в документацию интегрируемых проектов.
|
||||
@@ -22,6 +22,7 @@ language: ru
|
||||
|
||||
| Версия | Дата | Изменения |
|
||||
|--------|------|-----------|
|
||||
| 2.7 | 2026-03-15 | Явно запрещён синтез данных в `event_logs`; интеграторы не должны придумывать серийные номера компонентов, если источник их не отдал |
|
||||
| 2.6 | 2026-03-15 | Добавлена необязательная секция `event_logs` для dedup/upsert логов `host` / `bmc` / `redfish` вне history timeline |
|
||||
| 2.5 | 2026-03-15 | Добавлено общее необязательное поле `manufactured_year_week` для компонентных секций (`YYYY-Www`) |
|
||||
| 2.4 | 2026-03-15 | Добавлена первая волна component telemetry: health/life поля для `cpus`, `memory`, `storage`, `pcie_devices`, `power_supplies` |
|
||||
@@ -40,6 +41,7 @@ language: ru
|
||||
3. **Частичность** — можно передавать только те секции, данные по которым доступны. Пустой массив и отсутствие секции эквивалентны.
|
||||
4. **Строгая схема** — endpoint использует строгий JSON-декодер; неизвестные поля приводят к `400 Bad Request`.
|
||||
5. **Event-driven** — импорт создаёт события в timeline (LOG_COLLECTED, INSTALLED, REMOVED, FIRMWARE_CHANGED и др.).
|
||||
6. **Без синтеза со стороны интегратора** — сборщик передаёт только фактически собранные значения. Нельзя придумывать `serial_number`, `component_ref`, `message`, `message_id` или другие идентификаторы/атрибуты, если источник их не предоставил или парсер не смог их надёжно извлечь.
|
||||
|
||||
---
|
||||
|
||||
@@ -556,6 +558,7 @@ PSU без `serial_number` игнорируется.
|
||||
**Правила event_logs:**
|
||||
- Логи дедуплицируются в рамках asset + source + fingerprint.
|
||||
- Если `fingerprint` не передан, система строит его из нормализованных полей (`source`, `message_id`, `message`, `component_ref`, временная нормализация).
|
||||
- Интегратор/сборщик логов не должен синтезировать содержимое событий: не придумывайте `message`, `message_id`, `component_ref`, serial/device identifiers или иные поля, если они отсутствуют в исходном логе или не были надёжно извлечены.
|
||||
- Повторное получение того же события обновляет `last_seen_at`/счётчик повторов и не должно создавать новый timeline/history event.
|
||||
- `event_logs` используются для отдельного UI-представления логов и не изменяют canonical state компонентов/asset по умолчанию.
|
||||
|
||||
@@ -666,6 +669,8 @@ PSU без `serial_number` игнорируется.
|
||||
|
||||
## Обработка отсутствующих serial_number
|
||||
|
||||
Общее правило для всех секций: если источник не вернул серийный номер и сборщик не смог его надёжно извлечь, интегратор не должен подставлять вымышленные значения, хеши, локальные placeholder-идентификаторы или серийные номера "по догадке". Разрешены только явно оговорённые ниже server-side fallback-правила ingest.
|
||||
|
||||
| Тип | Поведение |
|
||||
|-----|-----------|
|
||||
| CPU | Генерируется: `{board_serial}-CPU-{socket}` |
|
||||
|
||||
Reference in New Issue
Block a user