> ## Documentation Index
> Fetch the complete documentation index at: https://agentheya.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Monitoring

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

<Info>
  **Field reference:** [`monitoring`](/reference/monitoring) · [`langfuse`](/reference/langfuse) — every field, type, default, and tier for this page.
</Info>

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](https://langfuse.com)**. Trace data never leaves your infrastructure — nothing is sent to Langfuse Cloud.

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

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

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

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

```bash theme={null}
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](/manage-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`](https://agentheya.com/api/manage-mcp/schema/langfuse) |

Example:

```json theme={null}
{
  "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](/reference/langfuse).