Alerting Monitors — the starting point for creating and managing user-defined monitors.
User-defined monitors are policies that define the expected state or behaviour of your data. When data deviates from these policies, alerts are automatically triggered to notify your team. Monitors help you proactively manage data quality by continuously evaluating metrics, rules, and custom queries against your data assets.
When creating a user-defined monitor, you must attach it to an asset, and define the following components:
1. **Metric:** A quantifiable measure of data health (e.g., row count, null percentage, data freshness).
2. **Threshold:** A predefined value or range that, when exceeded, triggers an alert. Thresholds can be:
1. **Automatic**: ML-based thresholds that analyze historical datapoints to determine dynamic boundaries
2. **Relative**: Percentage-based boundaries that calculate moving averages from historical data
3. **Absolute**: Constant, fixed boundaries
3. **Notification endpoints:** Which endpoints to notify when the monitor is alerting (Optional)
***
## Monitor Types
Telmai supports three primary monitor types, each designed for different data quality scenarios:
1. [Built-in Metric](#built-in-metric)
2. [User-Defined Metric](#user-defined-metric)
3. [Record Validation Rule](#record-validation-rule)
4. [SQL Based Rule](#sql-based-rule)
### Built-in Metric
Monitor [built-in metrics](/telmai/monitoring-data/user-defined-monitors/built-in-metrics.md) managed by the Telmai platform.
**Use cases:**
* Track predefined data quality metrics (row count, null percentage, data freshness, completeness, etc.)
* Monitor standard data health indicators across your datasets
* Leverage out-of-the-box metrics without custom configuration
**Example:**
* Monitor `record_count` to ensure tables are being populated
* Check `freshness` to detect data delays
### User-Defined Metric
Define and monitor custom metrics using [Telmai expressions ](/telmai/monitoring-data/user-defined-monitors/user-defined-metrics.md#metric-expressions)or [push-down custom SQL](/telmai/monitoring-data/user-defined-monitors/user-defined-metrics.md#raw-sql-queries).
**Use cases:**
* Create custom calculations and aggregations
* Monitor business-specific KPIs
* Define complex metric logic using SQL queries
**Example expression:**
```sql
SUM(salary)/COUNT(*)
```
**Example custom SQL:**
```sql
SELECT emp_salary, emp_Region FROM `employee_table` WHERE emp_Age > 60
```
### Record Validation Rule
Define record validation checks and monitor the number of records passing these checks.
**Use cases:**
* Validate individual records against business rules
* Ensure data integrity at the row level
* Check data completeness and correctness across records
* Monitor the percentage of valid records over time
**Example expression:**
```
validate part_date expect is_date
```
The monitor tracks the percentage of records that pass the validation rule, and alerts are triggered when this percentage falls outside acceptable thresholds.
Click [here](/telmai/monitoring-data/user-defined-monitors/record-validation-rules.md) to learn more about using and creating Data Quality rules.
### SQL Based Rule
Define record validation checks and monitor the number of records passing these checks using a pushdown SQL query.
**Use cases:**
* Validate individual records against business rules that joins multiple datasets
* Ensure data integrity at the row level
* Monitor the percentage of valid records over time
**Example query:**
```sql
SELECT
CASE WHEN transaction_amount > 0 THEN 1 ELSE 0 END AS is_valid,
transaction_id AS record_id
FROM transactions
```
The monitor tracks the percentage of records that pass the validation rule, and alerts are triggered when this percentage falls outside acceptable thresholds.
Click [here](/telmai/monitoring-data/user-defined-monitors/sql-based-rules.md) to learn more about using and creating SQL based rules.
***
## Monitor Properties
Each monitor has the following properties:
| Property | Description | Required |
| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | -------------- |
| **Monitor Name** | Must be unique per asset (e.g., "Freshness Monitor" on `sales_data` is different from "Freshness Monitor" on `customer_data`) | Yes |
| **Monitor ID** | System-generated unique identifier | Auto-generated |
| **Monitor Type** | Built-in Metric, User-Defined Metric, Record Validation Rule, or SQL-based rule (cannot be changed after creation) | Yes |
| **Description** | Brief description for additional context | Optional |
| **Monitor Tags** | Tags for organizing and categorizing monitors | Optional |
| **Impact** | Severity level of the monitor (Critical, High, Medium, Low) | Optional |
| **Data Quality Metric** | For Built-in Metrics: the specific metric to monitor | Conditional |
| **Attributes** | For metrics that support scope: specific attributes to monitor | Conditional |
| **Threshold Configuration** | Automatic, Acceptable Drift %, or Acceptable Range | Yes |
| **Creator/Editor** | User who created or last modified the monitor | Auto-tracked |
| **Creation/Update Time** | Timestamp of creation and last update | Auto-tracked |
| **History** | Version history of monitor changes | Auto-tracked |
{% hint style="info" %}
**Note:** Monitor type can not be changed once set. To change the type, you must create a new monitor.
{% endhint %}
## Related Documentation
* [Built-in Metrics](/telmai/monitoring-data/user-defined-monitors/built-in-metrics.md)
* [User-defined Metrics](/telmai/monitoring-data/user-defined-monitors/user-defined-metrics.md)
* [Record Validation Rules](/telmai/monitoring-data/user-defined-monitors/record-validation-rules.md)
* [SQL Based Rules](/telmai/monitoring-data/user-defined-monitors/sql-based-rules.md)
* [Monitors Management](/telmai/monitoring-data/monitors-management.md)
* [Incident Portal](/telmai/monitoring-data/incident-portal.md)
* [Replay Scan](/telmai/monitoring-data/user-defined-monitors/replay-scan.md)
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.telm.ai/telmai/monitoring-data/user-defined-monitors.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.