Skip to main content
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.
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)
For additional setup information, see CLI overview.
import { Frequency, DnsAssertionBuilder, DnsMonitor } from "checkly/constructs"

new DnsMonitor("dns-monitor", {
  name: "DNS A Record Monitor",
  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")
    ],
  },
})

​
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
ParameterTypeRequiredDefaultDescription
requestobject✅-DNS request configuration object
degradedResponseTimenumber❌500Response time threshold in milliseconds for degraded status
maxResponseTimenumber❌1000Maximum response time in milliseconds before marking as failed

​
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:
ParameterTypeRequiredDefaultDescription
querystring✅-The DNS query (domain name or IP address)
recordTypeDnsRecordType✅-DNS record type: A, AAAA, CNAME, MX, NS, TXT, SOA
nameServerstring❌-Custom DNS server to query (e.g. “9.9.9.9”)
portnumber❌53Port of the DNS server
protocolDnsProtocol❌UDPProtocol to use: UDP or TCP
assertionsDnsAssertion[]❌[]Response assertions using DnsAssertionBuilder
Define assertions using the DnsAssertionBuilder to validate DNS responses:
DnsAssertionBuilder.responseTime().lessThan(1000)
DnsAssertionBuilder.textAnswer().contains("192.168.1.1")
DnsAssertionBuilder.jsonAnswer("$.Answer[0].data").equals("93.184.216.34")
Learn more in Assertions.
​
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",
  },
})

​
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
})