Merge pull request #210 from checkly/agent-update-7

TREE-738: Agent v7.0.0 documentation update

Author: ejanusevicius

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

@@ -318,8 +318,7 @@ Set how often the monitor runs (every 10 seconds to 24 hours):
 </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**: DNS monitors do not currently support [private locations](/platform/private-locations/overview)
+* **Locations:** Select [public](/concepts/locations/#public-locations) or [private](/platform/private-locations/overview) locations to run the monitor from
 
 ### Additional Settings
 

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

@@ -60,10 +60,6 @@ DNS monitors support the following DNS record types:
 - **SOA**: Start of authority records
 - **TXT**: Text records (SPF, DKIM, DMARC, etc.)
 
-## Limitations
-
-- **Private locations**: DNS monitors do not currently support private locations. You can only run DNS monitors from Checkly's global public locations.
-
 ## DNS Monitor Results
 
 Select a specific check run to inspect its results:

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

@@ -96,8 +96,7 @@ Set how often the monitor runs (every 10 seconds to 24 hours):
 </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](/platform/private-locations/overview)
+* **Locations:** Select [public](/concepts/locations/#public-locations) or [private](/platform/private-locations/overview) locations to run the monitor from
 
 ### Additional Settings
 

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

@@ -68,10 +68,32 @@ Learn more in our documentation on [Results](/concepts/results).
 
 ## Troubleshooting Common Issues
 
+<Accordion title="NET_RAW capability error on private locations">
+Container runtimes drop the `NET_RAW` capability by default. ICMP requires raw sockets, so the Checkly Agent needs this capability explicitly granted.
+
+**How to fix**:
+
+In **Kubernetes**, update your pod spec or Helm values:
+
+```yaml
+securityContext:
+  capabilities:
+    add: ["NET_RAW"]
+```
+
+In **Docker**:
+
+```bash
+docker run --cap-add=NET_RAW ghcr.io/checkly/agent:latest
+```
+
+`NET_RAW` only grants permission to create raw sockets. It does not escalate broader container privileges.
+</Accordion>
+
 <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**: 
+**Root cause**:
 * Many organizations block ICMP echo request packets at the firewall, load balancer, or host level as a security measure
 
 **How to detect and fix**:
@@ -80,21 +102,4 @@ Learn more in our documentation on [Results](/concepts/results).
 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/tcp-monitors/configuration.mdx

@@ -60,7 +60,7 @@ Set how often the monitor runs (every 10 seconds to 24 hours):
 </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) or [private](/platform/private-locations/overview) locations to run the monitor from
+* **Locations:** Select [public](/concepts/locations/#public-locations) or [private](/platform/private-locations/overview) locations to run the monitor from
 
 ### Additional Settings
 

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

@@ -65,7 +65,7 @@ Learn more in our documentation on [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.
+Select [public](/concepts/locations#public-locations) or [private](/platform/private-locations/overview) locations to run the monitor from.
 
 <Frame>
   <img src="/images/url-monitor-locations.png" alt="URL monitor locations selection interface showing global monitoring locations" />

docs.json

@@ -83,7 +83,7 @@
                     "pages": [
                       "platform/private-locations/overview",
                       "platform/private-locations/agent-configuration",
-                      "platform/private-locations/dev-agent",
+                      "platform/private-locations/agent-images",
                       "platform/private-locations/kubernetes-deployment",
                       "platform/private-locations/proxy-setup",
                       "platform/private-locations/scaling-redundancy",
@@ -1297,6 +1297,10 @@
     {
       "source": "/api-reference/error-groups/retrieve-one-error-group/",
       "destination": "/api-reference/error-groups/retrieve-an-error-group"
+    },
+     {
+      "source": "/platform/private-locations/dev-agent",
+      "destination": "/platform/private-locations/agent-images"
     },
     {
       "source": "/api-reference/error-groups/update-an-error-group-mainly-used-for-archiving-error-groups/",

platform/private-locations/agent-configuration.mdx

@@ -16,6 +16,7 @@ Variable|Description
 `USE_OS_DNS_RESOLVER`|When set to true, TCP monitors will resolve DNS using `getaddrinfo` C function, instead of using the network. This enables easier DNS resolution for internal services e.g. services running in the same Kubernetes cluster.
 `DEPENDENCY_CACHE`|(Default: `OFF`) Set to `CHECKLY_S3` to enable dependency caching for [Playwright Check Suites](/detect/synthetic-monitoring/playwright-checks/overview). Caches installed dependencies between runs to speed up check execution. Learn more about [dependency caching](/detect/synthetic-monitoring/playwright-checks/custom-dependencies#dependency-caching).
 `AGENT_HEALTH_PORT`|(Default: `8081`) Port for the HTTP [health probe endpoints](#health-probe-endpoints).
+`EXTERNAL_OBSERVABILITY`| Enabled by default. Set to `off` to disable [external observability](#external-observability) reporting of agent runtime errors to Checkly.
 
 For example, you can add these variables to the standard docker run command like this:
 
@@ -164,6 +165,18 @@ Endpoint|Description
 
 These endpoints are useful for configuring [Kubernetes readiness and liveness probes](https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes/) or any other container orchestration health checks.
 
+## External Observability
+
+The Checkly Agent reports error-level events to Checkly to help detect crashes, bugs, and environment-related issues. This is enabled by default starting with agent v7.0.0.
+
+Only limited technical metadata is collected (e.g. error messages, stack traces, agent version, platform, go runtime information). Sensitive data such as API keys, environment variables, check configuration, URLs, headers, and response bodies is **never** sent.
+
+To disable external observability, set the `EXTERNAL_OBSERVABILITY` environment variable to `off`:
+
+```bash Terminal
+-e EXTERNAL_OBSERVABILITY=off
+```
+
 ## Agent Version and Runtimes
 
 Each Checkly Agent only supports specific [runtimes](/platform/runtimes/overview/). This is to keep the container image at an acceptable size. When you change the runtime a check uses, you may also need to change to the corresponding agent version. Similarly, if you update the agent version to one using a different runtime you also need to update your checks to use the same runtime.

platform/private-locations/agent-images.mdx

@@ -0,0 +1,88 @@
+---
+title: 'Agent Images'
+sidebarTitle: 'Agent Images'
+---
+
+Checkly provides different agent images:
+
+* [Standard](#standard-image): The full agent image, supporting all check types
+
+* [Dev](#dev-image): The standard image with build tools for compiling npm packages with native dependencies
+
+* [Uptime](#uptime-image): A lightweight image for running uptime monitors only
+
+## Image Tag Format
+
+Image tags define which agent variant and version you run.
+
+```bash
+# Standard
+docker pull checkly/agent:X.Y.Z
+
+# Dev (with build tools)
+docker pull checkly/agent-dev:X.Y.Z
+
+# Uptime
+docker pull checkly/agent-uptime:X.Y.Z
+```
+
+<Note>Use versioned tags for reproducible deployments. Floating tags (like `:latest`) may change between pulls. Browse available versions on [Docker Hub](https://hub.docker.com/r/checkly/agent/tags).</Note>
+
+## Standard Image
+
+The standard image (`checkly/agent:X.Y.Z`) is the default and recommended option for most setups.
+
+It supports the full range of Checkly monitors:
+
+* [Synthetic checks](/detect/synthetic-monitoring/overview): API, Multistep, Browser and Playwright Check Suites
+* [Uptime monitors](/detect/uptime-monitoring/overview): URL, DNS, TCP, ICMP, Heartbeat
+
+Use the standard image unless you have a specific need for the dev or uptime variants.
+
+## Uptime Image
+
+The uptime image (`checkly/agent-uptime:X.Y.Z`) is a lightweight version of the agent designed for [uptime monitoring](/detect/uptime-monitoring/overview) only.
+
+It supports URL, DNS, TCP, ICMP and Heartbeat monitors.
+
+## Dev Image
+
+If any of the checks you run on Private Locations rely on npm packages with native code, those packages need to be compiled during installation.
+
+The standard agent is optimized for size and doesn’t ship with build tools. In those cases, you’ll need to use the dev image instead.
+
+#### When to Use the Dev Image
+
+Use the dev image (`checkly/agent-dev:X.Y.Z`) when your checks require npm packages with native dependencies that need compilation. Common examples include:
+
+- `sqlite3` - SQLite database
+- `zookeeper` - Apache ZooKeeper client
+
+If your checks only use pure JavaScript packages, the standard runtime image is recommended for its smaller size and faster startup.
+
+#### What's Included in the Dev Image
+
+The dev agent works exactly like the standard agent, but includes the build tools required to compile native modules. 
+
+It adds the following to the standard image:
+
+| Tool | Purpose |
+|------|---------|
+| `gcc`, `g++`, `make` | Compile native extensions |
+| `python3` | Required by node-gyp |
+
+These tools enable compilation of native Node.js modules during `npm install`.
+
+#### FAQ
+
+<Accordion title="Can I use the dev image in production?">
+Yes, the dev image is production-ready. It contains the same runtime as the standard image, plus build tools. The only tradeoff is a larger image size.
+</Accordion>
+
+<Accordion title="Do I need the dev image for Playwright checks?">
+No. Playwright and its dependencies are pre-installed in both variants. You only need the dev image if your check code imports npm packages with native dependencies.
+</Accordion>
+
+<Accordion title="How do I know if a package needs the dev image?">
+If `npm install` fails with errors about `node-gyp`, `python`, `gcc`, or "compilation failed", you likely need the dev image.
+</Accordion>

platform/private-locations/change-log.mdx

@@ -16,6 +16,17 @@ Learn more about:
 
 ## Full release history
 
+<Update label="v7.0.0" tags={["March 2026"]}>
+  - Added support for running [ICMP](/detect/uptime-monitoring/icmp-monitors/overview) and [DNS monitors](/detect/uptime-monitoring/dns-monitors/overview) on Private Locations
+  - Introduced the [uptime agent image](/platform/private-locations/agent-images#uptime-image), a lightweight version of the agent for running uptime monitors (URL, DNS, TCP, ICMP, Heartbeat) only
+  - Added [external observability](/platform/private-locations/agent-configuration#external-observability) for Private Location agents to capture runtime errors
+    - Error-level events can be reported to Checkly to help detect crashes, bugs, and environment-related issues
+    - Only limited technical metadata is collected (error message, stack trace, agent version, platform, Go runtime)
+    - Sensitive data such as API keys, environment variables, check configuration, URLs, headers, and response bodies is never sent
+    - Enabled by default, can be disabled with `EXTERNAL_OBSERVABILITY=off`
+  - Support for runtime `2026.04`
+</Update>
+
 <Update label="v6.3.2" tags={["March 2026"]}>
   - Improved error logging for failed Playwright test report uploads, including the report file size
   - Increased the maximum artifact upload size from 75 MB to 150 MB
@@ -30,7 +41,7 @@ Learn more about:
 </Update>
 
 <Update label="v6.3.0" tags={["December 2025"]}>
-  - Added [agent-dev image](https://www.checklyhq.com/docs/platform/private-locations/dev-agent/) including build tools to support building native npm packages. Going forward, the dev variant is published as a separate image rather than a tag on the main agent image
+  - Added [agent-dev image](https://www.checklyhq.com/docs/platform/private-locations/agent-images/) including build tools to support building native npm packages. Going forward, the dev variant is published as a separate image rather than a tag on the main agent image
   - Improved secret scrubbing speed
   - Improved error logging for hanging or long running Playwright Check Suite jobs
 </Update>
@@ -40,7 +51,7 @@ Learn more about:
 </Update>
 
 <Update label="v6.1.7" tags={["December 2025"]}>
-  - Added support for a [dev image](https://www.checklyhq.com/docs/platform/private-locations/dev-agent/) including build tools to support building native npm packages
+  - Added support for a [dev image](https://www.checklyhq.com/docs/platform/private-locations/agent-images/) including build tools to support building native npm packages
   - Improved internal logging and metrics for [Playwright Check Suites](/detect/synthetic-monitoring/playwright-checks/overview)
   - Browser and Multistep checks using runtime 2025.04 now automatically scrub the `Authorization` header from requests
 </Update>