Nightingale Categraf Docker Input Plugin: Collectingdocker_*Metrics via the Docker API【免费下载链接】nightingaleNightingale is to monitoring and alerting what Grafana is to visualization.项目地址: https://gitcode.com/GitHub_Trending/ni/nightingale本指南围绕 Nightingale 项目中 Categraf 采集器的 Docker Input 插件展开它通过 Docker API 采集docker_*系列指标并配套验证过的 Docker Dashboard 与告警规则。读完本文你将掌握input.docker插件的完整配置参数、验证方法、权限与容器化部署要点以及如何利用该插件构建容器监控大盘与告警。插件概览基于 Docker API 的容器指标采集Docker Input 基于 telegraf/inputs.docker 的实现思路通过调用 Docker API 采集容器运行时指标并统一以docker_*前缀输出。仓库中的Docker Dashboard见 docker_dashboard.json正是按这些指标编写并完成真实验证的因此使用该模板时必须启用 Docker input 插件否则大盘将无数据可展示。与之对应cAdvisor 也是一种推荐的容器采集方式但它输出的是container_*指标应使用独立的cAdvisor集成目录下的大盘不能与本模板混用。两者的区分非常明确采集方式指标前缀配套大盘Docker input本文docker_*Docker DashboardcAdvisorcontainer_*cAdvisor集成采集配置docker.toml 完整参数说明插件的配置文件位于conf/input.docker/docker.toml仓库内的模板见 integrations/Docker/collect/docker/docker.toml。最基本的实例配置如下[[instances]] endpoint unix:///var/run/docker.sock gather_services false gather_extend_memstats false container_id_label_enable true container_id_label_short_style false timeout 5s total_include [cpu, blkio, network]下面对照配置文件模板逐项说明各参数的含义与取值连接与采集基础endpointDocker API 的访问地址。默认unix:///var/run/docker.sock要使用 TCP 方式可设为tcp://[ip]:[port]若使用环境变量方式如 docker-machine 场景可设为ENV。模板中默认留空endpoint 实际使用时必须显式填写否则插件不工作。gather_services是否采集 Docker Swarm 服务指标desired_replicas、running_replicas。默认false非 Swarm 环境无需开启。gather_extend_memstats是否额外采集扩展的内存统计信息。默认false。timeout对 Docker 的 list、info、stats 等命令的超时时间示例为5s。容器过滤container_name_include/container_name_exclude按容器名包含/排除支持 glob 通配。两者都为空数组时采集所有容器。container_state_include/container_state_exclude按容器状态过滤支持created、restarting、running、removing、paused、exited、dead等状态。留空时仅采集 running 状态的容器。docker_label_include/docker_label_exclude将 Docker 标签作为标签引入时的包含/排除规则支持 glob。模板默认排除annotation*、io.kubernetes*、*description*等易产生高基数或噪声的标签。指标维度控制perdevice_include对哪些类别下发 per-device 指标可选cpucpu0、cpu1...、blkio8:0、8:1...、networketh0、eth1...。perdevice为 true 时此设置无效。total_include对哪些类别下发 total 汇总指标可选cpu、blkio、network。其中cpu的 total 由 Docker daemon 直接上报network与blkio的 total 由本插件聚合得到。total为 false 时此设置无效。tag_env指定哪些容器环境变量作为标签例如[JAVA_HOME, HEAP_SIZE]。TLS 配置可选# use_tls false # tls_ca /etc/telegraf/ca.pem # tls_cert /etc/telegraf/cert.pem # tls_key /etc/telegraf/key.pem # insecure_skip_verify false当 endpoint 指向远程 TLS Docker 服务时可配置 CA 证书、客户端证书与密钥insecure_skip_verify用于跳过证书链与主机名校验。采集周期全局interval默认 15 秒控制采集频率也可通过interval_times按global.interval * interval_times放大单个实例的采集周期labels可为该实例的所有序列追加固定标签如{ regioncloud, productn9e }。验证采集--test 模式配置完成后可用 Categraf 的测试模式验证插件是否工作./categraf --test --inputs docker至少应看到以下三个指标说明 Docker API 已打通、容器枚举与 CPU 统计正常docker_upDocker daemon 可达性探针值为 1 表示正常docker_n_containers_running当前 running 状态容器数docker_container_cpu_usage_percent容器 CPU 使用率百分比。container_id 标签从字段到标签的演进该插件在演进中有一个重要变化container_id作为 label 而非 field 输出删除了部分旧指标。也就是说容器 ID 会以标签形式附加到每条指标上便于按容器维度聚合查询而不是作为字段值增加存储体积。通过以下两个配置控制该标签container_id_label_enable true container_id_label_short_style falsecontainer_id_label_enable默认true即把容器 ID 写入标签container_id_label_short_style短格式开关。容器 ID 很长64 位十六进制若设为true只保留前 12 位可显著降低标签基数。仓库内 docker/compose-postgres/categraf/conf/input.docker/docker.toml 的 compose 示例即采用了container_id_label_short_style true的短格式实践。指标全景从 Docker Dashboard 看可用指标仓库的 docker_dashboard.json 是这些指标的直接消费者从中可以梳理出完整的指标体系均以docker_前缀Daemon 与容器概览docker_updaemon 可达性docker_n_containers_running/docker_n_containers_stopped/docker_n_containers_paused各状态容器数docker_n_images镜像数量。CPU 维度docker_container_cpu_usage_percent容器 CPU 使用率百分比docker_container_cpu_throttling_throttled_periods/docker_container_cpu_throttling_periodsCPU 限流期数两者相除可得限流率用于判断容器 CPU 配额是否吃紧。内存维度docker_container_mem_usage_percent内存使用率百分比docker_container_mem_max_usage、docker_container_mem_limit历史峰值与 limit可用于判断内存泄漏或配额设置。网络维度rx/tx 成对出现docker_container_net_rx_bytes/docker_container_net_tx_bytes进出方向字节数docker_container_net_rx_dropped/docker_container_net_tx_dropped进出方向丢弃报文数docker_container_net_rx_errors/docker_container_net_tx_errors进出方向错误报文数。Blkio 维度docker_container_blkio_io_service_bytes_recursive_read/docker_container_blkio_io_service_bytes_recursive_write递归统计的块设备读写字节数。状态维度docker_container_status_oomkilled、docker_container_status_restart_count、docker_container_health_status等用于支撑 OOM、重启循环、健康检查失败类告警。配套告警规则integrations/Docker/alerts/docker_by_categraf.json 提供了一套基于上述指标的现成告警规则默认处于 disabled 状态导入后可自行启用包括告警名判定 PromQL 要点严重级别Docker daemon 不可达docker_up 01P1Docker 容器健康检查失败docker_container_health_status 21Docker 容器被 OOM Killdocker_container_status_oomkilled 11Docker 容器反复重启increase(docker_container_status_restart_count[10m]) 31Docker 容器内存使用率逼近上限docker_container_mem_usage_percent 902Docker 容器 CPU 被限流rate(docker_container_cpu_throttling_throttled_periods[5m]) / rate(docker_container_cpu_throttling_periods[5m]) 0.252每条规则都附带可执行的处置说明action 字段例如 OOM 告警会引导通过docker_container_mem_max_usage历史峰值区分“limit 太小”与“应用内存泄漏”再决定调大--memory还是抓堆定位CPU 限流告警则引导核对--cpus配额并抓取 CPU profile。中文文案与英文翻译对应关系见 integrations/Docker/i18n/en_US.json。权限问题socket 访问Docker 的 unix socket/var/run/docker.sock默认仅 root 或 docker 组成员可访问。Categraf 最好以 root 账号运行否则需要把 Categraf 的运行账号加入 docker 组。假设 Categraf 使用categraf账号运行sudo usermod -aG docker categraf加入后需重新登录或重启 Categraf 进程使组成员关系生效。若使用 TCP endpoint 而非 unix socket则不存在此权限问题但需要自行保证连接安全如配合上文 TLS 配置。运行在容器中挂载 docker.sock如果 Categraf 自身运行在容器内需要把 Docker unix socket 挂载进 Categraf 容器例如启动参数-v /var/run/docker.sock:/var/run/docker.sock在 docker compose 环境中可在 Categraf 服务的 volumes 中加入对应配置volumes: - /var/run/docker.sock:/var/run/docker.sock仓库的 compose 示例docker/compose-postgres/categraf/conf/input.docker/docker.toml展示了容器化部署下的完整配置形态可作参考。注意将 socket 挂载进容器等同于把宿主机的 Docker 控制权交给该容器请仅在可信环境中使用。停用该插件如果暂时不需要采集 Docker 指标有两种停用方式方法一把input.docker目录改名为不以input.开头的名字例如disabled.dockerCategraf 会跳过非input.*前缀的目录不加载该插件方法二将docker.toml中的endpoint配置留空插件将不会执行采集。两种方式都不需要改动其他配置文件便于临时开关或灰度验证。小结Docker input 是 Nightingale/Categraf 生态中容器监控的默认入口它以docker_*指标覆盖 daemon 可用性、容器数量、CPU/内存/网络/Blkio 与异常状态配套的 Docker Dashboard 与告警规则集开箱即用。实操时只需关注三件事正确配置endpoint与过滤/维度参数、确保 socket 权限可用root 或 docker 组、容器化部署时挂载 socket。如需容器级采集的另一种方案可参考仓库中的 cAdvisor 集成但注意其指标前缀与大盘均与 Docker input 相互独立不可混用。【免费下载链接】nightingaleNightingale is to monitoring and alerting what Grafana is to visualization.项目地址: https://gitcode.com/GitHub_Trending/ni/nightingale创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考