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

# Monitor

> An always-on evaluation rule for production sessions

## What is a Monitor?

A Monitor is an always-on evaluation rule for a product's production sessions. The Monitor is the rule; the production sessions are the data it watches. Once you create a Monitor, Galtea keeps scoring a sampled fraction of that product's production sessions on its own, with no run to trigger by hand.

Each Monitor watches one [Product](/concepts/product). You can narrow it to a single [Version](/concepts/product/version), or leave the version unset to watch every version of the product. For each production session it decides to score, the Monitor evaluates the session with a set of metric families and records the result.

<Note>A Monitor scores **production** sessions (sessions logged with `is_production=True`). It does not run your test suites and does not create new sessions. See [Monitor Production Responses](/sdk/tutorials/monitor-production-responses-to-user-queries) for how production sessions are logged. Production sessions can also be created by ingesting OpenTelemetry traces; see [Monitor Real User Traffic via OpenTelemetry](/sdk/tutorials/monitor-real-user-traffic-with-opentelemetry).</Note>

## Finding monitors in the dashboard

In the dashboard, open a product, switch to **Production** view mode, then pick **Monitors** in the sidebar, under **Product**. That page lists every monitor for the product. The entry appears only in Production view mode, because monitors watch production sessions; use the Development/Production switch in the sidebar if you do not see it.

From there you can create a monitor, open one to see its results, and edit, pause, resume, or delete it. Each row shows the monitor's status, its recent score, its sampling rate, and its credit spend for the month.

## Seeing production scores across the whole product

A monitor's own page shows the results of that one monitor. To see the trend across every production evaluation of the product, open the product's **Analytics** section in **Production** view mode. It shows an **evaluation scores over time** chart: the average score per day across all production evaluations that match your current filters.

The chart is only in Production view mode, because it is a production-monitoring view. One **Group by** switch at the top of the Analytics page sets how the score charts group their scores: **by specification** (the default: one line per specification, built from the metrics linked to it) or **by metric** (one line per metric). It drives this chart, the selected version's score rings, and the version comparison radar. Your choice is remembered, so the page opens the same way next time. When your metrics have evaluations but none of your specifications does, the page opens grouped by metric instead, because grouping by specification would show nothing there. Development and Production decide this separately, because they hold different evaluations. You can still switch to specification by hand. Every chart shows only the grouping you picked: if nothing has scores under that grouping, the chart says so instead of showing the other grouping's data. The chart follows the same filters as the rest of the page, so changing the version, test, metric, language, or time frame updates it too. It aggregates every matching production evaluation, including ones you triggered by hand, so it is a product-wide trend, not one monitor's view.

## Metric families follow revisions automatically

A Monitor binds **metric families**, not specific metric revisions. A metric family is every revision of a metric that shares the same family key (`metric.metric_group_id` in the SDK). When you revise a metric, the Monitor picks up the new revision automatically. You do not edit the Monitor.

This is why `metric_group_ids` takes family keys, not metric IDs. Read the family key off any metric in the family:

```python theme={"system"}
metric = galtea.metrics.get(metric_id="your-metric-id")
family_key = metric.metric_group_id
```

## Sampling

`sampling_percentage` sets the fraction of production sessions the Monitor scores, from just above `0` up to `100`. It defaults to `10` (10%). Sampling keeps monitoring affordable on high-traffic products: you get a representative signal without scoring every single session.

Changing `sampling_percentage` only affects sessions that close after the change. Raising it does not go back and score older sessions that were already skipped.

## When a session gets scored

A Monitor scores a production session once the session is closed. A session closes either when you explicitly finish it, or when the product's auto-close setting closes it after a period of inactivity. Sessions that end with an error are not scored. There is no per-Monitor inactivity setting: closing is decided by the session's own state, so every Monitor on a product agrees on when a session is ready.

This depends on the product's Auto Close Scope. When that scope excludes production (`None` or `Development`), open production sessions never close on inactivity, so the Monitor scores only the production sessions you explicitly finish.

A closed session can still gain a turn. When it does, the session reopens and the Monitor scores it again once it closes for good. The earlier scores move to the `Outdated` status, so they drop out of charts and averages while staying readable. The product's [Closed Session Inference Creation Policy](/concepts/product#product-properties) controls this.

## Credit cap

`monthly_credit_cap` is an optional ceiling on how many credits the Monitor spends per month:

* **`None` (default)** means the Monitor is uncapped. It scores sampled sessions until the organization runs out of credits.
* **A positive number** caps monthly spend. Only the "greater than zero" rule is enforced. The cap may be larger than the organization's monthly credit allocation; the effective budget is `min(organization balance, cap)`. So the cap protects a single Monitor's spend, and the organization balance is always the hard limit.

## Status

A Monitor has a `status` that tells you whether it is scoring and, if not, why. This makes the reasons a Monitor stopped visible instead of silent:

* **`ACTIVE`** — the Monitor is scoring sampled production sessions. New Monitors start here.
* **`PAUSED`** — a user paused the Monitor. It scores nothing until resumed. Sessions that close while it is paused are skipped for good. After a resume, the Monitor only scores sessions that close from that point on.
* **`CAPPED`** — the monthly credit cap was reached. Sessions that close while it is capped are skipped for good, like `PAUSED`. Scoring resumes next month, or sooner if you raise the cap.
* **`NO_CREDITS`** — the organization ran out of credits. Sessions that close in the meantime are skipped for good. Scoring resumes when credits are available.
* **`FAILING`** — reserved for a Monitor that keeps failing to score sessions. The system does not currently set it automatically.

You can set only `ACTIVE` (to resume) or `PAUSED` (to pause). `CAPPED`, `NO_CREDITS`, and `FAILING` are set by the system and are rejected if you try to set them yourself.

## SDK Integration

The SDK lets you create, list, retrieve, update (including pause and resume), and delete monitors. See the [Monitor Service API documentation](/sdk/api/monitor/service) for more details.

<Card title="Monitor Service" icon="code" iconType="solid" href="/sdk/api/monitor/service">
  Manage monitors programmatically
</Card>

## Monitor Properties

<ResponseField name="id" type="string">
  Unique identifier of the monitor.
</ResponseField>

<ResponseField name="name" type="string" required>
  Name of the monitor.
</ResponseField>

<ResponseField name="product_id" type="string" required>
  The ID of the product whose production sessions this monitor scores.
</ResponseField>

<ResponseField name="version_id" type="string" optional>
  The ID of a single version to watch. When unset, the monitor watches every version of the product.
  Changing it only affects sessions that close after the change; sessions already skipped under the old value are not picked up.
</ResponseField>

<ResponseField name="metric_group_ids" type="list[string]" required>
  The metric family IDs (`metric.metric_group_id`) the monitor scores with. At least one is required.
  The monitor binds the family, not a specific revision, so revising a metric is picked up automatically.
</ResponseField>

<ResponseField name="sampling_percentage" type="number" default="10">
  Percentage of production sessions to score, from just above `0` up to `100`. Defaults to `10` (10%).
</ResponseField>

<ResponseField name="monthly_credit_cap" type="int" optional>
  Maximum credits to spend per month. Must be positive when set. `None` means uncapped.
  The effective budget is `min(organization balance, cap)`, so a cap may exceed the monthly allocation.
</ResponseField>

<ResponseField name="status" type="Enum">
  The lifecycle status of the monitor.
  Possible values: `ACTIVE`, `PAUSED`, `CAPPED`, `NO_CREDITS`, `FAILING`.
  Only `ACTIVE` and `PAUSED` can be set by a user; the rest are system-set.
</ResponseField>

<ResponseField name="created_at" type="string">
  Timestamp of when the monitor was created (ISO 8601 format).
</ResponseField>

## Related

<CardGroup cols={2}>
  <Card title="Concepts overview" icon="diagram-project" iconType="solid" href="/concepts/overview">
    How Galtea's concepts connect — diagram + per-entity quick reference.
  </Card>

  <Card title="Product" icon="box" iconType="solid" href="/concepts/product">
    A functionality or service being evaluated
  </Card>

  <Card title="Metric" icon="gauge" iconType="solid" href="/concepts/metric">
    Ways to evaluate and score product performance
  </Card>
</CardGroup>