> ## 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**

<Info>
  **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.
</Info>

***

## 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**](./setup-guides-overview#kafka)
* [**Authorization & access roles**](./setup-guides-overview#authorization--access-roles)
* [**Elasticsearch**](#configuring-elasticsearch)
* [**Logging**](./setup-guides-overview#logging)

***

## 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` |

<Info>
  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`.
</Info>

#### 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`           |

<Info>
  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.
</Info>

### 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_ALLOW_ORIGIN` | 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](./ingress-configuration).

***

## Troubleshooting

### Common issues

<AccordionGroup>
  <Accordion title="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>

  <Accordion title="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>

  <Accordion title="High storage consumption">
    **Symptoms:** Elasticsearch disk usage grows rapidly or cluster health turns yellow/red.

    **Solutions:**

    1. Review your index lifecycle management (ILM) policies to ensure old audit data is rolled over and deleted on schedule
    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. Consider reducing the retention period for audit logs in your ILM policy
  </Accordion>

  <Accordion title="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
  </Accordion>
</AccordionGroup>

***

## Related resources

<CardGroup cols={2}>
  <Card title="Audit Log" icon="clipboard-check" href="../docs/platform-deep-dive/core-extensions/audit">
    Learn about the audit logging system and how to view audit trails
  </Card>

  <Card title="Elasticsearch Indexing" icon="magnifying-glass" href="./flowx-engine-setup-guide/configuring-elasticsearch-indexing/elasticsearch-indexing">
    Configure Elasticsearch indexing for process data
  </Card>
</CardGroup>