Telegraf nvidia_smi 输入插件深度解析基于 NVIDIA SMI 的 GPU 指标采集配置与实现原理【免费下载链接】telegrafAgent for collecting, processing, aggregating, and writing metrics, logs, and other arbitrary data.项目地址: https://gitcode.com/GitHub_Trending/te/telegrafTelegraf 的nvidia_smi输入插件通过调用nvidia-smi二进制并解析其 XML 输出周期性采集 GPU 利用率、显存、温度、功耗、时钟节流等完整指标。阅读本文后你将掌握该插件的完整配置方法含 Linux/Windows 平台差异与 Docker 部署、全部测量值measurement与字段fields清单以及插件在源码层面如何探测驱动 XML Schema 版本并自适应解析的底层原理。插件工作原理与前置条件该插件通过 NVIDIA System Management InterfaceSMI收集 GPU 指标包括显存与 GPU 使用率、温度等。插件的运行前提是系统上已安装nvidia-smi二进制——这是插件唯一的硬性依赖插件本身不直接访问驱动接口而是以子进程方式调用nvidia-smi并解析其输出。从源码 nvidia_smi.go 可以看到核心调用链Gather方法执行exec.Command(smi.BinPath, -q, -x)即向nvidia-smi传入-qquery all和-xXML 格式输出参数再通过internal.CombinedOutputTimeout施加超时控制。参数-q -x在插件注册时固化于 init 函数 的nvidiaSMIArgs字段中插件的默认配置为BinPath默认/usr/bin/nvidia-smiTimeout默认5s启动错误行为Startup Error Behavior除插件专属与全局配置外该插件支持通过startup_error_behavior指定启动出错时的行为可用取值为error启动出错时 Telegraf 停止并退出。这是默认行为。ignoreTelegraf 忽略该插件的启动错误并禁用它但继续处理其他所有插件。retry不可用NOT AVAILABLE。probeTelegraf 会调用插件的Probe() error方法若存在。若该方法返回错误Telegraf 禁用该插件但继续处理其他插件。源码中Probe的实现位于 nvidia_smi.go它提前执行一次nvidia-smi -q -x命令命令失败即返回错误从而让配置了probe行为的 Telegraf 能在无 GPU 的机器上优雅地跳过该插件。测试用例 TestProbe 使用bash -c exit 0/1模拟命令成功与失败两种场景验证了该路径TestErrorBehaviorIgnore/Error/Retry等测试则覆盖了各行为分支下Start与Gather的错误传递语义见 nvidia_smi_test.go。配置详解插件示例配置与 sample.conf 一致# Pulls statistics from nvidia GPUs attached to the host [[inputs.nvidia_smi]] ## Optional: path to nvidia-smi binary, defaults /usr/bin/nvidia-smi ## We will first try to locate the nvidia-smi binary with the explicitly specified value (or default value), ## if it is not found, we will try to locate it on PATH(exec.LookPath), if it is still not found, an error will be returned # bin_path /usr/bin/nvidia-smi ## Optional: timeout for GPU polling # timeout 5s参数说明与源码印证参数类型默认值说明bin_pathstring/usr/bin/nvidia-sminvidia-smi二进制路径。查找顺序为显式值或默认值→exec.LookPath在 PATH 中查找 → 均失败则返回错误timeoutduration5s每次 GPU 轮询即执行nvidia-smi子进程的超时时间bin_path的三级查找逻辑可在 Start 方法 中确认先用os.Stat检查指定路径是否存在若不存在则调用exec.LookPath(nvidia-smi)仍找不到时返回internal.StartupError这也是startup_error_behavior各行为分支的触发入口。Linux 平台在 Linux 上nvidia-smi通常位于/usr/bin/nvidia-smi与默认值一致一般无需显式配置bin_path。Windows 平台在 Windows 上nvidia-smi通常位于C:\Program Files\NVIDIA Corporation\NVSMI\nvidia-smi.exe在 Windows 10 上也可能位于C:\Windows\System32\nvidia-smi.exe。注意在telegraf.conf中需要对路径中的\转义写法为bin_path C:\\Program Files\\NVIDIA Corporation\\NVSMI\\nvidia-smi.exeSchema 版本自适应插件如何解析不同驱动的 XML 输出这是该插件实现中最值得关注的机制。不同代次的 NVIDIA 驱动导出的 XML 遵循不同版本的 DTDnvsmi_device_v11.dtd、nvsmi_device_v12.dtd、nvsmi_device_v13.dtd字段结构存在差异。插件的解析入口 parse 方法 的工作方式用encoding/xml的流式解码器扫描输出定位以DOCTYPE开头的 XML 指令从指令末尾提取形如nvsmi_device_vXX.dtd的文件名截取出版本号例如v12按版本号分派到对应的包解析v10/v11→schema_v11.Parsev12→schema_v12.Parsev13→schema_v13.Parse若遇到未知版本记录一次告警sync.Once保证只提示一次并回退到最新的schema_v13解析器。三个版本的解析器分别位于 schema_v11、schema_v12 与 schema_v13。以 v13 解析器为例每块 GPU 先构造 tagsindex、name、arch、uuid、compute_mode、pstate再逐项调用common.SetIfUsed填充 fields最后通过acc.AddFields(nvidia_smi, fields, tags, timestamp)提交指标见 schema_v13/parser.go。指标时间戳优先取自 XML 中的timestamp元素ANSIC 格式解析解析失败时退回当前时间见 parser.go。字段值的清洗规则N/A 与 deprecated 的处理共享工具包 common/setters.go 定义了字段落地的三条规则SetIfUsed值经TrimSpace后若为空、N/A或Requested functionality has been deprecated则直接跳过该字段——这正是“并非每个字段在每块 GPU/每版驱动上都可用”这一行为的实现来源数值解析number()函数剥离单位如20475 MiB、16x只取首个词并去掉尾部x再按int/float解析解析失败同样静默丢弃字段SetActiveIfUsed把二值状态字符串Active/Not Active归一化为整数1/0用于所有clocks_event_reason_*字段。另外两个值得注意的实现细节均可在源码中直接确认旧驱动字段名映射535 之前的驱动在 XML 中用clocks_throttle_reason_*元素名上报节流原因schema_v12解析器将它们输出为统一的现代字段名clocks_event_reason_*见 schema_v12/parser.goschema_v11的 types.go 定义了相应的 XML 结构power_draw的取值优先级v13 解析器会先尝试PowerReadings再尝试GpuPowerReadings两个节点当驱动上报瞬时功耗instant_power_draw时取瞬时值这与 README 中“power_draw在驱动报告instant_power_draw时为瞬时值”的描述一致见 schema_v13/parser.go。指标清单Metrics测量值nvidia_smi每块 GPU 一条TagsnameGPU 型号例如GeForce GTX 1070 TiarchGPU 架构例如Ampereschema v12compute_modeGPU 计算模式例如DefaultindexGPU 在 nvidia-smi 输出中的索引例如1pstateGPU 性能状态例如P0uuidGPU 唯一标识例如GPU-f9ba66fc-a7f5-94c5-da19-019ef2f9c665Fieldsdriver_versionstringcuda_versionstringserialstringvbios_versionstringdisplay_activestringdisplay_modestringcurrent_eccstringfan_speedinteger百分比memory_freeintegerMiBmemory_usedintegerMiBmemory_totalintegerMiBmemory_reservedintegerMiButilization_gpuinteger百分比utilization_memoryinteger百分比utilization_encoderinteger百分比utilization_decoderinteger百分比utilization_jpeginteger百分比schema v12utilization_ofainteger百分比schema v12clocks_current_graphicsintegerMHzclocks_current_smintegerMHzclocks_current_memoryintegerMHzclocks_current_videointegerMHzclocks_event_reason_sw_power_capinteger激活时为 1clocks_event_reason_sw_thermal_slowdowninteger激活时为 1clocks_event_reason_hw_thermal_slowdowninteger激活时为 1clocks_event_reason_hw_power_brake_slowdowninteger激活时为 1clocks_event_reason_hw_slowdowninteger激活时为 1clocks_event_reason_sync_boostinteger激活时为 1clocks_event_reason_gpu_idleinteger激活时为 1clocks_event_reason_applications_clocks_settinginteger激活时为 1clocks_event_reason_display_clocks_settinginteger激活时为 1clocks_event_reasons_counters_sw_power_capinteger微秒schema v13clocks_event_reasons_counters_sw_therm_slowdowninteger微秒schema v13clocks_event_reasons_counters_hw_therm_slowdowninteger微秒schema v13clocks_event_reasons_counters_hw_power_brakeinteger微秒schema v13clocks_event_reasons_counters_sync_boostinteger微秒schema v13temperature_gpuinteger摄氏度temperature_memoryinteger摄氏度schema v12temperature_gpu_targetinteger摄氏度schema v12temperature_gpu_target_mininteger摄氏度schema v12temperature_gpu_target_maxinteger摄氏度schema v12temperature_max_thresholdinteger摄氏度schema v12temperature_slow_thresholdinteger摄氏度schema v12temperature_max_gpu_thresholdinteger摄氏度schema v12temperature_max_mem_thresholdinteger摄氏度schema v12temperature_gpu_tlimitinteger摄氏度schema v12temperature_max_tlimit_thresholdinteger摄氏度schema v13temperature_slow_tlimit_thresholdinteger摄氏度schema v13temperature_max_gpu_tlimit_thresholdinteger摄氏度schema v13temperature_max_mem_tlimit_thresholdinteger摄氏度schema v13power_drawfloatW驱动报告instant_power_draw时为瞬时值power_draw_averagefloatWschema v12power_limitfloatW当前生效的限制power_limit_defaultfloatWschema v12power_limit_minfloatWschema v12power_limit_maxfloatWschema v12power_limit_requestedfloatWschema v12module_power_drawfloatWschema v12驱动报告instant_power_draw时为瞬时值pcie_link_gen_currentintegerpcie_link_width_currentintegerpcie_rx_utilintegerKB/sschema v12pcie_tx_utilintegerKB/sschema v12encoder_stats_session_countintegerencoder_stats_average_fpsintegerencoder_stats_average_latencyintegerfbc_stats_session_countintegerfbc_stats_average_fpsintegerfbc_stats_average_latencyintegerretired_pages_multiple_single_bitintegerretired_pages_double_bitintegerretired_pages_blackliststringretired_pages_pendingstringremapped_rows_correctableintegerremapped_rows_uncorrectableintegerremapped_rows_pendingstringremapped_rows_failurestringecc_errors_volatile_dram_correctableintegerschema v13ecc_errors_volatile_dram_uncorrectableintegerschema v13ecc_errors_volatile_sram_correctableintegerschema v13ecc_errors_volatile_sram_uncorrectableintegerschema v13ecc_errors_volatile_sram_uncorrectable_parityintegerschema v13ecc_errors_volatile_sram_uncorrectable_secdedintegerschema v13ecc_errors_aggregate_dram_correctableintegerschema v13ecc_errors_aggregate_dram_uncorrectableintegerschema v13ecc_errors_aggregate_sram_correctableintegerschema v13ecc_errors_aggregate_sram_uncorrectableintegerschema v13ecc_errors_aggregate_sram_uncorrectable_parityintegerschema v13ecc_errors_aggregate_sram_uncorrectable_secdedintegerschema v13ecc_errors_aggregate_sram_uncorrectable_l2integerschema v13ecc_errors_aggregate_sram_uncorrectable_microcontrollerintegerschema v13ecc_errors_aggregate_sram_uncorrectable_otherintegerschema v13ecc_errors_aggregate_sram_uncorrectable_pcieintegerschema v13ecc_errors_aggregate_sram_uncorrectable_smintegerschema v13ecc_errors_aggregate_sram_threshold_exceededstringschema v13ecc_errors_channel_repair_pendingstringschema v13ecc_errors_tpc_repair_pendingstringschema v13ecc_errors_unrepairable_memorystringschema v13测量值nvidia_smi_migschema v12每个 MIG 设备一条TagsindexMIG 设备索引例如0gpu_indexGPU 实例索引例如6compute_index计算实例索引例如0name、arch、pstate、uuid、compute_mode同nvidia_smi取自承载该 MIG 设备的 GPUFieldsmemory_fb_freeintegerMiBmemory_fb_usedintegerMiBmemory_fb_totalintegerMiBmemory_fb_reservedintegerMiBmemory_bar1_freeintegerMiBmemory_bar1_usedintegerMiBmemory_bar1_totalintegerMiBsram_uncorrectableinteger测量值nvidia_smi_processschema v12每个进程与 GPU 组合一条Tagsname进程名例如pythontype上下文类型C表示计算、G表示图形或CGFieldspidintegerused_memoryintegerMiB并非每个字段在每块 GPU 或每版驱动上都有字段只在nvidia-smi报告了有效值时才输出因此卡片报告N/A或Requested functionality has been deprecated的字段会被直接省略该行为由 common/setters.go 实现。上文schema v12与schema v13标记指的是所安装驱动报告的 XML Schema 版本它决定了可采集字段的上限。驱动早于 535 时节流原因在 XML 中仍以旧元素名clocks_throttle_reason_*上报但 Telegraf 会统一以现代字段名clocks_event_reason_*输出。提示clocks_event_reason_*字段以1Active/0Not Active报告 GPU 当前处于降频状态的原因。在 schema v13 下其中五个还配有clocks_event_reasons_counters_*计数器字段累计该状态持续的微秒数。计数器能捕获发生在两次采集间隔之间、开始又结束的降频事件由于它们只增不减建议结合 derivative 聚合器 将其转换为速率。注意*_tlimit*温度是相对于 GPU 热限thermal limit的余量因此temperature_gpu_tlimit在 GPU 逼近降频阈值时是向零倒数count down的不报告热限的卡片则暴露绝对的temperature_max_threshold变体。输出示例nvidia_smi,compute_modeDefault,host8218cf,index0,nameGeForce\ GTX\ 1070,pstateP2,uuidGPU-823bc202-6279-6f2c-d729-868a30f14d96 fan_speed100i,memory_free7563i,memory_total8112i,memory_used549i,temperature_gpu53i,utilization_gpu100i,utilization_memory90i 1523991122000000000 nvidia_smi,compute_modeDefault,host8218cf,index1,nameGeForce\ GTX\ 1080,pstateP2,uuidGPU-f9ba66fc-a7f5-94c5-da19-019ef2f9c665 fan_speed100i,memory_free7557i,memory_total8114i,memory_used557i,temperature_gpu50i,utilization_gpu100i,utilization_memory85i 1523991122000000000 nvidia_smi,compute_modeDefault,host8218cf,index2,nameGeForce\ GTX\ 1080,pstateP2,uuidGPU-d4cfc28d-0481-8d07-b81a-ddfc63d74adf fan_speed100i,memory_free7557i,memory_total8114i,memory_used557i,temperature_gpu58i,utilization_gpu100i,utilization_memory86i 1523991122000000000测试数据目录 testdata 中保存了从 GeForce GTX 1070 Ti、Tesla T4、A10G 到 A100-SXM4-80GB含 4 个 MIG 设备、RTX 3080v12 与 v13 两版等多款真实卡型的nvidia-smi -q -x完整 XML 样本TestGatherValidXML 逐一断言解析出的 tags/fields 与预期完全一致可作为各字段实际取值的权威参照。故障排查Troubleshooting手动运行nvidia-smi查看完整输出即可快速定位问题。Linuxsudo -u telegraf -- /usr/bin/nvidia-smi -q -xWindowsC:\Program Files\NVIDIA Corporation\NVSMI\nvidia-smi.exe -q -x在提交 issue 时请附上该命令的输出。结合源码可知插件解析阶段若遇到未知 schema 版本只会在日志中警告一次并回退 v13 解析器parse 方法因此排查“新驱动下个别字段缺失”的问题时这份原始 XML 输出同样是必需的输入。局限性Limitations显存超频下的内存时钟读数当显存被超频时获取当前内存时钟值似乎存在问题。此问题未必影响所有人但已在一块 EVGA 2080 Ti 上确认存在。Docker 环境容器内使用时要么基于nvidia/cuda生成同时安装了 telegraf 的自定义镜像要么通过卷挂载把所需的nvidia-smi二进制注入容器。无论哪种方式都需要透传/dev/nvidia*设备、nvidia-smi二进制以及 NVIDIA 运行时库。一个最小化的 docker-compose 示例如下telegraf: image: telegraf runtime: nvidia devices: - /dev/nvidiactl:/dev/nvidiactl - /dev/nvidia0:/dev/nvidia0 volumes: - ./telegraf/etc/telegraf.conf:/etc/telegraf/telegraf.conf:ro - /usr/bin/nvidia-smi:/usr/bin/nvidia-smi:ro - /usr/lib/x86_64-linux-gnu/nvidia:/usr/lib/x86_64-linux-gnu/nvidia:ro environment: - LD_PRELOAD/usr/lib/x86_64-linux-gnu/nvidia/current/libnvidia-ml.so插件的全局配置能力与其他 Telegraf 插件一致nvidia_smi还支持修改指标/标签/字段、创建别名、调整插件顺序等全局配置项详见 CONFIGURATION.md。小结nvidia_smi插件以“外部命令 XML 解析”的轻量方式覆盖了 GPU 利用率、显存、温度、功耗、PCIe、编码/解码、MIG 分区与进程级显存占用等监控面其工程上的两个亮点值得借鉴一是通过 DOCTYPE 指令探测驱动 schema 版本并分派到 v11/v12/v13 三套解析器对未知版本优雅降级二是common工具包对N/A、deprecated 标记、单位剥离与二值状态归一化的统一处理使字段输出在驱动间保持一致语义。配置上只需确认bin_path可达并合理设置timeout再按部署形态选择startup_error_behavior无 GPU 的节点推荐ignore或probe即可在多机混合的 GPU 集群中稳定采集指标。【免费下载链接】telegrafAgent for collecting, processing, aggregating, and writing metrics, logs, and other arbitrary data.项目地址: https://gitcode.com/GitHub_Trending/te/telegraf创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考