> For the complete documentation index, see [llms.txt](https://docs.telm.ai/telmai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.telm.ai/telmai/monitoring-data/user-defined-monitors.md).

# User-defined Monitors

The four kinds of monitors you can add to an asset, and what each one checks.

On top of the [built-in monitors](https://docs.telm.ai/telmai/monitoring-data/out-of-box-monitors.md) that every asset gets, you can add your own. A user-defined monitor is attached to one asset and defines:

1. **What to check** — a metric, or a rule that every row should pass.
2. **When to alert** — learned from past scans, a percentage of normal, or fixed limits.
3. **Who to notify** and whether to **create a ticket** — both optional.

To create one, open the asset's **Monitors** tab and click **New monitor**. See [Creating a Monitor](https://docs.telm.ai/telmai/monitoring-data/monitors-management/creating-a-monitor.md).

<figure><img src="https://604868671-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MkO3-a8YVu1iq1jP__S%2Fuploads%2Fgit-blob-8bbdd69639c611075b1f403faa39bfb4f449bd45%2Fmonitor-builder-logic-2026-11-04.png?alt=media" alt="The Monitor logic step of the monitor builder, with Monitor type, Metric, Attributes and the alert options" width="560"><figcaption><p>Choosing what a monitor checks.</p></figcaption></figure>

## Monitor types

| Monitor type                                | What it checks                                    | Tracked as         |
| ------------------------------------------- | ------------------------------------------------- | ------------------ |
| [Data quality metric](#data-quality-metric) | A ready-made metric managed by the platform       | The metric's value |
| [Custom metric](#custom-metric)             | Your own metric, from an expression or custom SQL | The metric's value |
| [Row quality check](#row-quality-check)     | A rule that runs on every row                     | Pass rate          |
| [SQL row check](#sql-row-check)             | Your own SQL that marks each row valid or not     | Pass rate          |

The type can't be changed once the monitor is created. To change it, create a new monitor.

### Data quality metric

Monitor one of the [built-in metrics](https://docs.telm.ai/telmai/monitoring-data/user-defined-monitors/built-in-metrics.md) managed by Telmai, such as record count, completeness, uniqueness or freshness, on the whole table or on chosen attributes.

**Examples:**

* Monitor **Record Count** to make sure a table keeps being loaded.
* Monitor **Uniqueness** on `customer_id`.

### Custom metric

Define your own metric with a [Telmai expression](https://docs.telm.ai/telmai/monitoring-data/user-defined-monitors/user-defined-metrics.md#metric-expressions) or [custom SQL](https://docs.telm.ai/telmai/monitoring-data/user-defined-monitors/user-defined-metrics.md#raw-sql-queries) that runs in your database.

**Use cases:**

* Track business KPIs, such as revenue per region.
* Build calculations and aggregations that the built-in metrics don't cover.

**Example expression:**

```sql
SUM(salary)/COUNT(*)
```

**Example custom SQL:**

```sql
SELECT AVG(emp_salary), emp_region FROM `employee_table` WHERE emp_age > 60 GROUP BY emp_region
```

### Row quality check

Write a rule that each row should pass, and track the share of rows that pass it. Rules are written in Telmai's rule language, for example:

```sql
validate part_date expect is_date
```

See [Record Validation Rules](https://docs.telm.ai/telmai/monitoring-data/user-defined-monitors/record-validation-rules.md).

### SQL row check

Write SQL that runs in your database and returns, for each row, whether it is valid. Use it for rules that need joins or database functions.

```sql
SELECT
    CASE WHEN transaction_amount > 0 THEN 1 ELSE 0 END AS is_valid,
    transaction_id AS record_id
FROM transactions
```

See [SQL Based Rules](https://docs.telm.ai/telmai/monitoring-data/user-defined-monitors/sql-based-rules.md).

Row quality checks and SQL row checks are the asset's **row checks**. Their results appear in [Reports > Row checks](https://docs.telm.ai/telmai/monitoring-data/reports.md#row-checks), and they decide which rows [data binning](https://docs.telm.ai/telmai/monitoring-data/monitors-management/configuring-data-binning.md) sends where.

## When to alert

| Option                    | For        | Alerts when                                                       |
| ------------------------- | ---------- | ----------------------------------------------------------------- |
| Learn what's normal       | All types  | A value falls outside the range Telmai learned from recent scans. |
| Stay within a % of normal | Metrics    | A value drifts further from normal than the percentage you set.   |
| Allow a percentage change | Row checks | The pass rate changes more than the percentage you set.           |
| Stay within fixed limits  | Metrics    | A value goes outside the limits you set.                          |
| Set pass rate limits      | Row checks | The pass rate goes outside the minimum and maximum you set.       |

## Monitor properties

| Property                  | Description                                                         | Required        |
| ------------------------- | ------------------------------------------------------------------- | --------------- |
| Monitor Name              | Unique on the asset. Telmai suggests one.                           | Yes             |
| Monitor Type              | One of the four types above. Can't be changed after creation.       | Yes             |
| Description               | Why the monitor matters and what to do when it alerts.              | Optional        |
| Monitor Tags              | Tags to group and filter monitors and incidents.                    | Optional        |
| Impact                    | **LOW** (the default), **MEDIUM** or **HIGH**.                      | Yes             |
| Metric and Attributes     | For data quality metrics: what to measure, and on which attributes. | Depends on type |
| When to alert             | One of the alert options above.                                     | Yes             |
| Created and Last modified | Who created and last changed the monitor, and when.                 | Automatic       |

## Related

* [Built-in Metrics](https://docs.telm.ai/telmai/monitoring-data/user-defined-monitors/built-in-metrics.md)
* [User-defined Metrics](https://docs.telm.ai/telmai/monitoring-data/user-defined-monitors/user-defined-metrics.md)
* [Record Validation Rules](https://docs.telm.ai/telmai/monitoring-data/user-defined-monitors/record-validation-rules.md)
* [SQL Based Rules](https://docs.telm.ai/telmai/monitoring-data/user-defined-monitors/sql-based-rules.md)
* [Replay Scan](https://docs.telm.ai/telmai/monitoring-data/user-defined-monitors/replay-scan.md)
* [Monitors Management](https://docs.telm.ai/telmai/monitoring-data/monitors-management.md)
* [Incidents](https://docs.telm.ai/telmai/monitoring-data/incident-portal.md)
