Synthetic Events

§2.6.1 Definition #

Synthetic events are records generated by eventd itself, not received from KMES. They are written directly to the event store database, bypassing KMES ring buffers entirely.

Synthetic events do not have KMES headers. They do not carry identity stamps, sequence numbers, or origin class values. They have an eventd-assigned timestamp (wall clock at generation time) and an event type string identifying the kind of synthetic event.

§2.6.2 When synthetic events are generated #

eventd MUST generate synthetic events for the following conditions:

• Sequence gaps -- when lost events are detected on any CPU (see §2.5).
• eventd startup -- when eventd starts and successfully attaches to KMES ring buffers.
• eventd shutdown -- when eventd begins a graceful shutdown, recording the last persisted sequence number per CPU.
• Storage errors -- when a write to the event store fails (disk full, SQLite error).
• Configuration changes -- when eventd reads a changed configuration value from the registry.

Additional synthetic event types MAY be defined in future versions.

§2.6.3 Shard assignment #

CPU-specific synthetic events (gap records) MUST be written to the shard assigned to the CPU that generated them. They are handed off to the writer thread alongside regular events from that CPU.

Daemon-wide synthetic events (startup, shutdown, configuration changes) MUST be written to shard 0. These events are infrequent and the minor write imbalance is negligible.

§2.6.4 Storage #

Synthetic events are written to the same shard databases as KMES events. They participate in the same batching, retention, and query mechanisms. They are distinguishable from KMES events by their record type in the storage schema.

§2.6.5 Ordering #

Synthetic events are ordered by their eventd-assigned timestamp. They do not participate in per-CPU sequence numbering. A synthetic event's timestamp reflects when eventd generated it, not when the condition it describes occurred (e.g., a gap record's timestamp is when the gap was detected, not when the lost events were emitted).