Enable and configure audit logging

Enable audit logging in Telegraf Controller at startup with a signing key, 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.
• A signing key of at least 32 characters. See Generate a signing key.
• 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

Audit logging requires two settings at startup: AUDIT_ENABLED set to true, and a signing key of at least 32 characters that Telegraf Controller uses to sign each audit entry. Provide the key in one of the following ways:

• The AUDIT_HMAC_KEY environment variable, which holds the key itself.
• The AUDIT_HMAC_KEY_FILE environment variable or the --audit-hmac-key-file command flag, which name a file that holds the key. Telegraf Controller trims surrounding whitespace, so a trailing newline in the file is fine.

If both are set, AUDIT_HMAC_KEY takes precedence. Telegraf Controller never writes the key to disk or to the database.

Generate a signing key

Any random string of at least 32 characters works as a key. To generate one and store it in a file:

openssl rand -base64 48 > /etc/telegraf-controller/audit-key
chmod 600 /etc/telegraf-controller/audit-key

-join ((48..57 + 65..90 + 97..122) | Get-Random -Count 48 | ForEach-Object { [char]$_ }) |
  Set-Content -NoNewline "C:\ProgramData\TelegrafController\audit-key"

Store the file outside the audit log data directory and restrict read access to the account that runs Telegraf Controller.

Start Telegraf Controller with audit logging enabled

[Service]
Environment=AUDIT_ENABLED=true
Environment=AUDIT_HMAC_KEY_FILE=/etc/telegraf-controller/audit-key

sudo systemctl daemon-reload
sudo systemctl restart telegraf-controller

export AUDIT_ENABLED=true
export AUDIT_HMAC_KEY_FILE=/etc/telegraf-controller/audit-key
telegraf_controller --no-interactive

telegraf_controller --audit-enabled \
  --audit-hmac-key-file=/etc/telegraf-controller/audit-key \
  --no-interactive

$env:AUDIT_ENABLED="true"
$env:AUDIT_HMAC_KEY_FILE="C:\ProgramData\TelegrafController\audit-key"
./telegraf_controller.exe --no-interactive

./telegraf_controller.exe --audit-enabled `
  --audit-hmac-key-file="C:\ProgramData\TelegrafController\audit-key" `
  --no-interactive

docker run \
  --env AUDIT_ENABLED=true \
  --env AUDIT_HMAC_KEY_FILE=/run/secrets/audit-key \
  --volume /etc/telegraf-controller/audit-key:/run/secrets/audit-key:ro \
  influxdata/telegraf-controller:1.2.0

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.
• The server log reports the result of the startup chain check. See Verify integrity.

Start without a key

If AUDIT_ENABLED is true but no signing key is configured, or the key is shorter than 32 characters, Telegraf Controller starts with audit logging disabled and logs the reason, for example:

Audit HMAC key is not configured: set AUDIT_HMAC_KEY or pass --audit-hmac-key-file; audit logging stays disabled

The Settings > Audit Logging section displays as disabled until you restart with a key.

When you start the executable in a terminal without --no-interactive and no key is configured, Telegraf Controller prompts for the key instead:

Audit log signing key (at least 32 characters, empty to start without audit logging):

Input is hidden, and the key applies to that run only. Press Enter without a key to start with audit logging disabled.

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.

Every audit event is forwarded, including sign-in, sign-out, constant, and agent-deletion events. If a forwarder fails, Telegraf Controller logs Audit forward failed with a running failure count and keeps running. The entry is still written to local storage.

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_ENABLED (or set it to a value other than true) and restart Telegraf Controller. Starting without a signing key has the same effect. 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.