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

# Your First DNS Monitor

> Create your first DevHelm DNS monitor to verify domain name resolution

By the end of this guide, you'll have a DNS monitor checking that your domain resolves correctly and returns the expected records.

<Accordion title="Prerequisites">
  * DevHelm CLI installed or an API token for REST calls
  * An API token set as `DEVHELM_API_TOKEN` — see [Authentication](/authentication)
  * A domain name to monitor
</Accordion>

## Create the monitor

<Steps>
  <Step title="Create the DNS monitor">
    <CodeGroup>
      ```bash CLI theme={null}
      devhelm monitors create \
        --name "example.com DNS" \
        --type DNS \
        --url example.com \
        --frequency 300 \
        --regions us-east,eu-west
      ```

      ```yaml devhelm.yml theme={null}
      version: "1"
      monitors:
        - name: example.com DNS
          type: DNS
          config:
            hostname: example.com
            recordTypes:
              - A
              - AAAA
          frequencySeconds: 300
          regions:
            - us-east
            - eu-west
      ```

      ```bash API theme={null}
      curl -X POST https://api.devhelm.io/api/v1/monitors \
        -H "Authorization: Bearer $DEVHELM_API_TOKEN" \
        -H "Content-Type: application/json" \
        -d '{
          "name": "example.com DNS",
          "type": "DNS",
          "config": {
            "hostname": "example.com",
            "recordTypes": ["A", "AAAA"]
          },
          "frequencySeconds": 300,
          "regions": ["us-east", "eu-west"]
        }'
      ```
    </CodeGroup>

    With the CLI, `--url` is the hostname to resolve and default record types apply. To check specific record types, set `config.recordTypes` via YAML config-as-code or the API, as shown in the other tabs.
  </Step>

  <Step title="Verify it's running">
    ```bash theme={null}
    devhelm monitors list --type DNS
    devhelm monitors get <monitor-id>
    ```
  </Step>

  <Step title="Check results">
    Results include resolved records, query time, and the nameserver used.

    ```bash theme={null}
    devhelm monitors checks <monitor-id> --limit 5
    ```
  </Step>
</Steps>

## Add assertions

Verify that DNS returns the records you expect:

```yaml theme={null}
monitors:
  - name: example.com DNS
    type: DNS
    config:
      hostname: example.com
      recordTypes:
        - A
    frequencySeconds: 300
    regions:
      - us-east
    assertions:
      - config:
          type: dns_resolves
        severity: fail
      - config:
          type: dns_expected_ips
          ips:
            - "93.184.216.34"
        severity: fail
      - config:
          type: dns_response_time
          maxMs: 500
        severity: warn
```

Key DNS assertions:

| Type                | What it checks                                  |
| ------------------- | ----------------------------------------------- |
| `dns_resolves`      | The domain resolves to at least one record      |
| `dns_expected_ips`  | Resolved IPs match an expected list             |
| `dns_record_count`  | Number of returned records matches expectations |
| `dns_response_time` | Query completes within a threshold              |

For the full list (12 assertion types), see [DNS configuration](/monitoring/dns/configuration).

## Common use cases

<AccordionGroup>
  <Accordion title="DNS migration validation">
    After changing DNS providers, verify that all regions resolve to the correct IPs. Run from multiple regions to catch propagation issues.
  </Accordion>

  <Accordion title="CDN failover detection">
    Monitor CNAME records that point to your CDN. If the CNAME changes unexpectedly, an assertion failure triggers an incident.
  </Accordion>

  <Accordion title="MX record monitoring">
    Verify that MX records are present and point to the correct mail servers to catch email delivery issues early.
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup cols={2}>
  <Card title="DNS monitor reference" icon="server" href="/monitoring/dns/overview">
    All DNS configuration options and record types.
  </Card>

  <Card title="First alert" icon="bell" href="/guides/first-alert">
    Get notified when DNS resolution fails.
  </Card>

  <Card title="Multi-region monitoring" icon="earth-americas" href="/guides/multi-region-monitoring">
    Detect region-specific DNS issues.
  </Card>
</CardGroup>