> ## Documentation Index
> Fetch the complete documentation index at: https://www.checklyhq.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# DnsMonitor Construct

> Learn how to configure DNS monitors with the Checkly CLI.

> [!TIP]
>
> Learn more about DNS Monitors in [the DNS monitor overview](https://www.checklyhq.com/docs/detect/uptime-monitoring/dns-monitors/overview.md).

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](https://www.checklyhq.com/docs/cli/overview.md).

```ts Basic Example theme={null}
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")
    ],
  },
})
```

```ts Advanced Example theme={null}
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**

| 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](#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 |

**General Monitor Settings**

| 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` | ❌ | [`noRetries()`](https://www.checklyhq.com/docs/constructs/retry-strategy#default-retry-strategy) | 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:**

```ts theme={null}
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:**

```ts highlight={3} theme={null}
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:**

```ts highlight={3} theme={null}
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](https://www.checklyhq.com/docs/detect/uptime-monitoring/dns-monitors/configuration.md#json-response-schemas). This allows you to target specific fields using JSON path assertions. The response structure varies by record type. [Learn more about using JSON path](https://www.checklyhq.com/docs/detect/assertions.md#json-responses-with-json-path).

Here are some examples:

* Assert the total response time of the DNS request

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

* Assert the DNS response code

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

* Assert against specific JSON fields in the response.

```ts theme={null}
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](https://www.checklyhq.com/docs/detect/assertions.md).

### 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:**

```ts highlight={2} theme={null}
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:**

```ts highlight={2} theme={null}
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](https://www.checklyhq.com/docs/concepts/locations.md#public-locations) where the DNS Monitor should run from. Multiple locations provide geographic coverage and help detect regional DNS issues.

**Usage:**

```ts highlight={2} theme={null}
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:**

```ts highlight={2} theme={null}
new DnsMonitor("my-monitor", {
  activated: false // Disabled monitor
})
```

**intent** `CheckIntent | null`

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. Left unset, or set to `null`, the check has no intent.

> [!NOTE]
>
> Intent is used for [automatic repair](https://www.checklyhq.com/docs/resolve/automatic-check-repair.md) 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:

```ts theme={null}
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.",
      },
    ],
  },
})
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.