Documentation
Complete guide to setting up website monitoring with PingZen. API documentation, code examples, and best practices.
A DNS monitor asks for one record type on one name and reports what came back. It answers two questions: does the name resolve at all, and does it resolve to the value you expect. It says nothing about the service behind the name — that is a different monitor.
What It Is For
The name stopped resolving
A zone that was deleted, a delegation that broke after a registrar change, nameservers that stopped answering. Your servers are fine and nobody can reach any of them. A DNS monitor names that cause in one line instead of an hour of guessing.
The record changed behind your back
Write down the value you expect and the monitor goes down the moment the answer stops containing it. This catches a hijacked or hacked account, a colleague editing the wrong zone, a migration that half rolled back, and a CDN or SaaS provider that moved your name somewhere new.
The records nobody looks at until something breaks
MX records that route your mail, TXT records holding SPF, DKIM or a provider's domain verification, NS records that carry the delegation, a CNAME pointing at a CDN. Nothing alerts you when one of these disappears — mail just stops being delivered, or a service quietly says your domain is no longer verified.
How long resolution takes
Every check records the time the lookup took. Slow DNS is added to the front of every single request a visitor makes, and it is invisible in server-side timings.
What It Is Not For
A DNS monitor reads a record. It never connects to whatever that record points at:
| You want to know | Use instead |
|---|---|
| Is the domain registration about to expire? This is the most common mix-up. Records keep resolving normally right up to the day the registry pulls the domain — a DNS monitor gives you no warning at all, it goes down together with everything else | WHOIS monitor |
| Does the site behind the name actually work? An A record resolves perfectly while the web server returns 502 to everyone | HTTP / HTTPS monitor |
| Does the mail server accept mail? An MX record only says which host is supposed to take it | SMTP monitor on the host the MX record names |
| Is my IP or domain on a spam blacklist? Blacklists are published over DNS, but checking them means querying dozens of providers, not one record | DNSBL monitor |
| Is the host reachable? A name can resolve to an address that answers nothing | Ping monitor |
| Is one specific nameserver alive, and do all of them agree? The monitor asks a resolver, not each of your authoritative servers in turn | UDP or TCP monitor on port 53 of each nameserver, which tells you the server answers but not what it answers |
What Every Check Does
One query, for the record type you picked, sent through the public recursive resolver PingZen is configured to use. The check records:
- The resolved values — the full list of records that came back, kept with every check result
- Resolution time — how long the answer took, in milliseconds
Because the query goes through a recursive resolver, you see what the public internet sees, cached answers included. A record you changed a minute ago can take until the old TTL runs out to show up here. That is normally what you want from a monitor: it reports the answer your users are actually getting.
Record Types
| Type | What you watch with it |
|---|---|
A | The IPv4 address the name points to. The default, and the right choice if you are not sure |
AAAA | The IPv6 address. Useful on its own, because an AAAA record can be missing or wrong while A is perfect |
CNAME | The alias target — a CDN, a load balancer, a SaaS host |
MX | Mail routing. Values are recorded as priority and host together, like 10 mail.example.com. |
TXT | SPF, DKIM, DMARC and domain-verification strings. A record split into several strings is recorded joined with a space |
NS | The delegation — which nameservers are meant to be authoritative for the zone |
SOA | The zone's own record. Mostly used as proof that the zone still exists and is being served |
PTR | Reverse lookup for an address. Mail servers are judged on this one |
Those eight are the whole list. Any other type — SRV, CAA and the rest — is rejected, and the check fails with a message saying the record type is not supported.
Expected Values
Leave the expected values empty and the monitor only asks whether the name resolves. Fill them in and every value you listed has to appear in the answer.
- Matching is exact and literal, value by value. It is not a substring search and not a pattern.
- The answer may contain more than you listed. Two A records when you listed one is fine; the listed one just has to be there.
- If any listed value is missing, the check fails and the error message shows both what was missing and what came back instead, so you can see the new value without leaving the monitor.
- The resolved values are still recorded on a failed check, exactly as on a passing one.
- Names inside
CNAME,NSandMXanswers come back with a trailing dot —mail.example.com.— so write them that way.MXvalues also carry the priority in front. - Up to 100 values per monitor.
Expected values are set in the monitor form, comma-separated, and through the API or the MCP tools.
Status Logic
A DNS monitor is up or down. There is no degraded state and no slow-answer threshold — a lookup that takes a long time but returns the right answer is still up.
| Result | Status |
|---|---|
| The record came back, and no expected values are set | UP |
| The record came back and contains every expected value | UP |
| An expected value is missing from the answer | DOWN |
| The name does not exist (NXDOMAIN) | DOWN |
| The name exists, but has no record of that type | DOWN |
| No nameserver would answer, or the network failed | DOWN |
| No answer arrived before the timeout | TIMEOUT |
Every failure carries the reason in its own words — “Domain not found”, “No MX record found”, “Expected values not found” — so the monitor page tells you which of these happened.
One failed lookup is not an outage: as with every monitor, DOWN is confirmed only after several failing checks in a row, three by default. See incidents for what happens next.
Configuration
Name
The name to look up, with or without a dns:// prefix: example.com and dns://example.com behave the same. For a subdomain, write the full name — mail.example.com, not mail. No port.
Record type
One of the eight types above. A by default. One monitor asks for one type, so watching both the A record and the MX records of a domain means two monitors.
Expected values
Optional. Every value listed must be in the answer, or the check fails. Empty means "any answer will do". Up to 100 values.
Check interval
60 seconds by default. Records change rarely, so a longer interval usually loses you nothing — unless the point of the monitor is to catch an unauthorised change quickly.
Timeout
5 seconds by default. PingZen also has its own ceiling on DNS queries, and the check uses whichever of the two is shorter.
Which resolver is used
Queries go through the public recursive resolver PingZen is configured to use. You do not choose a nameserver per monitor — the form shows a DNS server box, but the check does not use it yet.
Key Features
- Eight record types: A, AAAA, CNAME, MX, TXT, NS, SOA and PTR
- Optional expected values, with the missing and the actual values both shown on failure
- Resolved values and resolution time recorded on every check, passing or failing
- A separate reason for each way a lookup can fail, instead of one flat “down”
- Sees the answer a public resolver gives, which is the answer your users get
Common Questions
What protocols can I monitor?
PingZen supports 23 protocols: HTTP/HTTPS, WebSocket (WS/WSS), TCP, UDP, ICMP Ping, gRPC, DNS, WHOIS, TLS/SSL certificates, Email (SMTP/IMAP/POP3), FTP/FTPS, DNSBL, PageSpeed, SOCKS5, MTProxy, API Check, and Transaction. You can monitor websites, APIs, servers, databases, and any network service.
How fast can I get alerts?
Telegram alerts are delivered within 1-2 seconds of detection. Slack and Discord notifications arrive almost instantly. You can configure multiple alert channels for redundancy.
Can I organize monitors by project?
Yes! PingZen supports workspaces, which let you organize monitors by project, environment, or team. Each workspace can have its own alert configurations and team members.
Is there an API for automation?
Absolutely. PingZen provides a full REST API with OpenAPI documentation. You can create, update, and delete monitors programmatically.
How do status pages work?
Status pages are public, branded pages showing your services' uptime. You can display real-time status and allow customers to subscribe for updates.
What happens if I reach my monitor limit?
We'll notify you when approaching your limit. You can pause some monitors or contact us for increased capacity. We never stop monitoring without warning, ensuring your critical services stay protected.
Ready to stop missing downtime?
Join thousands of teams who trust PingZen. Setup takes 30 seconds.