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
`intent`	`CheckIntent`	❌	-	Structured guidance for root cause analysis and check repair. See General Monitor Options.
`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

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`

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

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

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

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

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

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

CheckIntent

Describe what your check is intended to verify and the behavior that should be preserved. Checkly uses intent for root cause analysis across all check types. It is separate from description and does not replace executable assertions.

Intent is used for automatic repair only for Browser and Multistep Checks.

The object accepts the following fields:

Field	Type	Required	Description
`goal`	`string`	Yes	The outcome your check should verify. Must contain 1–2,000 characters after trimming.
`constraints`	`CheckIntentConstraint[]`	No	Outcomes and guardrails that refine the goal. Omitted constraints become an empty array.

Each constraint has a required type and statement:

REQUIRED_OUTCOME: an outcome the check must verify.
MUST_PRESERVE: behavior or an assertion that should be preserved when repairing the check.

Each statement must contain 1–1,000 characters after trimming. You can specify at most 20 constraints of each type. The CLI trims leading and trailing whitespace from the goal and statements and rejects unknown fields.For example, configure intent on a Browser Check:

import { BrowserCheck } from "checkly/constructs"

new BrowserCheck("dashboard-intent", {
  name: "Authenticated dashboard",
  code: {
    entrypoint: "./dashboard.spec.ts",
  },
  intent: {
    goal: "Verify that authenticated users can open the dashboard.",
    constraints: [
      {
        type: "REQUIRED_OUTCOME",
        statement: "Authentication succeeds for a valid user.",
      },
      {
        type: "MUST_PRESERVE",
        statement: "Do not remove or weaken the authentication assertion.",
      },
    ],
  },
})

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