Defining monitors in code

Instead of defining your monitor placement specifications in the UI, you can also provide a YML file to specify where to place monitors programmatically. This is beneficial if you prefer to manage monitor placement through code, e.g., enforce it through your CI/CD development process.

Getting started

Install the CLI
Set up an API Client by clicking Add client with the following scopes

Edit SQL Tests
Edit Automatic Monitors
Edit Custom Monitors

Run synq-monitors using the credentials from above

Create a YAML file where you’ll be managing the monitor setup, for example, synq_monitors.yml. You can split your configuration up into multiple files and use namespaces to manage individual domains or data products independently.

Using NamespacesMonitors in one namespace are isolated from those in another, which helps you:

Avoid conflicts when multiple teams manage monitors in parallel.
Keep different pipelines or environments separate (e.g., transformation models in CI vs. external tables in prod).
Apply ownership, defaults, and alerts consistently within a group.

You can define a namespace at the top of your YAML file, or override it inside individual monitor definitions when needed.

Example content of the file

namespace: "data-team-pipeline"

defaults:
  severity: ERROR

monitors:
  - name: freshness_on_orders
    time_partitioning: created_at
    type: freshness
    expression: "created_at"
    monitored_ids:
      - orders_table_eu
      - orders_table_us

  - name: volume_on_logs
    time_partitioning: at
    type: volume
    monitored_id: log_table
    segmentation: "country"
    filter: "country IN ('US', 'CA')"

  - name: stats_on_user_fields
    type: field_stats
    time_partitioning: registered_at
    fields:
      - age
      - signup_method
    monitored_id: users_table
    mode:
      anomaly_engine:
        sensitivity: BALANCED
    schedule:
      daily: 0

  - name: custom_numeric_active_users
    time_partitioning: registered_at
    type: custom_numeric
    metric_aggregation: "COUNT(DISTINCT user_id)"
    monitored_ids:
      - active_users_table
    mode:
      fixed_thresholds:
        min: 100
        max: 10000
    schedule:
      hourly: 15

Configuring a monitor

You can define all custom monitor types as code (freshness, volume, custom_numeric, and field_stats). Read more about each monitor type.

Obtaining IDs from the UI

When configuring a monitor, monitored_id is the full table identifier as represented in the platform. You can locate this ID by navigating to a table in the UI (using the catalog or search functionality) and copying the ID from the URL. In the example below, bq-synq-demo::nyc_taxi::financial_statement will be the ID.

Understanding the configurable parameters

You can see all the configurable parameters in the Available YAML Fields in the readme. For more examples of configuring individual monitors, see our Examples repo.

Verifying monitors in the UI

If you navigate to the Settings menu for a monitor, you can verify that it’s created by code by seeing the Monitor was created via API and can't be managed in APP label.

Muting monitors SQL Tests

Get Started

Alerts

Monitors

Monitors Types

Data Products

Scout AI

Ownership

Incidents

Analytics

Lineage

BI Integrations

Data Warehouse Integrations

Transactional databases

Code Integrations

dbt Integrations

SQLMesh Integrations

Coalesce Integrations

Orchestration Tool Integrations

Alerting Integrations

Catalogs

Google Cloud Integrations

Admin

Security

Support

Developer API

Defining monitors in code

Getting started