> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flowx.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Audit setup

> This guide will walk you through the process of setting up the Audit service and configuring it to meet your needs.

## Infrastructure prerequisites

The Audit service requires the following components to be set up before it can be started:

* **Docker engine**
* **Kafka**
* **Elasticsearch**

> [!NOTE]
>
> **Redis is not required.** audit-core does not depend on Redis. If you previously configured Redis for this service, those environment variables can be removed from your deployment.

***

## Dependencies

The Audit service is built as a Docker image and runs on top of Kafka and Elasticsearch. Therefore, these services must be set up and running before starting the Audit service.

* [**Kafka configuration**](https://docs.flowx.ai/6.x/setup-guides/setup-guides-overview.md#kafka-configuration)
* [**Authorization & access roles**](https://docs.flowx.ai/6.x/setup-guides/setup-guides-overview.md#authorization-&-access-management)
* [**Elasticsearch**](#configuring-elasticsearch)
* [**Logging**](https://docs.flowx.ai/6.x/setup-guides/setup-guides-overview.md#logging-configuration)

***

## Configuration

### Configuring Kafka

To configure the Kafka server for the Audit service, set the following environment variables:

#### Connection settings

| Variable | Description | Default Value |
| - | - | - |
| `KAFKA_BOOTSTRAP_SERVERS` | Kafka broker addresses (fallback: `SPRING_KAFKA_BOOTSTRAP_SERVERS`) | `localhost:9092` |
| `KAFKA_SECURITY_PROTOCOL` | Security protocol for Kafka connections (fallback: `SPRING_KAFKA_SECURITY_PROTOCOL`) | `PLAINTEXT` |
| `KAFKA_MESSAGE_MAX_BYTES` | Maximum message size (bytes) | `52428800` (50 MB) |

#### Consumer configuration

| Variable | Description | Default Value |
| - | - | - |
| `SPRING_KAFKA_CONSUMER_GROUPID` | Consumer group ID for audit logs | `audit-gid` |
| `KAFKA_CONSUMER_THREADS` | Number of consumer threads | `1` |
| `KAFKA_AUTHEXCEPTIONRETRYINTERVAL` | Retry interval after auth failure (seconds) | `10` |

#### OAuth authentication (when using SASL\_PLAINTEXT)

| Environment Variable | Description | Default Value |
| - | - | - |
| `KAFKA_OAUTH_CLIENT_ID` | OAuth client ID | `kafka` |
| `KAFKA_OAUTH_CLIENT_SECRET` | OAuth client secret | `kafka-secret` |
| `KAFKA_OAUTH_TOKEN_ENDPOINT_URI` | OAuth token endpoint | `kafka.auth.localhost` |

> [!NOTE]
>
> When using the `kafka-auth` profile, the security protocol will automatically be set to `SASL_PLAINTEXT` and the SASL mechanism will be set to `OAUTHBEARER`.

#### Topic naming configuration

| Variable | Description | Default Value |
| - | - | - |
| `KAFKA_TOPIC_NAMING_PACKAGE` | Package prefix for topic names | `ai.flowx.` |
| `KAFKA_TOPIC_NAMING_ENVIRONMENT` | Environment segment for topic names | ` ` |
| `KAFKA_TOPIC_NAMING_VERSION` | Version suffix for topic names | `.v1` |
| `KAFKA_TOPIC_NAMING_SEPARATOR` | Primary separator for topic names | `.` |
| `KAFKA_TOPIC_NAMING_SEPARATOR2` | Secondary separator for topic names | `-` |

#### Kafka topics

| Variable | Description | Default Value |
| - | - | - |
| `KAFKA_TOPIC_AUDIT_IN` | Topic for receiving audit logs | `ai.flowx.core.trigger.save.audit.v1` |

### Configuring Elasticsearch

Configure Elasticsearch connection for audit data storage:

| Variable | Description | Default Value |
| - | - | - |
| `SPRING_ELASTICSEARCH_REST_PROTOCOL` | Connection protocol | `https` |
| `SPRING_ELASTICSEARCH_REST_URIS` | URL(s) of Elasticsearch nodes (no protocol) | - |
| `SPRING_ELASTICSEARCH_REST_DISABLESSL` | Disable SSL verification | `false` |
| `SPRING_ELASTICSEARCH_REST_USERNAME` | Authentication username | - |
| `SPRING_ELASTICSEARCH_REST_PASSWORD` | Authentication password | - |
| `FLOWX_ELASTICSEARCH_INDEXSETTINGS_NAME` | Audit data stream name | `audit-logs` |
| `FLOWX_ELASTICSEARCH_INDEXSETTINGS_SHARDS` | Number of primary shards | `2` |
| `FLOWX_ELASTICSEARCH_INDEXSETTINGS_REPLICAS` | Number of replica shards | `0` |
| `FLOWX_ELASTICSEARCH_INDEXROLLOVERDAYS` | Days before the data stream rolls over to a new backing index | `30` |
| `FLOWX_ELASTICSEARCH_INDEXROLLOVERMAXPRIMARYSHARDSIZE` | Also roll over when a primary shard reaches this size, as a number and a unit such as `50gb` | Not set: roll over by age only |
| `FLOWX_ELASTICSEARCH_INDEXRETENTIONDAYS` | Days after a backing index rolls over before it's deleted | Not set: indices are never deleted |

> [!NOTE]
>
> The Elasticsearch index settings determine how your audit data is distributed and replicated across the cluster. The number of shards affects search performance and indexing, while replicas provide redundancy.

> [!WARNING]
>
> The Audit service rewrites the index lifecycle management (ILM) policy `{FLOWX_ELASTICSEARCH_INDEXSETTINGS_NAME}_policy` (by default `audit-logs_policy`) every time it starts. The policy it writes rolls the data stream over after `FLOWX_ELASTICSEARCH_INDEXROLLOVERDAYS` days, or when a primary shard reaches `FLOWX_ELASTICSEARCH_INDEXROLLOVERMAXPRIMARYSHARDSIZE`. It has a delete phase only when `FLOWX_ELASTICSEARCH_INDEXRETENTIONDAYS` is set.
>
> Any change you make to this policy directly in Elasticsearch, such as adding a delete or warm phase, is lost the next time the Audit service restarts or is upgraded. Set retention with `FLOWX_ELASTICSEARCH_INDEXRETENTIONDAYS` instead.

> [!WARNING]
>
> `FLOWX_ELASTICSEARCH_INDEXRETENTIONDAYS` deletes audit data. The retention period counts from the day each backing index rolls over, not from the day it was created. When you first set it, the Audit service also deletes backing indices that rolled over more than that many days ago. Back up any audit data you must keep before you set it.

### CAS lib configuration

| Environment Variable | Description | Default Value |
| - | - | - |
| `FLOWX_SPICEDB_HOST` | SpiceDB server hostname | `spicedb` |
| `FLOWX_SPICEDB_PORT` | SpiceDB server port | `50051` |
| `FLOWX_SPICEDB_TOKEN` | SpiceDB authentication token | `-` |

### Configuring logging

To control the log levels, set the following environment variables:

| Variable | Description | Default Value |
| - | - | - |
| `LOGGING_LEVEL_ROOT` | Log level for root service | `INFO` |
| `LOGGING_LEVEL_APP` | Log level for application | `INFO` |

***

## Ingress and CORS

The Audit Core service is exposed externally on the admin host. Routing is configured through the FlowX Helm chart, which renders either a Kubernetes Ingress (default) or a Gateway API HTTPRoute per service. CORS handling lives in the service code; only the allowed-origins list is deployment-specific.

### Service route

| Host group | External path | Backend receives |
| - | - | - |
| admin | `/audit` | `/` |

The path is set through `services.audit-core.ingress.admin.path` (or `services.audit-core.gateway.admin.paths`) in the chart values.

### CORS configuration

| Environment Variable | Description | Default Value |
| - | - | - |
| `APPLICATION_CORS_ALLOWORIGIN` | Comma-separated list of origins allowed to call this service from the browser. Supports wildcard subdomains. Must include every Designer and integration domain that issues browser requests against Audit Core. | `-` |

Allowed methods, allowed headers (including `Authorization`, `Content-Type`, `Fx-Workspace-Id`), and credential handling are baked into the service's `application.yaml` with safe defaults. Override these only if you have a non-standard requirement.

For the complete route reference, Gateway API HTTPRoute configuration, and route customization, see the [ingress configuration guide](https://docs.flowx.ai/6.x/setup-guides/ingress-configuration.md).

***

## Troubleshooting

### Common issues

> [accordion] Audit logs not appearing
>
> **Symptoms:** Audit events are not being recorded or are missing from search results.
>
> **Solutions:**
>
> 1. Verify the `KAFKA_TOPIC_AUDIT_IN` topic exists and matches the topic other services publish to (`ai.flowx.core.trigger.save.audit.v1`)
> 2. Check that the consumer group ID (`SPRING_KAFKA_CONSUMER_GROUPID`) is correctly configured and not conflicting with another consumer
> 3. Ensure Kafka connectivity by verifying `KAFKA_BOOTSTRAP_SERVERS` is reachable from the pod
> 4. Check consumer thread count (`KAFKA_CONSUMER_THREADS`) — increase if throughput is insufficient

> [accordion] Elasticsearch connection errors
>
> **Symptoms:** Service fails to start or throws connection errors related to Elasticsearch.
>
> **Solutions:**
>
> 1. Verify `SPRING_ELASTICSEARCH_REST_URIS` points to a reachable Elasticsearch node (do not include the protocol in this value)
> 2. Check that `SPRING_ELASTICSEARCH_REST_PROTOCOL` matches your Elasticsearch setup (`https` or `http`)
> 3. If using SSL, ensure `SPRING_ELASTICSEARCH_REST_DISABLESSL` is set appropriately and certificates are valid
> 4. Verify `SPRING_ELASTICSEARCH_REST_USERNAME` and `SPRING_ELASTICSEARCH_REST_PASSWORD` credentials are correct

> [accordion] High storage consumption
>
> **Symptoms:** Elasticsearch disk usage grows rapidly or cluster health turns yellow/red.
>
> **Solutions:**
>
> 1. Check the backing indices of the audit data stream: the `{FLOWX_ELASTICSEARCH_INDEXSETTINGS_NAME}_policy` ILM policy that the Audit service writes rolls indices over but never deletes them
> 2. Adjust `FLOWX_ELASTICSEARCH_INDEXSETTINGS_SHARDS` and `FLOWX_ELASTICSEARCH_INDEXSETTINGS_REPLICAS` — fewer replicas reduce storage at the cost of redundancy
> 3. Check the `FLOWX_ELASTICSEARCH_INDEXSETTINGS_NAME` data stream for excessive index count
> 4. Don't set audit retention by editing `{FLOWX_ELASTICSEARCH_INDEXSETTINGS_NAME}_policy` in Elasticsearch: the Audit service rewrites that policy on every startup, so the change doesn't last

> [accordion] Audit events delayed
>
> **Symptoms:** Audit entries appear in Elasticsearch with significant delay after the triggering action.
>
> **Solutions:**
>
> 1. Check Kafka consumer lag for the audit consumer group using your Kafka monitoring tools
> 2. Increase `KAFKA_CONSUMER_THREADS` to allow parallel consumption if lag is consistently high
> 3. Verify Elasticsearch cluster health — a degraded cluster slows down indexing
> 4. Check `KAFKA_AUTHEXCEPTIONRETRYINTERVAL` — frequent auth failures with long retry intervals can cause delays

***

## Related resources

> [card] [Audit Log](https://docs.flowx.ai/6.x/docs/platform-deep-dive/core-extensions/audit.md)
>
> Learn about the audit logging system and how to view audit trails

> [card] [Elasticsearch Indexing](https://docs.flowx.ai/6.x/setup-guides/flowx-engine-setup-guide/configuring-elasticsearch-indexing/elasticsearch-indexing.md)
>
> Configure Elasticsearch indexing for process data


## Related topics

- [FlowX.AI Audit](https://docs.flowx.ai/6.x/docs/platform-deep-dive/core-extensions/audit.md)
- [Microservices setup guides](https://docs.flowx.ai/6.x/setup-guides/setup-guides-overview.md)
- [Security](https://docs.flowx.ai/6.x/docs/platform-overview/security.md)
- [Documents plugin setup](https://docs.flowx.ai/6.x/setup-guides/documents-plugin-setup.md)
- [Authorization system setup](https://docs.flowx.ai/6.x/setup-guides/authorization-setup-guide.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.