initial outline icmp documentation

concepts/results.mdx

@@ -172,6 +172,10 @@ Each result includes:
 	* firstByte: time until the first byte of the response is received
 	* download: duration of the HTTP download
 
+## ICMP monitor results
+
+....
+
 ## Multistep check results
 
 Multistep check results are navigated using the tree on the left side of the screen. If you are running checks in parallel, first select the location you are interested in.

detect/uptime-monitoring/dns-monitors/configuration.mdx

@@ -317,8 +317,8 @@ Set how often the monitor runs (every 10 seconds to 24 hours):
   <img className="hidden dark:block" src="/images/dns-monitors/scheduling-dark.png" alt="DNS monitor scheduling strategy and location selection interface" />
 </Frame>
 
-* **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
+* **Strategy:** Choose between round-robin or parallel execution. Learn more about [scheduling strategies](/concepts/scheduling)
+* **Locations:** Select one or more [public](/concepts/locations/#public-locations) locations to run the monitor from
 * **Private locations**: DNS monitors do not currently support private locations
 ### Additional Settings
 

detect/uptime-monitoring/icmp-monitors/configuration.mdx

@@ -0,0 +1,64 @@
+---
+title: 'ICMP Monitor Configuration'
+description: 'Configure your ICMP monitor to verify host reachability and measure network latency.'
+sidebarTitle: 'Configuration'
+---
+
+### Basic Setup
+
+Configure your ICMP monitor by specifying the target host:
+
+[IMG]
+
+* **Hostname or IP address:** The server you want to monitor (e.g. `db.example.com` or `203.0.113.1`)
+* **IP family:** Choose between IPv4 (default) or IPv6
+* **Pings per run:** Number of ICMP Echo Request packets to send per check run (1-50, default: 10)
+
+### Assertions
+
+Validate latency metrics to ensure your infrastructure meets performance requirements:
+
+[IMG]
+
+You can create assertions based on:
+
+* **Latency metrics:** Validate `min`, `max`, `avg`, or `stddev` latency values
+* **JSON response:** Assert against the full JSON response structure
+
+### Packet Loss Limits
+
+Define packet loss thresholds to determine when an ICMP monitor should be considered degraded or failed:
+
+<Frame>
+  <img className="block dark:hidden" src="/images/icmp-packet-loss-threshold.png" alt="ICMP monitor packet loss limits interface" />
+  <img className="hidden dark:block" src="/images/icmp-packet-loss-threshold-dark.png" alt="ICMP monitor packet loss limits interface" />
+</Frame>
+
+### Frequency
+
+Set how often the monitor runs (every 10 seconds to 24 hours):
+
+<Frame>
+  <img className="block dark:hidden" src="/images/dns-monitors/frequency.png" alt="ICMP monitor frequency selection interface" />
+  <img className="hidden dark:block" src="/images/dns-monitors/frequency-dark.png" alt="ICMP monitor frequency selection interface" />
+</Frame>
+
+### Scheduling & Locations
+
+<Frame>
+  <img className="block dark:hidden" src="/images/dns-monitors/scheduling.png" alt="ICMP monitor scheduling strategy and location selection interface" />
+  <img className="hidden dark:block" src="/images/dns-monitors/scheduling-dark.png" alt="ICMP monitor scheduling strategy and location selection interface" />
+</Frame>
+
+* **Strategy:** Choose between round-robin or parallel execution. Learn more about [scheduling strategies](/concepts/scheduling)
+* **Locations:** Select one or more [public](/concepts/locations/#public-locations) locations to run the monitor from
+* **Private locations**: ICMP 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](/integrations/alerts/webhooks) for custom integrations
+
+

detect/uptime-monitoring/icmp-monitors/overview.mdx

@@ -0,0 +1,77 @@
+---
+title: 'ICMP Monitors Overview'
+description: 'Monitor host reachability and network latency using ICMP ping.'
+sidebarTitle: Overview
+---
+<Tip>
+**Monitoring as Code**: Learn more about the [ICMP Monitor Construct](/constructs/icmp-monitor).
+</Tip>
+
+## What are ICMP Monitors?
+
+ICMP monitors verify that a host is reachable and responding. Typical use cases include:
+
+* Detecting network-level outages before they're visible via HTTP endpoints
+* Monitoring latency across regions to identify geographic performance issues
+* Verifying reachability for servers, load balancers, or network appliances that don't expose HTTP endpoints or open TCP ports
+* Tracking packet loss to catch network quality degradation early
+
+## How do ICMP monitors work?
+
+ICMP monitors perform ping tests:
+
+* Hostname resolution: If a hostname is provided, Checkly resolves it to an IP address.
+* Ping execution: Multiple ICMP Echo Request packets (configurable from 1–50, default: 10) are sent from your configured location(s).
+* Response valildation: ICMP Echo Reply packets are received. Round-trip latency and packet loss are measured and evaluated against your configured assertions.
+
+For example, pinging checklyhq.com with 10 pings returns:
+
+```json
+{
+  "latency": {
+    "min": 12.3,
+    "max": 18.7,
+    "avg": 14.2,
+    "stddev": 2.1
+  },
+  "packetLoss": 0,
+  "timingPhases": { "dns": 5.2 },
+  "pingsSucceeded": 10,
+  "pingsFailed": 0
+}
+```
+
+The response appears on the results page as both raw output and parsed JSON. You can use it as a reference to define [assertions](/detect/uptime-monitoring/icmp-monitors/configuration#assertions) for expected values.
+
+## Troubleshooting Common Issues
+
+<Accordion title="100% packet loss but the host is reachable via HTTP">
+**Symptom**: ICMP monitor shows complete packet loss, but the website/API works fine
+
+**Root cause**:
+- **Firewall rules blocking ICMP**: Many organizations block ICMP echo request packets at the firewall, load balancer, or host level as a security measure
+
+**How to detect and fix**:
+1. **Verify HTTP connectivity**: Create an API or URL monitor for the same hostname to confirm it's reachable
+2. **Check both protocols**: Test both IPv4 and IPv6, some hosts allow ICMP on one protocol but not the other
+3. **Confirm with infrastructure team**: Ask if ICMP is intentionally blocked in security policies
+
+**When to use a different monitor type**: If ICMP is deliberately blocked, use TCP, URL, or API checks instead to verify availability at the application layer.
+</Accordion>
+
+<Accordion title="High latency or packet loss from specific regions">
+**Symptom**: ICMP monitor shows high latency or packet loss from certain locations but not others
+
+**Root causes**:
+- **Geographic routing**: Network paths vary by region, some routes may be congested
+- **Transit provider issues**: Problems with specific ISPs or peering connections
+- **Rate limiting**: Some hosts rate-limit ICMP responses, affecting distant locations more
+
+**How to detect and fix**:
+1. **Compare across locations**: Run monitors from multiple regions to identify which paths are affected
+2. **Monitor trends over time**: Check if issues are persistent or intermittent
+3. **Cross-reference with other monitor types**: Compare ICMP latency with TCP/HTTP latency from the same locations
+4. **Use latency assertions**: Set region-specific assertions, e.g., `latency.avg` less than `50ms` for nearby regions, `200ms` for distant ones
+
+**Investigation tip**: Persistent high latency from a specific region often indicates routing issues with your hosting provider or CDN configuration.
+</Accordion>

detect/uptime-monitoring/overview.mdx

@@ -22,22 +22,27 @@ Uptime monitoring is essential for ensuring your applications are always availab
 Choose the Uptime Monitor that best fits your monitoring needs:
 <Columns cols={1}>
     <Card title="URL Monitors" href="/detect/uptime-monitoring/url-monitors/overview" horizontal>
-    URL monitors monitor the availability and performance of a specific URL or public endpoint.
+    Monitor the availability and performance of a specific URL or public endpoint.
 
     </Card>
 
-    <Card title="Heartbeat Monitors" href="/detect/uptime-monitoring/heartbeat-monitors/overview" horizontal>
-    Heartbeat Monitors detect when cron jobs or scheduled tasks fail to run.
+    <Card title="TCP Monitors" href="/detect/uptime-monitoring/tcp-monitors/overview" horizontal>
+    Monitor the availability and performance of TCP connections.
 
     </Card>
 
-    <Card title="TCP Monitors" href="/detect/uptime-monitoring/tcp-monitors/overview" horizontal>
-    TCP Monitors monitor the availability and performance of TCP connections.
+    <Card title="DNS Monitors" href="/detect/uptime-monitoring/dns-monitors/overview" horizontal>
+    Verify that DNS records resolve successfully and return the expected values.
 
     </Card>
 
-    <Card title="DNS Monitors" href="/detect/uptime-monitoring/dns-monitors/overview" horizontal>
-    DNS monitors verify that DNS records resolve successfully and return the expected values.
+    <Card title="ICMP Monitors" href="/detect/uptime-monitoring/icmp-monitors/overview" horizontal>
+    Verify host reachability and measure packet loss.
+
+    </Card>
+
+    <Card title="Heartbeat Monitors" href="/detect/uptime-monitoring/heartbeat-monitors/overview" horizontal>
+    Detect when cron jobs or scheduled tasks fail to run.
 
     </Card>
 </Columns>

detect/uptime-monitoring/tcp-monitors/configuration.mdx

@@ -62,8 +62,8 @@ Set how often the monitor runs (every 10 seconds to 24 hours):
   <img src="/images/tcp-scheduling-strategy.png" alt="TCP monitor scheduling strategy and location selection interface" />
 </Frame>
 
-* **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/) or [private](/platform/private-locations/overview) locations to run the monitor from
+* **Strategy:** Choose between round-robin or parallel execution. Learn more about [scheduling strategies](/concepts/scheduling)
+* **Locations:** Select one or more [public](/concepts/locations/#public-locations) or [private](/platform/private-locations/overview) locations to run the monitor from
 
 ### Additional Settings
 

docs.json

@@ -162,13 +162,6 @@
                       "detect/uptime-monitoring/url-monitors/configuration"
                     ]
                   },
-                  {
-                    "group": "Heartbeat Monitors",
-                    "pages": [
-                      "detect/uptime-monitoring/heartbeat-monitors/overview",
-                      "detect/uptime-monitoring/heartbeat-monitors/examples"
-                    ]
-                  },
                   {
                     "group": "TCP Monitors",
                     "pages": [
@@ -182,6 +175,20 @@
                       "detect/uptime-monitoring/dns-monitors/overview",
                       "detect/uptime-monitoring/dns-monitors/configuration"
                     ]
+                  },
+                  {
+                    "group": "ICMP Monitors",
+                    "pages": [
+                      "detect/uptime-monitoring/icmp-monitors/overview",
+                      "detect/uptime-monitoring/icmp-monitors/configuration"
+                    ]
+                  },
+                  {
+                    "group": "Heartbeat Monitors",
+                    "pages": [
+                      "detect/uptime-monitoring/heartbeat-monitors/overview",
+                      "detect/uptime-monitoring/heartbeat-monitors/examples"
+                    ]
                   }
                 ]
               },