Metric Monitor

string · required

Displayed in the Monte Carlo UI and in incident notifications. Max 512 characters.

description: Alert on unexpected row count changes in the orders table

object · required

Provide either table or sql, not both.

data_source:
  table: analytics:core.fct_orders

Properties

table — fully qualified table name

string · optional · one of table or sql required

Format: database:schema.table. Mutually exclusive with sql.

data_source:
  table: analytics:core.fct_orders

sql — custom SQL query

string · optional · one of table or sql required

Custom SQL query that returns the dataset to monitor. Mutually exclusive with table. Not compatible with use_partition_clause.

data_source:
  sql: "SELECT * FROM analytics.core.fct_orders WHERE region = 'NA'"

transforms — AI-powered field transforms

array of objects · optional

AI-powered field transforms applied to the data source before metric computation.

data_source:
  table: analytics:core.fct_orders
  transforms:
    - function: classification
      field: description
      alias: description_category
      categories:
        - label: electronics
          description: Electronic devices
        - label: clothing
          description: Apparel items

array of objects · required

Each entry defines a metric to track and the condition that triggers an alert. Provide either metric (built-in) or custom_metric, not both. Multiple conditions are allowed. Supported alert condition types: threshold (default), noop.

Available operators: AUTO · AUTO_HIGH · AUTO_LOW · GT · GTE · LT · LTE · EQ · NEQ · INSIDE_RANGE · OUTSIDE_RANGE · NOOP

Threshold types:

• Static — fixed numeric value via threshold_value with an explicit operator (GT, LT, etc.).
• Range — lower_threshold and upper_threshold with INSIDE_RANGE or OUTSIDE_RANGE.
• Anomaly detection (AUTO) — ML-based. AUTO catches both high and low deviations. AUTO_HIGH/AUTO_LOW catch one-sided deviations. Control aggressiveness with the monitor-level sensitivity field.

🚧

Pipeline metric operator restriction

Pipeline metrics (ROW_COUNT_CHANGE, TIME_SINCE_LAST_ROW_COUNT_CHANGE, RELATIVE_ROW_COUNT) only support AUTO. Using explicit operators (GT, LT, etc.) on these metrics produces an error.

alert_conditions:
  - metric: ROW_COUNT_CHANGE
    operator: AUTO
  - metric: NULL_RATE
    operator: GT
    threshold_value: 0.05
    fields:
      - EMAIL

Properties

metric — built-in metric name

string · optional · one of metric or custom_metric required

Built-in metric name (e.g., ROW_COUNT_CHANGE, NULL_RATE, NUMERIC_MEAN). See Available Metrics. Mutually exclusive with custom_metric.

alert_conditions:
  - metric: NULL_RATE

custom_metric — custom SQL-based metric

object · optional · one of metric or custom_metric required

Mutually exclusive with metric.

alert_conditions:
  - custom_metric:
      display_name: Average Order Value
      sql_expression: "AVG(order_total)"
    operator: AUTO

fields — columns to compute the metric on

array of strings · optional · required for field-level metrics like NULL_COUNT

Not allowed for table-level metrics (e.g., ROW_COUNT_CHANGE).

alert_conditions:
  - metric: NULL_RATE
    fields:
      - EMAIL
      - PHONE_NUMBER

field_pattern — pattern-based field selection

object · optional

Selects fields dynamically by name pattern instead of listing them explicitly. Use instead of fields when column names follow conventions.

alert_conditions:
  - metric: NULL_RATE
    operator: GT
    threshold_value: 0.01
    field_pattern:
      operator: ENDING_WITH
      value: _id
      field_type: NUMERIC

operator — comparison operator

enum · optional
Accepted values: AUTO · AUTO_HIGH · AUTO_LOW · GT · GTE · LT · LTE · EQ · NEQ · INSIDE_RANGE · OUTSIDE_RANGE · NOOP

AUTO uses ML anomaly detection (both high and low deviations). AUTO_HIGH/AUTO_LOW detect one-sided deviations. NOOP collects data without alerting. Explicit operators (GT, LT, etc.) require threshold_value. INSIDE_RANGE/OUTSIDE_RANGE require lower_threshold and upper_threshold.

alert_conditions:
  - metric: NULL_RATE
    operator: GT
    threshold_value: 0.05

threshold_value — static threshold for comparison

number · optional · required when using explicit operators like GT, LT, etc.

Ignored when operator is AUTO, AUTO_HIGH, or AUTO_LOW.

alert_conditions:
  - metric: NUMERIC_MEAN
    operator: LT
    threshold_value: 100

lower_threshold — lower bound for range operators

number · optional · required for INSIDE_RANGE / OUTSIDE_RANGE

Used with INSIDE_RANGE or OUTSIDE_RANGE operators.

alert_conditions:
  - metric: NUMERIC_MEAN
    operator: OUTSIDE_RANGE
    lower_threshold: 10
    upper_threshold: 1000

upper_threshold — upper bound for range operators

number · optional · required for INSIDE_RANGE / OUTSIDE_RANGE

Used with INSIDE_RANGE or OUTSIDE_RANGE operators.

alert_conditions:
  - metric: NUMERIC_MEAN
    operator: INSIDE_RANGE
    lower_threshold: 0
    upper_threshold: 100

type — alert condition type

string · optional · default: threshold
Accepted values: threshold · noop

Use noop to collect data without alerting. When type: noop, you must set operator: NOOP — the CLI rejects a noop condition with no operator.

alert_conditions:
  - metric: NULL_RATE
    type: noop
    operator: NOOP

baseline_trailing_days — trailing days for ML baseline

integer · optional

Number of trailing days for the ML baseline window. Used with drift metrics like PSI, KS_TEST, JS_DIVERGENCE. Minimum: 1.

alert_conditions:
  - metric: PSI
    operator: AUTO
    baseline_trailing_days: 30

baseline_start / baseline_end — fixed baseline period

string (ISO 8601 datetime) · optional

Fixed start and end of the baseline period. Used with drift/cardinality metrics. Must be a full ISO 8601 datetime (YYYY-MM-DDThh:mm:ss) — a date-only value like "2025-01-01" is rejected with "Not a valid datetime."

alert_conditions:
  - metric: KS_TEST
    operator: AUTO
    baseline_start: "2025-01-01T00:00:00"
    baseline_end: "2025-03-31T00:00:00"

num_bins — histogram bins for drift metrics

integer · optional

Number of histogram bins for drift metrics (PSI, KS_TEST, JS_DIVERGENCE). Range: 2--1000.

alert_conditions:
  - metric: PSI
    operator: AUTO
    num_bins: 50

id — stable identifier for this alert condition

string · optional

Preserved across updates.

alert_conditions:
  - metric: NULL_RATE
    id: null-rate-email

object · optional · default: system-managed schedule

Controls when the monitor runs. Supported modes: fixed, dynamic, manual. Crontab (interval_crontab) is not supported — use interval_minutes instead. Minimum interval_minutes is 60.

When using aggregate_by, interval_minutes must be a multiple of the bucket size:

Omitting schedule means Monte Carlo runs the monitor on the default collection cycle (typically every 6--12 hours depending on table activity and your plan).

schedule:
  type: fixed
  interval_minutes: 1440

Properties

type — schedule type

enum · optional · default: fixed
Accepted values: fixed · dynamic · manual

schedule:
  type: dynamic

interval_minutes — run interval for fixed schedules

integer · optional

Must align with aggregate_by (e.g., daily aggregation requires a multiple of 1440). Minimum: 60.

schedule:
  type: fixed
  interval_minutes: 1440

interval_crontab — crontab schedule

array of strings · optional

Not supported for metric monitors. Use interval_minutes instead. Custom SQL and validation monitors support crontab.

start_time — schedule start time

string · optional

ISO 8601 format.

schedule:
  type: fixed
  interval_minutes: 1440
  start_time: "2025-01-01T06:00:00Z"

timezone — schedule timezone

string · optional

Timezone identifier (e.g., America/New_York).

schedule:
  type: fixed
  interval_minutes: 1440
  timezone: America/New_York

dynamic_schedule_tables — tables that trigger this monitor

array of strings · optional

Tables whose update events trigger this monitor (for dynamic schedules).

schedule:
  type: dynamic
  dynamic_schedule_tables:
    - analytics:core.fct_orders

dynamic_schedule_jobs — jobs that trigger this monitor

array of objects · optional

Jobs whose completion triggers this monitor (for dynamic schedules).

schedule:
  type: dynamic
  dynamic_schedule_jobs:
    - job_type: DbtJob
      job_name: daily_build
      project_name: analytics

min_interval_minutes — minimum interval between dynamic runs

integer · optional

Minimum interval between runs for dynamic schedules.

schedule:
  type: dynamic
  dynamic_schedule_tables:
    - analytics:core.fct_orders
  min_interval_minutes: 60

string · optional

Timestamp or date column used to bucket data by time. Omit for whole-table scans on each run. A DATE column limits you to daily (or coarser) aggregation; aggregate_by: hour on a DATE column produces meaningless buckets.

aggregate_time_field: created_at

string · optional

SQL expression that evaluates to a timestamp, used instead of aggregate_time_field when the time column needs transformation (e.g., epoch to timestamp).

aggregate_time_sql: "TO_TIMESTAMP(epoch_seconds)"

enum · optional
Accepted values: hour · day · week · month

Must align with schedule.interval_minutes (e.g., daily requires a multiple of 1440, hourly requires a multiple of 60).

aggregate_by: day

string · optional

Timezone identifier (e.g., America/New_York).

aggregate_timezone: America/New_York

integer · optional · default: 0

Number of hours to offset from the current period to account for late-arriving data (e.g., 24 for daily, 1 for hourly). Negative values are allowed to include one future time bucket (e.g., -24 for daily aggregation). Only valid when aggregate_by is set.

collection_lag: 2

string · optional

SQL WHERE clause (without the WHERE keyword) to filter rows before metric computation.

where_condition: "status != 'deleted'"

boolean · optional · default: false

Use the table's partition clause for efficient querying. Not allowed when data_source.sql is used.

use_partition_clause: true

array of strings · optional · default: []

Each unique combination of values creates a separate time series. Maximum 5 segment fields. Use segment_sql when you need to bucket or transform values.

segment_fields:
  - region
  - product_category

array of strings · optional · default: []

SQL expressions for segmentation when column names alone are insufficient. Use instead of segment_fields when you need to bucket or transform values.

segment_sql:
  - "CASE WHEN country IN ('US','CA','MX') THEN 'NA' ELSE 'INTL' END"

boolean · optional · default: false

Enable support for high-cardinality segmentation (more than the default segment limit).

high_segment_count: true

enum · optional
Accepted values: low · medium · high

Controls how aggressively AUTO thresholds flag anomalies.

sensitivity: medium

array of strings (exactly one entry) · required on all accounts created after January 2025

Set default_domain in montecarlo.yml to avoid repeating it on every monitor.

domains:
  - my-domain

object · optional

sampling_config:
  percentage: 10

Properties

percentage — percentage of rows to sample

number · optional

Percentage of rows to sample (0--100).

sampling_config:
  percentage: 25

count — fixed number of rows to sample

integer · optional

sampling_config:
  count: 10000

string · required

Required for monitors created after Jan 29, 2024 (existing monitors keep working). Changing the name creates a new monitor and deletes the old one — incident history does not transfer.

name: orders_row_count

string · optional · required if multiple warehouses

Warehouse UUID or name. Overrides default_resource from montecarlo.yml.

warehouse: my-snowflake

string · optional

Overrides the default connection.

connection_name: snowflake-analytics

integer · optional

Query execution timeout in seconds.

timeout: 300

array of objects · optional

tags:
  - name: team
    value: analytics
  - name: environment
    value: production

enum · optional
Accepted values: P1 · P2 · P3 · P4 · P5

priority: P2

array of strings · optional

Audience names linking this monitor to channels defined in Notifications as Code. In exported/rendered YAML, appears as labels.

audiences:
  - data-engineering
  - platform-alerts

array of strings · optional

Separate audiences for run-failure notifications. Falls back to audiences if not set.

failure_audiences:
  - data-engineering-oncall

enum · optional
Accepted values: ACCURACY · COMPLETENESS · CONSISTENCY · TIMELINESS · UNIQUENESS · VALIDITY

data_quality_dimension: COMPLETENESS

string · optional

Visible in the Monte Carlo UI. Not included in notifications.

notes: Owned by the analytics team. Reviewed quarterly.

boolean · optional · default: false

Creates the monitor in a paused state. Omitting this on a later update resets to false (active) due to PUT semantics — always include it if you want the monitor to stay in draft.

is_draft: true

string · optional

Include the UUID of an existing monitor to update it instead of creating a new one.

uuid: 0dae7702-0950-45c7-909c-7e183bddca19