Monitoring

Live health snapshot for the published agent, plus optional Langfuse trace export.

Field reference: monitoring · langfuse — every field, type, default, and tier for this page.

The Monitoring page surfaces a live health snapshot of your agent’s recent traffic and lets you forward every query and tool call to a Langfuse project for deeper traces, evals, and per-subscriber analytics.

Health snapshot

The Health section at the top of the page summarises traffic for a window you pick from the dropdown (1h, 6h, 24h, 72h, 7d). Click the refresh icon to re-fetch.

The four headline cards show:

Card	What it shows
Queries	Total queries in the window, with the number that errored.
Error rate	Percentage of queries that errored (turns yellow above 2%, red above 10%).
Spend	Total USD cost in the window, with total tokens used.
Live eval pass	Pass rate for queries that ran the live-eval scoring, with the success / total count.

Below the cards:

• Queries per hour — a bar chart over the window with errored queries layered in red.
• Top tools called — the most-invoked tools, sized by call count.
• Recent errors — the latest errored queries with timestamp, the access surface (web, API, MCP, etc.), and error message.

Langfuse integration

Every query, generation, and tool call from this agent is captured as a trace in our self-hosted Langfuse. Trace data never leaves your infrastructure — nothing is sent to Langfuse Cloud.

There is nothing to configure. The first time you open this page, the platform creates a Langfuse organization and project dedicated to this agent, mints that project’s API keys, and stores them encrypted. You never see or paste a credential.

Isolation

Each agent gets its own Langfuse project, inside its own Langfuse organization. An agent’s API keys are scoped to its project alone: they cannot read a sibling agent’s traces, and they cannot even list a sibling’s project. Trace tags (like agent:<name>) exist for filtering — they are not an access boundary.

Opening Langfuse

Click Open this agent on Langfuse in the section header. This signs you into the Langfuse UI automatically and drops you on this agent’s project — the real Langfuse interface, with its traces, sessions, dashboards, evals, and playground. Three quick-jump cards link straight to:

• Traces — every query, step, and tool call.
• Sessions — conversations grouped per subscriber.
• Dashboards — Langfuse’s cost, latency, and quality charts.

Only the agent owner can open Langfuse. A Langfuse session acts as the owner, and Langfuse’s open-source build cannot scope a signed-in user below the organization level, so we do not hand that session to collaborators — even ones granted monitoring access.

Settings

The only owner-editable fields are:

• The ON / OFF toggle in the card header — pauses or resumes trace export without tearing down the project.
• Environment (optional) — Langfuse environment tag (e.g. production). Lowercase letters, digits, - and _; cannot start with langfuse.
• Tags (optional, comma-separated) — stamped on every trace for filtering.

Click Save Langfuse settings to persist; the cached Langfuse client is dropped so the next query picks up the change.

Running the stack

Langfuse is part of the project’s docker-compose.yml, under the langfuse profile:

docker compose --profile langfuse up -d

If it isn’t running, the Monitoring page says so instead of provisioning. In production it is bound to loopback and reached through the gateway described in deploy/nginx-langfuse.conf.

Privacy

The system prompt is never sent to Langfuse — only its length in characters. This is hard-wired and not user-configurable. Model, duration, token counts, and tool-call shapes are exported normally.

In practice

Catch a regression fast. Glance at the Error rate card after a config change. If it’s gone yellow (>2%) or red (>10%), check Recent errors for the message and surface, and the Queries per hour chart to see when the spike started — usually right after the change you just made.

Find your cost drivers. The Top tools called panel shows where the agent spends its effort. A tool you expected to be rare dominating the list often means the agent is over-reaching for it — tighten that tool’s description or add a rule. Pair with the Spend card to watch cost per window.

Go deep with Langfuse. When the health snapshot isn’t enough — you need the full reasoning trace of one bad conversation — connect a Langfuse project and jump straight to that query’s trace. Use a separate Langfuse project per agent so traffic stays isolated.

Manage via the Management MCP

Langfuse trace export can be toggled and tagged via the Management MCP — the credentials themselves are auto-provisioned and not editable.

Endpoint	https://manage.agentheya.com/mcp
Tool	config.set
Section	langfuse
Schema (HTTP)	GET /api/manage-mcp/schema/langfuse

Example:

{
  "tool": "config.set",
  "owner_id": "<your owner_id>",
  "agent_id": "<your agent_id>",
  "section": "langfuse",
  "data": { "enabled": true, "environment": "production", "tags": ["prod"] }
}

Only enabled, environment, and tags are editable. The credential fields (public_key, secret_key, host) and the project/organization IDs are auto-provisioned by the platform and cannot be set here — see the langfuse field reference.