---
layout: docs
page_title: Audit Logging (Enterprise)
description: >-
  Audit logging secures Consul by capturing a record of HTTP API access and usage. Learn how to format agent configuration files to enable audit logs and specify the path to save logs to.
---

# Audit Logging

@include 'alerts/enterprise-alert.mdx'

This page describes the process to enable and configure audit logging on Consul Enterprise clusters. Audit logging enables security and compliance teams within an organization to get greater insight into Consul access and usage patterns.

## Introduction

Audit logs capture a list of authenticated events that Consul processes through its HTTP API. This list includes both attempted and committed operations, and each item includes a timestamp, the operation performed, and the user who initiated the action. Consul compiles these events into JSON format for export.

Consul's audit logs only capture events initiated through the HTTP API. The audit log does not record operations that take place over the internal RPC communication channel used for agent communication.

For detailed specifications to configure the Consul Enterprise's audit logging behavior, review the [Agent audit log configuration reference](/consul/docs/reference/agent/configuration-file/log#audit).

## Configure audit logging

You must enable audit logging on every agent to accurately capture all operations performed through the HTTP API. To enable logging, add the [`audit` configuration block](/consul/docs/reference/agent/configuration-file/log#audit) to the agent's configuration.


### Log to file

The following example configures a destination called `My Sink`. Audit logging operates continuously, which requires you to set rotation parameters. This example configures Consul to generate a JSON file at the destination path, and then rotate to a new file either when the log file size is greater than 25165824 bytes (24 megabytes) or when 24 hours pass without a log rotation. Because files rotate, audit events are saved in files named: `/tmp/audit-<TIMESTAMP>.json`.

<CodeTabs>

```hcl
audit {
  enabled = true
  sink "My sink" {
    type   = "file"
    format = "json"
    path   = "/tmp/audit.json"
    delivery_guarantee = "best-effort"
    rotate_duration = "24h"
    rotate_max_files = 15
    rotate_bytes = 25165824
  }
}
```

```json
{
  "audit": {
    "enabled": true,
    "sink": {
      "My sink": {
        "type": "file",
        "format": "json",
        "path": "/tmp/audit.json",
        "delivery_guarantee": "best-effort",
        "rotate_duration": "24h",
        "rotate_max_files": 15,
        "rotate_bytes": 25165824
      }
    }
  }
}
```

```yaml
server:
  auditLogs:
      enabled: true
      sinks:
        - name: My Sink
          type: file
          format: json
          path: /tmp/audit.json
          delivery_guarantee: best-effort
          rotate_duration: 24h
          rotate_max_files: 15
          rotate_bytes: 25165824
```
</CodeTabs>


## Log to standard out

The following example configures a destination called `My Sink` which emits audit logs to standard out.

<CodeTabs>

```hcl
audit {
  enabled = true
  sink "My sink" {
    type   = "file"
    format = "json"
    path   = "/dev/stdout"
    delivery_guarantee = "best-effort"
  }
}
```

```json
{
  "audit": {
    "enabled": true,
    "sink": {
      "My sink": {
        "type": "file",
        "format": "json",
        "path": "/dev/stdout",
        "delivery_guarantee": "best-effort"
      }
    }
  }
}
```

```yaml
server:
  auditLogs:
      enabled: true
      sinks:
        - name: My Sink
          type: file
          format: json
          path: /dev/stdout
          delivery_guarantee: best-effort
```

</CodeTabs>


Audit logging configuration parameters are not part of Consul's [reloadable configurations](/consul/docs/fundamentals/agent#reloadable-configurations). You must fully restart the Consul agents to apply the configuration.

## Review audit log content

In this example you will review logging for two different requests. Both of them use the [`/v1/catalog/service/`](/consul/api-docs/catalog#list-nodes-for-service) endpoint to retrieve information about the `ssh` service in the Consul catalog. The difference between the two requests is that one is not authenticated and the other uses a valid ACL token.

### Anonymous request

The following example shows an HTTP request recorded in the audit log. At the bottom, the `stage` field is set to `OperationStart`, which indicates the agent began processing the request.

The value of the `payload.auth.accessor_id` field is the accessor ID of the ACL token included with the request. In this case, `00000000-0000-0000-0000-000000000002` is the ID of the anonymous token.

<CodeBlockConfig hideClipboard highlight="10,21">

```json
{
  "created_at": "2025-07-31T14:32:38.559349128Z",
  "event_type": "audit",
  "payload": {
    "id": "674891c9-a5a0-e0ba-c738-00cab3c42f16",
    "version": "1",
    "type": "HTTPEvent",
    "timestamp": "2025-07-31T14:32:38.558390378Z",
    "auth": {
      "accessor_id": "00000000-0000-0000-0000-000000000002",
      "description": "Anonymous Token",
      "create_time": "2025-07-30T09:14:52.866798047Z"
    },
    "request": {
      "operation": "GET",
      "endpoint": "/v1/catalog/service/ssh",
      "remote_addr": "127.0.0.1:45110",
      "user_agent": "curl/7.88.1",
      "host": "127.0.0.1:8500"
    },
    "stage": "OperationStart"
  }
}
```

</CodeBlockConfig>

After Consul processes the request, it writes a corresponding log entry for the HTTP response. In the following example, the `stage` field is set to `OperationComplete` which indicates the agent has completed processing the request. Directly above, the status indicates the HTTP request was completed with `200` response.

<CodeBlockConfig hideClipboard highlight="22,24">

```json
{
  "created_at": "2025-07-31T14:32:38.562146462Z",
  "event_type": "audit",
  "payload": {
    "id": "c7d9614e-b110-729a-4c0b-6123f5c341a1",
    "version": "1",
    "type": "HTTPEvent",
    "timestamp": "2025-07-31T14:32:38.561802712Z",
    "auth": {
      "accessor_id": "00000000-0000-0000-0000-000000000002",
      "description": "Anonymous Token",
      "create_time": "2025-07-30T09:14:52.866798047Z"
    },
    "request": {
      "operation": "GET",
      "endpoint": "/v1/catalog/service/ssh",
      "remote_addr": "127.0.0.1:45110",
      "user_agent": "curl/7.88.1",
      "host": "127.0.0.1:8500"
    },
    "response": {
      "status": "200"
    },
    "stage": "OperationComplete"
  }
}
```

</CodeBlockConfig>

### Authenticated request

The following example shows an HTTP request recorded in the audit log. At the bottom, the `stage` field is set to `OperationStart`, which indicates the agent began processing the request.

The value of the `payload.auth.accessor_id` field is the accessor ID of the ACL token included with the request.

<CodeBlockConfig hideClipboard highlight="10,21">

```json
{
  "created_at": "2025-07-31T14:55:23.751575302Z",
  "event_type": "audit",
  "payload": {
    "id": "bcaa81eb-0687-9d62-f288-bf82215fa5c6",
    "version": "1",
    "type": "HTTPEvent",
    "timestamp": "2025-07-31T14:55:23.746568552Z",
    "auth": {
      "accessor_id": "540c5184-3bc7-852a-641c-cac2b46f2885",
      "description": "Bootstrap Token (Global Management)",
      "create_time": "2025-07-30T09:14:55.301395548Z"
    },
    "request": {
      "operation": "GET",
      "endpoint": "/v1/catalog/service/ssh",
      "remote_addr": "127.0.0.1:54166",
      "user_agent": "curl/7.88.1",
      "host": "127.0.0.1:8500"
    },
    "stage": "OperationStart"
  }
}
```

</CodeBlockConfig>

After Consul processes the request, it writes a corresponding log entry for the HTTP response. In the following example, the `stage` field is set to `OperationComplete`, which indicates the agent has completed processing the request. Directly above, the status indicates the HTTP request was completed with `200` response.

<CodeBlockConfig hideClipboard highlight="22,24">

```json
{
  "created_at": "2025-07-31T14:55:23.754546469Z",
  "event_type": "audit",
  "payload": {
    "id": "16193bc9-71cf-1d4b-a772-faba8b9dea00",
    "version": "1",
    "type": "HTTPEvent",
    "timestamp": "2025-07-31T14:55:23.75438301Z",
    "auth": {
      "accessor_id": "540c5184-3bc7-852a-641c-cac2b46f2885",
      "description": "Bootstrap Token (Global Management)",
      "create_time": "2025-07-30T09:14:55.301395548Z"
    },
    "request": {
      "operation": "GET",
      "endpoint": "/v1/catalog/service/ssh",
      "remote_addr": "127.0.0.1:54166",
      "user_agent": "curl/7.88.1",
      "host": "127.0.0.1:8500"
    },
    "response": {
      "status": "200"
    },
    "stage": "OperationComplete"
  }
}
```

</CodeBlockConfig>


