Enable and configure audit logging

Enable audit logging in Telegraf Controller at startup, change the retention period as needed, and optionally forward events to external destinations for long-term storage or SIEM integration.

• Prerequisites
• Enable audit logging
• Configure retention
• Forward audit events
• Disable audit logging

Prerequisites

• A valid Telegraf Enterprise license applied to your Telegraf Controller instance.
• Permission to modify the Telegraf Controller startup environment (for example, the systemd unit file or startup environment).
• The Owner or Administrator role to change the retention period from the UI.

Enable audit logging

Set AUDIT_LOGGING_ENABLED to true before starting Telegraf Controller.

[Service]
Environment=AUDIT_LOGGING_ENABLED=true

sudo systemctl daemon-reload
sudo systemctl restart telegraf-controller

export AUDIT_LOGGING_ENABLED=true
telegraf_controller --no-interactive

telegraf_controller --audit-enabled --no-interactive

$env:AUDIT_LOGGING_ENABLED="true"
./telegraf_controller.exe --no-interactive

./telegraf_controller.exe --audit-enabled --no-interactive

After Telegraf Controller starts:

• The Settings > Audit Logging section displays as enabled.
• Audit entries begin appearing in the platform data directory described in Where audit logs are stored.

Configure retention

Telegraf Controller keeps audit entries for 90 days (2160 hours) by default and runs a cleanup job every 12 hours that removes entries older than the retention threshold.

Available retention values:

Change audit log retention from the Settings page

1. Sign in as an Owner or Administrator.
2. Navigate to the Settings page from the left navigation menu.
3. In the Audit Logging section, select a value from Audit log retention.
4. Click Save.

The new retention value takes effect immediately. The next cleanup run removes any entries that fall outside the new window.

Set the initial retention at startup

Use the AUDIT_LOG_RETENTION environment variable to seed the retention period when Telegraf Controller initializes its settings on first startup.

export AUDIT_LOG_RETENTION=8760

Forward audit events

Telegraf Controller can forward each audit event to one or more external destinations in addition to writing it to local storage. Forwarders are configured at startup only and run independently, which lets you enable any combination of syslog, webhook, and file forwarders.

Forward to syslog

Forward audit events to a syslog server over TCP or UDP.

export AUDIT_SYSLOG_HOST=syslog.example.com
export AUDIT_SYSLOG_PORT=514
export AUDIT_SYSLOG_PROTOCOL=tcp

Forward to a webhook

Forward audit events as JSON POST requests to an HTTP webhook.

export AUDIT_WEBHOOK_URL=https://siem.example.com/ingest
export AUDIT_WEBHOOK_AUTH_HEADER="Bearer xxxxxxxxxxxx"

The webhook forwarder retries each event up to three times with backoff and a 10-second request timeout. Events that return 408, 429, or 5xx responses are retried; events that return other 4xx responses are dropped. Telegraf Controller honors a Retry-After response header when present.

Append to a file

Append each event to a file as a single JSON object per line (.jsonl).

export AUDIT_FILE_PATH=/var/log/telegraf-controller/audit.jsonl

The path must be writable by the Telegraf Controller process. Telegraf Controller does not rotate or trim this file. Pair it with a system log rotator (such as logrotate) if you keep the forwarder on long term.

Disable audit logging

To turn audit logging off, remove AUDIT_LOGGING_ENABLED (or set it to a value other than true) and restart Telegraf Controller. The startup-only policy applies in both directions: audit logging cannot be disabled from the UI.

Existing audit files remain on disk and continue to be readable through GET /api/audit-logger until they age out of retention.