Audit logs

Telegraf Controller records security-relevant events to an append-only, tamper-evident audit log. Use audit logs to investigate access patterns, detect unauthorized changes, and demonstrate compliance with internal or external policies.

• What gets audited
• Where audit logs are stored
• Tamper detection
• License and permissions

What gets audited

Telegraf Controller captures the following categories of events:

• Authentication: user sign-in (local, LDAP, or OIDC) and sign-out.
• Agent lifecycle: agent registration, status transitions (such as moving in and out of the not reporting state), and agent deletion (manual deletions and removals driven by reporting-rule retention).
• Configuration lifecycle: configuration creation, updates, and deletion, and configuration version operations (rollbacks, change note updates, and version pruning).

Each entry records:

• Action: the specific event identifier.
• Actor: the user, API token, or system component that triggered the event.
• Source: IP address and user-agent of the request, where applicable.
• Outcome: Success, Failure, or Denied.
• Timestamp: when the event occurred, in UTC.
• Sequence number, hash, and previous hash: used to detect tampering.

Where audit logs are stored

Telegraf Controller writes audit entries to per-month SQLite files in a platform-specific data directory:

Files are named audit-YYYY-MM.log, one per calendar month. Each file is a SQLite database that enforces immutability through a database trigger: attempts to delete rows are rolled back. Telegraf Controller keeps up to 48 months of audit files available for query.

In a high-availability (HA) cluster, audit logging is per node, not shared. Each node writes its own audit files and, when queried, returns only its own events. To review activity across the cluster, forward each node’s events to a shared destination and aggregate them there. See Audit logs in a cluster.

Tamper detection

Each entry includes a SHA-256 hash that incorporates the entry’s contents and the hash of the previous entry, forming a chain. Sequence numbers are contiguous within and across monthly files. Any modification, deletion, or out-of-order insertion breaks the chain.

In a high-availability cluster, each node maintains its own hash chain and sequence numbers, so events from different nodes merged into a single stream do not form one valid chain. Verify integrity per node: separate aggregated events by their originating node, then check each node’s chain on its own. See Audit logs in a cluster.

License and permissions

Audit logging is part of Telegraf Enterprise and is unavailable in the free tier. With a valid license:

• Audit logging is enabled at startup only by setting AUDIT_ENABLED. See Enable and configure audit logging.
• Only the retention period is modifiable at runtime, from the Settings page.
• Only the Owner and Administrator roles can read audit log entries. See View audit logs.