DnsMonitor Construct

Learn how to configure DNS monitors with the Checkly CLI.

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)

For additional setup information, see CLI overview.

Basic Example

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

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

General Monitor Settings

Property	Type	Required	Default	Description
name	string	✅	-	Friendly name for your monitor
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

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
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

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",
  },
})

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