From 88718f920d7843efbe89244217035083dfe9c1bd Mon Sep 17 00:00:00 2001 From: Hannes Lenke Date: Wed, 28 Oct 2026 21:21:21 -0400 Subject: [PATCH] docs: document CHECKLY_RUN_FILE_MAX_BYTES and the Outdated agent badge (checkly/agent 8.12.0) Agent 8.12.0 reads a new environment variable, CHECKLY_RUN_FILE_MAX_BYTES, that caps the size of the files it reads from a Browser or Multistep check run and uploads, such as the Playwright report. The agent configuration page now lists the variable with its proven default (2147483647 bytes), the omitted-report log line, the 2 GiB cap and the 14 MiB fallback for an invalid value. The v8.12.0 changelog entry gets a bullet for it. Since the 8.12.0 release the API and the private location page flag agents on an older version as Outdated (isOutdated: true in runningAgents). The "Updating the agent container" section now says so. Proof: release-watch/2026-10-28/run3/agent-8.12.0 (docker runs of checkly/agent:8.12.0 against a mock API, probes inside the image, 8.11.0 as control, local API and webapp on monorepo 5858d7e03f with seeded agent heartbeats). Co-Authored-By: Claude Opus 5.5 --- platform/private-locations/agent-configuration.mdx | 3 +++ platform/private-locations/change-log.mdx | 1 + 2 files changed, 4 insertions(+) diff --git a/platform/private-locations/agent-configuration.mdx b/platform/private-locations/agent-configuration.mdx index ae4504a6..a92b1f96 100644 --- a/platform/private-locations/agent-configuration.mdx +++ b/platform/private-locations/agent-configuration.mdx @@ -19,6 +19,7 @@ Variable|Description `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_SERVER_PORT`|(Default: `8080`) Port for the HTTP [health probe endpoints](#health-probe-endpoints) and Prometheus metrics. Applies to agent v8.12.0 and later. Earlier agents use `AGENT_HEALTH_PORT` (default `8081`) for health probes. `EXTERNAL_OBSERVABILITY`| Enabled by default. Set to `off` to disable [external observability](#external-observability) reporting of agent runtime errors to Checkly. +`CHECKLY_RUN_FILE_MAX_BYTES`|(Default and maximum: 2147483647 bytes, just under 2 GiB) Largest file, in bytes, that the agent reads from a Browser or Multistep check run and uploads, such as the Playwright report. A larger file is left out of the check result, not truncated. For the Playwright report, the check log says `Report omitted because it is larger than MiB`. A value that is not a positive integer is ignored with a warning in the agent log, and the limit is then 14 MiB. Applies to agent v8.12.0 and later. For example, you can add these variables to the standard docker run command like this: @@ -71,6 +72,8 @@ New versions of the Checkly Agent are released regularly to [Docker Hub](https:/ View our [changelog](/platform/private-locations/change-log) to learn more about each version. +Agents running a version older than v8.12.0 are shown with an **Outdated** badge under **Connected agents by version** on the private location page, and the API returns `isOutdated: true` for them in `runningAgents` (`GET /v1/private-locations/{id}`, or `GET /v1/private-locations?versions=true` for all private locations). Update them to v8.12.0 or later. + ### Manual updates To manually upgrade your Checkly Agent containers, first pull the image: diff --git a/platform/private-locations/change-log.mdx b/platform/private-locations/change-log.mdx index 4269e9ce..5d735b40 100644 --- a/platform/private-locations/change-log.mdx +++ b/platform/private-locations/change-log.mdx @@ -26,6 +26,7 @@ Learn more about: - Playwright Check Suites scrub secrets several times faster. - The agent now exposes a single port, 8080, for health probes and Prometheus metrics. If your Kubernetes probes or scrape configuration use port 8081 or 8082, point them to 8080. - A single `/metrics` endpoint now covers every check type the agent runs. Use the `component` label to separate uptime metrics from synthetics metrics. Metric names and labels are consistent across both, so one dashboard covers the whole agent. +- Added the `CHECKLY_RUN_FILE_MAX_BYTES` environment variable to cap the size of files the agent reads from a Browser or Multistep check run, such as the Playwright report. A file above the cap is left out of the check result. The default is just under 2 GiB. See [agent configuration](/platform/private-locations/agent-configuration).