企业官网建设流程全解析

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.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"]

下面对照配置文件模板逐项说明各参数的含义与取值：

连接与采集基础

• endpoint：Docker 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 指标，可选cpu（cpu0、cpu1...）、blkio（8:0、8:1...）、network（eth0、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可为该实例的所有序列追加固定标签，如{ region="cloud", product="n9e" }。

验证采集：--test 模式

配置完成后，可用 Categraf 的测试模式验证插件是否工作：

./categraf --test --inputs docker

至少应看到以下三个指标，说明 Docker API 已打通、容器枚举与 CPU 统计正常：

• docker_up：Docker daemon 可达性探针，值为 1 表示正常；
• docker_n_containers_running：当前 running 状态容器数；
• docker_container_cpu_usage_percent：容器 CPU 使用率百分比。

container_id 标签：从字段到标签的演进

该插件在演进中有一个重要变化：

1. container_id作为 label 而非 field 输出；
2. 删除了部分旧指标。

也就是说，容器 ID 会以标签形式附加到每条指标上，便于按容器维度聚合查询，而不是作为字段值增加存储体积。通过以下两个配置控制该标签：

container_id_label_enable = true container_id_label_short_style = false

• container_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_up：daemon 可达性；
• 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_periods：CPU 限流期数，两者相除可得限流率，用于判断容器 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 状态，导入后可自行启用），包括：

每条规则都附带可执行的处置说明（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.docker），Categraf 会跳过非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