Windmill 监控指南用 Prometheus 与 Pushgateway 采集 Server/Worker 指标与 Job 业务指标【免费下载链接】windmillOpen-source developer platform to power your entire infra and turn scripts into webhooks, workflows and UIs. Fastest workflow engine (13x vs Airflow). Open-source alternative to Retool and Temporal.项目地址: https://gitcode.com/GitHub_Trending/wi/windmill本文以 Windmill 开源仓库中的 job-monitoring-prometheus 部署示例 为主体讲解如何搭建一套完整的监控栈通过 Prometheus 抓取 Windmill server 与 worker 暴露的指标并借助 Prometheus Pushgateway 让短暂运行的 Job 也能推送自己的业务指标最终在 Grafana 中统一可视化。读完本文你将掌握 Windmill 指标开关的底层原理、docker-compose 下的服务发现配置以及规避 Pushgateway 指标残留 陷阱的实战技巧。一、整体监控架构Windmill 的监控分为两个层面对应两种截然不同的采集模型采集对象数据产生方式采集模型适用指标Windmill server / worker 进程常驻进程持续暴露/metrics端点Prometheus 主动拉取scrape队列长度、运行中的 Job 数、Worker 心跳、API 延迟等进程级指标单个 Windmill Job脚本/流程Job 生命周期极短Prometheus 来不及抓取Job 主动推送push到 Pushgatewayjob_records_processed这类业务指标Windmill 服务器和 worker 都会产生可供 Prometheus 抓取的指标而单个 Job 由于临时性ephemeral本质往往在 Prometheus 完成一次抓取之前就已经结束因此需要借助 Prometheus 官方推荐的 Pushgateway 模型来完成指标上报。本示例正是围绕这两条链路设计的。完整的监控栈由四类服务组成Windmill一个 PostgreSQL 数据库、一个 server、至少一个 worker示例中部署了 3 个 worker 副本Prometheus负责抓取 server/worker 指标以及抓取 Pushgateway 中 Job 推送的指标Prometheus Pushgateway接收 Job 推送的指标并暂存Grafana可视化以上所有指标可选。二、一键启动整套监控栈仓库中的 docker-compose.yml 已经把所有服务组装完毕直接运行docker compose up -d启动完成后各服务访问地址如下服务地址说明Windmillhttp://localhost:8000主控制台Prometheushttp://localhost:9090抓取与查询Grafanahttp://localhost:3000可视化compose 中实际映射为 3030Pushgateway 指标端点http://localhost:9091/metrics可被 Prometheus 抓取Pushgateway 管理界面http://localhost:9091管理 metric groupGrafana 的默认管理员账号密码定义在 grafana/grafana.ini 中admin_user windmilladmin_password changemePrometheus 数据源则通过 grafana/datasource.yml 自动预置指向http://prometheus:9090。compose 文件中几个值得注意的细节Pushgateway 使用了--persistence.file/data/persistence.dat将推送的指标持久化到卷中重启后指标不会丢失Prometheus 设置了--storage.tsdb.retention.time365d的长期保留策略Windmill server 与 worker 均通过depends_on等待 PostgreSQL 健康检查通过后再启动数据库密码为示例用的changeme生产环境务必替换。启动后你可以在 Prometheus 的 Status 页面http://localhost:9090/targets直接确认各抓取目标是否在线。三、监控 Windmill Server 与 Worker3.1 开启指标端点METRICS_ADDR 的底层原理Windmill 的指标功能默认关闭需要通过环境变量METRICS_ADDR开启该功能属于 Windmill Enterprise Edition。开启后进程会在8001端口默认值暴露/metrics端点。从源码看该变量的解析逻辑位于 backend/windmill-common/src/lib.rspub static ref METRICS_PORT: u16 std::env::var(METRICS_PORT) .ok().and_then(|s| s.parse::u16().ok()) .unwrap_or(8001); pub static ref METRICS_ADDR: SocketAddr std::env::var(METRICS_ADDR) .ok().map(|s| { s.parse::bool() .map(|b| b.then(|| SocketAddr::from(([0, 0, 0, 0], *METRICS_PORT)))) .or_else(|_| s.parse::SocketAddr().map(Some)) }) ... .unwrap_or_else(|| SocketAddr::from(([0, 0, 0, 0], *METRICS_PORT))); pub static ref METRICS_ENABLED: AtomicBool AtomicBool::new( std::env::var(METRICS_PORT).is_ok() || std::env::var(METRICS_ADDR).is_ok() );由此可以提炼出三种配置方式及其行为配置方式行为METRICS_ADDR1或true在默认端口8001的0.0.0.0上监听/metrics即 README 与 compose 示例的用法METRICS_ADDR0.0.0.0:9100SocketAddr 形式解析为完整地址覆盖默认端口按指定地址监听METRICS_PORT9100单独设置仅指定端口同样会触发METRICS_ENABLED为 true在0.0.0.0:9100监听也就是说METRICS_ENABLED只要检测到这两个环境变量中任意一个存在即为 true监听地址默认绑定0.0.0.0以便容器外部访问。除了环境变量也可以在 Windmill 实例设置instance settings → core中打开 Expose Metrics 开关其对应的全局设置项为expose_metrics源码见 backend/src/monitor.rs 的apply_metrics_enabled测试覆盖见 backend/tests/instance_config.rs。此外实例设置 → debug 菜单还可以开启额外的 debug-level 指标。3.2 让 Prometheus 通过 Docker 服务发现找到 Windmill在 docker-compose 部署方式下需要做四处调整才能让 Prometheus 自动发现并抓取 Windmill 容器暴露指标端口给windmill_server和windmill_worker两个服务的expose块加入8001默认指标端口使服务发现能确定抓取哪个端口打标签区分角色为容器添加prometheus-jobwindmill_server与prometheus-jobwindmill_worker标签便于服务发现按角色过滤挂载 Docker socketPrometheus 容器需要以user: root运行并把宿主机的/var/run/docker.sock只读挂载进去compose 中对应- /var/run/docker.sock:/var/run/docker.sock:ro # for service discovery配置 scrape_configs在 prometheus/prometheus.yml 中添加如下抓取配置scrape_configs: - job_name: windmill_server docker_sd_configs: - host: unix:///var/run/docker.sock relabel_configs: - source_labels: [__meta_docker_container_label_prometheus_job] regex: windmill_server action: keep scrape_interval: 1s - job_name: windmill_worker docker_sd_configs: - host: unix:///var/run/docker.sock relabel_configs: - source_labels: [__meta_docker_container_label_prometheus_job] regex: windmill_worker action: keep scrape_interval: 1s这里docker_sd_configs负责从 Docker socket 发现容器relabel_configs中的action: keep则按容器标签prometheus-job的值过滤只保留 server 或 worker。抓取间隔设为1s能够获得更细腻的时序数据windmill server 与 worker 指标对实时性要求较高。3.3 多 Docker daemon 场景如果 Windmill 容器分散在多个 Docker daemon 上上述方案依然成立无需修改 relabel 逻辑只需把 Prometheus 的docker_sd_configs中的host从本地 socket 改为远程 daemon 的 HTTP(S) 地址例如http://remote_docker_daemon:2375并且可以在数组中列出多个远程 daemon 地址。3.4 查看监控结果配置就绪后server 与 worker 的指标会持续被 Prometheus 抓取可在 Grafana 中可视化。仓库在 grafana/dashboards/ 下提供了现成的仪表盘windmill_monitoring_dashboard.json展示最核心的进程级指标Windmill 监控仪表盘四、让单个 Job 产生自己的指标4.1 为什么需要 PushgatewayJob 是临时进程一个 Job 可能只运行几百毫秒就结束Prometheus 按固定间隔抓取时很可能错过它。Pushgateway 的模型是作业主动把指标推到网关Prometheus 再从网关拉取正好解决这一问题。4.2 用 Python 脚本推送指标在 Windmill 中新建一个 Python 脚本教程中命名为u/admin/random_number_metric_script内容如下import os import random from prometheus_client import CollectorRegistry, Gauge, push_to_gateway PROMETHEUS_GATEWAY_URL prometheus_gateway:9091 def main(): job_path os.environ.get(WM_JOB_PATH) registry CollectorRegistry() gauge Gauge( job_records_processed, Number of records processed for {}.format(job_path), registryregistry, ) val random.randint(0, 100) print(Storing metrics value: , val) gauge.set(val) push_to_gateway(PROMETHEUS_GATEWAY_URL, jobjob_path, registryregistry)这段脚本的核心逻辑使用prometheus-client库的CollectorRegistry创建独立 registry避免与默认 registry 冲突定义了一个名为job_records_processed的 Gauge 指标关键设计通过os.environ.get(WM_JOB_PATH)读取 Windmill 注入的环境变量即脚本路径并将其作为 Pushgateway 的job标签。这样该脚本的所有运行都会推送到同一个指标分组便于跨多次运行观察趋势push_to_gateway还支持grouping_key参数如需按 Job ID 等更细粒度区分可传入额外的分组标签。脚本所需的依赖prometheus-client可在 Windmill 脚本的依赖一栏中声明。若不想用 Python官方还提供了 Golangprometheus/client_golang、TypeScriptprom-client等客户端bash 场景则可以直接用 CURL 命令向 Pushgateway 推送。脚本创建完成后为它配置一个每 5 秒运行一次的调度schedule即可持续向 Pushgateway 推送新值。4.3 在 Prometheus UI 中直接查询如果不使用 Grafana可以直接在 Prometheus 的 Graph 页面http://localhost:9090/graph输入如下 PromQL 查看原始指标job_records_processed{exported_jobu/admin/random_number_metric_script}注意这里使用了exported_job标签因为 Prometheus 会用自己的job标签即抓取配置中的job_name此处为prometheus_gateway覆盖被抓取数据中的job标签原job标签会被改名为exported_job保留下来Prometheus UI 中查看 Job 指标五、Grafana 可视化与 Pushgateway 陷阱仓库在 grafana/dashboards/ 提供了job_metric_dashboard.json可直接导入 Grafana 使用。该仪表盘包含两个面板第二个面板正是为了演示 Pushgateway 的一个关键陷阱。5.1 面板一原始指标第一个面板是job_records_processed的简单时间序列展示。由于 Job 每 5 秒运行一次面板的Min Step被调整为 5 秒以便尽可能显示全部测量点job_records_processed 原始指标5.2 面板二Pushgateway 的指标残留问题与解法问题Pushgateway 中被推送的值会一直保留直到有新的值推入。这意味着如果调度被意外停止、或脚本开始报错不再推送旧值依然停留在仪表盘上保持不变——这掩盖了故障不利于发现异常行为。解法理想情况下指标应在无新数据时回落到默认值如0。Pushgateway 内置了一个指标push_time_seconds记录每次成功推送的时间戳按指标与标签分组。将业务指标与push_time_seconds的irate相乘就能得到一个瞬时表示一旦推送停止irate迅速归零乘积也随之归零。第二个面板的实现思路如下job_records_processed{exported_jobu/admin/random_number_metric_script} * irate(push_time_seconds{jobprometheus_gateway, exported_jobu/admin/random_number_metric_script}[1m])其中Min Step需设为1sirate才能正常工作irate计算的是相邻两个样本间的瞬时变化率抓取间隔为 1s 时其数值才准确反映此刻是否仍在推送。该面板的即时值显示效果job_records_processed 瞬时表示5.3 最终效果两个面板组合后的仪表盘如下。图中两条浅蓝色竖线之间作者手动停止了 Windmill 的调度可以看到上方的原始指标保持不变残留值而下方的瞬时表示立即跌到 0——这正是上述技巧的价值所在Grafana 双面板仪表盘六、小结与生产实践建议回到示例的核心链路Windmill server/worker 通过METRICS_ADDR暴露/metrics端点供 Prometheus 拉取短暂运行的 Job 通过prometheus-client的push_to_gateway把业务指标推给 Pushgateway 再由 Prometheus 拉取Grafana 统一呈现。落地到生产环境时建议关注以下几点务必处理 Pushgateway 的残留问题结合push_time_seconds的irate构造瞬时指标或在脚本中显式处理失败/停止场景否则告警会失效合理设置抓取间隔本示例为了演示将scrape_interval设为1s生产环境应按指标重要性与资源开销权衡安全性挂载 Docker socket、以 root 运行 Prometheus 均需在可信环境中使用Pushgateway 默认无鉴权部署在公网前应增加访问控制版本前提METRICS_ADDR指标开关属于 Enterprise Edition 能力社区版CE部署时请以实际版本文档为准。更多配套资源可继续查阅完整部署 compose 文件、Prometheus 抓取配置、Grafana 仪表盘定义。【免费下载链接】windmillOpen-source developer platform to power your entire infra and turn scripts into webhooks, workflows and UIs. Fastest workflow engine (13x vs Airflow). Open-source alternative to Retool and Temporal.项目地址: https://gitcode.com/GitHub_Trending/wi/windmill创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
