DnsMonitor Construct

Learn more about DNS Monitors in the DNS monitor overview.

Use DNS Monitors to verify that DNS records resolve correctly and to track lookup performance over time.

Prerequisites

Before creating DNS Monitors, ensure you have:

An initialized Checkly CLI project
A domain or hostname you want to monitor
Basic understanding of DNS record types (A, AAAA, CNAME, MX, NS, TXT, SOA, HTTPS)

For additional setup information, see CLI overview.

import { Frequency, DnsAssertionBuilder, DnsMonitor } from "checkly/constructs"

new DnsMonitor("dns-monitor", {
  name: "DNS A Record Monitor",
  description: "Asserts `example.com` A record resolves to the **expected IP**.",
  activated: true,
  maxResponseTime: 1000,
  degradedResponseTime: 500,
  frequency: Frequency.EVERY_5M,
  locations: ["us-east-1", "eu-central-1"],
  request: {
    query: "example.com",
    recordType: "A",
    assertions: [
      DnsAssertionBuilder.jsonAnswer("$.Answer[0].data").equals("93.184.216.34")
    ],
  },
})

import { Frequency, DnsAssertionBuilder, DnsMonitor } from "checkly/constructs"

new DnsMonitor("advanced-dns-monitor", {
  name: "Advanced DNS Monitor",
  description: "Asserts `api.example.com` A record resolves to the **expected IP**.",
  activated: true,
  frequency: Frequency.EVERY_5M,
  locations: ["us-east-1", "eu-central-1"],
  maxResponseTime: 800,
  degradedResponseTime: 400,
  tags: ["dns", "production", "critical"],
  request: {
    query: "api.example.com",
    recordType: "A",
    nameServer: "9.9.9.9",
    port: 53,
    protocol: "UDP",
    assertions: [
      DnsAssertionBuilder.jsonAnswer("$.Answer[0].TTL").greaterThan(300),
      DnsAssertionBuilder.responseTime().lessThan(500),
      DnsAssertionBuilder.jsonAnswer("$.Answer[0].data").equals("93.184.216.34")
    ],
  },
})

Configuration

A DNS Monitor has its own DNS-specific settings, plus the standard monitor options shared across all check types.

DNS Monitor Settings
General Monitor Settings

Parameter	Type	Required	Default	Description
`request`	`object`	✅	-	DNS request configuration object
`degradedResponseTime`	`number`	❌	`500`	Response time threshold in milliseconds for degraded status
`maxResponseTime`	`number`	❌	`1000`	Maximum response time in milliseconds before marking as failed

Property	Type	Required	Default	Description
`name`	`string`	✅	-	Friendly name for your monitor
`description`	`string`	❌	`null`	A description of the monitor. Supports markdown. Max 500 characters
`activated`	`boolean`	❌	`true`	Whether the monitor is enabled
`alertChannels`	`Array<AlertChannel \| AlertChannelRef>`	❌	`[]`	Array of AlertChannel objects for notifications
`alertEscalationPolicy`	`AlertEscalationPolicy`	❌	-	Advanced alert escalation settings
`frequency`	`Frequency`	❌	`EVERY_10M`	How often to run your monitor
`group`	`CheckGroupV1` `CheckGroupV2`	❌	-	The CheckGroup this monitor belongs to
`locations`	`string[]`	❌	`[]`	Array of public location codes
`privateLocations`	`string[]`	❌	`[]`	Array of Private Location slugs
`muted`	`boolean`	❌	`false`	Whether alert notifications are muted
`tags`	`string[]`	❌	`[]`	Array of tags to organize monitors
`testOnly`	`boolean`	❌	`false`	Only run with test, not during deploy
`retryStrategy`	`RetryStrategy`	❌	-	Strategy for configuring retries
`runParallel`	`boolean`	❌	`false`	Run monitors in parallel or round-robin
`triggerIncident`	`IncidentTrigger`	❌	-	Create and resolve an incident based on the check’s alert configuration

`DnsMonitor` Options

request

object

required

DNS request configuration that defines the DNS query to perform and how to validate the response.Usage:

new DnsMonitor("dns-monitor", {
  name: "DNS A Record Monitor",
  request: {
    query: "example.com",
    recordType: "A",
    assertions: [
      DnsAssertionBuilder.jsonAnswer("$.Answer[0].data").equals("93.184.216.34")
    ]
  }
})

Parameters:

Parameter	Type	Required	Default	Description
`query`	`string`	✅	-	The DNS query (domain name or IP address)
`recordType`	`DnsRecordType`	✅	-	DNS record type: A, AAAA, CNAME, MX, NS, TXT, SOA, HTTPS
`nameServer`	`string`	❌	-	Custom DNS server to query (e.g. “9.9.9.9”)
`port`	`number`	❌	`53`	Port of the DNS server
`protocol`	`DnsProtocol`	❌	`UDP`	Protocol to use: UDP or TCP
`assertions`	`DnsAssertion[]`	❌	`[]`	Response assertions using `DnsAssertionBuilder`

degradedResponseTime

number

default:"500"

Response time threshold in milliseconds for marking the DNS Monitor as degraded (warning state).Usage:

new DnsMonitor("dns-performance-tiers", {
  name: "DNS Performance Tiers",
  degradedResponseTime: 300, // Warn at 300ms
  request: {
    query: "example.com",
    recordType: "A",
    assertions: [
      DnsAssertionBuilder.jsonAnswer("$.Answer[0].data").equals("93.184.216.34")
    ],
  },
})

maxResponseTime

number

default:"1000"

Maximum response time in milliseconds before the DNS Monitor is marked as failed.Usage:

new DnsMonitor("fast-dns", {
  name: "Fast DNS Resolution",
  maxResponseTime: 500, // Fail at 500ms
  request: {
    query: "fast.example.com",
    recordType: "A",
  },
})

`DnsMonitor` Assertions

To define assertions for the request of an DnsMonitor you should use the DnsAssertionBuilder. The following sources are available for DNS monitor assertions:

responseTime(): Assert the total response time of the DNS request in milliseconds. Use this to set thresholds for failed lookups
responseCode(): By default, DNS monitors pass when the return code is NOERROR and fail on error codes (FORMERR, SERVFAIL, NXDOMAIN, etc.). You can override this behavior by defining a custom return code assertion
textAnswer(): The raw DNS response as plain text. Use this to check for specific strings in the response
jsonAnswer(property?): The DNS response in JSON format. This allows you to target specific fields using JSON path assertions. The response structure varies by record type. Learn more about using JSON path.

Here are some examples:

Assert the total response time of the DNS request

DnsAssertionBuilder.responseTime().lessThan(1000)
// Equivalent to:
{ source: 'RESPONSE_TIME', comparison: 'LESS_THAN', target: '1000' }

Assert the DNS response code

DnsAssertionBuilder.responseCode().equals('NOERROR')
// Equivalent to:
{ source: 'RESPONSE_CODE', comparison: 'EQUALS', target: 'NOERROR' }

Assert against specific JSON fields in the response.

DnsAssertionBuilder.jsonAnswer('$.Answer.length').equals(4)
// Equivalent to:
{ source: 'JSON_ANSWER', property: '$.Answer.length', comparison: 'EQUALS', target: '4' }

Learn more in our docs on Assertions.

General Monitor Options

name

string

required

Friendly name for your DNS Monitor that will be displayed in the Checkly dashboard and used in notifications.Usage:

new DnsMonitor("my-monitor", {
  name: "DNS Resolution Monitor",
  /* More options ... */
})

frequency

Frequency

How often the DNS Monitor should run. Use the Frequency enum to set the check interval.Usage:

new DnsMonitor("my-monitor", {
  frequency: Frequency.EVERY_1M,
  /* More options ... */
})

Available frequencies: EVERY_10S, EVERY_20S, EVERY_30S, EVERY_1M, EVERY_2M, EVERY_5M, EVERY_10M, EVERY_15M, EVERY_30M, EVERY_1H, EVERY_2H, EVERY_3H, EVERY_6H, EVERY_12H, EVERY_24H

locations

string[]

default:"[]"

Array of public location codes where the DNS Monitor should run from. Multiple locations provide geographic coverage and help detect regional DNS issues.Usage:

new DnsMonitor("global-dns-monitor", {
  locations: ["us-east-1", "eu-central-1", "ap-southeast-1"]
})

activated

boolean

default:"true"

Whether the DNS Monitor is enabled and will run according to its schedule.Usage:

new DnsMonitor("my-monitor", {
  activated: false // Disabled monitor
})

Getting Started

DETECT

COMMUNICATE

Project & Configuration

Platform

Configuration

`DnsMonitor` Options

`DnsMonitor` Assertions

General Monitor Options

​Configuration

​DnsMonitor Options

​DnsMonitor Assertions

​General Monitor Options

Configuration

`DnsMonitor` Options

`DnsMonitor` Assertions

General Monitor Options