可观测性后端运维前端云原生微服务AI Agent【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址https://gitcode.com/GitHub_Trending/on/oneuptime点击查看免费下载导读OneUptime Docker Agent 是一个预构建的容器镜像内置一套经过调优的 OpenTelemetry Collector 配置。将它部署在现有容器旁边即可自动发现主机上的每一个容器采集 CPU / 内存 / 网络 / 块 I/O 指标与容器日志并通过 OTLP 协议将全部数据转发至 OneUptime。本文是完整的安装与运维指南覆盖一行命令快速启动、Docker Compose 方式、全部环境变量说明、采集数据清单、升级与卸载以及各类典型故障如 Docker Socket 权限、API 版本不匹配、无日志、主机断连的排查方法。本文对应仓库文档Docker Agent 安装指南en以及配套的 Agent 源码与配置目录 agents/DockerAgent。关于在采集数据之上配置 Docker 监控器与告警见 Docker Monitor 文档。概览一个镜像、一条命令Docker Agent 的核心设计是单镜像、单命令无需手工编写或维护 OpenTelemetry Collector 配置Agent 镜像已经打包好完整的otel-collector-config.yaml并内置 inventory 快照轮询器。其工作链路如下自动发现通过挂载进容器的/var/run/docker.sock与 Docker Engine API 通信自动发现主机上全部容器指标采集docker_statsreceiver 按固定间隔默认 30s抓取每个容器的 CPU、内存、网络、块 I/O 等指标日志采集filelogreceiver 读取/var/lib/docker/containers/*/*-json.log即 Docker 默认json-file日志驱动写入的 JSON 行文件并补充容器元数据与推导出的严重级别转发上报经过 resource 打标、batch 批处理、memory_limiter 内存保护后由otlphttpexporter 将指标与日志 POST 到 OneUptime 的/otlp端点。从仓库中的 Collector 配置agents/DockerAgent/otel-collector-config.yaml可以看到三条管线service: pipelines: metrics: receivers: [docker_stats] processors: [memory_limiter, resourcedetection, resource, batch] exporters: [otlphttp] logs: receivers: [filelog] processors: [memory_limiter, filter/drop_self_logs, resourcedetection, resource, batch] exporters: [otlphttp] logs/inventory: receivers: [filelog/inventory] processors: [memory_limiter, resourcedetection, resource, batch] exporters: [otlphttp]指标、运行时日志与库存快照各走一条独立管线其中logs/inventory单独成管线是为了避免按正文内容匹配的filter/drop_self_logs过滤器误吞库存快照。Agent 启动后由 entrypoint.sh 在后台拉起 inventory 轮询器随后exec /otelcol-contrib将 Collector 作为前台受监督进程运行——Collector 一旦退出容器便会重启。Agent 连接成功后该 Docker 主机将自动出现在 OneUptime 控制台的 Docker 区域无需手动创建主机条目Docker Monitor 文档对此有明确说明主机在 Agent 首次上报遥测数据时自动注册。前提条件在部署前请确认以下条件Docker Engine 20.10 或更高版本文档明确的最低版本要求宿主机上可访问/var/run/docker.sockAgent 依赖该 Unix Socket 与 Docker Engine API 通信一个 OneUptime 遥测采集 TokenTelemetry Ingestion Token在Project Settings → Telemetry APM → Ingestion Keys中创建并复制其值部署时作为ONEUPTIME_SERVICE_TOKEN传入。需要特别提醒的日志前提Agent 的filelogreceiver 只能解析 Docker 的json-file日志驱动Docker 默认驱动写出的*-json.log文件无法读取local驱动二进制 protobuf 格式或journald、syslog、fluentd、gelf等远程驱动。若某些容器改用了其他驱动它们将没有日志上报。详情见下文 日志驱动要求。快速开始单命令将YOUR_ONEUPTIME_URL、YOUR_TELEMETRY_INGESTION_TOKEN与主机名替换为你的环境值。主机名决定该 Docker 主机在 OneUptime 中的显示名称建议取稳定的标识例如prod-docker-01docker 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_URLYOUR_ONEUPTIME_URL \ -e ONEUPTIME_SERVICE_TOKENYOUR_TELEMETRY_INGESTION_TOKEN \ -e DOCKER_HOST_NAMEmy-docker-host \ oneuptime/docker-agent:release命令要点解析参数作用--user 0:0以 root 运行否则无权访问/var/run/docker.sock见故障排查-v /var/run/docker.sock:/var/run/docker.sock:ro只读挂载 Docker Socket供docker_statsreceiver 抓取指标-v /var/lib/docker/containers:/var/lib/docker/containers:ro只读挂载容器日志目录供filelogreceiver 读取*-json.log--restart unless-stopped保证 Collector 异常退出后自动重启执行完这一步即可——Agent 一旦连接主机便会自动出现在 OneUptime 控制台的Docker区域。备选方案 — Docker Compose偏好 Docker Compose 时将以下内容写入docker-compose.ymlservices: oneuptime-docker-agent: image: oneuptime/docker-agent:release container_name: oneuptime-docker-agent user: 0:0 restart: unless-stopped volumes: - /var/run/docker.sock:/var/run/docker.sock:ro - /var/lib/docker/containers:/var/lib/docker/containers:ro environment: - ONEUPTIME_URLYOUR_ONEUPTIME_URL - ONEUPTIME_SERVICE_TOKENYOUR_TELEMETRY_INGESTION_TOKEN - DOCKER_HOST_NAMEmy-docker-host logging: driver: json-file options: max-size: 10m max-file: 3启动docker compose up -d仓库自带版本 agents/DockerAgent/docker-compose.yml 与之等价并体现了两个可复用的细节DOCKER_HOST_NAME${DOCKER_HOST_NAME:-docker-host}允许通过.env注入缺省时回落为docker-hostDOCKER_API_VERSION${DOCKER_API_VERSION-1.44}刻意使用${VAR-default}而非${VAR:-default}——冒号形式会把显式设置为空字符串的变量也替换成默认值从而吞掉设为空串以自动协商 API 版本这条逃生通道。# 来自 agents/DockerAgent/docker-compose.yml - DOCKER_API_VERSION${DOCKER_API_VERSION-1.44}环境变量变量必填说明ONEUPTIME_URL是OneUptime 实例地址例如https://oneuptime.com或你的自托管地址ONEUPTIME_SERVICE_TOKEN是遥测采集 Token来自Project Settings → Telemetry APM → Ingestion KeysDOCKER_HOST_NAME否该主机的友好名称默认docker-host每个主机建议设置为稳定的值如prod-docker-01DOCKER_API_VERSION否Agent 与 Docker Engine API 通信使用的 API 版本默认1.44较旧守护进程上应调低或置空以自动协商见故障排查这些变量在 Collector 配置中的落地方式agents/DockerAgent/otel-collector-config.yamlONEUPTIME_URL决定 OTLP exporter 端点endpoint: ${env:ONEUPTIME_URL}/otlpONEUPTIME_SERVICE_TOKEN作为请求头x-oneuptime-service-token: ${env:ONEUPTIME_SERVICE_TOKEN}DOCKER_HOST_NAME被打到资源属性上host.name: ${env:DOCKER_HOST_NAME}——这正是 Docker 主机页按主机过滤日志/指标所依赖的字段见故障排查主机名显示为容器 IDDOCKER_API_VERSION传给docker_statsreceiverapi_version: ${env:DOCKER_API_VERSION}。镜像标签仓库 agents/DockerAgent/README.md 列出的可用镜像标签标签说明oneuptime/docker-agent:release最新稳定版社区oneuptime/docker-agent:enterprise-release最新稳定版企业版oneuptime/docker-agent:version固定版本如10.0.31ghcr.io/oneuptime/docker-agent:release同一镜像在 GHCR 上的镜像副本验证安装检查 Agent 是否在运行docker ps --filter nameoneuptime-docker-agent查看 Agent 日志docker logs -f oneuptime-docker-agent在日志中寻找启动成功标记Everything is ready. Begin running and processing data.大约一分钟后主机应出现在 OneUptime 控制台中并有指标与日志持续流入。采集的数据指标清单类别数据每容器CPU总使用量、使用百分比、cgroup 限流时间throttling time内存使用量、限额、百分比、RSS、缓存网络接收/发送的字节数与包数块 I/O读/写字节数与操作数容器信息运行时长uptime、重启次数、进程数Agent 使用 OpenTelemetry 的docker_statsreceiver默认每 30 秒抓取一次 Docker Engine API。Docker Monitor 文档packages/App/FeatureSet/Docs/Content/en/monitor/docker-monitor.md给出了对应的具体指标名可供配置监控器查询时直接使用CPUcontainer.cpu.utilizationdocker stats的 CPU% 列100% 等于一个完整 CPU 核、container.cpu.usage.total生命周期累计计数器、container.cpu.throttling_data.throttled_time累计被 cgroup 限流的纳秒数、container.cpu.throttling_data.throttled_periods限流周期数内存container.memory.usage.total、container.memory.usage.limit、container.memory.percent网络container.network.io.usage.rx_bytes、container.network.io.usage.tx_bytes块 I/Ocontainer.blockio.io_service_bytes_recursive.read、container.blockio.io_service_bytes_recursive.write容器信息container.uptime秒、container.restarts生命周期计数器、container.pids.countcgroup pids 控制器统计的任务数。注意container.restarts与container.cpu.throttling_data.throttled_time是单调递增的生命周期计数器因此 Docker Monitor 的高重启/高限流告警模板评估的是窗口内计数器的增量而非绝对值否则任何重启过的容器都会永远触发告警。这些计数器在每次 30s 抓取之间取差若把collection_interval提高到 60s 以上每个时间桶只剩一个样本增量恒为 0会静默禁用这两个告警模板——如需修改抓取间隔请务必留意。在 Collector 配置中这类依赖告警模板的指标重启、运行时长、进程数、CPU 限流在 contrib 版docker_statsreceiver 里默认是关闭的Agent 的配置中显式开启agents/DockerAgent/otel-collector-config.yamlmetrics: 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日志采集容器日志自动从/var/lib/docker/containers/*/*-json.log采集并经过一系列 Operator 处理json_parser解析 Docker JSON 信封 →regex_parser从文件路径提取容器 ID → 多层move把log移入 body、stream移入log.iostream属性 →recombine合并多行堆栈 → severity 推导。最终以原生 OpenTelemetry 日志记录格式上报severityText、severityNumber、body、attributes、traceId、spanId均被填充。两个值得注意的实现细节多行日志合并Dockerjson-file驱动按行写 JSON 信封多行堆栈如 Node.js 的 at ...帧会被拆成多条记录。Agent 的recombineOperator 以body matches ^[^\s\}\)\]]判断新纪录起点把同一容器日志文件中以空白或右括号开头的行与前一条合并并以log.file.path作为source_identifier防止跨容器串并force_flush_period: 5s、max_log_size: 1048576兜底排除自身日志filelogreceiver 通过exclude前缀通配/var/lib/docker/containers/${env:HOSTNAME}*/*-json.log容器内HOSTNAME默认是短容器 ID而 Docker 以完整 ID 命名日志目录避免 Collector 采集并上报自己的抓取/导出堆栈形成回环配置中还额外以filter/drop_self_logs处理器丢弃特征性的 Collector 自日志。严重级别推导是日志链路中较精巧的一环。Dockerjson-file驱动本身不记录严重级别而 OTel 日志记录依赖severity_number/severity_text做过滤因此 Agent 使用routerregex_parserseverity_parser的组合进行最佳努力推导级别关键字只在其该在的位置才被采信有两种形态按序匹配行首前导preamble关键字位于记录首行且其前的都是前导字符——标点、数字及以结构分隔符.]-:/|)}结尾的单词 token。即[ERROR] ...、Monolog 的app.INFO: ...、2026-08-31 07:25:04 INFO ...、Python 的... - myapp - INFO - ...、logfmt 的levelerror ...均命中而散文式表述Connection error, retrying不会被误判。重复匹配是惰性的取前导中第一个关键字级别字段行内任意位置形如level/lvl/severity/severity_text/levelname/log.level/log_level的键以:或分隔的值。即 zap、logrus 的 JSON{level:info}与非首字段的 logfmtts... levelerror msg...。无关键字时回退到流stderr →ERRORstdout →INFO文本级别再经severity_parserpreset: default 自定义映射提升到 LogRecord 的severity_number自定义映射覆盖了 stanza 内建预设缺失的级别warning→warn、error→err/crit/critical、fatal→panic/alert/emerg/emergencynginx 会输出[emerg]、info→notice。该行为的边界用例含不得被误判的行由测试 Tests/Ops/ContainerAgentLogSeverity.test.js 固化约束。升级 Agentdocker pull oneuptime/docker-agent:release docker rm -f oneuptime-docker-agent # 重新执行上面的 docker run 命令或使用 Docker Composedocker compose pull docker compose up -d卸载 Agentdocker rm -f oneuptime-docker-agent若使用 Docker Composedocker compose down自托管 OneUptime自托管场景下把ONEUPTIME_URL指向自己的实例-e ONEUPTIME_URLhttps://your-oneuptime-host.example.com如果实例仅提供 HTTP使用http://并带上对应端口。日志驱动要求Agent 只采集使用 Dockerjson-file日志驱动的容器日志。虽然这是 Docker 默认驱动但部分安装会改成local二进制 protobuf 写入local-logs/而非*-json.log或远程驱动journald、syslog、fluentd、gelf等——filelogreceiver 都无法读取。检查某个容器的当前日志驱动docker inspect container --format {{.HostConfig.LogConfig.Type}}检查守护进程默认驱动docker info --format {{.LoggingDriver}}将 Compose 服务切换为json-file并配置合理的轮转为每个服务添加logging块services: 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并**重新创建而非仅重启**受影响的容器——日志驱动在容器创建时即被绑定已存在的容器必须删除重建才会切换到新驱动# Docker Compose docker compose up -d --force-recreate service # 纯 Docker docker rm -f container docker run ... image注意Agent 自身在 Compose 中也配置了logging: json-file并限制max-size: 10m、max-file: 3避免 Agent 自己的日志无限增长。故障排查Docker Socket 权限被拒绝Agent 容器必须以 root--user 0:0运行才能访问/var/run/docker.sock。请确认--user 0:0标志或 Compose 中的user: 0:0存在。Agent 以 client version is too new 反复重启Error: cannot start pipelines: failed to start docker_stats receiver: Error response from daemon: client version 1.44 is too new. Maximum supported API version is 1.41守护进程会拒绝比自己最大值更新的客户端导致 receiver 无法启动Collector 随之退出——容器因此进入重启循环。查看守护进程支持的最大 API 版本并传给 Agentdocker version --format {{ .Server.APIVersion }} # 例如 Engine 20.10 上为 1.41然后将-e DOCKER_API_VERSION1.41或你查到的值加入docker run或在 Compose 中设置DOCKER_API_VERSION。较新的守护进程仍会提供旧版 API因此该设置在守护进程升级后依然有效可在合适时机移除。如果不想手动查版本号把DOCKER_API_VERSION设为空字符串即可。此时 Agent 会让 Docker SDK 与守护进程协商版本一次HEAD /_ping随后采用守护进程自己的最大值兼容新旧守护进程docker run -d ... -e DOCKER_API_VERSION ...仓库中 Collector 配置对该空值做了特别设计agents/DockerAgent/otel-collector-config.yamlapi_version使用不带默认值的${env:DOCKER_API_VERSION}而非${env:DOCKER_API_VERSION:-1.44}——因为 confmap 的:-默认值只在变量未设置时生效无法捕获 Compose 对缺失.env条目注入的空字符串而未设置的情况本来就会退化为自动协商这恰是两者中更安全的行为。Agent 显示为断连检查 Agent 是否在运行docker ps --filter nameoneuptime-docker-agent检查 Agent 日志docker logs oneuptime-docker-agent | grep -i error核实 OneUptime URL 与服务 Token 是否正确确保 Docker 主机能在网络上访问 OneUptime 实例没有任何指标出现确认 Docker Socket 在 Agent 容器内可访问docker exec oneuptime-docker-agent ls -la /var/run/docker.sock检查 Collector 日志中的导出错误docker logs oneuptime-docker-agent | tail -100确保服务 Token 有效且未过期指标正常但日志为空若指标已出现而Logs页为空或只有 Agent 自身日志最常见原因是容器未使用json-file日志驱动。诊断步骤# 1. 检查 Agent 的 filelog receiver 正在监视哪些文件 docker logs oneuptime-docker-agent 21 | grep -E Started watching file|no files match # 2. 检查容器实际使用的日志驱动 docker inspect container --format {{.HostConfig.LogConfig.Type}} # 3. 检查 receiver 期望的日志文件是否真的存在 docker run --rm --volumes-from oneuptime-docker-agent alpine:3.19 \ sh -c ls /var/lib/docker/containers/*/*-json.log 21 | head若第 1 步显示no files match the configured criteria或第 3 步对相关容器返回空列表则这些容器未使用json-file驱动按上文 日志驱动要求 切换即可。修改后必须重建容器。日志已采集但不出现在特定 Docker 主机页Docker 主机页按resource.host.name等于主机的hostIdentifier过滤该值取自传给 Agent 的DOCKER_HOST_NAME环境变量。如果你在主机自动注册后修改了DOCKER_HOST_NAMEOneUptime 会以新名称创建第二条主机记录日志将出现在新记录下。# 确认 Agent 正在打上的主机名 docker inspect oneuptime-docker-agent --format {{range .Config.Env}}{{println .}}{{end}} | grep DOCKER_HOST_NAME主机名显示为容器 ID将DOCKER_HOST_NAME环境变量设为友好名称并重新创建容器。常用命令速查# 查看 Agent 状态 docker ps --filter nameoneuptime-docker-agent # 查看 Agent 日志 docker logs -f oneuptime-docker-agent # 验证 Docker Socket 访问 docker exec oneuptime-docker-agent ls -la /var/run/docker.sock进阶本地构建镜像如需自行构建镜像开发或离线环境在仓库根目录执行npm run prerun # 从 Dockerfile.tpl 生成 Dockerfile docker build -f ./agents/DockerAgent/Dockerfile -t oneuptime/docker-agent:local .镜像对应的模板与入口见 agents/DockerAgent/Dockerfile.tpl 与 agents/DockerAgent/entrypoint.sh。此外仓库还提供 systemd 单元 agents/DockerAgent/systemd/oneuptime-docker-agent.service 与安装脚本 agents/DockerAgent/install.sh可用于以 systemd 方式托管 Agent适用于 Docker 由 systemd 管理的服务器。下一步配置Docker 监控器对容器 CPU / 内存 / 重启等条件告警——见 Docker Monitor 文档对于 Kubernetes 集群而非独立 Docker 主机使用 OneUptime Kubernetes Agent对于非容器化主机Linux / macOS / Windows 虚拟机与裸金属使用 主机 OpenTelemetry Collector。赞分享可观测性后端运维前端云原生微服务AI Agent【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址https://gitcode.com/GitHub_Trending/on/oneuptime点击查看免费下载相关推荐OneUptime Docker Agent 实战指南一条命令把 Docker 主机指标、容器日志接入 OneUptimeOneUptime Docker Agent 实战指南一条命令把 Docker 主机指标、容器日志接入 OneUptime OneUptime Docker可观测性后端运维前端云原生微服务AI AgentOneUptime Docker Agent一条命令完成 Docker 主机监控、容器日志采集与 OTLP 数据上报OneUptime Docker Agent一条命令完成 Docker 主机监控、容器日志采集与 OTLP 数据上报 OneUptime Docker Age可观测性后端运维前端云原生微服务AI AgentOneUptime Docker Agent 部署与运维完全指南一条命令接入 Docker 主机遥测监控OneUptime Docker Agent 部署与运维完全指南一条命令接入 Docker 主机遥测监控 本指南围绕 OneUptime 开源仓库中的 Doc可观测性后端运维前端云原生微服务AI Agent上一篇如何用开源替代方案解锁惠普游戏本硬件控制的真正潜力下一篇2025 Android进度轮终极解决方案从集成到定制全指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考