使用 cAdvisor v2 REST API 的 Go 客户端库：从初始化到容器统计的完整实战指南

可观测性指标监控云原生【免费下载链接】cadvisorAnalyzes resource usage and performance characteristics of running containers.项目地址https://gitcode.com/gh_mirrors/ca/cadvisor点击查看免费下载本篇技术指南以 cAdvisor 仓库中 client/v2/README.md 为骨架系统讲解如何用 Go 语言编写一个访问 cAdvisor REST API 的客户端程序。你将掌握 v2 客户端库的初始化方式、MachineInfo/VersionInfo/Attributes等核心方法的具体用法与返回结构、其底层 HTTP 请求的实现原理以及仓库中配套的单元测试如何验证这些行为——阅读完即可在自己的 Go 项目中直接接入 cAdvisor 指标数据。一、v2 客户端库是什么cAdvisorContainer Advisor是 Google 开源的容器资源监控与分析工具它通过 REST API 对外暴露正在运行的容器与宿主机的资源使用情况。为了让 Go 程序能够以类型安全、可编程的方式消费这些 API仓库在 client/v2/client.go 中实现了一个专门面向 v2 API 的 Go 客户端其包注释明确写道Client library to programmatically access cAdvisor API.这个客户端定位在client/v2包中与client包面向 v1 API形成互补。它负责把 HTTP 请求、JSON 编解码等底层细节封装起来向上层开发者暴露一组面向业务的方法例如获取机器信息、版本信息、机器属性以及容器历史统计。二、创建客户端NewClient 与 URL 规范使用该客户端的第一步是创建实例文档给出了最简洁的用法client, err : client.NewClient(http://192.168.59.103:8080/)文档特别提醒请务必将示例 URL 替换为你实际部署的 cAdvisor REST 端点地址。如果 cAdvisor 部署在本地默认端口通常写作http://localhost:8080/。底层实现NewClient 做了什么查看 client/v2/client.go#L39-L47 的源码可以发现NewClient并非简单保存 URLfunc NewClient(url string) (*Client, error) { if !strings.HasSuffix(url, /) { url / } return Client{ baseURL: fmt.Sprintf(%sapi/v2.1/, url), }, nil }这里有两个值得注意的实现细节自动补齐末尾斜杠如果传入的 URL 不以/结尾客户端会自动补上避免后续路径拼接出错强制拼接api/v2.1/前缀所有请求最终都会指向 cAdvisor 的v2.1 API 版本。也就是说你传入http://host:8080/实际访问的是http://host:8080/api/v2.1/。Client结构体本身极其轻量只有一个字段baseURL string见 client/v2/client.go#L33-L36。在服务端v2 API 的路由由 cmd/internal/api/versions.go 中的version2_0等版本实现注册管理客户端默认访问的 v2.1 端点支持version、attributes、machine、summary、stats、spec、ps、custommetrics等多种请求类型。需要说明的是虽然客户端固定使用api/v2.1/前缀但 v2.0 与 v2.1 的端点布局高度一致二者共享同一套请求类型注册逻辑。三、MachineInfo机器硬件信息用法client.MachineInfo()文档明确指出v2 API 没有独立的 MachineInfo 端点因此 v2 客户端直接复用了 v1 的机器信息模型返回类型为*v1.MachineInfo。也就是说虽然走的是 v2 客户端拿到的数据结构和 v1 完全一致。返回结构示例文档给出了一个典型的返回值字段含运行时元数据实际打印结果因环境而异(*v1.MachineInfo)(0xc208022b10)({ NumCores: (int) 4, MemoryCapacity: (int64) 2106028032, Filesystems: ([]v1.FsInfo) (len1 cap4) { (v1.FsInfo) { Device: (string) (len9) /dev/sda1, Capacity: (uint64) 19507089408 } } })可以看到MachineInfo至少包含NumCores机器 CPU 核心数MemoryCapacity机器总内存字节Filesystems机器上的文件系统列表每个条目包含块设备名如/dev/sda1与容量。从源码看完整字段随着仓库演进MachineInfo的完整定义被迁移到了 lib/model/machine.go#L182-L251并在 info/v1/machine.go#L55 通过类型别名type MachineInfo model.MachineInfo暴露给 v1 包。完整的字段比文档示例丰富得多包括Timestamp信息采集时间点CPUVendorIDCPU 厂商 IDNumCores/NumPhysicalCores/NumSockets/NumBooks/NumDrawers多层次的核数、物理核数、插槽数等拓扑信息CpuFrequency核心最大主频单位 KHzMemoryCapacity/SwapCapacity/MemoryByType内存、交换分区容量及按类型划分的内存信息HugePages大页配置MachineID/SystemUUID/BootID机器标识、系统 UUID 与启动 IDFilesystems文件系统列表DiskMap磁盘映射NetworkDevices网络设备TopologyCPU/内存布局与层级描述CloudProvider/InstanceType/InstanceID云厂商、实例类型与实例 ID。对应 JSON 序列化字段为num_cores、memory_capacity、filesystems、cpu_frequency_khz等。这一点与客户端实现相互印证MachineInfo()内部通过httpGetJSONData把响应 JSON 反序列化进v1.MachineInfo结构见 client/v2/client.go#L52-L60。服务端如何响应在服务端v2 处理器对machine请求的处理逻辑是调用m.GetMachineInfo()后直接输出v1.MachineInfo代码注释// TODO(rjnagal): Move machineInfo from v1.表明这是历史上为兼容 v1 模型而保留的设计见 cmd/internal/api/versions.go#L342-L350。另外在 v1 的页面资产中cmd/internal/pages/assets/js/containers.js#L189 也通过api/v1.0/machine拉取机器信息用于前端绘图可见机器信息是监控页面与 API 共同依赖的基础数据。四、VersionInfo获取 cAdvisor 版本号用法client.VersionInfo()文档描述该方法返回 cAdvisor 的版本字符串。注意它与其他方法不同——返回的不是 JSON 结构而是一个纯文本字符串方法签名func (c *Client) VersionInfo() (version string, err error)。底层实现查看 client/v2/client.go#L73-L77func (c *Client) VersionInfo() (version string, err error) { u : c.versionInfoURL() version, err c.httpGetString(u, version info) return }它走的是httpGetString而不是httpGetJSONData因为服务端对该端点的响应就是一个裸字符串。这一点在服务端处理器中同样有印证v2 对version请求的处理是writeResult(versionInfo.CadvisorVersion, w)直接写出CadvisorVersion字段见 cmd/internal/api/versions.go#L322-L328。在单元测试TestGetVersionv1中见 client/v2/client_test.go#L97-L111测试服务器直接返回0.1.2这类裸字符串客户端断言收到的版本字符串完全一致验证了纯文本返回的契约。五、Attributes机器硬件与软件属性全集用法client.Attributes()文档描述该方法返回一个 info/v2 的 Attributes 结构所有字段都会被填充。Attributes 既包含硬件属性与 MachineInfo 返回的内容重叠又包含软件属性如内核版本、操作系统版本、Docker 版本、cAdvisor 自身版本等。返回结构示例文档给出了典型的返回示例(*v2.Attributes)({ KernelVersion: (string) (len17) 3.13.0-44-generic ContainerOsVersion: (string) (len18) Ubuntu 14.04.1 LTS DockerVersion: (string) (len9) 1.5.0-rc4 CadvisorVersion: (string) (len6) 0.10.1 NumCores: (int) 4, MemoryCapacity: (int64) 2106028032, Filesystems: ([]v2.FsInfo) (len1 cap4) { (v2.FsInfo) { Device: (string) (len9) /dev/sda1, Capacity: (uint64) 19507089408 } } })这个示例取自较早版本字段中的NumCores/MemoryCapacity/Filesystems属于硬件维度而KernelVersion/ContainerOsVersion/DockerVersion/CadvisorVersion属于软件维度。Attributes 完整字段清单结合 info/v2/machine.go#L24-L76 的源码Attributes的完整字段含 JSON 标签如下字段JSON key含义KernelVersionkernel_version内核版本ContainerOsVersioncontainer_os_versioncAdvisor 容器所用 OS 镜像版本直接跑在宿主机上时即宿主机 OSDockerVersiondocker_versionDocker 版本DockerAPIVersiondocker_api_versionDocker API 版本CadvisorVersioncadvisor_versioncAdvisor 自身版本NumCoresnum_coresCPU 核心数CpuFrequencycpu_frequency_khz核心最大主频KHzMemoryCapacitymemory_capacity内存容量字节MachineIDmachine_id机器 IDSystemUUIDsystem_uuid系统 UUIDHugePageshugepages大页信息Filesystemsfilesystems文件系统列表DiskMapdisk_map磁盘映射NetworkDevicesnetwork_devices网络设备TopologytopologyCPU/内存拓扑CloudProvidercloud_provider云厂商InstanceTypeinstance_type云实例类型Attributes 是怎么拼出来的服务端对该端点的处理逻辑见 cmd/internal/api/versions.go#L329-L341非常清晰先取MachineInfo再取VersionInfo然后调用 info/v2/machine.go#L78-L98 中的v2.GetAttributes(machineInfo, versionInfo)把两者合并为一个Attributes结构软件字段KernelVersion、ContainerOsVersion、DockerVersion、DockerAPIVersion、CadvisorVersion来自VersionInfo硬件字段NumCores、CpuFrequency、MemoryCapacity、MachineID、SystemUUID、HugePages、Filesystems、DiskMap、NetworkDevices、Topology、CloudProvider、InstanceType来自MachineInfo。因此调用一次Attributes()就能同时拿到宿主机硬件与运行环境软件的全景信息非常适合做环境自检、采集端元数据上报等场景。VersionInfo结构体的定义可在 lib/model/machine.go#L315-L332 查看含CadvisorRevision等 git 版本字段。六、客户端方法速览Stats 与 MachineStatsREADME 只重点介绍了前三个方法但 client/v2/client.go 还提供了两个同样重要、常用于指标采集的方法这里一并补充。Stats按容器名拉取历史统计func (c *Client) Stats(name string, request *v2.RequestOptions) (map[string]v2.ContainerInfo, error)Stats以容器名或 Docker 容器 ID为参数返回map[string]v2.ContainerInfo——key 为容器标识value 为该容器的规格描述与历史统计序列。RequestOptions在 lib/model/projection.go#L33-L42 中定义字段含义IdType容器标识类型name默认、docker、podman对应 info/v2/container.go#L26-L30 中的常量Count返回的统计样本数量-1表示不限制Recursive是否同时返回子容器的统计默认falseMaxAge若统计数据早于该时间则强制刷新nil不刷新0总是刷新从实现上看client/v2/client.go#L91-L108这些选项会被编码为 HTTP 查询参数type、count、recursive、max_age拼接到/stats/{name}端点上。关于这些参数的语义可参考 docs/api_v2.md 中的约定count默认 64recursive默认 false容器 ID 支持typedocker或typepodman指定。ContainerInfo结构的完整定义含ContainerSpec与ContainerStats系列覆盖 CPU、内存、网络、文件系统、进程、大页、perf 事件等见 info/v2/container.go#L61-L192。MachineStats整机统计func (c *Client) MachineStats() ([]v2.MachineStats, error)MachineStats返回整机层面的统计序列MachineStats结构info/v2/machine.go#L100-L140包含时间戳、CPU 聚合/瞬时统计、内存、网络、文件系统容量与用量、任务负载等其中MachineFsStats还内嵌了磁盘 I/O 统计读完成次数、合并读、读扇区、读耗时等见 info/v2/machine.go#L142-L197是磁盘监控的重要数据来源。事件客户端若需要监听容器生命周期事件创建、OOM、删除等仓库在 client/clientexample/main.go 中演示了事件客户端的两种用法EventStaticInfo(?oom_eventstrue)拉取静态事件列表EventStreamingInfo(?creation_eventstruestreamtrueoom_eventstruedeletion_eventstrue, einfo)通过 channel 持续接收事件流可作为完整客户端集成的参考样例。七、统一 HTTP 请求管道错误处理与 JSON 解析客户端所有方法最终都汇聚到两个内部函数见 client/v2/client.go#L130-L178理解了它们就理解了整个客户端的行为边界httpGetResponse(postData, urlPath, infoName)底层网络层。当postData非空时使用http.Post并携带application/json请求体否则使用http.Get响应体统一用io.ReadAll读完状态码非 200 时返回错误错误信息包含响应体文本如request ... failed with error: ...连接失败、空响应同样返回带上下文的错误。httpGetJSONData(data, postData, url, infoName)在httpGetResponse基础上追加json.UnmarshalJSON 解析失败时错误信息会带上原始响应体便于排查。这套统一管道的好处是所有方法共享一致的重试前检查与错误语义。单元测试TestRequestFailsclient/v2/client_test.go#L183-L204专门验证了服务端返回 500 时客户端会原样携带错误文本返回给调用方。八、用单元测试验证客户端行为仓库为 v2 客户端提供了完整的单元测试client/v2/client_test.go全部采用httptest.NewServer构造本地假服务端通过cadvisorTestClient辅助函数把假服务端 URL 交给NewClient从而在无真实 cAdvisor 的环境下验证行为测试函数验证内容TestGetMachineInfo请求路径为/api/v2.1/machine返回的*v1.MachineInfo与预期深度相等reflect.DeepEqualTestGetVersionv1请求/api/v2.1/version验证纯文本版本字符串往返一致TestGetAttributes请求/api/v2.1/attributes验证*v2.Attributes完整往返TestMachineStats请求/api/v2.1/machinestats验证[]v2.MachineStats中的 CPU 与文件系统统计TestRequestFails服务端返回 500断言客户端返回包含服务端错误文本的 error从测试断言中可以确认各端点的最终请求路径与 client/v2/client.go#L110-L128 中的 URL 构造函数一一对应machineInfoURL→/api/v2.1/machinemachineStatsURL→/api/v2.1/machinestatsversionInfoURL→/api/v2.1/versionattributesURL→/api/v2.1/attributesstatsURL(name)→/api/v2.1/stats/{name}这些测试既是质量保障也是理解客户端契约的最佳文档。九、完整使用示例与常见问题最小可运行示例把以下代码片段放入你的 Go 项目替换 URL 为你自己的 cAdvisor 地址package main import ( fmt client github.com/google/cadvisor/client/v2 ) func main() { c, err : client.NewClient(http://localhost:8080/) if err ! nil { panic(err) } // 1. 机器硬件信息v1 模型含核数、内存、文件系统等 mi, err : c.MachineInfo() if err ! nil { panic(err) } fmt.Printf(cores%d memory%d filesystems%v\n, mi.NumCores, mi.MemoryCapacity, mi.Filesystems) // 2. cAdvisor 版本纯文本 ver, err : c.VersionInfo() if err ! nil { panic(err) } fmt.Println(cadvisor version:, ver) // 3. 硬件 软件属性全集 attr, err : c.Attributes() if err ! nil { panic(err) } fmt.Printf(kernel%s os%s docker%s\n, attr.KernelVersion, attr.ContainerOsVersion, attr.DockerVersion) }常见问题与注意事项URL 末尾斜杠NewClient会自动补齐但建议按文档习惯带上http://host:port/的标准形态API 版本客户端固定访问api/v2.1/需确认部署的 cAdvisor 版本支持 v2.1 API当前仓库的服务端实现于 cmd/internal/api/versions.go 中注册了完整 v2 请求类型v2.1 为其当前版本对于MachineInfo与Attributes即使 cAdvisor 版本较老v2 端点也会以兼容形式返回对应数据错误处理所有方法在连接失败、非 200 状态码、JSON 解析失败时都会返回带上下文的 error调用方应显式检查并记录参考TestRequestFails的断言语义容器统计参数用Stats(name, v2.RequestOptions{IdType: docker, Count: 64, Recursive: true})可一次拉取某 Docker 容器及其子容器的最近 64 个采样Count传-1表示不限制数量机器统计用途MachineStats()返回的磁盘 I/O 统计读/写完成次数、耗时等适合做宿主机磁盘健康度分析。十、总结client/v2是 cAdvisor 官方提供的、面向 v2 REST API 的 Go 客户端实现通过NewClient一行初始化后即可用类型安全的方式获取机器信息MachineInfo、版本号VersionInfo、硬件与软件属性全集Attributes、整机统计MachineStats以及任意容器/子容器的历史统计Stats。其背后是一套统一且健壮的 HTTP 请求管道非 200 即报错、JSON 解析失败带原始响应并有配套单元测试固化了端点路径与数据结构契约。无论是构建自定义监控系统、为 Kubernetes 平台补充采集能力还是快速验证 cAdvisor 部署的正确性这个客户端都是最直接的切入点。更多 API 细节可继续阅读 docs/api_v2.md 与 info/v2/container.go、info/v2/machine.go 中的类型定义。赞分享可观测性指标监控云原生【免费下载链接】cadvisorAnalyzes resource usage and performance characteristics of running containers.项目地址https://gitcode.com/gh_mirrors/ca/cadvisor点击查看免费下载相关推荐OpenCloud 中的 MinIO Go SDKminio-go/v7实战指南从 S3 客户端初始化到对象上传OpenCloud 中的 MinIO Go SDKminio go/v7实战指南从 S3 客户端初始化到对象上传 minio go/v7 是 MinIO后端微服务存储认证鉴权REST Client实战构建完整的API客户端应用REST Client实战构建完整的API客户端应用 REST Client是一个简单易用的HTTP和REST客户端库专为Ruby开发者设计。它采用Sina后端API设计OpenCloud 项目中的 Go HTTP 客户端利器Resty v2 完整实战指南OpenCloud 项目中的 Go HTTP 客户端利器Resty v2 完整实战指南 Resty 是一款受 Ruby rest client 启发、专为 G后端微服务存储认证鉴权上一篇从冲突到兼容PGlite中pgvector扩展OID分配机制深度解析下一篇探索PDFMathTranslate智能保留数学公式的学术文献翻译神器创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考