> ## 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 and go to its **Monitors** tab. That tab lists every monitor for the product and is the home for all monitor management. It appears only in **Production** view mode, because monitors watch production sessions. Use the view-mode selector at the top of the product page to switch to Production if you do not see it.

From the tab 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.

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

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

## 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.
* **`CAPPED`** — the monthly credit cap was reached. Scoring resumes next month, or sooner if you raise the cap.
* **`NO_CREDITS`** — the organization ran out of credits. Scoring resumes when credits are available.
* **`FAILING`** — the Monitor keeps failing to score sessions and needs attention.

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