Telegraf system 输入插件详解include 选项、legacy 与细粒度指标、缓存机制与 DMI 采集原理【免费下载链接】telegrafAgent for collecting, processing, aggregating, and writing metrics, logs, and other arbitrary data.项目地址: https://gitcode.com/GitHub_Trending/te/telegraf本文围绕 Telegraf 的system输入插件展开讲解它如何通过include选项在兼容旧版legacy与细粒度指标之间切换覆盖 load、users、cpus、uptime、os、dmi 六类数据的采集原理、权限要求与缓存配置os_cache_ttl/dmi_cache_ttl并结合 源码实现 与测试用例说明字段来源、默认值及平台限制读完后可完整掌握该插件的推荐配置方式与指标输出结构。插件定位与基本信息system插件采集通用系统统计信息如系统负载、运行时间uptime、登录用户数等作用类似于 Unix 下的uptime命令。它是 Telegraf 最早期的插件之一自 v0.1.6 引入支持所有平台标签system平台all。插件定义见 plugins/inputs/system/README.md配置模板见 plugins/inputs/system/sample.conf。插件支持 Telegraf 的全局插件配置能力包括修改指标/标签/字段、别名、插件排序等通用配置项详见 CONFIGURATION.md。配置详解完整的配置模板如下源自 sample.conf# Read metrics about system load uptime [[inputs.system]] ## Information to collect; available options are: ## legacy - legacy layout of system metrics; see README for details ## cpus - CPU counts of the system ## dmi - BIOS, baseboard, chassis and product information from DMI/SMBIOS ## load - 1, 5 and 15-minute load averages ## os - operating system release and uname information ## uptime - system uptime ## users - logged-in user counts # include [legacy] ## How long to cache the result of the os group between gathers. ## Set higher to reduce the number of os-release/uname reads, lower to ## to surface distro upgrades and kexecd kernels faster. Set to zero to ## re-read the data on every gather. # os_cache_ttl 8h ## How long to cache the result of the dmi group between gathers. ## DMI/SMBIOS data is effectively static for the life of the machine, ## so a long cache is typical. Set to zero to re-read on every gather. # dmi_cache_ttl 8h各配置项说明配置项类型默认值说明includestring 数组[legacy]未配置时选择要采集的数据组legacy、cpus、dmi、load、os、uptime、usersos_cache_ttl时长8hos组结果在两次采集之间的缓存时长调大可减少读取/etc/os-release和uname次数调小可更快反映发行版升级或 kexec 内核设为 0 表示每次采集都重读dmi_cache_ttl时长8hdmi组结果缓存时长DMI/SMBIOS 数据在一台机器的生命周期内基本静态长缓存是常规做法设为 0 表示每次采集都重读从源码看默认值在插件注册时设定init()函数将OSCacheTTL和DMICacheTTL均初始化为 8 小时system.go#L334-L340。Init()阶段还会做三件事system.go#L44-L73默认值若include为空则回退为[legacy]合法性校验与去重遍历include只接受legacy/load/users/cpus/uptime/os/dmi七种取值出现非法值会报错invalid include option ...该行为由测试 TestInitErrors 验证重复项会被去重平台能力检查若启用了dmi但当前平台不支持仅输出告警日志并移除该项不致启动失败。支持 DMI这一约束通过构建标签实现——dmi_supported.go 中linux || windows平台下dmiSupported true其他平台dmi_other.go为false。legacy 与细粒度选项的选择这是该插件最关键的设计决策点原文档的结论值得完整理解legacy是兼容默认值但不推荐。它会产生三条稀疏指标一条包含 CPU、负载、用户信息一条是 uptimecounter一条是格式化后的 uptime 字符串untyped。但如果你的输出端是 Prometheuslegacy可能是更好的选择因为这几条指标带正确的类型typed。细粒度选项cpus、load、users、uptime等会产出单条无类型untyped的system指标所有选中的字段合并在同一条指标里。要复现legacy集的字段应使用include [load, users, cpus, uptime]。两者可同时使用此时共输出四条指标细粒度集合 1 条 legacy3 条。从 Gather() 的实现可以印证这一行为os/dmi/load/users/cpus/uptime各分支把字段合并进同一个fieldsmap最后统一通过acc.AddFields(system, fields, nil, now)发出一条无类型指标而legacy分支走独立的gatherLegacy()内部用AddGauge/AddCounter/AddFields分别发出三条不同类型的指标system.go#L163-L209。权限与平台限制各数据组对文件访问与权限有明确要求users组n_users需要读/var/run/utmp某些系统上需要将telegraf用户加入utmp组若该文件不存在n_users会被跳过。n_unique_users统计唯一登录用户名数同一用户多个会话只计一次权限要求相同。os组在 Linux 上读/etc/os-release通常全局可读在 POSIX 系统上调用uname系统调用。os字段总是取自 Go 运行时arch在无法查询内核时回退为运行时架构因此两者始终存在。在 gopsutil 无法提供平台 release 或内核数据的平台上部分 FreeBSD/OpenBSD/Solarisplatform、platform_family、platform_version、kernel_version可能为空。结果在采集间缓存见os_cache_ttl。dmi组暴露 DMI/SMBIOS 的 BIOS、主板baseboard、机箱chassis和产品信息。Linux 上从/sys/class/dmi/id/读取大部分字段不需要 root但序列号和资产标签通常被内核限制无 root 时读不到。Windows 上通过 WMI 读取。macOS、BSD 和 Solaris 不支持dmi选项在这些平台上会被忽略即上文Init()中dmiSupported检查的行为。结果在采集间缓存见dmi_cache_ttl。从Gather()的分支实现看用户读取失败时的处理相当宽容os.IsNotExist和os.IsPermission只打 Trace 日志其他错误才打 Warnsystem.go#L119-L130——这与utmp 缺失就静默跳过n_users的文档描述一致。指标Metrics说明include选项决定了生成哪些 measurement 和字段。细粒度选项cpus、load、users等填充单条无类型的system指标legacy则发出三条带类型的system指标。细粒度选项指标os组的字段以字符串形式上报反映操作系统发布信息加上uname风格的内核数据os与arch字段总是填充platform、platform_family、platform_version、kernel_version在不支持的平台上可能为空。dmi组的字段在系统未暴露时为空在内核限制通常是无 root 权限下的序列号、资产标签、产品 UUID时为unknown。system细粒度untyped字段对应 include类型说明n_cpuscpusinteger逻辑 CPU 数n_physical_cpuscpusinteger物理 CPU 数bios_vendordmistringBIOS 厂商如Dell Inc.bios_versiondmistringBIOS 版本如2.18.0bios_datedmistringBIOS 发布日期如04/12/2024board_vendordmistring主板厂商board_productdmistring主板产品名如0X3D66board_versiondmistring主板版本board_serialdmistring主板序列号受限board_asset_tagdmistring主板资产标签受限chassis_vendordmistring机箱厂商chassis_type_codedmistring机箱类型代码SMBIOS DSP0134 定义chassis_typedmistring人类可读的机箱类型描述chassis_versiondmistring机箱版本chassis_serialdmistring机箱序列号受限chassis_asset_tagdmistring机箱资产标签受限product_vendordmistring系统产品厂商如Dell Inc.product_namedmistring系统产品名如PowerEdge R750product_familydmistring系统产品系列product_versiondmistring系统产品版本product_serialdmistring系统产品序列号受限product_skudmistring系统产品 SKUproduct_uuiddmistring系统产品 UUID受限load1loadfloat1 分钟平均负载load5loadfloat5 分钟平均负载load15loadfloat15 分钟平均负载ososstring操作系统家族archosstring体系结构platformosstring发行版 / 平台标识platform_familyosstring平台家族如debian、rhelplatform_versionosstring发行版版本kernel_versionosstringuname -r返回的内核 releaseuptimeuptimeinteger系统运行秒数n_usersusersinteger登录用户会话数n_unique_usersusersinteger唯一登录用户名数legacy 设置指标当include包含legacy时发出以下三条指标systemgauge字段类型说明load1float1 分钟平均负载load5float5 分钟平均负载load15float15 分钟平均负载n_usersinteger登录用户会话数n_unique_usersinteger唯一登录用户名数n_cpusinteger逻辑 CPU 数n_physical_cpusinteger物理 CPU 数uptimeinteger系统运行秒数systemcounter字段类型说明uptimeinteger系统运行秒数systemuntyped字段类型说明uptime_formatstring人类可读的运行时长实现细节采集调用链与缓存机制各数据组的底层调用从 Gather() 的分支结构看每组数据的底层依赖如下load调用 gopsutil 的load.Avg()若报错且错误信息含 not implemented平台不支持则静默跳过不产生错误指标cpuscpu.Counts(true)取逻辑 CPU 数cpu.Counts(false)取物理 CPU 数任一失败都会通过acc.AddError上报uptimehost.Uptime()返回秒数uint64usershost.Users()返回会话列表n_users取列表长度n_unique_users由 findUniqueUsers() 用 map 按用户名去重计数。测试 TestUniqueUsers 覆盖了单条、空、全重复、全唯一、混合重复等场景os见下节dmi见下节。os 组的采集与缓存gatherOS() 刻意绕开 gopsutil 的host.Info()后者会顺带探测虚拟化、开机时间、进程数等无关项只调用三个函数host.PlatformInformation()→platform、platform_family、platform_versionhost.KernelVersion()→kernel_versionhost.KernelArch()→arch若为空则回退runtime.GOARCH。os字段直接取runtime.GOOS。任何一项返回 not implemented 都会被容忍置空其他错误才上报。缓存逻辑在Gather()中只有当time.Since(s.osCachedAt) OSCacheTTL时才重新调用gatherOS()否则直接maps.Copy已缓存的字段system.go#L81-L94。dmi组是同样的模式且 dmi 读取失败时会保留上一次成功缓存的字段而不立即清空——即缓存失效前错误不会导致字段消失system.go#L95-L107。dmi 组的采集gatherDMI() 基于ghw库读取 DMI/SMBIOS构造 context 时显式WithDisableWarnings和WithDisableTools即不 shell 出去执行dmidecode等外部工具纯读 sysfs/WMI然后依次调用ghw.BIOS、ghw.Baseboard、ghw.Chassis、ghw.Product共产出 21 个字段。任一子项 not implemented 时跳过该子项其余字段照常输出。uptime_format 的生成legacy指标中的uptime_format字符串由 formatUptime() 生成先算整天数超过 1 天带复数s剩余部分取模输出时:分时占两位、分补零例如14 days, 11:07。测试如何覆盖各分支测试文件 system_test.go 展示了各分支的验证方式用户组Linux 上通过HOST_VAR环境变量把 gopsutil 指向临时目录中的空 utmp 文件使host.Users()确定性地返回 0 个用户system_users_linux_test.go其他平台运行时探测不可用时跳过相关用例。os 组TestGatherOSValues用HOST_ETC指向 testdata/os-release/os-release 测试文件内容为IDtelegraftest、VERSION_ID1.0的示例发行版断言platform/platform_family/platform_version并对依赖宿主机内核的arch、kernel_version只校验非空。dmi 组TestGatherDMIValues用GHW_CHROOT把 ghw 指向 testdata/dmi 目录模拟/sys/class/dmi/id/下 20 个文件验证全部 21 个字段同时验证缓存行为——第二次Gather()后dmiCachedAt不变证明 TTL 内的第二次采集复用了缓存而非重读 DMIsystem_test.go#L299-L356。TestGather的表驱动用例分别验证了defaultnil include → 三条 legacy 指标、cpus、load/users/cpus/uptime四组合单条无类型指标、legacy、users各自产出的指标结构与上文指标表格一一对应。示例输出默认配置默认include [legacy]输出与旧版本完全向后兼容system,hostworker-01 load13.72,load52.4,load152.1,n_users3i,n_unique_users2i,n_cpus4i,n_physical_cpus2i 1748000000000000000 system,hostworker-01 uptime1249632i 1748000000000000000 system,hostworker-01 uptime_format14 days, 11:07 1748000000000000000推荐配置使用include [cpus, load, users, uptime]时所有字段合并在一条指标中system,hostworker-01 load13.72,load52.4,load152.1,n_users3i,n_unique_users2i,n_cpus4i,n_physical_cpus2i,uptime1249632i 1748000000000000000启用全部选项同时启用所有选项含os与dmi时输出形如字段值仅为示例system,hostworker-01 load13.72,load52.4,load152.1,n_users3i,n_unique_users2i,n_cpus4i,n_physical_cpus2i,uptime1249632i oslinux,archx86_64,platformubuntu,platform_familydebian,platform_version26.04,kernel_version7.0.0-7-generic bios_vendorDell Inc.,bios_version2.18.0,bios_date04/12/2024,board_vendorDell Inc.,board_product0X3D66,board_versionA00,board_serialCN747503AB0123,board_asset_tag,chassis_vendorDell Inc.,chassis_type23,chassis_type_descriptionRack mount chassis,chassis_version,chassis_serial7XK4P03,chassis_asset_tag,product_vendorDell Inc.,product_namePowerEdge R750,product_familyPowerEdge,product_version,product_serial7XK4P03,product_skuSKUNotProvided;ModelNamePowerEdge R750,product_uuid4c4c4544-0058-4b10-8034-b3c04f503033 1748000000000000000小结与实践建议新项目建议放弃legacy改用include [load, users, cpus, uptime]按需追加os记录发行版/内核信息便于排查环境漂移与dmi记录硬件身份适合资产纳管场景Prometheus 输出场景若下游依赖legacy三条指标的类型语义gauge/counter可保留legacy或同时启用细粒度选项做过渡性能敏感场景os与dmi组默认 8 小时缓存对几乎静态的这两类数据足够如需更快感知内核切换kexec或发行版升级调小os_cache_ttl权限排障n_users缺失时优先检查/var/run/utmp读权限与utmp组dmi序列号类字段为unknown属于内核限制需要 root 或 SELinux/AppArmor 相应放行平台注意dmi仅支持 Linux 与 Windows由 dmi_supported.go 的构建标签决定其他平台配置了该项也只会得到一条告警日志而不会报错。【免费下载链接】telegrafAgent for collecting, processing, aggregating, and writing metrics, logs, and other arbitrary data.项目地址: https://gitcode.com/GitHub_Trending/te/telegraf创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考