diff --git a/api-reference/openapi.json b/api-reference/openapi.json index d9e3fe5..92612bf 100644 --- a/api-reference/openapi.json +++ b/api-reference/openapi.json @@ -5335,7 +5335,7 @@ This endpoint will return data within a 6-hour timeframe. If the `from` and `to` "schema": { "type": "string", "format": "date", - "default": "2025-10-13T10:55:35.647Z" + "default": "2025-10-14T02:33:35.308Z" } }, { @@ -5345,7 +5345,7 @@ This endpoint will return data within a 6-hour timeframe. If the `from` and `to` "schema": { "type": "string", "format": "date", - "default": "2025-10-14T10:55:35.647Z" + "default": "2025-10-15T02:33:35.309Z" } } ], @@ -5441,7 +5441,7 @@ This endpoint will return data within a 6-hour timeframe. If the `from` and `to` "schema": { "type": "string", "format": "date", - "default": "2025-10-13T10:55:35.650Z" + "default": "2025-10-14T02:33:35.312Z" } }, { @@ -5451,7 +5451,7 @@ This endpoint will return data within a 6-hour timeframe. If the `from` and `to` "schema": { "type": "string", "format": "date", - "default": "2025-10-14T10:55:35.650Z" + "default": "2025-10-15T02:33:35.312Z" } }, { @@ -27733,7 +27733,7 @@ For example, set **Authorization** header while using cURL: `curl -H \"Authoriza "publicIncidentUpdateDate": { "type": "string", "format": "date-time", - "default": "2025-10-14T10:55:36.513Z" + "default": "2025-10-15T02:33:36.303Z" }, "notifySubscribers": { "type": "boolean", @@ -28223,7 +28223,7 @@ For example, set **Authorization** header while using cURL: `curl -H \"Authoriza "publicIncidentUpdateDate": { "type": "string", "format": "date-time", - "default": "2025-10-14T10:55:36.573Z" + "default": "2025-10-15T02:33:36.370Z" }, "created_at": { "type": "string", diff --git a/detect/uptime-monitoring/dns-monitors/configuration.mdx b/detect/uptime-monitoring/dns-monitors/configuration.mdx new file mode 100644 index 0000000..8e22204 --- /dev/null +++ b/detect/uptime-monitoring/dns-monitors/configuration.mdx @@ -0,0 +1,389 @@ +--- +title: 'DNS Monitor Configuration' +description: 'Configure your DNS monitor to verify record resolution.' +sidebarTitle: 'Configuration' +--- + +{/* +To configure a DNS monitor using code, learn more about the [DNS Monitor Construct](/constructs/dns-monitor). + */} + +### Basic Setup + +Specify the domain and record type you want to check: + + + DNS monitor setup interface showing domain, record type, dns server and protocol + DNS monitor setup interface showing domain, record type, dns server and protocol + + +* **Domain:** The domain you want to monitor (e.g. `checklyhq.com`) +* **Record type:** The DNS record to query. See [supported record types](/detect/uptime-monitoring/dns-monitors/overview#supported-dns-record-types) for the full list. +* **DNS server:** Queries use 8.8.8.8 (Google DNS) by default with automatic failover to 1.1.1.1 (Cloudflare) and an internal AWS resolver on errors. You can specify a custom nameserver and port (e.g., `1.1.1.1:53` or `dns.google:53`) to test resolver-specific behavior +* **Protocol:** You can pin DNS queries to UDP-only or TCP-only. + +### Assertions + +Assertions let you define what the expected result of a DNS query should be. + +The raw and JSON responses are shown on the results page of a DNS monitor run and can be used as a reference when defining assertions. + + + DNS monitor assertions and corresponding data fields + DNS monitor assertions and corresponding data fields + + +* **Response time:** The lookup time in milliseconds. Use this to set thresholds for failed lookups + +* **Return code:** 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 + +* **Text response:** The raw DNS response as plain text. Use this to check for specific strings in the response + +* **JSON response:** The DNS response parsed as JSON. This allows you to target specific fields using JSON path assertions. The response structure varies by record type. See [JSON response schemas](#json-response-schemas) below for all supported record types. + +With JSON path assertions, you can: + +* `$.Answer.length` → verify the number of records returned +* `$.Answer[0].TTL` → validate TTL values are within expected ranges +* `$.Answer[0].data` → check specific IP addresses or record values +* `$.Status` → verify the DNS response status code + +Learn more about JSON path assertions: [JSON responses with JSON path](/detect/synthetic-monitoring/api-checks/assertions/#json-responses-with-json-path). + +### JSON Response Schemas + +The DNS response is parsed into a structured JSON format. All responses share a common structure: + +```json +{ + "Answer": [ + // Array of answer records + ], + "Question": [ + { + "name": "example.com.", + "type": "A" + } + ], + "Status": "NOERROR", + "TC": false, + "RD": true, + "RA": true, + "AD": false, + "CD": false +} +``` + +**Key fields**: +- `Answer` - Array of DNS records returned +- `Question` - The DNS query that was made +- `Status` - Response status (NOERROR, NXDOMAIN, SERVFAIL, etc.) +- `TC` - Truncated flag +- `RD` - Recursion desired flag +- `RA` - Recursion available flag +- `AD` - Authenticated data flag +- `CD` - Checking disabled flag + + +```json +{ + "Answer": [ + { + "name": "checklyhq.com.", + "type": "A", + "TTL": 27, + "data": "18.66.102.85" + }, + { + "name": "checklyhq.com.", + "type": "A", + "TTL": 27, + "data": "18.66.102.10" + } + ], + "Question": [ + { + "name": "checklyhq.com.", + "type": "A" + } + ], + "Status": "NOERROR", + "TC": false, + "RD": true, + "RA": true, + "AD": false, + "CD": false +} +``` + +Common assertions: +- `$.Answer[0].data` - Check specific IP address +- `$.Answer.length` - Verify number of A records +- `$.Answer[0].TTL` - Validate TTL value + + + +```json +{ + "Answer": [ + { + "name": "example.com.", + "type": "AAAA", + "TTL": 300, + "data": "2606:2800:220:1:248:1893:25c8:1946" + } + ], + "Question": [ + { + "name": "example.com.", + "type": "AAAA" + } + ], + "Status": "NOERROR" +} +``` + +Common assertions: +- `$.Answer[0].data` - Check IPv6 address +- `$.Answer[0].TTL` - Validate TTL value + + + +```json +{ + "Answer": [ + { + "name": "www.example.com.", + "type": "CNAME", + "TTL": 300, + "data": "example.com." + } + ], + "Question": [ + { + "name": "www.example.com.", + "type": "CNAME" + } + ], + "Status": "NOERROR" +} +``` + +Common assertions: +- `$.Answer[0].data` - Verify canonical name target + + + +```json +{ + "Answer": [ + { + "name": "example.com.", + "type": "MX", + "TTL": 3600, + "data": "10 mail.example.com." + }, + { + "name": "example.com.", + "type": "MX", + "TTL": 3600, + "data": "20 mail2.example.com." + } + ], + "Question": [ + { + "name": "example.com.", + "type": "MX" + } + ], + "Status": "NOERROR" +} +``` + +Common assertions: +- `$.Answer[0].data` - Check MX priority and mail server (format: "priority hostname") +- `$.Answer.length` - Verify number of mail servers + + + +```json +{ + "Answer": [ + { + "name": "example.com.", + "type": "TXT", + "TTL": 300, + "data": "v=spf1 include:_spf.example.com ~all" + } + ], + "Question": [ + { + "name": "example.com.", + "type": "TXT" + } + ], + "Status": "NOERROR" +} +``` + +Common assertions: +- `$.Answer[0].data` - Verify SPF, DKIM, or other TXT records +- Text response contains `v=spf1` - Check for SPF record + + + +```json +{ + "Answer": [ + { + "name": "example.com.", + "type": "NS", + "TTL": 86400, + "data": "ns1.example.com." + }, + { + "name": "example.com.", + "type": "NS", + "TTL": 86400, + "data": "ns2.example.com." + } + ], + "Question": [ + { + "name": "example.com.", + "type": "NS" + } + ], + "Status": "NOERROR" +} +``` + +Common assertions: +- `$.Answer.length` - Verify number of nameservers +- `$.Answer[0].data` - Check specific nameserver + + + +```json +{ + "Answer": [ + { + "name": "example.com.", + "type": "SOA", + "TTL": 3600, + "data": "ns1.example.com. admin.example.com. 2024010100 7200 3600 1209600 3600" + } + ], + "Question": [ + { + "name": "example.com.", + "type": "SOA" + } + ], + "Status": "NOERROR" +} +``` + +**SOA data format**: `primary-ns responsible-email serial refresh retry expire minimum` + +Common assertions: +- `$.Answer[0].data` - Verify SOA record (contains serial number and nameserver) +- Text response contains expected serial number + + + +**Record type support**: DNS monitors currently support A, AAAA, CNAME, MX, NS, SOA, and TXT record types. Additional record types (SRV, CAA, PTR, etc.) may be added in future updates. + + +### Response Time Limits + +Define performance thresholds for degraded or failed states: + + + DNS monitor response time limits interface + DNS monitor response time limits interface + + +### Frequency + +Set how often the monitor runs (every 10 seconds to 24 hours): + + + DNS monitor frequency selection interface + DNS monitor frequency selection interface + + +### Scheduling & Locations + + + DNS monitor scheduling strategy and location selection interface + DNS monitor scheduling strategy and location selection interface + + +* **Strategy:** Choose between round-robin or parallel execution. Learn more about [scheduling strategies](/monitoring/global-locations#scheduling-strategies) +* **Locations:** Select one or more [public](/monitoring/global-locations/) locations to run the monitor from. +* **Private locations**: DNS monitors do not currently support private locations. +### Additional Settings + +* **Name:** Give your monitor a clear name to identify it in dashboards and alerts +* **Tags:** Use tags to organize monitors across dashboards and [maintenance windows](/communicate/maintenance-windows/overview) +* **Retries:** Define how failed runs should be retried. See [retry strategies](/communicate/alerts/retries) +* **Alerting:** Configure your [alert settings](/communicate/alerts/configuration), [alert channels](/communicate/alerts/channels), or set up [webhooks](/communicate/alerts/webhooks) for custom integrations + +## Common Use Cases + + +**Scenario**: Your CDN provides multiple IP addresses for redundancy. You need to ensure all IPs are reachable. + +**Configuration**: +- **Domain**: `cdn.example.com` +- **Record type**: A +- **Assertions**: + - `$.Answer.length` equals `4` (verify all IPs present) + - `$.Answer[0].TTL` is less than `300` (ensure low TTL for quick failover) + - `$.Answer[0].data` equals expected IP address + + + +**Scenario**: Monitor SPF, DKIM, and DMARC records to prevent email spoofing. + +**Configuration**: +- **Domain**: `example.com` +- **Record type**: TXT +- **Assertions**: + - Text response contains `v=spf1` + - `$.Answer[0].data` contains `v=spf1` + +For DMARC: +- **Domain**: `_dmarc.example.com` +- **Record type**: TXT +- **Assertions**: + - Text response contains `v=DMARC1` + - `$.Answer[0].data` contains `p=reject` or `p=quarantine` + + + +**Scenario**: Ensure primary and backup mail servers are correctly configured. + +**Configuration**: +- **Domain**: `example.com` +- **Record type**: MX +- **Assertions**: + - `$.Answer.length` is greater than `1` (at least 2 MX records) + - `$.Answer[0].data` contains `10 mail.example.com.` (priority 10 + hostname) + - Text response contains `mail.example.com` + + + +**Scenario**: After updating nameservers, verify all nameservers return consistent results. + +**Configuration**: +- **Domain**: `example.com` +- **Record type**: NS +- Create separate monitors for each nameserver: + - Monitor 1: DNS server `ns1.example.com:53` + - Monitor 2: DNS server `ns2.example.com:53` +- **Assertions**: + - `$.Answer.length` equals expected count + - `$.Answer[0].data` equals `ns1.example.com.` or `ns2.example.com.` + \ No newline at end of file diff --git a/detect/uptime-monitoring/dns-monitors/overview.mdx b/detect/uptime-monitoring/dns-monitors/overview.mdx new file mode 100644 index 0000000..e25e4b1 --- /dev/null +++ b/detect/uptime-monitoring/dns-monitors/overview.mdx @@ -0,0 +1,131 @@ +--- +title: 'DNS Monitors Overview' +description: 'Monitor the resolution and lookup times of DNS records' +sidebarTitle: Overview +--- + + +## What are DNS Monitors? + +DNS monitors check that your DNS records resolve as expected. They help you catch misconfigurations, expired records, or propagation issues before they impact your users. + +**Typical use cases include:** +- Detecting if your domain stops resolving to its IP address to prevent downtime +- Verifying that records resolve correctly when queried against a specific nameserver (e.g. 208.67.222.222 for OpenDNS) to catch resolver-specific issues +- Monitoring DNS response times to detect performance degradation or resolver latency +- Spotting slow or inconsistent DNS resolution across different regions + +## How do DNS monitors work? + +DNS monitors perform lookups to verify your DNS configuration: + +1. **Query initiation**: Checkly runs a DNS lookup from your configured location(s) + +2. **Resolver selection**: The query is sent to a DNS resolver: + - **Default**: 8.8.8.8 (Google DNS) + - **Automatic failover**: If the default resolver returns an error code (SERVFAIL, NXDOMAIN, etc.), Checkly automatically retries with 1.1.1.1 (Cloudflare DNS), then an internal AWS resolver + - **Custom resolver**: You can specify a custom nameserver and port for testing resolver-specific behavior + +3. **DNS chain resolution**: The resolver queries the authoritative nameserver and retrieves the requested record type + +4. **Response validation**: The response is validated against your configured assertions + +For example, querying the A record for `checklyhq.com` returns: + +``` +NOERROR 0ms +;; opcode: QUERY, status: NOERROR, id: 16122 +;; flags: qr aa rd ra; QUERY: 1, ANSWER: 4, AUTHORITY: 0, ADDITIONAL: 0 + +;; QUESTION SECTION: +;checklyhq.com. IN A + +;; ANSWER SECTION: +checklyhq.com. 6 IN A 18.66.102.127 +checklyhq.com. 6 IN A 18.66.102.76 +checklyhq.com. 6 IN A 18.66.102.10 +checklyhq.com. 6 IN A 18.66.102.85 +``` + +The query response appears on the results page as both raw output and parsed JSON. Use it as a reference to define [assertions](/detect/uptime-monitoring/dns-monitors/configuration#assertions) for expected values. + +## Supported DNS record types + +DNS monitors support the following DNS record types: + +- **A**: IPv4 address records +- **AAAA**: IPv6 address records +- **CNAME**: Canonical name (alias) records +- **MX**: Mail exchange server records +- **NS**: Nameserver records +- **SOA**: Start of authority records +- **TXT**: Text records (SPF, DKIM, DMARC, etc.) + +## Limitations + + +DNS monitors are currently available through the UI only. Support for Monitoring as Code (CLI, Terraform, Pulumi) will be released in a future update. Check the [changelog](https://feedback.checklyhq.com/changelog) for updates. + + +Current limitations: + +- **Private locations**: DNS monitors do not currently support private locations. You can only run DNS monitors from Checkly's global public locations. + +## Troubleshooting Common Issues + + +**Symptom**: DNS updated but users still reach old infrastructure + +**Root causes**: +- **TTL caching**: Old records remain cached until TTL expires +- **Resolver differences**: Different DNS resolvers update at different times +- **CDN caching**: Content delivery networks may cache DNS responses independently + +**How to detect and fix**: +1. **Verify new IP is resolving**: Use assertion `$.Answer[0].data` to check that the correct IP is returned +2. **Monitor TTL timing**: Add assertion `$.Answer[0].TTL` to track when records should fully propagate +3. **Test multiple resolvers**: Configure monitors with different nameservers (8.8.8.8, 1.1.1.1, custom) to verify all resolvers have updated +4. **Check multiple regions**: Run monitors from multiple Checkly locations to catch regional propagation issues + +**Prevention tip**: Lower TTL values 24-48 hours before planned DNS changes to speed up propagation. + + + +**Symptom**: Expected multiple records (A, MX, NS, etc.) but getting fewer or more than expected + +**Root causes**: +- **Dynamic infrastructure**: Auto-scaling events add/remove instances +- **Health checks**: Load balancers automatically remove unhealthy instances from DNS +- **Configuration drift**: Manual changes not reflected in monitoring + +**How to detect and fix**: +1. **Set exact count assertion**: Use `$.Answer.length` equals `X` for static infrastructure +2. **Use range assertions**: For auto-scaled systems, use `$.Answer.length` is greater than `2` and less than `10` +3. **Monitor specific records**: Use `$.Answer[?(@.data == '203.0.113.1')]` to verify critical IPs are present +4. **Alert on unexpected changes**: Set alerts to notify when record count deviates from baseline + +**Example for MX records**: Ensure backup mail servers are configured with `$.Answer.length` equals `2` or greater. + + + +**Symptom**: DNS resolves from your network but fails for certain users or regions + +**Root causes**: +- **Resolver behavior differences**: Public resolvers (Google, Cloudflare, ISP) may have different caching policies or DNSSEC validation +- **Geographic DNS routing**: GeoDNS returns different results based on query location +- **Corporate/ISP filtering**: Organizations may block or redirect certain domains +- **DNSSEC validation failures**: Some resolvers enforce DNSSEC while others don't + +**How to detect and fix**: +1. **Test multiple resolvers**: Create separate monitors with different nameservers: + - Google DNS: `8.8.8.8:53` + - Cloudflare DNS: `1.1.1.1:53` + - OpenDNS: `208.67.222.222:53` + - User-reported resolver: Custom IP +2. **Monitor from multiple locations**: Run monitors from regions where users report issues +3. **Validate DNSSEC**: Use `dig +dnssec` locally to check for DNSSEC issues +4. **Check for hijacking**: Compare responses across resolvers to detect DNS hijacking or filtering + +**Pro tip**: If users report issues with specific ISPs, test against those ISP's DNS resolvers directly. + + diff --git a/detect/uptime-monitoring/overview.mdx b/detect/uptime-monitoring/overview.mdx index e7f3334..e003bb7 100644 --- a/detect/uptime-monitoring/overview.mdx +++ b/detect/uptime-monitoring/overview.mdx @@ -35,6 +35,11 @@ Choose the Uptime Monitor that best fits your monitoring needs: TCP Monitors monitor the availability and performance of TCP connections. + + + DNS monitors verify that DNS records resolve successfully and return the expected values. + + ## Benefits of Uptime Monitoring @@ -43,5 +48,6 @@ Uptime monitoring continuously checks if your applications and services are acce - Ensuring your marketing site returns a 200 OK - Verifying your documentation site loads quickly - Monitoring database connectivity with TCP checks +- Checking that your domain resolves correctly with DNS monitors - Confirming heartbeat endpoints are responding in your CI/CD pipeline diff --git a/detect/uptime-monitoring/tcp-monitors/configuration.mdx b/detect/uptime-monitoring/tcp-monitors/configuration.mdx index 9a741ec..ae91cec 100644 --- a/detect/uptime-monitoring/tcp-monitors/configuration.mdx +++ b/detect/uptime-monitoring/tcp-monitors/configuration.mdx @@ -8,7 +8,7 @@ sidebarTitle: 'Configuration' TCP monitors verify the availability of non-HTTP services by establishing a connection to a specific host and port. -**To configure a TCP monitor using code, learn more about the [TCP Monitor Construct](/constructs/tcp-monitor). +To configure a TCP monitor using code, learn more about the [TCP Monitor Construct](/constructs/tcp-monitor). ### Basic Setup diff --git a/detect/uptime-monitoring/url-monitors/configuration.mdx b/detect/uptime-monitoring/url-monitors/configuration.mdx index c9e28e4..4975739 100644 --- a/detect/uptime-monitoring/url-monitors/configuration.mdx +++ b/detect/uptime-monitoring/url-monitors/configuration.mdx @@ -20,9 +20,7 @@ Use assertions to validate the status code of your URL request. When one or more URL monitor assertions interface showing status code configuration -**Status Code** -Verify your endpoint returns the expected HTTP status code using the comparison dropdown. Choose from equals, not equals, greater than, or less than. - +**Status Code:** Verify your endpoint returns the expected HTTP status code using the comparison dropdown. Choose from equals, not equals, greater than, or less than. ### Response Time Limits diff --git a/detect/uptime-monitoring/url-monitors/overview.mdx b/detect/uptime-monitoring/url-monitors/overview.mdx index 6c10039..7ce9118 100644 --- a/detect/uptime-monitoring/url-monitors/overview.mdx +++ b/detect/uptime-monitoring/url-monitors/overview.mdx @@ -83,7 +83,6 @@ Schedule your monitor to run at the frequency you want. - Always check status codes -- Include content assertions for critical functionality - Set appropriate response time thresholds - Test assertions thoroughly before deployment diff --git a/docs.json b/docs.json index 5f5e3ca..8b8e67d 100644 --- a/docs.json +++ b/docs.json @@ -171,6 +171,13 @@ "detect/uptime-monitoring/tcp-monitors/overview", "detect/uptime-monitoring/tcp-monitors/configuration" ] + }, + { + "group": "DNS Monitors", + "pages": [ + "detect/uptime-monitoring/dns-monitors/overview", + "detect/uptime-monitoring/dns-monitors/configuration" + ] } ] }, diff --git a/images/dns-monitors/assertions-dark.png b/images/dns-monitors/assertions-dark.png new file mode 100644 index 0000000..e590a23 Binary files /dev/null and b/images/dns-monitors/assertions-dark.png differ diff --git a/images/dns-monitors/assertions.png b/images/dns-monitors/assertions.png new file mode 100644 index 0000000..c87afef Binary files /dev/null and b/images/dns-monitors/assertions.png differ diff --git a/images/dns-monitors/frequency-dark.png b/images/dns-monitors/frequency-dark.png new file mode 100644 index 0000000..9dc3999 Binary files /dev/null and b/images/dns-monitors/frequency-dark.png differ diff --git a/images/dns-monitors/frequency.png b/images/dns-monitors/frequency.png new file mode 100644 index 0000000..ce7f336 Binary files /dev/null and b/images/dns-monitors/frequency.png differ diff --git a/images/dns-monitors/request-dark.png b/images/dns-monitors/request-dark.png new file mode 100644 index 0000000..a11e3ff Binary files /dev/null and b/images/dns-monitors/request-dark.png differ diff --git a/images/dns-monitors/request.png b/images/dns-monitors/request.png new file mode 100644 index 0000000..fb848cf Binary files /dev/null and b/images/dns-monitors/request.png differ diff --git a/images/dns-monitors/response-time-dark.png b/images/dns-monitors/response-time-dark.png new file mode 100644 index 0000000..368c3dc Binary files /dev/null and b/images/dns-monitors/response-time-dark.png differ diff --git a/images/dns-monitors/response-time.png b/images/dns-monitors/response-time.png new file mode 100644 index 0000000..4c376e2 Binary files /dev/null and b/images/dns-monitors/response-time.png differ diff --git a/images/dns-monitors/scheduling-dark.png b/images/dns-monitors/scheduling-dark.png new file mode 100644 index 0000000..c34c70a Binary files /dev/null and b/images/dns-monitors/scheduling-dark.png differ diff --git a/images/dns-monitors/scheduling.png b/images/dns-monitors/scheduling.png new file mode 100644 index 0000000..fd51c31 Binary files /dev/null and b/images/dns-monitors/scheduling.png differ