> 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/monitors-management/creating-a-monitor.md).

# Creating a Monitor

Build a monitor in four steps — what to check, who gets notified, ticketing, and details.

1. Open the asset from **Assets** and go to its **Monitors** tab.
2. Click **New monitor**.

The **New monitor** panel opens beside the list, with a new **Untitled** row marked **NEW** at the top of the list until you save or discard it. The builder has four steps: **Monitor logic**, **Who gets notified**, **Create a ticket** and **Details**. The footer shows which step you are on, for example **Step 1 of 4**. Use **Next** and **Back** to move between steps, **Save** on the last step, and **Discard** to drop the new monitor.

As you work, the **Summary** at the top sums up the monitor in plain words, with its impact, notifications and ticketing. For example: *Monitoring Completeness on COMPANY\_CATEGORY. We will learn the normal range from recent scans and alert when the value becomes unusual.*

{% hint style="info" %}
If you leave the builder with unsaved changes, Telmai asks whether to **Discard changes** or **Keep editing**.
{% endhint %}

## Step 1: Monitor logic

<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 New monitor panel with the Summary and the Monitor logic step: Monitor type, Metric, Attributes, When should we alert? and Advanced" width="560"><figcaption><p>Step 1: Monitor logic.</p></figcaption></figure>

### Monitor type

Choose the **Monitor type**. It can't be changed after the monitor is created.

| Monitor type        | What it checks                                                                                                                                                              |
| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Data quality metric | A ready-made metric managed by the platform, such as completeness or uniqueness. See [Built-in Metrics](/telmai/monitoring-data/user-defined-monitors/built-in-metrics.md). |
| Custom metric       | Your own metric, from an expression or custom SQL. See [User-defined Metrics](/telmai/monitoring-data/user-defined-monitors/user-defined-metrics.md).                       |
| Row quality check   | A rule that runs on every row, tracked as a pass rate. See [Record Validation Rules](/telmai/monitoring-data/user-defined-monitors/record-validation-rules.md).             |
| SQL row check       | Your own SQL that marks each row valid or not, tracked as a pass rate. See [SQL Based Rules](/telmai/monitoring-data/user-defined-monitors/sql-based-rules.md).             |

Some types aren't available for every asset. Hover over a greyed-out type to see why, for example because the asset is file-based or set to scan metadata only.

### What do you want to check?

* **Data quality metric** — choose the **Metric**, grouped into health metrics and PII metrics. For metrics measured per attribute, also choose the **Attributes**.
* **Custom metric** — choose **Expression** or **SQL query**:
  * **Expression** combines attributes with functions, for example ``sum(`salary`)/count(*) group by county``. Up to 250 characters.
  * **SQL query** returns a number in the first column. Use `@now` for the latest scan time. Up to 2,000 characters. Assets that scan metadata only can use SQL query only.
* **Row quality check** — click **Open expression editor** to write the rule in the **Expression editor**. You can start from a rule template, map input variables, add static variables, exclude null values, and **Test** the rule before you **Apply** it.
* **SQL row check** — write SQL that returns **is\_valid** (1 or 0), **record\_id**, and optionally **record\_id\_name**, in that order. When you click **Next**, Telmai checks the SQL against your data before continuing.

### When to alert

For metrics, choose under **When should we alert?**:

| Option                    | Alerts when                                                                                          |
| ------------------------- | ---------------------------------------------------------------------------------------------------- |
| Learn what's normal       | A value falls outside the range seen in recent scans. Telmai learns the range with machine learning. |
| Stay within a % of normal | A value drifts further than the percentage you set. Set **From** and **To**, between −100% and 100%. |
| Stay within fixed limits  | A value goes outside limits you set (**From** and **To**). Ignores scan history.                     |

For row checks, choose under **When is the pass rate unacceptable?**:

| Option                    | Alerts when                                                                                                                                                |
| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Learn what's normal       | The percentage of valid rows is unusually different from recent scans.                                                                                     |
| Allow a percentage change | The pass rate changes more than the percentage you set.                                                                                                    |
| Set pass rate limits      | The pass rate goes outside the limits you set: **Minimum pass rate** (alerts when fewer rows pass) and **Maximum pass rate** (alerts when more rows pass). |

For limits, set at least one bound.

### Advanced

* **History to compare against** — how many recent scans to compare against, from 1 to 20. **Automatic** picks the count for you. Only for **Learn what's normal** and the percentage options.
* **When there's no value** — **Ignore** it, **Replace with Zero**, or **Replace with Average**.

## Step 2: Who gets notified

<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-8e2431e49b4c5de2eea2f97c477772eb547625ae%2Fmonitor-builder-notify-2026-11-04.png?alt=media" alt="The Who gets notified step with the Send notifications switch, the Channels picker and Manage channels" width="560"><figcaption><p>Step 2: Who gets notified.</p></figcaption></figure>

This step is optional. Monitors work without notifications.

1. Turn on **Send notifications**.
2. In **Channels**, type in **Add channels** and choose alert channels. Add as many as you need.

Admins can click **Manage channels** to create a channel without leaving the builder; a new channel is added to the monitor automatically. If no channel exists yet, the switch is disabled until one is created. See [Configuring Notifications](/telmai/monitoring-data/monitors-management/configuring-notifications.md).

## Step 3: Create a ticket

<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-5793f2f40fa988ffdccb2f901ddba3c92af88485%2Fmonitor-builder-ticket-2026-11-04.png?alt=media" alt="The Create a ticket step with the Create tickets automatically switch and the Template field" width="560"><figcaption><p>Step 3: Create a ticket.</p></figcaption></figure>

This step is optional. To create a ticket automatically when the monitor alerts:

1. Turn on the switch in the step's header (**Create tickets automatically**).
2. Choose a ticket **Template**.

Tenant admins can click **Manage templates** to create one. Ticketing needs the [Jira](/telmai/integrations/jira-integration.md) or [ServiceNow](/telmai/integrations/servicenow-integration.md) integration.

## Step 4: Details

<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-20abac1c85aaa55d12c5fbb0d7e24b126723cad1%2Fmonitor-builder-details-2026-11-04.png?alt=media" alt="The Details step with Name, Description, Impact and Tags" width="560"><figcaption><p>Step 4: Details.</p></figcaption></figure>

| Field       | Description                                                                                                                                                                       |
| ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Name        | Required, and unique on the asset. Telmai fills in a name from the metric or type and the asset, such as *Completeness · customer\_accounts*. Change it to something descriptive. |
| Description | Why the monitor matters and what to do when it alerts.                                                                                                                            |
| Tags        | Type a tag and press Enter, or choose one from the list. Tags group incidents on the [Incidents](/telmai/monitoring-data/incident-portal.md) page.                                |
| Impact      | **LOW**, **MEDIUM** or **HIGH**. The default is **LOW**.                                                                                                                          |

Click **Save**. The monitor is created enabled and runs on the asset's next scan.

### Save & Replay

For a **Custom metric** written as a **SQL query** that uses `@now`, the arrow next to **Save** offers **Save & Replay**. It saves the monitor and runs it against up to 20 past scans, so you get a history straight away. See [Replay Scan](/telmai/monitoring-data/user-defined-monitors/replay-scan.md).

## Related

* [Managing Existing Monitors](/telmai/monitoring-data/monitors-management/managing-existing-monitors.md)
* [Monitor Recommendations](/telmai/monitoring-data/monitors-management/monitor-recommendations.md)
* [Configuring Notifications](/telmai/monitoring-data/monitors-management/configuring-notifications.md)
