diff --git a/detect/uptime-monitoring/dns-monitors/configuration.mdx b/detect/uptime-monitoring/dns-monitors/configuration.mdx index 7ff075d0..7848e7ce 100644 --- a/detect/uptime-monitoring/dns-monitors/configuration.mdx +++ b/detect/uptime-monitoring/dns-monitors/configuration.mdx @@ -318,8 +318,7 @@ Set how often the monitor runs (every 10 seconds to 24 hours): * **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 diff --git a/detect/uptime-monitoring/dns-monitors/overview.mdx b/detect/uptime-monitoring/dns-monitors/overview.mdx index 313d054d..cc0aeb35 100644 --- a/detect/uptime-monitoring/dns-monitors/overview.mdx +++ b/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: diff --git a/detect/uptime-monitoring/icmp-monitors/configuration.mdx b/detect/uptime-monitoring/icmp-monitors/configuration.mdx index 2c3439ec..6bc2edd2 100644 --- a/detect/uptime-monitoring/icmp-monitors/configuration.mdx +++ b/detect/uptime-monitoring/icmp-monitors/configuration.mdx @@ -96,8 +96,7 @@ Set how often the monitor runs (every 10 seconds to 24 hours): * **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 diff --git a/detect/uptime-monitoring/icmp-monitors/overview.mdx b/detect/uptime-monitoring/icmp-monitors/overview.mdx index e42da0b5..16c52c86 100644 --- a/detect/uptime-monitoring/icmp-monitors/overview.mdx +++ b/detect/uptime-monitoring/icmp-monitors/overview.mdx @@ -68,10 +68,32 @@ Learn more in our documentation on [Results](/concepts/results). ## Troubleshooting Common Issues + +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. + + **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 - - - -**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 \ No newline at end of file diff --git a/detect/uptime-monitoring/tcp-monitors/configuration.mdx b/detect/uptime-monitoring/tcp-monitors/configuration.mdx index 2afcd14e..78a83dc4 100644 --- a/detect/uptime-monitoring/tcp-monitors/configuration.mdx +++ b/detect/uptime-monitoring/tcp-monitors/configuration.mdx @@ -60,7 +60,7 @@ Set how often the monitor runs (every 10 seconds to 24 hours): * **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 diff --git a/detect/uptime-monitoring/url-monitors/configuration.mdx b/detect/uptime-monitoring/url-monitors/configuration.mdx index bb2d3570..36ff19c8 100644 --- a/detect/uptime-monitoring/url-monitors/configuration.mdx +++ b/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. URL monitor locations selection interface showing global monitoring locations diff --git a/docs.json b/docs.json index 6feecc89..3c32bafc 100644 --- a/docs.json +++ b/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/", diff --git a/platform/private-locations/agent-configuration.mdx b/platform/private-locations/agent-configuration.mdx index e73e14ff..77160512 100644 --- a/platform/private-locations/agent-configuration.mdx +++ b/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. diff --git a/platform/private-locations/agent-images.mdx b/platform/private-locations/agent-images.mdx new file mode 100644 index 00000000..b621ec96 --- /dev/null +++ b/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 +``` + +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). + +## 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 + + +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. + + + +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. + + + +If `npm install` fails with errors about `node-gyp`, `python`, `gcc`, or "compilation failed", you likely need the dev image. + \ No newline at end of file diff --git a/platform/private-locations/change-log.mdx b/platform/private-locations/change-log.mdx index 724913ec..f5c855c7 100644 --- a/platform/private-locations/change-log.mdx +++ b/platform/private-locations/change-log.mdx @@ -16,6 +16,17 @@ Learn more about: ## Full release history + + - 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` + + - 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: - - 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 @@ -40,7 +51,7 @@ Learn more about: - - 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 diff --git a/platform/private-locations/dev-agent.mdx b/platform/private-locations/dev-agent.mdx deleted file mode 100644 index d067b995..00000000 --- a/platform/private-locations/dev-agent.mdx +++ /dev/null @@ -1,82 +0,0 @@ ---- -title: 'Dev Image' -description: 'Use the dev agent for npm packages that require compilation.' -sidebarTitle: '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. - -## Available Tags - -### Versioned Tags (Recommended) - -```bash -# Runtime (production) -docker pull checkly/agent:1.2.3 - -# Dev (with build tools) -docker pull checkly/agent-dev:1.2.3 -``` - -### Floating Tags - -```bash -# Latest runtime release -docker pull checkly/agent:latest - -# Latest dev release -docker pull checkly/agent-dev:latest -``` - - Use versioned tags for reproducible deployments. Floating tags (like `:latest`) may change between pulls. - -## What's Included in the Dev Image - -The dev image 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`. - -## How to use it - -The dev agent works exactly like the standard agent, but includes the build tools required to compile native modules. - -To use the dev variant, simply change the image tag: - -```bash Dev agent (with build tools) -docker run \ - -e API_KEY="your_api_key_here" \ - --name checkly-agent-dev \ - -d checkly/agent-dev:latest -``` - -All other setup and configuration remains the same. For more information, see the [Private Locations documentation](/platform/private-locations/overview/). - -## FAQ - -### 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. - -### 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. - -### 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. diff --git a/platform/private-locations/overview.mdx b/platform/private-locations/overview.mdx index 63fc145f..72d9b5dc 100644 --- a/platform/private-locations/overview.mdx +++ b/platform/private-locations/overview.mdx @@ -113,7 +113,7 @@ Run production-grade agent deployments on a container orchestrator like Kubernet How to calculate the number of agents and amount of resources needed. - + Use the dev agent for npm packages that require compilation. diff --git a/quickstarts/tcp-monitor.mdx b/quickstarts/tcp-monitor.mdx index 3dc1e47e..014a749f 100644 --- a/quickstarts/tcp-monitor.mdx +++ b/quickstarts/tcp-monitor.mdx @@ -62,7 +62,7 @@ Set how often the monitor runs (every 10 seconds to 24 hours): * **Strategy:** Choose between round-robin or parallel execution. Learn more about [scheduling strategies](/monitoring/global-locations#scheduling-strategies) -* **Locations:** Select one or more [public](/concepts/locations) or [private](/platform/private-locations/overview) locations to run the monitor from +* **Locations:** Select [public](/concepts/locations) or [private](/platform/private-locations/overview) locations to run the monitor from ## Additional Settings diff --git a/quickstarts/url-monitor.mdx b/quickstarts/url-monitor.mdx index ee898063..e74942f9 100644 --- a/quickstarts/url-monitor.mdx +++ b/quickstarts/url-monitor.mdx @@ -56,7 +56,7 @@ Set how often the monitor runs (every 10 seconds to 24 hours). * **Scheduling:** Choose between round-robin or parallel execution. Learn more about [scheduling strategies](/concepts/scheduling) -* **Locations:** Select one or more [public](/concepts/locations) or [private](/platform/private-locations/overview) locations to run the monitor from +* **Locations:** Select [public](/concepts/locations) or [private](/platform/private-locations/overview) locations to run the monitor from ## Additional Settings