跳转至

浏览器拨测

Version-2.1.0


浏览器拨测属于 inputs.dialtesting 采集器中的 BROWSER 任务类型,用于通过 Lightpanda 或 Chrome 浏览器引擎模拟页面访问、交互和断言,并上报页面性能、步骤结果、失败原因及可选的失败截图。

基础拨测节点配置请参考网络拨测。本文只说明浏览器拨测相关的额外配置、部署和排查方式。

使用要求

浏览器拨测在 Linux 拨测节点上默认开启;非 Linux 环境下,DataKit 服务模式不会执行 BROWSER 任务,本地 debug 验证模式除外。

DataKit 默认使用 Lightpanda 执行 BROWSER 任务,也可显式选择 chrome 引擎运行官方 Chrome Headless Shell。任务中的 advance_options.engine 会被节点配置覆盖。Chrome 方案使用未经修改的官方二进制,只调整启动参数;不构建或使用自改 Chromium。

Chrome Headless Shell

datakit:<version> 镜像同时内置 Lightpanda 和官方 Chrome Headless Shell,默认使用 Lightpanda。主机部署需要自行安装所选浏览器。选择 engine = "chrome" 并通过 engine_path 指向对应可执行文件:

[inputs.dialtesting.browser]
  engine = "chrome"
  engine_path = "/usr/local/bin/chrome-headless-shell"
  load_images = false
  load_fonts = false
  allow_no_sandbox = true
  max_concurrency = 1

load_images、load_fonts 默认均为 false,分别禁止加载图片和网页字体;设置为 true 恢复对应资源加载。这两个配置只影响 Chrome/Chrome Headless Shell,不改变 Lightpanda 行为。也可使用环境变量 ENV_INPUT_DIALTESTING_BROWSER_LOAD_IMAGES、ENV_INPUT_DIALTESTING_BROWSER_LOAD_FONTS。

allow_no_sandbox 是拨测采集器的节点级配置,默认 true,对应环境变量为 ENV_INPUT_DIALTESTING_BROWSER_ALLOW_NO_SANDBOX,不影响 Lightpanda。非 root 用户仍先尝试启用 Chrome sandbox;只有启动明确报沙箱不可用时才允许关闭沙箱重试一次,并记录警告。root 用户在允许兼容模式时直接关闭沙箱启动。需要严格保留浏览器沙箱时,设置 allow_no_sandbox = false 或将对应环境变量设为 false,并使用非 root 用户及可用的沙箱配置;root 启动或沙箱不可用时会明确失败。任务脚本不能覆盖节点设置。默认值优先保证启动兼容性,关闭沙箱会失去浏览器自身的这层隔离保护。

DK 镜像设置了浏览器路径环境变量,切换引擎时可省略 engine_path。ENV_INPUT_DIALTESTING_BROWSER_ENGINE=lightpanda 或 chrome 选择节点引擎,默认仍为 lightpanda。Chrome 入口为官方 Shell 添加低内存启动参数;如需关闭该参数组合,可将 engine_path 改为 /usr/local/bin/chrome-headless-shell-standard,两者使用同一个官方二进制。

Chrome 的查找顺序为 engine_path、CHROME_EXECUTABLE_PATH、PATH 中的 chrome-headless-shell。显式配置的路径不可用时会直接报错,不回退到其他浏览器;自动查找不会选择桌面 Chrome、Chromium 或实验用的 headless_shell。

禁用加载不模拟加载成功:页面依赖图片 load 事件、验证码、二维码或字体加载成功时,应开启对应配置。截图和页面性能测量任务也应按需开启;字体回退会改变布局。这些是节点级配置,会影响该节点的 Chrome 浏览器任务。

Chrome 引擎通过每任务受控代理执行 disable_internal_network_task 对应的私网/CIDR 限制,详见内网拨测与代理。目前仍不支持 browser.ca_cert_file、browser.ca_cert_dir,配置后任务会明确失败;Chrome 使用系统证书信任库。Chrome 保留站点隔离,sandbox 行为由节点的 allow_no_sandbox 控制。当前每个任务独立启动浏览器,不跨租户共享会话或浏览器进程。

DataKit 按以下顺序查找 Lightpanda:

  1. [inputs.dialtesting.browser].engine_path
  2. LIGHTPANDA_EXECUTABLE_PATH
  3. PATH 中的 lightpanda

如需显式关闭浏览器拨测,可在 dialtesting.conf 中设置:

[[inputs.dialtesting]]
  [inputs.dialtesting.browser]
    enabled = false

max_concurrency 限制此采集器同时执行的浏览器任务总数,未设置时默认为 8。超出限制的任务会等待,可能增加调度延迟。0 表示不限制;升级后原有显式 0 仍不限制,如需限制请改为 8。资源受限节点建议设置为 1。

Kubernetes 部署

在 Deployment 的容器环境变量中选择浏览器,例如切换到 Chrome Headless Shell:

env:
  - name: ENV_INPUT_DIALTESTING_BROWSER_ENGINE
    value: "chrome"
  - name: ENV_INPUT_DIALTESTING_BROWSER_ENGINE_PATH
    value: "/usr/local/bin/chrome-headless-shell"

使用 DK 镜像时,也可省略 ENV_INPUT_DIALTESTING_BROWSER_ENGINE_PATH,使用镜像内的默认路径。切回 Lightpanda 时,将引擎设为 lightpanda;若已显式指定路径,同步改为 /usr/local/bin/lightpanda。配置对该采集器执行的浏览器任务统一生效,覆盖任务的 advance_options.engine。更新 Deployment 后重建 Pod,使新环境变量生效。

Kubernetes 中直接使用 DK 镜像:

pubrepo.guance.com/datakit/datakit:<version>

正式版和测试版都使用普通 DK 镜像 tag,两个浏览器无需分别选择镜像。例如版本号为 2.18.0 时:

用途 镜像 tag 示例
正式版 datakit:2.18.0
测试版 datakit:2.18.0-testing_testing-3308

默认仍使用 Lightpanda,只有显式设置 engine = "chrome" 才会切换到官方 Headless Shell。

镜像基于 Ubuntu 24.04,支持 Linux amd64、arm64,内置官方 Lightpanda 1.0.2、官方 Chrome Headless Shell 157.0.8103.38 和中英文字体。浏览器位于可复用的镜像层,DK 更新可复用已缓存的浏览器文件。数据库客户端、Python、Jolokia 和 externals 外部采集器继续保留。

镜像沿用普通 DK 的默认 root 运行账号。allow_no_sandbox = true 时,root 用户关闭 Chrome sandbox 启动。需要启用 sandbox 时,以非 root 用户运行,例如镜像内的 UID/GID 10001:10001,设置可写的 HOME,并确保挂载的配置、缓存和日志目录允许该用户读写;同时设置 allow_no_sandbox = false,为用户命名空间准备相应运行时权限。ICMP/NETPATH 的原始套接字功能也需要相应网络权限。

需要保留 Chrome sandbox 时,Docker 默认 seccomp 策略可能阻止浏览器创建用户命名空间。可按部署要求使用 Playwright v1.64.1 的官方配置,下载后使用 docker run --security-opt seccomp=./seccomp_profile.json ... 引用。Kubernetes 可由节点管理员提供允许浏览器用户命名空间的等效运行时配置。该配置只补充浏览器 sandbox 所需的系统调用权限,跨租户仍需独立容器及出口网络策略。

如需使用自定义 Lightpanda 二进制,可通过挂载方式提供可执行文件,并配置 engine_path:

[[inputs.dialtesting]]
  [inputs.dialtesting.browser]
    enabled = true
    engine = "lightpanda"
    engine_path = "/opt/datakit-browser/bin/lightpanda"
    max_concurrency = 8

主机部署

主机部署时,先选择浏览器引擎,再安装对应浏览器。只需安装所选引擎,不要求同时安装两个。DataKit 主机安装器目前不会自动安装 Chrome Headless Shell;浏览器固定版本安装一次后,日常升级 DK 可继续复用。

选择 主机需要准备的内容
Lightpanda Lightpanda 可执行文件及其所需的系统运行库,安装方法见下文
Chrome 官方 Chrome Headless Shell,以及对应版本的系统库、字体和 sandbox 配置

以下示例以 Linux 主机为例,使用固定版本的官方 Headless Shell。浏览器由 DataKit 按任务启动,无需另外运行常驻浏览器服务。

安装 Lightpanda

DK 镜像使用官方 Lightpanda 1.0.2,固定下载地址及 SHA-256,并通过 Ubuntu 24.04 提供运行库。主机安装时,amd64 二进制要求 glibc 2.35,arm64 二进制实际引用 glibc 2.38 符号,不能直接用于 Ubuntu 22.04。以下是在 x86_64 Linux 主机上安装官方 1.0.2 的示例:

curl -fL -o lightpanda \
  https://github.com/lightpanda-io/browser/releases/download/1.0.2/lightpanda-x86_64-linux
echo "ae7d01d261efb9e480e18ce3424533332883863bcf70b12a4321b5733f37e19e  lightpanda" | sha256sum -c -
sudo install -m 0755 lightpanda /usr/local/bin/lightpanda
rm lightpanda

arm64/aarch64 Linux 可使用:

curl -fL -o lightpanda \
  https://github.com/lightpanda-io/browser/releases/download/1.0.2/lightpanda-aarch64-linux
echo "ac546dfc43c533430da92b75ab36f2a29da7d6324d5d38baf606ef2e0d849345  lightpanda" | sha256sum -c -
sudo install -m 0755 lightpanda /usr/local/bin/lightpanda
rm lightpanda

安装完成后确认版本:

lightpanda version
lightpanda serve --help

安装 Headless Shell

以下示例固定使用官方 Chrome Headless Shell 157.0.8103.38,支持 Linux amd64 和 arm64。版本、下载地址与 SHA-256 必须一起更新。下载来源为 Chrome for Testing,Google 下载地址不可达或过慢时,示例会回退到微软 Playwright 镜像,并使用相同校验和验证文件。其他下载站只有在同步了对应文件并验证校验和后才能使用。

准备 curl、unzip 和 CA 证书;例如在 Ubuntu 上执行:

sudo apt-get update
sudo apt-get install -y --no-install-recommends ca-certificates curl unzip

下载、校验并安装到独立的版本目录:

(
  set -eu
  version=157.0.8103.38
  case "$(uname -m)" in
    x86_64|amd64)
      platform=linux64
      sha256=deafffa74660b34853a4119c361fd427ac8c9fcb62db51ddb8a797cd83a4ba2d
      ;;
    aarch64|arm64)
      platform=linux-arm64
      sha256=b9b910a57b2a15eb3e55000a2339f93a973934a413ebfc6e585a50ec6c42fd6c
      ;;
    *) echo "Unsupported architecture: $(uname -m)" >&2; exit 1 ;;
  esac
  install_dir="/opt/datakit-browser/chrome-headless-shell-$version"
  if [ -e "$install_dir" ]; then
    echo "Target exists: $install_dir; use the installed version or a new version directory" >&2
    exit 1
  fi
  download_dir=$(mktemp -d)
  trap 'rm -rf -- "$download_dir"' EXIT
  archive="$download_dir/chrome.zip"
  download_path="$version/$platform/chrome-headless-shell-$platform.zip"
  if ! curl -fL --retry 1 --connect-timeout 10 --max-time 180 --speed-limit 65536 --speed-time 20 \
      "https://storage.googleapis.com/chrome-for-testing-public/$download_path" -o "$archive"; then
    curl -fL --retry 3 --connect-timeout 10 --max-time 180 \
      "https://cdn.playwright.dev/builds/cft/$download_path" -o "$archive"
  fi
  echo "$sha256  $archive" | sha256sum -c -
  unzip -q "$archive" -d "$download_dir"
  sudo install -d -m 0755 /opt/datakit-browser
  sudo mv -T "$download_dir/chrome-headless-shell-$platform" "$install_dir"
  sudo chown -R root:root "$install_dir"
  sudo chmod 0755 "$install_dir" "$install_dir/chrome-headless-shell"
)

Headless Shell 运行要求

Headless Shell 使用 Chromium 的页面执行和渲染能力,实际仍会链接 GLib、NSS、X11/GBM、ATK、ALSA 等共享库。系统库之间还有传递依赖,所以包数量可能较多;这些库可由包管理器一次解析安装,已有的包会复用。无需安装桌面环境或启动 X Server。具体依赖随浏览器版本、发行版和架构变化,不能把通用 Chrome 清单当成所有主机的固定安装清单。

先检查当前主机缺少哪些动态库:

ldd /opt/datakit-browser/chrome-headless-shell-157.0.8103.38/chrome-headless-shell

输出中的 not found 表示缺少对应运行库。下面是 Ubuntu 24.04 的安装示例,不代表跨发行版通用的最小依赖集合:

sudo apt-get install -y --no-install-recommends \
  ca-certificates libstdc++6 libatomic1 libsystemd0 \
  libasound2t64 libatk-bridge2.0-0t64 libatk1.0-0t64 libatspi2.0-0t64 \
  libcairo2 libcups2t64 libdbus-1-3 libdrm2 libgbm1 libglib2.0-0t64 \
  libnspr4 libnss3 libpango-1.0-0 libx11-6 libxcb1 libxcomposite1 \
  libxdamage1 libxext6 libxfixes3 libxkbcommon0 libxrandr2

Ubuntu 22.04、Debian 等发行版的包名可能不同,尤其是带 t64 后缀的包,不应直接照搬上述命令。可参考 Chrome Linux 运行依赖说明,结合 ldd 输出补齐。出现 GLIBC_x.y not found 时,需要使用兼容的浏览器构建或运行环境,不要直接替换系统 glibc。ldd 检查通过后,仍需验证浏览器启动和实际拨测任务。

字体按页面需求安装。例如在 Ubuntu 上,英文和中文截图可使用:

sudo apt-get install -y --no-install-recommends fonts-liberation fonts-noto-cjk
# 页面需要 Emoji 时再安装:
# sudo apt-get install -y --no-install-recommends fonts-noto-color-emoji

load_fonts = false 只禁用网页字体下载,系统回退字体仍会参与布局和截图。缺少中文字体可能出现方框,字体不同也可能改变布局,因此字体应纳入拨测节点的环境配置。

磁盘容量需覆盖浏览器、系统库和字体;实际新增空间以下载文件及包管理器提示为准。磁盘占用不代表运行内存。

使用 DataKit 实际运行用户检查版本,例如服务账号为 datakit 时执行:

sudo -u datakit /opt/datakit-browser/chrome-headless-shell-157.0.8103.38/chrome-headless-shell --version

--version 只能检查二进制和基础运行库,不能证明 sandbox 或完整页面流程可用。浏览器继承 DataKit 的运行账号;单独执行一次 sudo -u datakit 不会改变 DK 服务账号。建议由非 root 的拨测 DK 实例启动 Chrome,并为该账号准备可写的配置、缓存和日志目录。要保留 Chrome sandbox,设置 allow_no_sandbox = false,并允许所需的用户命名空间;Ubuntu 24.04 等环境可能还需要针对浏览器安装路径配置 AppArmor,参考 Chromium 用户命名空间说明。前文的 Docker seccomp 文件用于容器部署,不能替代主机的 AppArmor 配置。只有允许兼容模式时,DK 才会在沙箱不可用后追加 --no-sandbox 重试;其他启动错误不会触发此重试。

配置 DataKit

复制拨测采集器配置:

cd /usr/local/datakit/conf.d/samples
sudo cp dialtesting.conf.sample ../dialtesting.conf

编辑 /usr/local/datakit/conf.d/dialtesting.conf,建议显式指定浏览器引擎和路径:

[[inputs.dialtesting]]
  server = "https://dflux-dial.guance.com"
  region_id = "<your-private-node-id>"
  ak = "<your-ak>"
  sk = "<your-sk>"
  pull_interval = "1m"
  time_out = "30s"

  [inputs.dialtesting.browser]
    engine = "lightpanda"
    engine_path = "/usr/local/bin/lightpanda"
    max_concurrency = 8

  [inputs.dialtesting.tags]
    region = "<your-region>"

选择 Chrome 时,在同一个拨测采集器的 browser 配置中改用以下内容;不要再新增一个 inputs.dialtesting 实例:

[inputs.dialtesting.browser]
  engine = "chrome"
  engine_path = "/opt/datakit-browser/chrome-headless-shell-157.0.8103.38/chrome-headless-shell"
  load_images = false
  load_fonts = false
  max_concurrency = 1

需要图片、网页字体或完整截图时,按页面需求开启 load_images、load_fonts。Chrome 的网络策略和自定义 CA 限制见前文,同样适用于主机部署。

也可以按所选引擎设置浏览器路径环境变量:

export LIGHTPANDA_EXECUTABLE_PATH=/usr/local/bin/lightpanda
# 选择 chrome 引擎时使用:
# export CHROME_EXECUTABLE_PATH=/opt/datakit-browser/chrome-headless-shell-157.0.8103.38/chrome-headless-shell

路径环境变量不会自动切换引擎,仍需配置 engine = "chrome" 或 engine = "lightpanda"。如果 DataKit 以 systemd 服务方式运行,当前 shell 中的 export 通常不会传递给 DataKit 服务进程。主机部署时更推荐在 dialtesting.conf 中配置 engine_path;使用环境变量时,应写入服务的环境配置再重启。

修改配置后重启 DataKit:

sudo datakit service restart

自定义 CA 证书

对于由企业或私有 CA 签发的站点证书,可在拨测节点导入 Lightpanda 信任的 CA:

[inputs.dialtesting.browser]
  ca_cert_file = "/etc/datakit/certs/internal-ca.pem"
  # ca_cert_dir = "/etc/datakit/certs"

请使用 PEM 证书。ca_cert_dir 会读取目录内的证书文件,两个字段可以同时配置。路径必须是拨测节点上的绝对路径,文件中不得包含私钥。

也可以使用 ENV_INPUT_DIALTESTING_BROWSER_CA_CERT_FILE 和 ENV_INPUT_DIALTESTING_BROWSER_CA_CERT_DIR。在 Kubernetes 中,可通过 ConfigMap 或 Secret 将 CA 证书挂载到 DataKit 容器,再配置容器内路径。

导入 CA 后仍会校验证书链、访问域名和证书有效期。该配置属于拨测节点级信任设置,不能由单个 BROWSER 任务覆盖。Lightpanda 在收到自定义 CA 参数时会替换当前信任池,因此 DataKit 会把检测到的系统 CA 目录与配置的自定义 CA 文件或目录作为不同参数同时传入。系统证书和自定义证书仍保留在各自目录中,只在 Lightpanda 内存中加载到同一个信任池。

内网拨测与代理

DataKit 默认禁止拨测内网地址。私有拨测节点需要访问 loopback、RFC1918 或 link-local 地址时,在拨测采集器中关闭该限制:

[[inputs.dialtesting]]
  disable_internal_network_task = false

DataKit 还会把该设置传给 Lightpanda。保持默认的 disable_internal_network_task = true 且未配置自定义 CIDR 列表时,Lightpanda 使用 --block-private-networks 启动。配置 disabled_internal_network_cidr_list 后,DataKit 会通过 --block-cidrs 精确阻断这些范围,不再阻断全部私网范围。将 disable_internal_network_task 设置为 false 时,Lightpanda 允许私网请求,无需另外配置引擎专用环境变量。

Chrome 使用同一组节点配置。启用限制后,DataKit 在进程内为每个任务启动仅监听随机 loopback 端口的受控代理,任务完成、启动失败或取消时关闭代理及其连接;无需额外安装代理服务或开放容器端口。HTTP、HTTPS 和 WebSocket 请求均经过代理,包括页面子资源和浏览器跟随重定向发出的请求。每次建立目标连接时,代理检查域名解析得到的全部 IPv4/IPv6 地址,任一地址命中禁用范围即拒绝,并直接连接检查通过的 IP,避免二次解析。HTTPS 使用 CONNECT 隧道,保留浏览器与站点之间的 TLS 和证书校验。

内置受控代理由 DataKit 自动管理,不需要配置 proxy_url。未配置该字段时,受控代理在检查地址后直接连接目标站点,私网/CIDR 限制仍然生效。proxy_url 仅用于再接入额外的上游代理;下文对上游协议、认证和 CONNECT 的要求只适用于这种额外代理。

Linux 主机和容器部署共用上述机制,不依赖 Kubernetes 或 NetworkPolicy,也不会自动修改主机或集群的防火墙规则。平台层网络策略由部署方管理。

默认范围包含私网、loopback、link-local、CGNAT 和 198.18.0.0/15 基准测试网段等非公网地址。自定义 disabled_internal_network_cidr_list 会替换默认范围,与 Lightpanda 的配置语义一致。域名被节点 DNS 解析到这些地址时也会阻断;不能以域名看起来是公网为由跳过检查。非法 CIDR 会使 Chrome 任务明确失败。

受控模式关闭 Chrome 的隐式 loopback 代理旁路、QUIC 和 WebRTC 非代理 UDP;该模式下不测量 HTTP/3 或直接 UDP 媒体路径。启动参数和应用代理仍不能代替容器/Pod 的出口网络策略。多租户部署应使用独立容器边界,并按允许的目的地址和协议限制出口,防止其他网络路径或浏览器漏洞绕过;共享网络命名空间中的 loopback 端口不是租户隔离边界。

同时支持 HTTP/2 或 HTTP/1.1 的站点仍可通过回退协议进行浏览器拨测,但结果不代表 HTTP/3 的连接性能;仅支持 HTTP/3 的站点不适用此受控模式。原生 HTTP 拨测的 HTTP/3 直连能力独立于浏览器代理,目前也不支持代理配置。

Lightpanda 1.0.2 支持以下默认 HTTP 代理配置:

[inputs.dialtesting.browser]
  proxy_url = "http://proxy.example.com:8080"
  # proxy_url = "http://user:password@proxy.example.com:8080"

也可以使用环境变量 ENV_INPUT_DIALTESTING_BROWSER_PROXY_URL。代理的生效优先级为:任务 advance_options.proxy_url > browser_config 中的 proxy_url > 节点 browser.proxy_url。Lightpanda 使用会解密 HTTPS 流量的代理时,需要通过 ca_cert_file 或 ca_cert_dir 导入代理 CA。

Chrome 也使用 proxy_url 及上述优先级,支持 HTTP/HTTPS 上游代理和 URL 中的 Basic 用户名、密码。DataKit 通过每任务受控代理连接上游,凭据不放入 Chrome 启动参数,也不转发给目标站点。上游必须支持对已解析的目标 IP:port 建立 CONNECT 隧道,包括访问 HTTP 站点所用的端口;不支持 SOCKS、PAC 或 NTLM 等认证方式,配置不会静默退回直连。域名由拨测节点解析,因此依赖上游专用 DNS 的环境需先配置节点解析。

节点管理员配置的 [inputs.dialtesting.browser].proxy_url(包括对应的节点环境变量)作为可信上游,允许其代理端点位于内网,最终目标仍严格执行私网/CIDR 检查。该信任仅在实际选用节点代理时生效;任务 advance_options.proxy_url 或 browser_config 的 proxy_url 覆盖节点设置后,上游代理自身的解析 IP 也接受节点 CIDR 策略检查,即使填写了与节点相同的地址,也不会继承信任。空白代理值视为未配置,继续使用下一优先级。

HTTPS 上游代理使用节点系统 CA 并始终校验证书,不受任务 ignore_https_errors 影响。Chrome 不支持上述 ca_cert_file、ca_cert_dir;需要信任企业 CA 时,应通过部署环境管理系统信任库。

本地验证

如果暂时没有通过页面下发 BROWSER 任务,可以用本地 JSON 任务验证浏览器执行链路。browser_config 是 YAML 字符串。

浏览器脚本示例:

name: browser-homepage
target: https://example.com
timeout_ms: 60000
viewport:
  width: 1280
  height: 720
steps:
  - name: open page
    action: goto
    url: https://example.com
  - name: assert title
    action: assert_title
    contains: Example

创建 /tmp/dialtesting-browser-task.json。写入 JSON 时,需要将上面的 YAML 作为字符串放到 browser_config 中,换行用 \n 表示:

{
  "BROWSER": [
    {
      "name": "browser-homepage",
      "url": "https://example.com",
      "status": "OK",
      "frequency": "1m",
      "post_url": "https://openway.guance.com?token=<your-token>",
      "browser_config": "name: browser-homepage\ntarget: https://example.com\ntimeout_ms: 60000\nviewport:\n  width: 1280\n  height: 720\nsteps:\n  - name: open page\n    action: goto\n    url: https://example.com\n  - name: assert title\n    action: assert_title\n    contains: Example\n"
    }
  ]
}

将 dialtesting.conf 中的 server 临时改成本地文件地址:

[[inputs.dialtesting]]
  server = "file:///tmp/dialtesting-browser-task.json"
  pull_interval = "10s"

  [inputs.dialtesting.browser]
    engine = "lightpanda"
    engine_path = "/usr/local/bin/lightpanda"
    max_concurrency = 8

使用 debug 运行:

datakit debug --input-conf /usr/local/datakit/conf.d/dialtesting.conf

正常情况下,指标中应能看到 BROWSER 任务:

curl -s http://127.0.0.1:9529/metrics | grep datakit_dialtesting

验证完成后,请将 server、region_id、ak、sk 等配置恢复为真实拨测节点配置。

BROWSER 任务示例

BROWSER 任务通过 browser_config 定义浏览器脚本。browser_config 是 YAML 字符串,常用字段如下:

浏览器拨测配置 YAML 可通过页面录制生成,具体操作请参考浏览器拨测录制说明。

字段 类型 是否必须 说明
name string N 脚本名称
target string N 默认目标地址,goto 步骤未配置 URL 时使用
timeout_ms int N 脚本总超时时间,单位为毫秒
viewport.width int N 浏览器视口宽度
viewport.height int N 浏览器视口高度
tags object N 自定义标签
steps array Y 浏览器执行步骤

steps 中可使用 goto、click、fill、wait_for_selector、wait_for_url、assert_title、assert_url、assert_text 等动作和断言。

wait_for_url 支持 contains、equals 或 text,会持续轮询,直到 URL 匹配或步骤/脚本超时。assert_title、assert_url 和 assert_text 也始终轮询;配置了步骤 timeout_ms 时优先使用步骤超时,否则使用脚本总超时。DataKit 默认的步骤超时时间为 60 秒。例如:

- name: 等待跳转到仪表板
  action: wait_for_url
  contains: https://console.example.com/dashboard
  timeout_ms: 15000
- name: 校验仪表板标题
  action: assert_title
  contains: Dashboard
  timeout_ms: 5000

完整任务 JSON 中,browser_config 位于 BROWSER 任务对象内:

{
  "BROWSER": [
    {
      "name": "browser-homepage",
      "url": "https://example.com",
      "status": "OK",
      "frequency": "1m",
      "post_url": "https://openway.guance.com?token=<your-token>",
      "browser_config": "<browser_config YAML string>",
      "advance_options": {
        "screenshot_on_failure": true
      }
    }
  ]
}

截图支持

将 advance_options.screenshot_on_failure 设置为 true 后,浏览器步骤失败时会采集 PNG。DataKit 上传图片并将元数据写入 steps[].screenshot;上传失败信息写入 screenshot_upload_error。

Lightpanda 截图是以文本为主的语义渲染,并非像素级还原的浏览器画面。它适合检查失败时的页面内容和 DOM 状态,但不会完整呈现 CSS、图片、Canvas 等 Chrome 渲染细节。当 Lightpanda 无法启动、浏览器进程已经退出或浏览器会话达到整体超时时,无法采集截图。

关联 RUM 数据

使用 Web RUM SDK 3.3.22 联调时,建议选择 Chrome/Chrome Headless Shell。Lightpanda 1.0.2 已修复旧版本的时间基准问题,但该 SDK 仍需将小数毫秒时间戳转换为整数毫秒。以下上下文注入不会修正 SDK 的上报格式。

目标页面已接入支持浏览器拨测关联的 Web RUM SDK 时,执行器会在受控页面的业务脚本运行前提供以下上下文:

全局变量 值 SDK 上报字段
window._DATAFLUX_SYNTHETICS_BROWSER true session_type = synthetics
window._GUANCE_SYNTHETICS_PUBLIC_ID 平台任务的 external_id synthetics_test_id
window._GUANCE_SYNTHETICS_RESULT_ID 当前尝试的 browser_run_id synthetics_result_id

上下文在受控页面导航、刷新和跨域导航后的新文档中继续注入;每次尝试使用独立的浏览器环境和结果 ID,避免不同任务、节点或并发执行串数据。SDK 可据此关联 View、Action、Resource、Error 和 LongTask。执行器不会安装或重复初始化 RUM SDK,也不会改变现有采样率和会话重放开关。缺少平台任务 ID 的本地脚本不会设置上述变量。

browser_run_id 保持为最后一次尝试的结果 ID。启用重试时,retry_records[].browser_run_id 保留各次尝试的结果 ID,可结合任务 ID 分别查询失败和成功尝试的 RUM 数据。旧记录可能没有该字段,不应按 URL 和时间猜测关联关系。一次尝试可能产生多个会话或页面,不应只保留第一条或最后一条查询结果。

本能力覆盖执行器控制的页面及其文档导航,不保证独立弹窗或新标签页的上下文注入;现有执行器不会自动切换到这些页面。RUM 数据是否可查还取决于 SDK 版本、采样、上报、入库和保留期,执行结束不保证 SDK 已完成刷新上报。此处仅建立采集端关联,不提供 RUM 权限查询或详情跳转接口;查询仍须校验工作空间、应用和数据访问权限。

排查方式

通过 DataKit 指标确认任务和上报状态:

curl -s http://127.0.0.1:9529/metrics | grep datakit_dialtesting

浏览器引擎环境可通过以下命令确认:

echo $LIGHTPANDA_EXECUTABLE_PATH
$LIGHTPANDA_EXECUTABLE_PATH version
command -v lightpanda

常见问题:

  • 拉不到任务:确认 server、region_id、ak、sk 配置正确,且 datakit_dialtesting_task_number{protocol="BROWSER"} 大于 0。
  • 页面已下发 BROWSER 任务但节点没有执行:确认没有显式配置 [inputs.dialtesting.browser].enabled = false,并检查 DataKit 日志中是否出现 browser.enabled is false or unsupported。
  • 任务不上报:确认任务 post_url 可访问,且发送失败、缓存、丢弃相关指标未持续增长。
  • 浏览器无法启动:确认节点选择的 engine、engine_path 与实际安装的浏览器一致,且 DataKit 运行用户可以读取并执行。使用路径环境变量时,检查对应的 LIGHTPANDA_EXECUTABLE_PATH 或 CHROME_EXECUTABLE_PATH 是否进入服务环境。
  • Chrome 依赖缺失:按运行要求检查 ldd 输出并补齐当前发行版的运行库;版本命令成功后,还需运行实际拨测任务。
  • Chrome 报 No usable sandbox!:allow_no_sandbox = true 时会记录警告并关闭沙箱重试一次;设为 false 时直接失败。若需保留 sandbox,检查非 root 运行用户、用户命名空间,以及主机 AppArmor 或容器 seccomp 策略。
  • 中文截图出现方框或布局异常:检查系统中文字体;需要网页字体的页面应开启 load_fonts。
  • 选择镜像:直接使用普通 datakit:<version>,其中同时内置 Lightpanda 和官方 Chrome Headless Shell,通过浏览器引擎配置选择。
  • 截图未上传:确认 advance_options.screenshot_on_failure 已设置为 true,并检查 screenshot_upload_error。浏览器启动失败、进程退出或任务整体超时时,可能没有可用于截图的活动会话。

文档评价

文档内容是否对您有帮助?