docker-ce 指标采集实践指南：go-metrics 统一 Prometheus 度量约定的原理与实战

容器运行时云原生【免费下载链接】docker-ce:warning: This repository is deprecated and will be archived (Docker CE itself is NOT deprecated) see the https://github.com/docker/docker-ce/blob/master/README.md :warning:项目地址https://gitcode.com/gh_mirrors/do/docker-ce点击查看免费下载go-metrics 是 Docker 官方为规范自身项目指标采集而封装的一个轻量库它并不是 Prometheus Go 客户端的替代品而是在其之上强制统一的命名、标签与单位约定让 Docker 生态中各模块导出的指标风格一致、易于检索与聚合。本文以本仓库components/engine/vendor/github.com/docker/go-metrics下的文档与源码为主线系统讲解其核心 API、最佳实践约定并结合 docker-ce 引擎内 daemon、builder、logger 等模块的真实用法帮助读者在自己的 Docker 组件或 Prometheus 集成中快速落地这套度量规范。一、go-metrics 是什么约定优先的 Prometheus 封装从包内docs.go的定义可以读出它的定位This package is small wrapper around the prometheus go client to help enforce convention and best practices for metrics collection in Docker projects.docs.go即这是一个“约定与最佳实践执行器”。它不是Prometheus client 的替代品而是用于保证不同 Docker 项目采集的指标在命名上保持一致的约束层。README 明确建议如果还没读过 Prometheus 官方关于命名与标签的最佳实践应当先补齐这部分知识而本库的目标是让“Docker 项目内所有指标”遵循同一套规则。从依赖关系看go.mod 声明模块为github.com/docker/go-metrics唯一运行时依赖是github.com/prometheus/client_golang再次印证它只是 Prometheus 客户端之上的薄封装。整个包的结构非常精简共 8 个源码文件职责划分清晰文件职责namespace.goNamespace类型与各指标类型的构造方法核心入口unit.go标准单位常量Unit类型counter.goCounter / LabeledCounter 接口与实现timer.goTimer / LabeledTimer 接口与实现基于 Histogramgauge.goGauge / LabeledGauge 接口与实现handler.goHTTP 指标采集的包装与默认分桶配置register.go全局注册与反注册helpers.go内部数值累加辅助函数二、Namespace 与 Subsystem统一指标命名空间README 第一条规则是Namespace 和 Subsystem。go-metrics提供一个Namespace类型允许为同一批指标指定相同的 namespace 与 subsystem。文档中的示例ns : metrics.NewNamespace(engine, daemon, metrics.Labels{ version: dockerversion.Version, commit: dockerversion.GitCommit, })在上例中engine是 namespacedaemon是 subsystem即采集指标所在的包。此时创建的所有指标其完整 Prometheus 名称会被拼成namespace_subsystem_name_unit。对照源码namespace.go 中NewNamespace(name, subsystem string, labels Labels)会构造Namespace结构体并缓存 name、subsystem 与常量标签func NewNamespace(name, subsystem string, labels Labels) *Namespace { if labels nil { labels make(map[string]string) } return Namespace{ name: name, subsystem: subsystem, labels: labels, } }名称拼接逻辑集中在makeName与NewDesc两处namespace.gofunc (n *Namespace) NewDesc(name, help string, unit Unit, labels ...string) *prometheus.Desc { name makeName(name, unit) namespace : n.name if n.subsystem ! { namespace fmt.Sprintf(%s_%s, namespace, n.subsystem) } name fmt.Sprintf(%s_%s, namespace, name) return prometheus.NewDesc(name, help, labels, prometheus.Labels(n.labels)) }可见 subsystem 为空时不会产生多余的_分隔符——builder命名空间即采用此写法见下文第九节。三、常量标签Const Labels让版本与提交信息随指标输出Namespace的另一个能力是附加常量标签。README 指出这通常用于携带应用版本号、git commit 等“每个数据点都相同”的信息避免在每个指标上重复录入。上述示例中version与commit会被自动注入该命名空间下创建的所有指标。源码实现上构造prometheus.CounterOpts/HistogramOpts/GaugeOpts时统一携带ConstLabels: prometheus.Labels(n.labels)见 namespace.go 的newCounterOpts等方法。此外Namespace.WithConstLabels(labels)返回一个合并了额外常量标签的新Namespacenamespace.go。值得注意的边界行为只有使用返回的新 Namespace创建的指标才会获得新增的常量标签新 Namespace 必须单独注册标签合并由mergeLabels完成后面的标签覆盖前面同名键namespace.go。四、将指标声明集中到单一文件README 第二条规则尽量把全部指标声明集中在一个文件里。这样其他人一眼就能看到 Namespace 上定义了哪些常量标签、各个指标又各自带哪些标签便于审计与维护。这一约定在 docker-ce 引擎中被严格贯彻daemon包把所有引擎级指标集中在 daemon/metrics.gobuilder的指标集中在 builder/dockerfile/metrics.gologger的指标集中在 daemon/logger/metrics.go全部以包级var声明 init()注册的结构组织。五、用标签代替多个指标LabeledTimer 实战README 第三条规则优先用标签而不是创建多个指标。文档示例围绕“容器动作耗时”展开——若想分别采集 create、start、delete 的耗时正确做法是定义一个container_actions指标用action标签区分动作类型containerActions ns.NewLabeledTimer(container_actions, The number of milliseconds it takes to process each container action, action)最后一个参数即标签名key。写入数据点时通过WithValues指定具体的actioncontainerActions.WithValues(create).UpdateSince(start)这条示例与 docker-ce 引擎的真实用法几乎完全一致。看 daemon/metrics.go 的init()ns : metrics.NewNamespace(engine, daemon, nil) containerActions ns.NewLabeledTimer(container_actions, The number of seconds it takes to process each container action, action) for _, a : range []string{ start, changes, commit, create, delete, } { containerActions.WithValues(a).Update(0) }注意这里文档说“milliseconds”而引擎实际把 help 文案写为 “The number of seconds…”。这是因为 Timer 底层是 PrometheusHistogramUpdate/UpdateSince内部会调用Observe(duration.Seconds())即观测值统一换算为秒见 timer.go。也就是说Timer 在 go-metrics 中即直方图适合分析延迟分布而不是单一均值。而for循环预置各 label 值是为了让系列在采集侧尽早暴露、避免首次请求后才出现的标签组合。引擎中WithValues(...).UpdateSince(start)的组合调用随处可见例如 daemon/info.go 与 daemon/info.go 用metrics.StartTimer(hostInfoFunctions.WithValues(system_info))()配合defer统计docker system info的耗时StartTimer的实现在 timer.go记录起始时刻并返回一个done func()调用时自动Update(time.Since(start))是“耗时指标”最省心的写法。六、Always use a unit单位命名约定README 第四条规则指标名必须体现计量单位。Timer 的标准单位是秒secondsCounter 的标准单位是 totalGauge 则必须显式指定单位。go-metrics 内置了一套标准单位unit.goNanoseconds Unit nanoseconds Seconds Unit seconds Bytes Unit bytes Total Unit total这套单位不只是“文档约定”而是直接参与指标命名。makeName(name, unit)namespace.go会把单位拼成后缀Counter自动追加_total见newCounterOpts中Name: makeName(name, Total)Timer自动追加_seconds见newTimerOptsGauge后缀取决于构造时传入的 Unit如metrics.Bytes→_bytes。README 建议如果确实没有现成单位可用优先在包内已有的 seconds / nanoseconds 中二选一而不是引入毫秒之类的近似单位确需新增时通过 PR 补充进包而不是各项目自行扩散。看引擎实际产生的指标名就一目了然daemon/metrics.goengine_cpus→ns.NewGauge(engine_cpus, …, metrics.Unit(cpus))daemon/metrics.goengine_memory→ns.NewGauge(engine_memory, …, metrics.Bytes)对外为engine_daemon_engine_memory_bytesdaemon/events/metrics.goeventsCounter与events_subscribersGauge单位metrics.Totaldaemon/logger/metrics.go三个失败/丢弃计数的 Counter七、四种基础指标类型与接口设计Namespace上提供了成对出现的“普通”与“带标签”构造方法均返回 go-metrics 自定义接口而非 Prometheus 原生类型构造方法返回接口底层 Prometheus 类型NewCounter/NewLabeledCounterCounter/LabeledCounterprometheus.Counter/CounterVecNewTimer/NewLabeledTimerTimer/LabeledTimerprometheus.Histogram/HistogramVecNewGauge/NewLabeledGaugeGauge/LabeledGaugeprometheus.Gauge/GaugeVecCountercounter.go接口方法Inc(vs ...float64)无参时对计数器 1有参时累加sumFloat64(vs...)helpers.go因此也支持一次性累加多个增量。Gaugegauge.go提供Inc(...float64)、Dec(...float64)、Add(float64)、Set(float64)其中Dec通过加负数实现。引擎用它表达当前状态量如 daemon/events/metrics.go 的events_subscribers当前事件订阅者数与 daemon/metrics.go 借助NewDescAdd(stateCtr)自定义的container_states统计各状态容器计数。Timertimer.goUpdate(duration)、UpdateSince(t)统一以秒为观测单位配合StartTimer使用体验最佳。LabeledXxx系列都遵循“先WithValues(...)填标签、后操作”的模式未填标签前不可直接写入数据这从接口设计上杜绝了漏填标签的低级错误。八、HTTP Metrics一行代码插桩 HTTP 处理器README 给出了把任意http.Handler变为可观测处理的完整示例namespace : metrics.NewNamespace(docker_distribution, http, metrics.Labels{handler: your_http_handler_name}) httpMetrics : namespace.NewDefaultHttpMetrics() metrics.Register(namespace) instrumentedHandler metrics.InstrumentHandler(httpMetrics, unInstrumentedHandler)README 同时强调创建 Namespace 时必须提供handler标签。需要提醒的是这段示例基于早期 API。当前 vendor 内的源码中NewDefaultHttpMetrics的签名已演进为需要传入 handler 名称参数namespace.gofunc (n *Namespace) NewDefaultHttpMetrics(handlerName string) []*HTTPMetric { return n.NewHttpMetricsWithOpts(handlerName, HTTPHandlerOpts{ DurationBuckets: defaultDurationBuckets, RequestSizeBuckets: defaultResponseSizeBuckets, ResponseSizeBuckets: defaultResponseSizeBuckets, }) }handler 名称会在构造各子指标时写入labels[handler]例如 namespace.go 的NewInFlightGaugeMetric。因此按当前源码正确的调用是namespace.NewDefaultHttpMetrics(your_http_handler_name)。一次NewDefaultHttpMetrics会生成5 类指标namespace.go指标名类型附加标签ns_sub_in_flight_requestsGaugehandlerns_sub_requests_totalCounterVechandler, code, methodns_sub_request_duration_secondsHistogramVechandler, methodns_sub_request_size_bytesHistogramVechandlerns_sub_response_size_bytesHistogramVechandler默认分桶配置定义在 handler.godefaultDurationBuckets []float64{.005, .01, .025, .05, .1, .25, .5, 1, 2.5, 5, 10, 25, 60} defaultRequestSizeBuckets prometheus.ExponentialBuckets(1024, 2, 22) //1K to 4G defaultResponseSizeBuckets defaultRequestSizeBuckets即延迟桶从 5ms 到 60s请求/响应大小桶按 2 的幂从 1KB 覆盖到 4GB。若默认桶不满足需求可改用NewHttpMetrics(handlerName, durationBuckets, requestSizeBuckets, responseSizeBuckets)自定义或使用更细粒度的NewHttpMetricsWithOpts三者对空桶数组都会直接panic如 namespace.go属于有意的防御设计。InstrumentHandler(metrics, handler)handler.go会依据每个HTTPMetric.handlerType依次包裹promhttp.InstrumentHandlerResponseSize、InstrumentHandlerRequestSize、InstrumentHandlerDuration、InstrumentHandlerCounter、InstrumentHandlerInFlight返回一个http.HandlerFunc原始 handler 逻辑零侵入。此外 handler.go 的Handler()直接返回promhttp.Handler()即标准的/metrics抓取端点。docker-ce 引擎的 metrics HTTP 服务正是这样搭建的见 cmd/dockerd/metrics.gomux : http.NewServeMux() mux.Handle(/metrics, metrics.Handler())九、注册与反注册把 Namespace 挂到全局 Registry创建好指标后必须注册才会被 Prometheus 采集。register.go提供两个极简函数func Register(n *Namespace) { prometheus.MustRegister(n) } func Deregister(n *Namespace) { prometheus.Unregister(n) }由于Namespace自身实现了Describe/Collectnamespace.go它本身就是一个prometheus.Collector注册时会把内部维护的所有指标批量暴露Register使用MustRegister若注册重复的 collector 会直接 panic把配置错误尽早暴露在init()阶段。Deregister常用于热卸载场景。docker-ce 引擎的各个模块都在自己的init()中完成注册例如 daemon/logger/metrics.gologgerMetrics : metrics.NewNamespace(logger, , nil) logWritesFailedCount loggerMetrics.NewCounter(log_write_operations_failed, Number of log write operations that failed) logReadsFailedCount loggerMetrics.NewCounter(log_read_operations_failed, Number of log reads from container stdio that failed) totalPartialLogs loggerMetrics.NewCounter(log_entries_size_greater_than_buffer, Number of log entries which are larger than the log buffer) metrics.Register(loggerMetrics)注意这里NewNamespace(logger, , nil)的 subsystem 为空最终指标名即为logger_log_write_operations_failed_total等。同样builder/dockerfile/metrics.go 用metrics.NewNamespace(builder, , nil)声明了builds_triggered与带reason标签的builds_failed并在init()中预注册 8 种失败原因Dockerfile 语法错误、空 Dockerfile、命令不支持、错误处理指令、目标不可达、缺失 onbuild 参数、未知指令、构建被取消这与container_actions的预置标签是同一套路。十、Additional Metrics包级贡献通用指标README 最后一部分指出本包还定义了一些Prometheus 客户端本身没有的额外指标如果某个自定义指标足够通用、可被多个项目复用就应定义在本包中而不是各自复制。例如引擎 vendor 里的 distribution/metrics/prometheus.go 就复用了 go-metrics 的Namespace机制定义registry_storage命名空间用于 blob/缓存相关的存储操作指标go-metrics 包内的StartTimer、HTTPHandlerOpts、各接口类型等均属这类“通用能力”避免每个项目各自发明一套。十一、在 docker-ce 中如何查看与配置这些指标以上所有指标最终通过 daemon 的 metrics HTTP 端点对外暴露配置项是--metrics-addrJSON 配置键为metrics-addr。定义见 cmd/dockerd/config.goflags.StringVar(conf.MetricsAddress, metrics-addr, , Set default address and port to serve the metrics api on)并在 daemon/config/config.go 中声明为 daemon 配置结构体字段。实际启停由 cmd/dockerd/daemon.go 的startMetricsServer(cli.Config.MetricsAddress)触发地址为空时不启动。典型启用方式dockerd --metrics-addr 127.0.0.1:9323 curl http://127.0.0.1:9323/metrics即可在/metrics看到engine_daemon_*、builder_*、logger_*等命名空间下的全部指标。此外daemon 在 Linux 上还会在ExecRoot下监听metrics.sockdaemon/metrics_unix.go并把 socket 以只读方式挂载进MetricsCollector类型的插件容器/run/docker/metrics.sock从而支持第三方指标采集插件通过 daemon/metrics.go 中的StartMetrics/StopMetrics生命周期接入——这是 go-metrics 约定在引擎层面的完整延伸。十二、实践要点小结命名三要素namespace_subsystem_name_unit通过NewNamespace一次性固定前两段避免各模块自由发挥常量标签放 Namespace可变维度放指标版本/commit 用常量标签动作类型、失败原因等用LabeledXxx的标签能用标签就不要造指标一组动作共用一个 LabeledTimer配合WithValues(...).UpdateSince(start)或StartTimer记录耗时单位必须显式Counter 自动带_total、Timer 自动带_secondsGauge 必须手动指定 Unit集中声明、预置标签把全部指标收敛到一个文件并在init()中预注册常见标签组合HTTP 服务一键插桩NewDefaultHttpMetrics(handlerName)InstrumentHandler即可获得请求数、延迟、大小、并发五类指标无需侵入业务代码。这套约定帮助 docker-ce 在 daemon、builder、logger、events、image 等数十个模块间维持一致的度量语义也让任何熟悉 Prometheus 的开发者拿到指标名即可读懂其含义。参考本仓库的 go-metrics 源码 与 引擎 daemon 指标注册示例你可以快速在自己的 Go 服务中复刻同样的度量体系。赞分享容器运行时云原生【免费下载链接】docker-ce:warning: This repository is deprecated and will be archived (Docker CE itself is NOT deprecated) see the https://github.com/docker/docker-ce/blob/master/README.md :warning:项目地址https://gitcode.com/gh_mirrors/do/docker-ce点击查看免费下载相关推荐Octant 项目中的 Docker go-metrics 实践用 Prometheus 约定统一 Kubernetes 平台指标采集Octant 项目中的 Docker go metrics 实践用 Prometheus 约定统一 Kubernetes 平台指标采集 导读 go metri云原生后端前端运维可观测性开发工具AWX 子系统指标Subsystem Metrics原理与实战从 Redis 存储到 Prometheus 采集AWX 子系统指标Subsystem Metrics原理与实战从 Redis 存储到 Prometheus 采集 导读 AWX 的子系统指标Subsys后端运维任务调度go-metrics 实战指南用 Prometheus 规范容器平台指标采集KubeSphere 仓库中的 Docker go-metrics 封装解析go metrics 实战指南用 Prometheus 规范容器平台指标采集KubeSphere 仓库中的 Docker go metrics 封装解析后端云原生容器编排微服务创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考