Audit logging¶
RG keeps an investigation-grade audit trail: every security- and operations-relevant action is recorded with its actor, target, outcome, source, and a correlation identifier. Audit writes are transactional with the action they describe, so a recorded action definitely happened and a happened action is definitely recorded. High-frequency heartbeat and telemetry are deliberately excluded to keep the trail meaningful.
What is audited¶
The audit trail captures the consequential actions across the platform, including: authentications, permission changes, pairing approvals, configuration changes, adapter invocations, firmware upgrades, native-GUI access, credential issuance and revocation, and secret access. This spans the security-relevant (who signed in, whose permissions changed, which secret was read) and the operations-relevant (what configuration changed, which firmware was applied, who opened a device's dashboard). Together they form a complete account of the decisions and changes that shape the fleet's state and who is allowed to act on it — the events an investigator or auditor would need to reconstruct what happened, as distinct from the continuous background telemetry of normal running.
The shape of an audit event¶
Each event is recorded with a consistent set of facts: the actor who performed it, the target it acted on, the outcome (success or failure), the source it came from, and a correlation identifier that ties related events together across a single operation or session. Configuration changes additionally carry before/after metadata, so a change record shows not just that a setting changed but what it changed from and to. This uniform shape is what makes the trail investigable: an analyst can follow a correlation identifier across an operation, filter by actor or target, and see the concrete delta of any configuration change — without the events being an inconsistent grab-bag that must be interpreted per type.
Transactional writes¶
Audit writes are transactional with the action they record. An action and its audit entry commit together, so there is no window in which an action takes effect without a record, and no orphaned record for an action that didn't complete. This closes the gap that best-effort or after-the-fact logging leaves, where a crash or race can drop the very events an investigation depends on. Because the record is bound to the action atomically, the audit trail can be trusted as authoritative: its presence or absence of an event is proof of whether that event occurred, which is exactly the property an investigation-grade trail must have.
What is excluded and why¶
The trail deliberately excludes high-frequency heartbeat and telemetry. Those signals — liveness checks, periodic metrics — occur constantly and describe normal running rather than consequential action, and folding them into the audit trail would bury meaningful events under volume and inflate retention with noise. Telemetry has its own monitoring path for exactly this reason. Keeping it out of audit preserves the trail's signal: what remains is the set of actions someone might need to answer for, not the ambient hum of a healthy fleet. This exclusion is a design choice in service of investigability, not a gap.
Retention across deployments¶
Retention adapts to the deployment while keeping the same record. Connected clusters replicate audit upward for long-term retention, so events are preserved centrally beyond any single cluster. Air-gapped clusters retain audit locally and export on demand, producing a complete local record without any external connection. In all cases, retention is configurable per organization, so an operator sets how long the trail is kept to match its own compliance obligations. The same investigation-grade event — actor, target, outcome, source, correlation identifier, and change deltas — is what gets retained, whether it lives in central long-term storage or inside an isolated cluster awaiting export.