Monitoring
The monitoring helper allows you to check and monitor the uptime status of an IP. This is useful for uptime checking when returning DNS records. It takes a single IP parameter that is then monitored in the background.How an IP’s status is determined
An IP is considered online if it responded to an ICMP ping in its most recent health check:- Each health check sends an ICMP ping with a 700 ms timeout, retrying up to 3 times. A single successful reply marks the IP as online; if all 3 attempts fail, it is marked as offline.
- While an IP is being actively requested by your script, it is re-checked approximately every 10 seconds. IPs that are requested less often are checked less frequently (up to every 2 minutes), and IPs that are not requested for 3 days stop being monitored.
- The first time an IP is requested, it is added to the background monitoring service and the DNS server synchronously waits for the initial check to complete. Subsequent requests return the cached status immediately.
- Monitoring is performed independently by each DNS server, so the status reflects reachability from the DNS server handling the query.
- Private and loopback addresses (
127.0.x.x,192.168.x.x) and invalid IPs are always reported as offline.
Monitoring is a network-level (ICMP) check only. It does not verify that an HTTP service or any specific port is responding. A server that responds to ping but has a failed application will still be reported as online. Make sure your servers allow inbound ICMP echo requests, otherwise they will always be reported as offline.
Functions
Monitoring.getStatus(IP: string): MonitoringStatus
Returns the current status of the IP.MonitoringStatus
The monitoring status object is returned by theMonitoring.getStatus helper and contains the monitoring information of a specific IP.
GeoDatabase
GeoDatabase is a wrapper around a GeoDNS library. It allows you to easily look up the geo location of an IP address.Functions
GeoDatabase.resolve(IP: string): GeoLocation
Returns the GeoLocation result for the specified IP based on a GeoDNS database.GeoDistance
GeoDistance contains helper methods to help you calculate the distance between two geographical points.Functions
GeoDistance.calculate(lat1: double, lon1: double, lat2: double, lon2: double): double
Returns the geographical distance between two geographical locations based on latitude and longitude.GeoDistance.calculate(loc1: GeoLocation, loc2: GeoLocation): double
Returns the geographical distance between two GeoLocation objects.GeoDistance.calculate(server: Server, location: GeoLocation): double
Returns the geographical distance between a Server object and a GeoLocation object.RoutingEngine
RoutingEngine helps with dynamic geographic routing, weight calculation, and round robin logic based on a list of servers.Functions
RoutingEngine.getWeightedRandom(servers: Array<Server>, onlineOnly: bool = false, applyWeight: bool = true): Server
Returns one server from an array of servers based on a round robin weighted random principle, using each server’sweight. If onlineOnly is set to true, servers that are offline (see Monitoring) are skipped. If no servers are online, null is returned.
RoutingEngine.getClosestServer(servers: Array<Server>, location: GeoLocation, onlineOnly: bool = false, applyWeight: bool = true): Server
Returns the server from an array of servers that is geographically closest to the given GeoLocation. If several servers are equally close, one of them is chosen using weighted round robin. IfonlineOnly is set to true, servers that are offline (see Monitoring) are skipped. onlineOnly defaults to false, so offline servers are only excluded when you pass true explicitly.
Server
The Server object is used to pass or return server information to various other helper methods and does not contain any functionality by itself.The
online constructor parameter is not used by RoutingEngine. Online status is always determined by the Monitoring health check, so setting online to false will not remove a server from rotation. To take a server out of rotation, remove it from the array.