---
title: Audit logs
description: Telegraf Controller records security-relevant events to a tamper-evident, append-only audit log. Use audit logs to investigate access, detect unauthorized changes, and demonstrate compliance.
url: https://docs.influxdata.com/telegraf/controller/admin/audit-logs/
estimated_tokens: 1403
publisher: InfluxData
canonical: https://docs.influxdata.com/telegraf/controller/admin/audit-logs/
date: '2026-09-23T16:27:16-06:00'
lastmod: '2026-09-23T16:27:16-06:00'
---

* Telegraf Enterprise

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.

#### Available with Telegraf Enterprise

Audit logging is available with Telegraf Enterprise. If you are interested in learning more about Telegraf Enterprise,[contact us](https://www.influxdata.com/products/telegraf-enterprise/).

[ Upgrade to Enterprise](https://www.influxdata.com/products/telegraf-enterprise/)

* [What gets audited](#what-gets-audited)
* [Where audit logs are stored](#where-audit-logs-are-stored)
* [Tamper detection](#tamper-detection)
* [License and permissions](#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](/telegraf/controller/configs/versions/)operations (rollbacks, change note updates, and version pruning).
* **Configuration group lifecycle**:[configuration group](/telegraf/controller/config-groups/) creation,
  updates (including membership changes), and deletion.
* **Constants**: [global constant](/telegraf/controller/configs/constants/)creation, value updates, and deletion.

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:

|Platform|                                    Default location                                    |
|--------|----------------------------------------------------------------------------------------|
| Linux  |`$XDG_STATE_HOME/telegraf-controller/` (typically `~/.local/state/telegraf-controller/`)|
| macOS  |                         `~/Library/Logs/telegraf-controller/`                          |
|Windows |                        `%LOCALAPPDATA%\telegraf-controller\Log`                        |

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](/telegraf/controller/admin/high-availability/),
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](/telegraf/controller/admin/high-availability/#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](/telegraf/controller/admin/high-availability/#audit-logs-in-a-cluster).

## License and permissions

Audit logging is part of [Telegraf Enterprise](/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](/telegraf/controller/admin/audit-logs/enable-configure/).
* 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](/telegraf/controller/admin/audit-logs/view/).

## [Enable and configure audit logging](/telegraf/controller/admin/audit-logs/enable-configure/)

Enable audit logging in Telegraf Controller at startup, configure the retention period, and optionally forward audit events to syslog, a webhook, or a file.

## [View audit logs](/telegraf/controller/admin/audit-logs/view/)

Query Telegraf Controller audit logs through the audit log API. Read access is restricted to Owners and Administrators.

#### Related

* [Telegraf Controller configuration options](/telegraf/controller/reference/config-options/)
* [Authentication and authorization](/telegraf/controller/reference/authentication-authorization/)
* [Telegraf Enterprise](/telegraf/enterprise/)
| Platform | Default location |
| --- | --- |
| Platform | Default location |
| Linux | $XDG_STATE_HOME/telegraf-controller/  (typically  ~/.local/state/telegraf-controller/ ) |
| macOS | ~/Library/Logs/telegraf-controller/ |
| Windows | %LOCALAPPDATA%\telegraf-controller\Log |