OneUptime Docker 监控实战容器指标采集、日志摄取与告警模板全解析【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptimeOneUptime 的 Docker 监控让你对 Docker 宿主机及其上的容器进行健康度与性能监控平台通过一个预配置的 OpenTelemetry Collector即OneUptime Docker Agent采集容器指标与容器日志再将其与你在监控中配置的判定条件进行比对。读完本篇你可以完成 Docker Agent 的部署、理解 Agent 侧 Collector 的采集与日志处理管线、掌握 Docker Monitor 的全部配置项并能用内置告警模板和排查手册快速落地容器监控。一、Docker 监控能做什么Docker 监控器利用来自你各主机的指标与日志为容器化工作负载提供可观测性具体能力包括监控 Docker 宿主机的整体健康以及每个容器per-container的健康跨容器追踪 CPU、内存、网络、块 I/O 与进程数量发现容器重启、崩溃和 CPU 限流throttling以原生 OpenTelemetry 格式接收结构化容器日志流对高 CPU、高内存、重启风暴等场景告警。从源码结构看指标与日志进入 OneUptime 后宿主机与容器会作为独立资源被自动注册并展示Dashboard 中存在 DockerHost 组件 与 DockerHost 数据模型服务端由 DockerHostService 管理宿主机注册容器资源由 DockerResourceService 维护监控判定则统一走 OpenTelemetryIngestService 的摄取管线。二、创建 Docker Monitor进入 OneUptime 仪表盘的Monitors监控页面点击Create Monitor创建监控选择Docker作为监控类型选择要监控的 Docker 宿主机与资源范围Host / Container配置指标查询metric queries与聚合方式按需配置监控判定条件。这套流程对应前端实现 DockerMonitorStepForm表单通过 ModelAPI 拉取项目下的全部DockerHost记录按name排序以hostIdentifier作为下拉选项的值同时提供 DockerTemplatePicker 与 DockerMetricPicker让你直接从预置告警模板或指标目录出发创建监控滚动时间窗口由RollingTimePicker组件选择对应 RollingTime 类型。三、配置选项详解3.1 Docker 宿主机选择要监控的 Docker 宿主机。宿主机是自动注册的OneUptime Docker Agent 第一次从该主机发送遥测数据时平台即依据resource.host.name属性自动建卡无需手工创建。Agent 侧的宿主机名由环境变量DOCKER_HOST_NAME提供经 Collector 的resource处理器打上host.name资源属性见 otel-collector-config.yaml 中processors.resource.attributes对host.name的 upsert。3.2 资源范围范围说明Host监控整个 Docker 宿主机聚合该主机上所有容器的数据Container按名称或镜像监控某一个具体容器3.3 指标查询为一个监控配置一条或多条指标查询。每条查询指定Metric name指标名——要查询的容器指标Aggregation聚合——对指标值的聚合方式Avg、Sum、Max、MinFilters过滤器——额外的基于属性的过滤例如按容器名、镜像或宿主机Group By分组——可选地按resource.container.name分组使每个容器被独立评估。此外还可以创建公式formula用数学表达式组合多条指标查询。这一点在实现中同样成立从 DockerMonitorStepForm 引用的MetricQueryConfigData与MetricsAggregationType等类型可以看到查询项、聚合方式与别名alias共同构成可被公式引用的指标视图。一个关键的实现细节来自 DockerAlertTemplates 中的源码注释Docker Agent 将容器身份作为 OTLPresource 属性打上因此 ClickHouse 中存储的属性带resource.前缀——resource.container.name、resource.container.image.name、resource.container.runtime值为docker与resource.host.name。所有模板都按resource.container.name分组使每个容器独立评估一次异常只产生针对该容器的事件而不是整个主机一个事件、由最忙的容器“沉默”掉其他所有容器。3.4 滚动时间窗口选择指标评估的时间窗口过去 1 / 5 / 10 / 15 / 30 / 60 分钟对应RollingTime.Past5Minutes等枚举值模板默认使用 Past 5 Minutes 或 Past 15 Minutes。四、Agent 侧采集机制源码级佐证Docker 指标采集基于 OpenTelemetrydocker_stats接收器通过 Docker Engine API 抓取默认间隔30 秒。查看仓库中的真实配置 DockerAgent/otel-collector-config.yaml 可以看到几个关键设计receivers: docker_stats: endpoint: unix:///var/run/docker.sock api_version: ${env:DOCKER_API_VERSION} collection_interval: 30s # 以下指标在 contrib 接收器中默认关闭必须显式开启 metrics: container.cpu.utilization: { enabled: true } container.cpu.throttling_data.throttled_periods: { enabled: true } container.cpu.throttling_data.throttled_time: { enabled: true } container.memory.percent: { enabled: true } container.pids.count: { enabled: true } container.restarts: { enabled: true } container.uptime: { enabled: true }值得注意的两点可选指标默认关闭container.restarts、container.uptime、container.pids.count、CPU 限流指标在 upstreamdocker_stats接收器里默认是 OFF 的而 OneUptime 的告警模板恰恰依赖它们——所以 Agent 显式把它们打开。这正是“容器重启循环”“容器宕机”模板能够工作的底层前提。API 版本协商api_version直接透传${env:DOCKER_API_VERSION}而非带:-1.44默认值的写法。原因是旧版 Docker Engine 会拒绝比它更新的客户端“client version 1.44 is too new”导致接收器启动失败、整个 Collector 一起退出留空时接收器会走 SDK 自动协商一次HEAD /_ping后取守护进程自身最大值对新旧守护进程都安全。日志管道同样值得细看filelog接收器 include/var/lib/docker/containers/*/*-json.log、exclude 以${env:HOSTNAME}为前缀的目录容器内 HOSTNAME 是 12 位短容器 ID与 Docker 按完整容器 ID 命名的日志目录匹配从而排除 Agent 自身日志避免反馈循环。其 operator 管线依次为json_parser解析 Docker JSON 日志信封并提取time→regex_parser从文件路径提取container_id并移入resource[container.id]→recombine把同一容器的多行堆栈以空白、]、}、)开头的续行合并为一条日志max_log_size: 1MBforce_flush_period: 5s→ 严重程度推断见下文→severity_parser将文本级别提升为severityNumber。最终service.pipelines定义了 metrics、logs 与logs/inventory库存快照三条管线全部经memory_limiterlimit 512 MiB、batch10s / 1024 条处理后通过otlphttp导出器发送到${env:ONEUPTIME_URL}/otlp并用x-oneuptime-service-token请求头鉴权。4.1 采集的指标CPU指标说明container.cpu.utilizationCPU 利用率。注意语义100% 等于一个完整 CPU 核即docker stats的 CPU% 列而非宿主机的 100%——一个跨两个核的容器会读到 200container.cpu.usage.total容器启动以来累计消耗的 CPU 时间生命周期累计计数器container.cpu.throttling_data.throttled_time容器被 cgroups 限流的总纳秒数累计计数器container.cpu.throttling_data.throttled_periods限流周期数累计计数器内存指标说明container.memory.usage.total当前内存使用量字节container.memory.usage.limit内存上限字节container.memory.percent内存使用占容器--memory上限的百分比若容器未设上限则除以宿主机总内存网络指标说明container.network.io.usage.rx_bytes累计接收字节数container.network.io.usage.tx_bytes累计发送字节数块 I/O指标说明container.blockio.io_service_bytes_recursive.read从块设备读取的字节数container.blockio.io_service_bytes_recursive.write写入块设备的字节数容器信息指标说明container.uptime容器运行时长秒container.restarts容器自创建以来的重启次数累计计数器container.pids.count容器内任务数——cgroup pids 控制器把内核线程也计入不只是进程指标目录与名称的对应关系可参考 Dashboard 侧的 DockerMetricCatalog 类型定义。4.2 采集的日志除指标外Docker Agent 还会经 filelog 接收器尾随每个容器的*-json.log文件以原生 OTLP 日志格式发送。每条日志记录被富化以下字段resource.host.name—— Docker 宿主机标识符resource.container.id—— 完整容器 ID从日志文件路径解析resource.container.runtime—— 恒为dockerattributes[log.iostream]——stdout或stderrseverityText/severityNumber—— 优先从行内的级别关键字读取如app.INFO:、{level:warn}、[ERROR]、levelerror无可识别级别的行回退到流stderr → ERRORstdout → INFObody—— 容器进程输出的原始日志行time—— Docker 守护进程为该行打的时间戳。日志最终展示在 Docker 宿主机的Logs日志标签页以及每个容器的详情页。严重程度推断的实现约束比“关键字匹配”更严格级别关键字只有在“级别应该出现的位置”才会被采信——要么位于行的引导段行首由标点、数字、以结构性分隔符结尾的词组成的前缀之后如[ERROR]、app.INFO:、2026-08-31 07:25:04 INFO、logfmt 的levelerror要么是行中某个 level 类字段level/lvl/severity/severity_text/levelname/log.level/log_level的值。因此正文里顺带提到 “error” 或 “panic” 的普通消息不会被误判仍保留流回退级别。severity_parser的自定义映射还覆盖了内置预设不认识的关键字notice → info、err/crit/critical → error、panic/alert/emerg/emergency → fatal。测试语料Tests/Ops/ContainerAgentLogSeverity.test.js对“不应匹配的行”做了回归固定。4.3 日志驱动Log Driver要求Docker Agent 只能采集使用 Dockerjson-file日志驱动的容器的日志。这是 Docker 的默认值但可被逐容器或全局覆盖local驱动—— 把二进制 protobuf 块写入/var/lib/docker/containers/id/local-logs/container.logfilelog 接收器无法解析journald、syslog、fluentd、gelf、awslogs、splunk等—— 日志发往远程目的地本地没有可尾随的文件none—— 直接丢弃日志。若使用了上述驱动你仍能在 Docker 宿主机页面看到指标但Logs 标签页将是空的或只有 Agent 自身的日志。检查某个容器当前的日志驱动docker inspect container --format {{.HostConfig.LogConfig.Type}}检查守护进程的默认值docker info --format {{.LoggingDriver}}将 Docker Compose 服务切换到带合理轮转的json-fileservices: my-app: image: my-app:latest logging: driver: json-file options: max-size: 100m max-file: 5切换守护进程默认值对之后创建的所有容器生效——编辑/etc/docker/daemon.json{ log-driver: json-file, log-opts: { max-size: 100m, max-file: 5 } }然后重启 Docker 守护进程并重建recreate不是重启受影响的容器Docker 在容器创建时就把日志驱动固定下来已存在的容器在被删除重建前会保留旧驱动# Docker Compose docker compose up -d --force-recreate service # 普通 docker docker rm -f container docker run ... image五、监控判定条件5.1 评估对象Docker 监控器始终评估Metric Value指标值——即所配置的指标查询或公式的值。条件表单没有 Filter Type 选择器只展示Metric、Aggregation、Condition、Threshold。5.2 聚合类型聚合说明Average时间窗口内的平均值Sum所有值求和Maximum Value窗口内的最高值Minimum Value窗口内的最低值All Values所有值都必须满足条件Any Value至少一个值满足条件5.3 条件类型静态阈值与填写的 Threshold 比较Greater Than、Less Than、Greater Than or Equal To、Less Than or Equal To、Equal To基线异常检测无阈值——表单改为展示Sensitivity敏感度与Baseline Window基线窗口把每个样本与该窗口构建出的“同一星期同一小时”基线比较Anomalously High—— 值高于预期区间Anomalously Low—— 值低于预期区间Anomalous—— 值双向离开预期区间。异常条件在“学习Learning”状态下不触发任何告警直到至少积累了所选基线窗口长度的历史指标。六、预置告警模板及其源码实现OneUptime 为常见 Docker 监控场景内置了告警模板定义集中在 DockerAlertTemplates模板 ID 见该文件 L362-L681在监控创建表单中通过DockerTemplatePicker一键生成MonitorStep。仓库文档给出的模板概览如下模板描述阈值聚合High Container CPU每容器 CPU 利用率 单核的 80%Max按容器分组High Container Memory内存使用占上限的百分比 85%Max按容器分组High CPU Throttling窗口内限流时长的增长 1000 ms / 5 min每分钟 Max−Min再求和按容器Container Restart Loop窗口内重启次数的增长 3 / 15 min每分钟 Max−Min再求和按容器High Container Process Count任务数进程加线程 2000Max按容器Container Down容器 uptime 归零 0Min几条必须理解的语义源码注释里写得很直白Max 按resource.container.name分组CPU、内存、进程数模板防止单一热点容器的信号被同主机上大量空闲容器稀释。highCpuTemplate 与 highMemoryTemplate 中可见aggregationType: MetricsAggregationType.Max与groupByAttributeKey: resource.container.name的显式组合。CPU 阈值是“绝对 CPU 预算”container.cpu.utilization是docker stats打印的那个数字100% 是一个完整核不是宿主的 100%。多核主机上该阈值是绝对预算而非占比容器本来就该用多核时请自行调高。container.restarts与throttled_time是生命周期计数器所以 Restart Loop 与 Throttling 两个模板比较的是窗口内增长量而非绝对值buildDockerDeltaMonitorConfig构造 Max−Min 差值公式——对单调递增计数器做绝对值比较会“一旦触发永远无法恢复”。增长量是在每个 1 分钟桶内、于相邻两次抓取之间度量的在 30 秒抓取间隔下约能捕获窗口内一半的单次事件阈值已按此校准若把collection_interval提到 60 秒及以上每桶只剩一个样本、差值恒为零这两个模板会被静默禁用。内存百分比的分母取决于容器是否设限container.memory.percent在有--memory时除容器上限否则除宿主机总内存——容器若以 86% 告警但未设上限它只是用了 86% 的机器内存并不会因“撞上不存在上限”而 OOM。每个模板同时构建 offline触发事件/告警与 online恢复两条判定实例事件标题采用[Docker] High CPU Usage (80% of one core) - hostIdentifier的形式其中宿主后缀由 dockerTitleSuffix 拼接避免从推荐页创建监控时名称重复。七、部署 Agent 的前提条件要使用 Docker 监控需要在每台要监控的 Docker 宿主机上安装 OneUptime Docker Agent通过环境变量传入ONEUPTIME_URL、ONEUPTIME_SERVICE_TOKEN与DOCKER_HOST_NAME确保要观察的容器使用json-file日志驱动见上文 4.3 节。Agent 以oneuptime/docker-agent:release镜像发布完整安装示例见 DockerAgent/README.md安装脚本为 DockerAgent/install.sh。最小化docker run命令如下来自该 READMEdocker run -d \ --name oneuptime-docker-agent \ --user 0:0 \ --restart unless-stopped \ -v /var/run/docker.sock:/var/run/docker.sock:ro \ -v /var/lib/docker/containers:/var/lib/docker/containers:ro \ -e ONEUPTIME_URLhttps://oneuptime.com \ -e ONEUPTIME_SERVICE_TOKENyour-service-token \ -e DOCKER_HOST_NAMEmy-docker-host \ oneuptime/docker-agent:release环境变量的完整清单变量必填说明ONEUPTIME_URL是你的 OneUptime 实例 URLONEUPTIME_SERVICE_TOKEN是遥测摄取服务令牌Settings → API KeysDOCKER_HOST_NAME否该宿主机在平台中的友好名称默认docker-hostDOCKER_API_VERSION否Agent 使用的 Engine API 版本默认 1.44旧宿主机设为其最大值或置为空字符串走自动协商前提要求来自 DockerAgent/README.mdDocker Engine 20.10、可访问/var/run/docker.sock、需采集日志的容器使用json-file驱动。另外注意 Agent 必须以 root--user 0:0运行才能读 docker.sock容器启动后宿主机会自动出现在 OneUptime 的 Docker 分区中。八、故障排查8.1 指标可见但 Logs 标签页是空的你的容器几乎可以肯定没有使用json-file日志驱动。运行 4.3 节的诊断命令docker inspect ... LogConfig.Type与docker info ... LoggingDriver把需要上报日志的容器切换过去并重建。8.2 filelog 接收器报no files match the configured criteria说明 include glob/var/lib/docker/containers/*/*-json.log在 Agent 启动时没有匹配到任何文件。可能原因该主机上没有任何容器使用json-file缺少 bind mount-v /var/lib/docker/containers:/var/lib/docker/containers:ro或它指向了一个空目录Agent 运行在 macOS 的 Docker Desktop 上但 Linux VM 的容器目录没有暴露出来。快速确认方式来自 DockerAgent/README.mddocker logs oneuptime-docker-agent 21 | grep -E Started watching file|no files match再用docker run --rm --volumes-from oneuptime-docker-agent alpine:3.19 sh -c ls /var/lib/docker/containers/*/*-json.log验证文件是否存在。8.3 日志到了但归到了错误的宿主机名下OneUptime 按resource.host.name自动注册 Docker 宿主机该值取自DOCKER_HOST_NAME。在首批遥测之后修改DOCKER_HOST_NAME会新建一条宿主机记录而不是重命名已有记录。可以这样确认 Agent 实际打上的名称docker inspect oneuptime-docker-agent --format {{range .Config.Env}}{{println .}}{{end}} | grep DOCKER_HOST_NAME8.4 “High CPU”不触发事件确认指标查询的聚合方式是Max不是 Avg且按resource.container.name分组。在繁忙主机上对全部容器取平均会被空闲容器稀释很少能越过阈值。8.5 其他常见问题Docker Socket Permission Denied确认docker run带了--user 0:0或 Compose 里user: 0:0容器反复重启并报client version 1.44 is too new守护进程拒绝比自身上限更新的客户端接收器随之启动失败。设置DOCKER_API_VERSION为守护进程的最大值docker version --format {{ .Server.APIVersion }}查询或置为空字符串让 SDK 自动协商升级/卸载docker pull oneuptime/docker-agent:release后docker rm -f oneuptime-docker-agent再按上面命令重跑或直接docker compose pull docker compose up -d卸载只需docker rm -f oneuptime-docker-agent。九、小结OneUptime 的 Docker 监控由三层协作完成Agent 层docker_stats接收器 filelog 日志管线见 DockerAgent/otel-collector-config.yaml负责把容器指标、日志与资源属性宿主机名、容器 ID、runtimedocker以原生 OTLP 格式发往${ONEUPTIME_URL}/otlp平台层按resource.host.name自动注册宿主机并维护容器资源监控层DockerMonitorStepForm DockerAlertTemplates提供 Host/Container 两种范围、六种聚合、静态阈值与基线异常两类条件以及六个语义经过源码级校准的预置告警模板。把握resource.前缀属性、Max 按容器分组的防稀释策略、以及生命周期计数器的“比增长不比绝对值”原则是正确使用这套 Docker 监控的三把钥匙。【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptime创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考