Langfuse
Traces every LLM call so teams can see what ran.
Capability: tracing · Tracing. This is a generic capability: every enabled instance receives the same one-way pushes, so several can be connected side by side.
Configure Langfuse in Atrium → (admins only)
Setup
Atrium provisions Langfuse orgs/projects + memberships for groups by writing to the Langfuse control database directly (self-hosted Langfuse exposes no admin API for this). Point it at that DB.
- Get the Langfuse control-DB connection string. The Postgres URL of your Langfuse instance's database (postgresql://user:pass@host:5432/langfuse). Read-write; used only to converge org/project membership.
- Note the org id. The Langfuse organization id new projects are created under (defaults to "ommax").
- Paste both below. The connection string is stored encrypted (AES-256-GCM).
What you paste back into Atrium
In order, the values the steps above produce:
- Langfuse DB connection string
- Org id
How it works
Atrium provisions Langfuse projects and memberships so each group gets its own trace store without an admin creating it by hand. Unusually for a connector, there is no HTTP API in play: self-hosted Langfuse exposes no admin API for org and membership management, so Atrium writes to the Langfuse control database directly. That is why the only credential is a Postgres connection string.
What Atrium does, and when
| When this happens | Atrium does this |
|---|---|
| A group is wired to tracing | Ensures a Langfuse project exists for it under the configured org id. |
| Group membership changes | Converges the corresponding Langfuse membership rows so the people who can see the traces are the people in the group. |
| Any of the above | Runs as SQL against the control DB through a pooled connection, not as API calls. Langfuse is not notified; it reads its own tables. |
Guarantees and limits
- This connector writes to a database another product owns. Its blast radius is that database, so treat the connection string as a production credential and scope the Postgres role to the Langfuse database alone.
- Tracing is a generic capability: every enabled instance receives the push.
- The connection string is stored encrypted (AES-256-GCM) and never returned to the browser.
- Org id defaults to "ommax" when left blank.
What "Test connection" proves
Opens a single-connection pool against the connection string, runs SELECT 1, and always closes it. A pass proves the database is reachable and the credentials in the URL are accepted. It does not check that the schema is a Langfuse schema or that the org id exists.
Troubleshooting
| Symptom | Cause | Fix |
|---|---|---|
| Test connection times out. | The Langfuse database is not reachable from the Atrium container, which is normal when it sits on a private network. | Expose it to Atrium's network or run Atrium where it can reach it. There is no fallback path; this connector needs direct database access. |
| Test passes, provisioning fails. | The Postgres role authenticates but lacks write permission on the org, project or membership tables. | Grant the role read and write on the Langfuse control tables. |
| Provisioning worked, then broke after a Langfuse upgrade. | A Langfuse release changed the control schema underneath the direct writes. | Expected coupling for a direct-DB connector. Check the Langfuse migration notes before upgrading, and treat schema changes as a compatibility event. |
Required scopes
Grant the credential exactly these scopes; they are the least-privilege set the connector needs:
direct Postgres access to the Langfuse control DB (org/project/membership tables)
Configuration fields
| Field | Type | Required | Notes |
|---|---|---|---|
databaseUrlControl-DB connection string | passwordsecret | yes | Postgres URL of the Langfuse control DB. Maps to LANGFUSE_DATABASE_URL. e.g. postgresql://user:pass@host:5432/langfuse |
orgIdOrg id | text | yes | Langfuse organization id new projects belong to. Maps to LANGFUSE_ORG_ID. e.g. ommax |
Operating notes
- Secret fields are encrypted at rest (AES-256-GCM) and never returned to the client. Editing an instance and leaving a secret field masked keeps the stored value.
- Adding a connector from the marketplace creates a disabled, credential-less instance ("Added, not yet connected"); it does nothing until an admin opens it, pastes credentials, and enables it.
- Use Test connection on the instance page before enabling: it performs a read-only probe with the credentials you entered.
- Connector credentials live in the Atrium database, not in container env vars; changing them here takes effect without a redeploy (within the resolver's 30-second cache).