Telegraf InfluxDB Input Plugin 详解：从 `/debug/vars` 采集 InfluxDB v1 与兼容端点指标

Telegraf InfluxDB Input Plugin 详解从/debug/vars采集 InfluxDB v1 与兼容端点指标【免费下载链接】telegrafAgent for collecting, processing, aggregating, and writing metrics, logs, and other arbitrary data.项目地址: https://gitcode.com/GitHub_Trending/te/telegraf本篇技术指南以 Telegraf 仓库中的 influxdb 输入插件文档 为核心讲解如何通过该插件从 InfluxDB v1 服务器的/debug/vars端点以及任何暴露 InfluxDB 格式 JSON 的 HTTP 端点采集数据库自身的运行状态指标。读完本文你将掌握插件的完整配置参数、底层 JSON 解析与度量生成机制、全部测量measurement与字段field语义以及用--test模式快速验证采集效果的实战方法。插件定位与适用场景inputs.influxdb是 Telegraf 内置的输入插件自Telegraf v0.2.5起提供分类标签为datastore支持在all所有平台上运行。它的核心职责是采集给定InfluxDB v1服务器上influxdb度量源自/debug/vars端点额外支持从任何暴露 InfluxDB 格式 JSON 数据的 HTTP 端点采集指标无论该端点背后是否真的连接了 Influx 数据库。需要注意一个重要的边界该插件面向 InfluxDB v1。若要采集InfluxDB v2 的指标原文档给出的方案是改用 prometheus 输入插件以 Prometheus 格式抓取 v2 的/metrics端点[[inputs.prometheus]] urls [http://localhost:8086/metrics] metric_version 1插件注册入口位于 plugins/inputs/all/influxdb.go通过import _ github.com/influxdata/telegraf/plugins/inputs/influxdb完成注册插件主体实现在 plugins/inputs/influxdb/influxdb.go。配置参数全解插件完整的可配置项见 sample.conf该文件通过//go:embed内嵌进二进制并作为SampleConfig()的返回值。最小可用的配置如下# Read InfluxDB-formatted JSON metrics from one or more HTTP endpoints [[inputs.influxdb]] ## Works with InfluxDB debug endpoints out of the box, ## but other services can use this format too. ## See the influxdb plugins README for more details. ## Multiple URLs from which to read InfluxDB-formatted JSON ## Default is http://localhost:8086/debug/vars. urls [ http://localhost:8086/debug/vars ] ## Username and password to send using HTTP Basic Authentication. # username # password ## Optional TLS Config # tls_ca /etc/telegraf/ca.pem # tls_cert /etc/telegraf/cert.pem # tls_key /etc/telegraf/key.pem ## Use TLS but skip chain host verification # insecure_skip_verify false ## http request header timeout timeout 5s各参数说明如下参数类型默认值作用urls字符串数组[http://localhost:8086/debug/vars]一个或多个待抓取的 HTTP 端点每个端点都会被并发请求并独立产出度量username/password字符串空发起请求时使用的 HTTP Basic Authentication 凭据tls_ca/tls_cert/tls_key字符串空可选的 TLS 配置指向 CA 证书、客户端证书与私钥路径insecure_skip_verify布尔false使用 TLS 时跳过证书链与主机名校验timeout时长5sHTTP 请求及响应头的超时时间从源码看InfluxDB结构体influxdb.go将上述参数直接映射为 TOML 字段并内嵌了tls.ClientConfig以复用 Telegraf 统一的 TLS 配置体系init()中注册插件时把Timeout默认值设为time.Duration(time.Second * 5)。需要认证的端点会在请求上调用req.SetBasicAuth(username, password)同时所有请求都会携带User-Agent: Telegraf/version头internal.Version来自编译期注入的版本号。与所有 Telegraf 插件一样inputs.influxdb还支持name_override、tags、fieldpass/fielddrop、tagpass/tagdrop、alias、处理器排序等全局与插件级配置详见 docs/CONFIGURATION.md。采集工作原理源码级解析流程Gather是插件的入口influxdb.go其执行流程可以概括为四个阶段默认值兜底若urls为空自动回退到http://localhost:8086/debug/vars。HTTP 客户端构建基于timeout设置http.Client的整体超时并在http.Transport上设置ResponseHeaderTimeout与 TLS 配置。客户端采用懒加载仅构建一次。并发抓取对每个 URL 启动一个 goroutine 调用gatherURL通过sync.WaitGroup等待全部完成单点失败不会中断整体采集而是通过acc.AddError(err)上报。错误聚合所有 URL 采集结束后统一返回任一端点的错误已进入 Accumulator 的错误队列。gatherURLinfluxdb.go则完成真正的解析工作其关键在于手工 JSON 流式解码。源码注释解释了为什么不直接json.Unmarshal到map[string]point一旦端点返回的任意值不是对象例如数组、字符串Go 解码器会报json: cannot unmarshal array into Go value of type influxdb.point导致整个响应解析失败。因此实现采用json.Decoder逐 Token 遍历顶层对象先确认文档根是{对象对每个顶层键读取字符串 key键名本身不参与度量命名对特殊结构体进行独立解码system→ 产出influxdb_system含current_time、started、uptimememstats→ 产出influxdb_memstatsGo 内存分配器全套统计字段见下文build→ 产出influxdb_buildbranch、build_time、commit、versioncmdline→ 产出influxdb_cmdline命令行参数以空格拼接为value字段crypto→ 产出influxdb_cryptofips、ensure_fips、implementation、password_hash其余所有键一律尝试按point结构解码point由name、tags、values三部分组成定义见 types.go。若解码失败、或解码后name为空、values为空则静默跳过——这正是插件能同时容忍“非对象值”“非 point 结构对象”的原因。每个 point 都会被打上url标签值为本次抓取的端点地址并以influxdb_name作为最终测量名写入 Accumulator。特殊计数统计name shard的 point 个数最后产出一条无标签的influxdb测量字段为n_shards。测试用例对以上行为给出了明确佐证TestBasicinfluxdb_test.go验证了当 JSON 中混有数组、字符串、嵌套对象、空values的 point 时只有合法 point 与influxdb n_shards0被产出TestInfluxDB/TestInfluxDB2验证了真实influx_return.json的 36 条度量产出其中influxdb_system的uptime字段以无符号整型u写入TestCloud1用真实环境的 4600 行/debug/vars快照testdata/cloud1.json与期望输出 testdata/cloud1.influx 逐条比对覆盖了企业版扩展测量influxdb_ae、influxdb_cluster、influxdb_rpc等的解析。错误处理方面TestErrorResponse确认非 200 响应会读取响应体最多 1024 字节常量maxErrorResponseBodyLength中的{error: ...}字段并拼装为apiError上报。支持的测量与字段详解[!NOTE] 插件的测量与字段由 InfluxDB 端/debug/vars实际返回的内容动态构建不同 InfluxDB 版本之间可能有所差异。下面以当前 InfluxDB v1 常见版本为准列出。以下测量在源端数据存在时才会生成且部分标注Enterprise Only的测量仅在 InfluxDB 企业版集群中出现。influxdb_ae企业版Anti-EntropyAE引擎统计用于修复集群中数据不一致的分片bytesRx数据节点接收的字节数。errors发生错误的 anti-entropy 任务总数。jobs数据节点已执行的任务总数。jobsActive当前正在执行活跃的任务数。influxdb_cluster企业版企业版集群数据节点的聚类特性统计copyShardReq将一个分片从一个数据节点复制到另一个的内部请求数。createIteratorReq来自集群其他数据节点的读请求数。expandSourcesReq为匹配某正则表达式的测量而发起的远程节点请求数。fieldDimensionsReq关于本节点测量字段、类型与标签键信息的远程请求数。iteratorCostReq内部迭代器开销请求数。openConnections数据节点正在处理的开放连接数含在单个 yamux 连接上复用的逻辑连接。removeShardReq删除本节点分片的内部请求数仅由influxd-ctl remove shard命令触发递增。writeShardFail来自远程节点且失败的内部写请求总数。writeShardPointsReq来自远程节点的每次内部写请求中的点数无论成功与否。writeShardReq来自远程数据节点的内部写请求数无论成功与否。influxdb_cq连续查询Continuous Queries统计queryFail已执行但失败的连续查询总数。queryOk成功执行的连续查询总数。influxdb_database数据库维度统计database标签标识具体库numMeasurements指定数据库当前的测量数量。numSeries指定数据库当前的序列基数。influxdb_hh / influxdb_hh_database / influxdb_hh_processor企业版Hinted HandoffHH提示式交接机制用于在目标节点不可达时暂存写请求三个测量分别从引擎整体、单数据库聚合、单队列分片三个粒度展开bytesRead从 HH 队列读出并发往目标数据节点的点数所占字节。bytesWritten写入 HH 队列的总字节数。queueBytesHH 队列中剩余的总字节数。queueDepthHH 队列中的段segment数量HH 队列由一串 10MB 的“段”文件构成。writeBlocked因并发 HH 请求数超限而被阻塞的写入次数。writeDropped因写入疑似损坏而从 HH 队列丢弃的写入次数。writeNodeReq成功向目标节点写入一批数据的写请求总数。writeNodeReqFail将一批数据从 HH 队列写入目标节点失败的写请求总数。writeNodeReqPoints从 HH 队列成功写入目标节点的点数。writeShardReq进入 HH 队列的每个写批次请求总数。writeShardReqPoints进入 HH 队列的点数。influxdb_hh_processor额外带shardID、node标签见 cloud1.influx 中的示例输出influxdb_hh_node含queueTotalSize字段与influxdb_hh_database也按各自粒度出现。influxdb_httpdInfluxDB HTTP 服务器统计authFail因需要认证但未提供或凭据错误而中止的 HTTP 请求数。clientError返回 4XX 客户端错误的 HTTP 响应数。fluxQueryReq已服务的 Flux 查询请求数。fluxQueryReqDurationNs执行 Flux 查询请求所花费的墙钟时间纳秒。pingReq服务/pingHTTP 端点的次数。pointsWrittenDropped被存储引擎丢弃的点数。pointsWrittenFail被/write端点接受但未能持久化的点数。pointsWrittenOK被/write端点成功接受并持久化的点数。promReadReq对 Prometheus/read端点的读请求数。promWriteReq对 Prometheus/write端点的写请求数。queryReq查询请求数。queryReqDurationNs查询请求总耗时纳秒。queryRespBytes查询响应返回的总字节数。recoveredPanicsHTTP 处理器恢复的 panic 总数。req服务的 HTTP 请求总数。reqActive当前活跃请求数。reqDurationNsHTTP 请求内部耗时墙钟纳秒。serverError因服务器错误返回的 HTTP 响应数。statusReq使用 HTTP/status端点服务的状态请求数。valuesWrittenOK被/write端点成功接受并持久化的值字段数量。writeReq使用/write端点服务的写请求数。writeReqActive当前活跃的写请求数。writeReqBytes写请求通过/write端点接收的行协议数据总字节数。writeReqDurationNs使用/writeHTTP 端点服务的写请求耗时纳秒。influxdb_memstatsGo 运行时内存分配器统计对应/debug/vars中的memstats对象字段名与原文档保持一致的大驼峰命名经插件原样透传Alloc堆对象已分配字节数。BuckHashSysprofile bucket 哈希表占用的内存字节数。Frees堆对象释放的累计次数。GCCPUFraction自 InfluxDB 启动以来垃圾回收GC占用的可用 CPU 时间比例。GCSysGC 元数据占用的内存字节数。HeapAlloc已分配的堆对象字节数。HeapIdle空闲未使用span 的字节数。HeapInuse使用中 span 的字节数。HeapObjects已分配的堆对象数量。HeapReleased归还给操作系统的物理内存字节数。HeapSys从操作系统获得的堆内存字节数。LastGC上一次 GC 完成的时间。Lookups运行时执行的指针查找次数。MCacheInuse已分配的 mcache 结构字节数。MCacheSys为 mcache 结构从操作系统获得的内存字节数。MSpanInuse已分配的 mspan 结构字节数。MSpanSys为 mspan 结构从操作系统获得的内存字节数。Mallocs堆对象分配的累计次数。NextGC下一轮 GC 的目标堆大小。NumForcedGC应用主动调用 GC 函数强制的 GC 周期数。NumGC已完成的 GC 周期数。OtherSys杂项堆外运行时分配的内存字节数。PauseTotalNs自程序启动以来 GC stop-the-world 暂停的累计纳秒数。StackInuse栈 span 的字节数。StackSys从操作系统获得的栈内存字节数。Sys从操作系统获得的内存总字节数。TotalAlloc为堆对象分配的累计字节数。插件在产出该测量时还额外生成了两个派生字段pause_ns取最近一次 GC 暂停时长即PauseNs[(NumGC255)%256]以及上述字段对应的下划线小写变体alloc、heap_alloc、gc_cpu_fraction等参见 influxdb.go。这正是示例输出中出现alloc...而非Alloc的原因。influxdb_queryExecutor查询执行器统计queriesActive当前正在处理的活跃查询数。queriesExecuted已执行启动的查询数。queriesFinished已执行完成的查询数。queryDurationNs已执行查询的总耗时纳秒。recoveredPanics查询执行器恢复的 panic 数。influxdb_rpc企业版集群 RPC 调用统计idleStreams所有存活 TCP 连接上空闲的多路复用流数量。liveConnections当前到其他节点的存活 TCP 连接数。liveStreams所有存活 TCP 连接上当前存活的多路复用流数量。rpcCalls向远程节点发起的 RPC 调用总数。rpcFailures未恢复的 RPC 失败总数。rpcReadBytesRPC 读取的总字节数。rpcRetries至少重试过一次的 RPC 调用数。rpcWriteBytesRPC 写入的总字节数。singleUse通过Dial打开的单次使用连接总数。singleUseOpen当前打开的单次使用连接数。totalConnections已建立的 TCP 连接总数。totalStreams已建立的流总数。influxdb_runtimeGo 内存分配器记录的 memstat 子集注意其字段沿用原文档/源端的大驼峰命名与influxdb_memstats的下划线变体不同Alloc当前已分配的堆对象字节数。Frees已释放存活堆对象的累计数量。HeapAlloc所有堆对象的字节数。HeapIdle空闲堆对象字节数。HeapInUse使用中 span 的字节数。HeapObjects已分配的堆对象数量。HeapReleased归还给操作系统的物理内存字节数。HeapSys从操作系统获得的堆内存字节数衡量为堆预留的虚拟地址空间。Lookups运行时执行的指针查找次数主要用于调试运行时内部。Mallocs堆对象分配总数存活对象总数即Frees。NumGC完成的 GC 周期数。NumGoroutineGo 协程总数。PauseTotalNsGC 暂停的总时长纳秒。Sys从操作系统获得的内存总字节数衡量 Go 运行时为堆、栈及其他内部数据结构预留的虚拟地址空间。TotalAlloc为堆对象分配的字节总数对象被释放时该统计不下降。influxdb_shard分片级统计database、id、engine、indexType、path、retentionPolicy、walPath等标签标注具体分片diskBytes分片大小字节包含数据目录与 WAL 目录。fieldsCreate已创建的字段数量。indexType索引类型inmem或tsi1。n_shards指定数据库中的分片总数。seriesCreate已创建的序列数量。writeBytes写入分片的字节数。writePointsDropped写入中被丢弃的点请求数。writePointsErr因错误未能写入的点请求数。writePointsOk成功写入的点数。writeReq写请求总数。writeReqErr因错误失败的写请求总数。writeReqOk成功的写请求总数。influxdb_subscriber订阅统计createFailures创建失败的订阅数。pointsWritten成功写入订阅者的总点数。writeFailures写入订阅者失败的批次总数。influxdb_tsm1_cacheTSM 缓存统计cacheAgeMs采样时刻距缓存上次快照的时长毫秒。cachedBytes已写入快照的总字节数。diskBytes磁盘快照大小字节。memBytes内存缓存大小字节。snapshotCount当前活跃快照的层数量。WALCompactionTimeMs压缩快照期间持有提交锁的时长毫秒。writeDropped因超时被丢弃的写入总数。writeErr失败的写入总数。writeOk成功的写入总数。influxdb_tsm1_engineTSM 存储引擎统计覆盖 cache 压缩与 TSM full/level 1/2/3/optimize 各档位压缩的耗时纳秒、错误数、队列深度与活跃/累计次数cacheCompactionDuration/cacheCompactionErr/cacheCompactions/cacheCompactionsActivetsmFullCompactionDuration/tsmFullCompactionErr/tsmFullCompactionQueue/tsmFullCompactions/tsmFullCompactionsActivetsmLevel1CompactionDuration/tsmLevel1CompactionErr/tsmLevel1CompactionQueue/tsmLevel1Compactions/tsmLevel1CompactionsActivetsmLevel2CompactionDuration/tsmLevel2CompactionErr/tsmLevel2CompactionQueue/tsmLevel2Compactions/tsmLevel2CompactionsActivetsmLevel3CompactionDuration/tsmLevel3CompactionErr/tsmLevel3CompactionQueue/tsmLevel3Compactions/tsmLevel3CompactionsActivetsmOptimizeCompactionDuration/tsmOptimizeCompactionErr/tsmOptimizeCompactionQueue/tsmOptimizeCompactions/tsmOptimizeCompactionsActiveinfluxdb_tsm1_filestoreTSM 文件存储统计diskBytesTSM 文件存储占用的磁盘字节数。numFilesTSM 文件存储中的文件总数。influxdb_tsm1_walTSM 预写日志WAL统计currentSegmentDiskBytes当前段磁盘大小字节。oldSegmentDiskBytes旧段磁盘大小字节。writeErr因错误失败的写入数。writeOK成功的写入数。influxdb_write写入路径统计pointReq请求写入的总点数。pointReqHH企业版本节点接收后进入目标节点 hinted handoff 的总点数。pointReqLocal企业版尝试写入本机local节点分片的点请求数。pointReqRemote企业版本节点接收但需转发到远程节点分片的点数。pointsWrittenOK写入/write端点并成功持久化的点数。req请求写入的批次总数。subWriteDrop未能发送到订阅分发器的批次总数。subWriteOk成功发送到订阅分发器的批次总数。valuesWrittenOK写入/write端点并成功持久化的值字段数量。writeDrop因时间戳不匹配任何现有保留策略而丢弃的点写入请求总数。writeError因写入本地或远程分片失败而未能成功写入的点批次总数。writeOk以请求的一致性级别写入的批次总数。writePartial企业版写入至少一个节点但未达到请求一致性级别的批次总数。writeTimeout未在默认写超时时间内完成的写请求总数。多端点配置与并行采集插件天然支持在urls中配置多个端点例如监控同一集群的多台 InfluxDB 节点[[inputs.influxdb]] urls [ http://127.0.0.1:8086/debug/vars, http://192.168.2.1:8086/debug/vars ]每个端点都会被独立、并发地请求Gather中对每个 URL 启动 goroutine产出的每条度量都会携带对应的url标签源码在 influxdb.go 中将url写入 point 标签特殊结构体同样带url标签因此可以方便地在查询时按来源节点区分、聚合或告警。对于“InfluxDB 格式端点”而言只要 JSON 顶层是对象且内部结构符合{name, tags, values}的 point 约定任何服务都可以接入这与是否真实关联 Influx 数据库无关。实战验证--test模式快速出图配置完成后可以用 Telegraf 的--test模式在不落库的情况下单次抓取并打印度量快速验证插件工作是否正常以下示例来自原文档telegraf --config ~/ws/telegraf.conf --input-filter influxdb --test输出形如influxdb_database,database_internal,hosttyrion,urlhttp://localhost:8086/debug/vars numMeasurements10,numSeries29 1463590500247354636 influxdb_httpd,bind:8086,hosttyrion,urlhttp://localhost:8086/debug/vars req7,reqActive1,reqDurationNs14227734 1463590500247354636 influxdb_measurement,database_internal,hosttyrion,measurementdatabase,urlhttp://localhost:8086/debug/vars numSeries1 1463590500247354636 influxdb_memstats,hosttyrion,urlhttp://localhost:8086/debug/vars alloc7642384i,buck_hash_sys1463471i,frees1169558i,gc_sys653312i,gc_cpu_fraction0.00003825652361068311,heap_alloc7642384i,heap_idle9912320i,heap_inuse9125888i,heap_objects48276i,heap_released0i,heap_sys19038208i,last_gc1463590480877651621i,lookups90i,mallocs1217834i,mcache_inuse4800i,mcache_sys16384i,mspan_inuse70920i,mspan_sys81920i,next_gc11679787i,num_gc141i,other_sys1244233i,pause_total_ns24034027i,stack_inuse884736i,stack_sys884736i,sys23382264i,total_alloc679012200i 1463590500277918755 influxdb_shard,database_internal,enginetsm1,hosttyrion,id4,path/Users/sparrc/.influxdb/data/_internal/monitor/4,retentionPolicymonitor,urlhttp://localhost:8086/debug/vars fieldsCreate65,seriesCreate26,writePointsOk7274,writeReq280 1463590500247354636 influxdb_subscriber,hosttyrion,urlhttp://localhost:8086/debug/vars pointsWritten7274 1463590500247354636 influxdb_tsm1_cache,database_internal,hosttyrion,path/Users/sparrc/.influxdb/data/_internal/monitor/1,retentionPolicymonitor,urlhttp://localhost:8086/debug/vars WALCompactionTimeMs0,cacheAgeMs2809192,cachedBytes0,diskBytes0,memBytes0,snapshotCount0 1463590500247354636 influxdb_tsm1_filestore,database_internal,hosttyrion,path/Users/sparrc/.influxdb/data/_internal/monitor/2,retentionPolicymonitor,urlhttp://localhost:8086/debug/vars diskBytes52907 1463590500247354636 influxdb_tsm1_wal,database_internal,hosttyrion,path/Users/sparrc/.influxdb/wal/_internal/monitor/3,retentionPolicymonitor,urlhttp://localhost:8086/debug/vars currentSegmentDiskBytes0,oldSegmentsDiskBytes65651 1463590500247354636 influxdb_write,hosttyrion,urlhttp://localhost:8086/debug/vars pointReq7274,pointReqLocal7274,req280,subWriteOk280,writeOk280 1463590500247354636 influxdb_shard,hosttyrion n_shards4i 1463590500247354636从输出可以看到几个值得留意的实现细节influxdb_memstats中alloc、gc_cpu_fraction等为插件生成的下划线小写字段其中pause_ns是最近一次 GC 暂停时长所有测量都带url标签部分还带有database、bind、path、retentionPolicy、engine、id等维度标签末尾的influxdb n_shards4i是无标签汇总测量用于快速了解分片总量整数型字段以i后缀标识浮点与布尔、字符串字段按各自类型透传TestBasic中已验证b: true、s: string、f: 0.5等类型的保留。错误处理与边界行为插件对异常情况有清晰的兜底策略全部可在 influxdb.go 及测试中确认非 200 状态码gatherURL调用readResponseError构造apiError尽力从响应体最多 1024 字节中解析{error: ...}字段拼入错误信息influxdb.go。TestErrorResponse验证了 401 响应能正确提取unable to parse authentication credentials。JSON 根非对象直接返回document root must be a JSON object错误。部分字段损坏单个特殊结构体解码失败会被continue跳过不影响同一响应中其他度量的产出。请求失败与超时timeout同时作用于整体客户端与响应头等待单 URL 失败通过acc.AddError上报不影响其余 URL 的并发采集。--test或真实采集均不落库修改插件只读端点数据对 InfluxDB 仅发起 GET 请求。延伸阅读插件文档与示例配置plugins/inputs/influxdb/README.md、plugins/inputs/influxdb/sample.conf插件核心实现plugins/inputs/influxdb/influxdb.go、数据结构定义 plugins/inputs/influxdb/types.go单元测试与真实快照plugins/inputs/influxdb/influxdb_test.go、plugins/inputs/influxdb/testdata/cloud1.json、plugins/inputs/influxdb/testdata/cloud1.influx插件注册入口plugins/inputs/all/influxdb.goInfluxDB v2 指标采集请参考 prometheus 输入插件插件通用配置别名、标签、字段过滤、顺序控制等见 docs/CONFIGURATION.md【免费下载链接】telegrafAgent for collecting, processing, aggregating, and writing metrics, logs, and other arbitrary data.项目地址: https://gitcode.com/GitHub_Trending/te/telegraf创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考