Skip to main content
Instead of defining your monitor placement specifications in the SYNQ 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

  1. Install the CLI
  2. Set up an API Client in SYNQ by clicking Add client with the following scopes
  • Edit SQL Tests
  • Edit Automatic Monitors
  • Edit Custom Monitors
  1. Run synq-monitors using the credentials from above

​
Defining monitors in code

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., dbt 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 SYNQ UI

When configuring a monitor, monitored_id is the full table, as represented by SYNQ. You can locate this ID by navigating to a table in the SYNQ 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. title

​
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 SYNQ 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. title