diff --git a/content/configuration/ai.md b/content/configuration/ai.md index 7205525a..62aab131 100644 --- a/content/configuration/ai.md +++ b/content/configuration/ai.md @@ -29,3 +29,37 @@ This is useful for compliance requirements where AI features must be completely ::callout{icon="material-symbols:info" color="info"} When `MCP_ENABLED` is set to `false`, the MCP server cannot be enabled through **Settings → AI → Model Context Protocol** in the admin interface, providing system administrators with complete control over AI integration features. See the [MCP Server](/guides/ai/mcp/installation) guide for more information. :: + +## Telemetry + +Send AI Assistant traces to an external observability platform for monitoring usage, performance, and cost. + +| Variable | Description | Default Value | +| -------- | ----------- | ------------- | +| `AI_TELEMETRY_ENABLED` | Enable OpenTelemetry-based tracing for AI Assistant requests. User IDs and Role ID will be included in traces. | `false` | +| `AI_TELEMETRY_PROVIDER` | Telemetry provider to use. Supported values: `langfuse`, `braintrust`. | `langfuse` | +| `AI_TELEMETRY_RECORD_IO` | Include full prompt inputs and response outputs in traces. | `false` | + +::callout{icon="material-symbols:warning" color="warning"} +Enabling `AI_TELEMETRY_RECORD_IO` will send the full content of user messages and AI responses to your telemetry provider. Only enable this if your telemetry provider meets your data privacy requirements. +:: + +### Langfuse + +Set `AI_TELEMETRY_PROVIDER` to `langfuse` (default). + +| Variable | Description | Default Value | +| -------- | ----------- | ------------- | +| `LANGFUSE_SECRET_KEY` | Langfuse secret key. | — | +| `LANGFUSE_PUBLIC_KEY` | Langfuse public key. | — | +| `LANGFUSE_BASE_URL` | Langfuse API base URL. | `https://cloud.langfuse.com` | + +### Braintrust + +Set `AI_TELEMETRY_PROVIDER` to `braintrust`. + +| Variable | Description | Default Value | +| -------- | ----------- | ------------- | +| `BRAINTRUST_API_KEY` | Braintrust API key. | — | +| `BRAINTRUST_PROJECT_NAME` | Braintrust project name for grouping traces. | — | +| `BRAINTRUST_API_URL` | Braintrust API URL. Only needed for self-hosted instances. | — | diff --git a/content/guides/11.ai/1.assistant/1.setup.md b/content/guides/11.ai/1.assistant/1.setup.md index 4839bca1..c76a9469 100644 --- a/content/guides/11.ai/1.assistant/1.setup.md +++ b/content/guides/11.ai/1.assistant/1.setup.md @@ -326,6 +326,46 @@ For details on creating prompts with variables, see [MCP Prompts](/guides/ai/mcp - [Google AI](https://aistudio.google.com/) - Consider self-hosted models via [OpenAI-compatible providers](#openai-compatible-providers) for cost control +## Telemetry + +Directus can send AI Assistant traces to [Langfuse](https://langfuse.com) or [Braintrust](https://braintrust.dev) for observability — monitor usage, latency, token costs, and full request/response content. + +Set the following environment variables to enable telemetry: + +```ini +AI_TELEMETRY_ENABLED=true +AI_TELEMETRY_PROVIDER=langfuse # or braintrust +``` + +### Langfuse + +```ini +AI_TELEMETRY_PROVIDER=langfuse +LANGFUSE_SECRET_KEY=sk-lf-... +LANGFUSE_PUBLIC_KEY=pk-lf-... +LANGFUSE_BASE_URL=https://cloud.langfuse.com # optional, default shown +``` + +![Langfuse trace dashboard showing AI Assistant requests](/img/ai-telemetry-langfuse.png) + +### Braintrust + +```ini +AI_TELEMETRY_PROVIDER=braintrust +BRAINTRUST_API_KEY=sk-... +BRAINTRUST_PROJECT_NAME=my-project # optional +``` + +![Braintrust trace dashboard showing AI Assistant requests](/img/ai-telemetry-braintrust.png) + +Optionally enable `AI_TELEMETRY_RECORD_IO=true` to include full prompt inputs and AI responses in traces. + +::callout{icon="material-symbols:warning" color="warning"} +Enabling `AI_TELEMETRY_RECORD_IO` will send the full content of user messages and AI responses to your telemetry provider. Only enable this if your provider meets your data privacy requirements. +:: + +See the [AI Configuration](/configuration/ai#telemetry) reference for all available variables. + ## Next Steps ::card-group diff --git a/public/img/ai-telemetry-braintrust.png b/public/img/ai-telemetry-braintrust.png new file mode 100644 index 00000000..acf5bea9 Binary files /dev/null and b/public/img/ai-telemetry-braintrust.png differ diff --git a/public/img/ai-telemetry-langfuse.png b/public/img/ai-telemetry-langfuse.png new file mode 100644 index 00000000..50fd9c7a Binary files /dev/null and b/public/img/ai-telemetry-langfuse.png differ