docs: add AI Bridge data retention documentation

mafredri · mafredri · commit abc982769fee · 2025-12-02T12:55:36.000Z
Add comprehensive documentation for AI Bridge data retention, addressing the concern raised in PR #21038 that AI Bridge retention should be documented alongside other retention settings. Changes: - docs/ai-coder/ai-bridge/setup.md: Add new Data Retention section with configuration options, duration formats, examples, and what data is retained - docs/ai-coder/ai-bridge/monitoring.md: Add Data Retention section with quick reference and links to detailed documentation - docs/ai-coder/ai-bridge/index.md: Add data retention link to Next steps - docs/admin/setup/data-retention.md: Add AI Bridge to the centralized data retention documentation with settings table, examples, behavior description, and cross-references to AI Bridge docs This improves discoverability by: 1. Documenting retention in the AI Bridge setup page (primary location) 2. Adding retention info to monitoring docs (relevant context) 3. Including AI Bridge in the central data retention page 4. Cross-linking between AI Bridge and admin retention docs Refs #21038
diff --git a/docs/admin/setup/data-retention.md b/docs/admin/setup/data-retention.md
@@ -1,8 +1,9 @@
 # Data Retention
 
 Coder supports configurable retention policies that automatically purge old
-Audit Logs, Connection Logs, Workspace Agent Logs, and API keys. These policies
-help manage database growth by removing records older than a specified duration.
+Audit Logs, Connection Logs, Workspace Agent Logs, API keys, and AI Bridge
+records. These policies help manage database growth by removing records older
+than a specified duration.
 
 ## Overview
 
@@ -32,6 +33,12 @@ a YAML configuration file.
 | Connection Logs      | `--connection-logs-retention`      | `CODER_CONNECTION_LOGS_RETENTION`      | `0` (disabled) | How long to retain Connection Logs      |
 | API Keys             | `--api-keys-retention`             | `CODER_API_KEYS_RETENTION`             | `7d`           | How long to retain expired API keys     |
 | Workspace Agent Logs | `--workspace-agent-logs-retention` | `CODER_WORKSPACE_AGENT_LOGS_RETENTION` | `7d`           | How long to retain workspace agent logs |
+| AI Bridge            | `--aibridge-retention`             | `CODER_AIBRIDGE_RETENTION`             | `60d`          | How long to retain AI Bridge records    |
+
+> [!NOTE]
+> AI Bridge retention is configured separately from other retention settings.
+> See [AI Bridge Setup](../../ai-coder/ai-bridge/setup.md#data-retention) for
+> detailed configuration options.
 
 ### Duration Format
 
@@ -51,7 +58,8 @@ coder server \
   --audit-logs-retention=365d \
   --connection-logs-retention=90d \
   --api-keys-retention=7d \
-  --workspace-agent-logs-retention=7d
+  --workspace-agent-logs-retention=7d \
+  --aibridge-retention=60d
 ```
 
 ### Environment Variables Example
@@ -61,6 +69,7 @@ export CODER_AUDIT_LOGS_RETENTION=365d
 export CODER_CONNECTION_LOGS_RETENTION=90d
 export CODER_API_KEYS_RETENTION=7d
 export CODER_WORKSPACE_AGENT_LOGS_RETENTION=7d
+export CODER_AIBRIDGE_RETENTION=60d
 ```
 
 ### YAML Configuration Example
@@ -71,6 +80,9 @@ retention:
   connection_logs: 90d
   api_keys: 7d
   workspace_agent_logs: 7d
+
+aibridge:
+  retention: 60d
 ```
 
 ## How Retention Works
@@ -116,6 +128,21 @@ For non-latest builds, logs are deleted if the agent hasn't connected within the
 retention period. Setting `--workspace-agent-logs-retention=7d` deletes logs for
 agents that haven't connected in 7 days (excluding those from the latest build).
 
+### AI Bridge Data Behavior
+
+AI Bridge retention applies to interception records and all related data:
+
+- **Interceptions**: Records of each proxied request with timestamps and user
+  attribution.
+- **Token usage**: Input and output token counts for cost tracking.
+- **Prompts**: The last user prompt from each conversation turn.
+- **Tool invocations**: MCP tool calls and their results.
+
+Setting `--aibridge-retention=60d` deletes AI Bridge records older than 60 days.
+The default of 60 days provides a reasonable balance between storage costs and
+the ability to analyze usage patterns. For compliance requirements, consider
+extending this to 90 days or longer.
+
 ## Best Practices
 
 ### Recommended Starting Configuration
@@ -128,6 +155,9 @@ retention:
   connection_logs: 90d
   api_keys: 7d
   workspace_agent_logs: 7d
+
+aibridge:
+  retention: 60d
 ```
 
 ### Compliance Considerations
@@ -171,6 +201,9 @@ retention:
   connection_logs: 0s      # Keep connection logs forever
   api_keys: 0s             # Keep expired API keys forever
   workspace_agent_logs: 0s # Keep workspace agent logs forever
+
+aibridge:
+  retention: 0s            # Keep AI Bridge records forever
 ```
 
 ## Monitoring
@@ -185,3 +218,9 @@ containing the table name (e.g., `audit_logs`, `connection_logs`, `api_keys`).
   purge procedures.
 - [Connection Logs](../monitoring/connection-logs.md): Learn about Connection
   Logs and monitoring.
+- [AI Bridge](../../ai-coder/ai-bridge/index.md): Learn about AI Bridge for
+  centralized LLM and MCP proxy management.
+- [AI Bridge Setup](../../ai-coder/ai-bridge/setup.md#data-retention): Configure
+  AI Bridge data retention.
+- [AI Bridge Monitoring](../../ai-coder/ai-bridge/monitoring.md): Monitor AI
+  Bridge usage and metrics.
diff --git a/docs/ai-coder/ai-bridge/index.md b/docs/ai-coder/ai-bridge/index.md
@@ -36,4 +36,5 @@ AI Bridge is best suited for organizations facing these centralized management a
 - [Configure AI clients](./client-config.md) to use AI Bridge
 - [Configure MCP servers](./mcp.md) for tool access
 - [Monitor usage and metrics](./monitoring.md)
+- [Configure data retention](./setup.md#data-retention) for compliance and storage management
 - [Reference documentation](./reference.md)
diff --git a/docs/ai-coder/ai-bridge/monitoring.md b/docs/ai-coder/ai-bridge/monitoring.md
@@ -9,3 +9,26 @@ AI Bridge records the last `user` prompt, token usage, and every tool invocation
 We provide an example Grafana dashboard that you can import as a starting point for your metrics. See [the Grafana dashboard README](https://github.com/coder/coder/blob/main/examples/monitoring/dashboards/grafana/aibridge/README.md).
 
 These logs and metrics can be used to determine usage patterns, track costs, and evaluate tooling adoption.
+
+## Data Retention
+
+AI Bridge data is retained for **60 days by default**. This includes interceptions,
+token usage, prompts, and tool invocations. You can configure the retention
+period using the `--aibridge-retention` flag or `CODER_AIBRIDGE_RETENTION`
+environment variable.
+
+For example, to retain data for 90 days:
+
+```sh
+coder server --aibridge-retention=90d
+```
+
+Setting retention to `0` keeps data indefinitely, but monitor your database size
+as AI Bridge data can grow significantly with heavy usage.
+
+For detailed configuration options, see:
+
+- [AI Bridge Data Retention](./setup.md#data-retention): Configure retention for
+  AI Bridge.
+- [Data Retention](../../admin/setup/data-retention.md): Overview of all data
+  retention policies in Coder.
diff --git a/docs/ai-coder/ai-bridge/setup.md b/docs/ai-coder/ai-bridge/setup.md
@@ -94,3 +94,85 @@ AI Bridge can relay traffic to other OpenAI- or Anthropic-compatible services or
 
 > [!NOTE]
 > See the [Supported APIs](./reference.md#supported-apis) section below for precise endpoint coverage and interception behavior.
+
+## Data Retention
+
+AI Bridge records prompts, token usage, and tool invocations for auditing and
+monitoring purposes. By default, this data is retained for 60 days. You can
+configure the retention period to meet your organization's compliance and
+storage requirements.
+
+### Configuration
+
+Configure retention using a CLI flag, environment variable, or YAML:
+
+| Setting        | CLI Flag               | Environment Variable       | Default | Description                          |
+|----------------|------------------------|----------------------------|---------|--------------------------------------|
+| AI Bridge Data | `--aibridge-retention` | `CODER_AIBRIDGE_RETENTION` | `60d`   | How long to retain AI Bridge records |
+
+### Duration Format
+
+Retention durations support days (`d`) and weeks (`w`) in addition to standard
+Go duration units (`h`, `m`, `s`):
+
+- `7d` - 7 days
+- `2w` - 2 weeks
+- `30d` - 30 days
+- `90d` - 90 days (recommended for compliance)
+- `365d` - 1 year
+
+### CLI Example
+
+```sh
+coder server \
+  --aibridge-enabled=true \
+  --aibridge-retention=90d
+```
+
+### Environment Variables Example
+
+```sh
+export CODER_AIBRIDGE_ENABLED=true
+export CODER_AIBRIDGE_RETENTION=90d
+```
+
+### YAML Configuration Example
+
+```yaml
+aibridge:
+  enabled: true
+  retention: 90d
+```
+
+### What Data is Retained
+
+AI Bridge retention applies to:
+
+- **Interceptions**: Records of each proxied request, including timestamps and
+  user attribution.
+- **Token usage**: Input and output token counts for cost tracking.
+- **Prompts**: The last user prompt from each conversation turn.
+- **Tool invocations**: MCP tool calls and their results.
+
+### Keeping Data Indefinitely
+
+To retain AI Bridge data indefinitely, set retention to `0`:
+
+```sh
+coder server --aibridge-retention=0
+```
+
+> [!WARNING]
+> Disabling retention can lead to significant database growth over time.
+> Monitor your database size and consider using
+> [external log aggregation](../../admin/setup/data-retention.md#external-log-aggregation)
+> for long-term storage.
+
+### How Retention Works
+
+Coder runs a background purge process approximately every 10 minutes that
+deletes AI Bridge records older than the configured retention period. The
+process runs in batches to avoid database lock contention.
+
+For more details on data retention across all Coder features, see the
+[Data Retention](../../admin/setup/data-retention.md) documentation.
