diff --git a/detect/uptime-monitoring/dns-monitors/configuration.mdx b/detect/uptime-monitoring/dns-monitors/configuration.mdx index 7ff075d0..2edbe2c5 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 one or more [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..43c77c14 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 one or more [public](/concepts/locations/#public-locations) or [private](/platform/private-locations/overview) locations to run the monitor from ### Additional Settings diff --git a/docs.json b/docs.json index 428afa15..d4592ff4 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", @@ -1273,6 +1273,10 @@ { "source": "/api-reference/error-groups/update-an-error-group-mainly-used-for-archiving-error-groups/", "destination": "/api-reference/error-groups/update-an-error-group" + }, + { + "source": "/platform/private-locations/dev-agent", + "destination": "/platform/private-locations/agent-images" } ] } diff --git a/platform/private-locations/agent-configuration.mdx b/platform/private-locations/agent-configuration.mdx index e73e14ff..804cbfd2 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`|(Default: `ON`) 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..ed445662 --- /dev/null +++ b/platform/private-locations/agent-images.mdx @@ -0,0 +1,105 @@ +--- +title: 'Agent Images' +sidebarTitle: 'Agent Images' +--- + +Checkly provides different agent images tailored to specific use cases: + +* **Standard**: The full agent image, supporting all check types + +* **Dev**: The standard image with build tools for compiling npm packages with native dependencies + +* **Uptime**: A lightweight image for running uptime monitors only + +## Image Tag Format + +Image tags define which agent variant and version you run. + +#### 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 + +# Uptime +docker pull checkly/agent-uptime:1.2.3 +``` + +#### Floating Tags + +```bash +# Latest runtime release +docker pull checkly/agent:latest + +# Latest dev release +docker pull checkly/agent-dev:latest + +# Latest uptime release +docker pull checkly/agent-uptime:latest +``` + + Use versioned tags for reproducible deployments. Floating tags (like `:latest`) may change between pulls. + +## 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: API, Multistep, Browser and Playwright Check Suites +* Uptime monitors: 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) is a lightweight version of the agent designed for uptime monitoring only. + +It supports URL, DNS, TCP, ICMP and Heartbeat monitors. + +Use this image if you only need uptime checks and want a smaller, more focused runtime. + +## 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..b9429eaa 100644 --- a/platform/private-locations/change-log.mdx +++ b/platform/private-locations/change-log.mdx @@ -16,6 +16,16 @@ Learn more about: ## Full release history + + - Added support for running ICMP and DNS monitors on Private Locations + - Introduced the [uptime agent image](LINK), a lightweight version of the agent for running uptime monitors (URL, DNS, TCP, ICMP, Heartbeat) only + - Added 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` + + - 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 +40,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 +50,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.