企业官网建设流程全解析

Telegraf Filecount 输入插件实战指南：统计目录文件数量、大小与新旧程度

【免费下载链接】telegrafAgent for collecting, processing, aggregating, and writing metrics, logs, and other arbitrary data.项目地址: https://gitcode.com/GitHub_Trending/te/telegraf

导读

filecount是 Telegraf 自带的一个轻量级输入插件（自 v1.8.0 起提供），用于统计指定目录中的文件数量与总大小，并额外输出目录内最老与最新文件的修改时间戳。它非常适合监控缓存目录是否膨胀、临时文件是否堆积、备份目录是否按时生成等场景。读完本文，你将掌握filecount的全部配置参数与语义、输出指标结构，以及其基于 glob 通配与目录树遍历的底层实现原理。

插件概览

filecount插件会报告指定目录中的文件数量和文件总大小。其完整实现位于 plugins/inputs/filecount/filecount.go，通过inputs.Add("filecount", ...)注册为 Telegraf 内置输入插件（见 plugins/inputs/all/filecount.go），在所有主流平台上均可运行。

插件定位为系统类（system）监控，适用于以下典型场景：

• 监控/var/cache/apt、/tmp等缓存目录的文件数增长与空间占用；
• 统计日志目录中的文件数量与最老文件时间，判断是否需要轮转归档；
• 检查备份目录是否在规定时间内生成了新文件；
• 监控上传/下载目录是否长期积压文件。

配置详解

filecount的完整可复制配置见 plugins/inputs/filecount/sample.conf，同时插件通过//go:embed sample.conf将示例配置嵌入到二进制中，可直接通过telegraf --config相关方式查看默认样例。完整配置如下：

# Count files in a directory [[inputs.filecount]] ## Directories to gather stats about. ## This accept standard unit glob matching rules, but with the addition of ## ** as a "super asterisk". ie: ## /var/log/** -> recursively find all directories in /var/log and count files in each directories ## /var/log/*/* -> find all directories with a parent dir in /var/log and count files in each directories ## /var/log -> count all files in /var/log and all of its subdirectories directories = ["/var/cache/apt", "/tmp"] ## Only count files that match the name pattern. Defaults to "*". name = "*" ## Count files in subdirectories. Defaults to true. recursive = true ## Only count regular files. Defaults to true. regular_only = true ## Follow all symlinks while walking the directory tree. Defaults to false. follow_symlinks = false ## Only count files that are at least this size. If size is ## a negative number, only count files that are smaller than the ## absolute value of size. Acceptable units are B, KiB, MiB, KB, ... ## Without quotes and units, interpreted as size in bytes. size = "0B" ## Only count files that have not been touched for at least this ## duration. If mtime is negative, only count files that have been ## touched in this duration. Defaults to "0s". mtime = "0s" ## Stop counting after this duration has passed (disabled by default) # timeout = "0s"

directories：目录与超级星号（super asterisk）

directories是必填的核心参数，支持标准通配符（glob）匹配规则，并额外支持**作为“超级星号”（super asterisk）。三个典型用法（摘自 sample.conf 注释）：

• /var/log/**：递归查找/var/log下的所有目录，并分别统计每个目录中的文件；
• /var/log/*/*：查找父目录位于/var/log下的所有目录（即二级目录），分别统计每个目录；
• /var/log：统计/var/log及其所有子目录中的全部文件。

**的解析由 internal/globpath/globpath.go 实现：hasSuperMeta检测路径中是否包含**；Compile会截取第一个**之前的片段作为递归入口rootGlob（见 globpath.go）；GetRoots返回实际需要遍历的根目录集合，而MatchString负责判断遍历到的目录是否命中最终模式（见 globpath.go）。

从源码结构看，含**的模式会先通过filepath.Glob(rootGlob)展开出若干根目录，再对每个根目录做树遍历，逐目录判断是否输出指标，因此输出是按“每个匹配到的目录”一条指标，而非汇总一条。

name：文件名过滤

name用于只统计匹配指定名称模式的文件，默认"*"。底层通过filepath.Match实现（见 filecount.go），支持*、?、[...]等标准模式。当取值为"*"时，该过滤器被直接跳过（返回 nil），不影响性能。

recursive：是否递归子目录

recursive默认true，统计目录树中所有层级的文件；设为false时只统计指定目录的直接子项。注意一个细节：当directories使用**超级星号时，即使recursive = false，也仍会对**展开出的多个目录分别统计（测试 TestNoRecursiveButSuperMeta 验证了这一点）。在实现上，recursive = false且模式不含**时，遍历遇到目录会返回filepath.SkipDir跳过（见 filecount.go）。

regular_only：仅统计普通文件

regular_only默认true，只统计常规文件（通过FileInfo.Mode().IsRegular()判断），从而排除目录本身、设备文件、套接字等特殊条目；设为false时目录也会被计入 count（见 filecount.go）。测试 TestRegularOnlyFilter 验证了开关两种行为下的数量差异。

follow_symlinks：是否跟随符号链接

follow_symlinks默认false。关闭时，遍历过程中遇到的符号链接会被直接跳过（resolveLink中对符号链接返回godirwalk.SkipThis，见 filecount.go）；开启时则使用os.Stat跟随链接并统计目标。目录树的实际遍历由第三方库karrick/godirwalk完成，其FollowSymbolicLinks选项被透传（见 filecount.go）。

size：按文件大小过滤

size默认"0B"，只统计“至少达到该大小”的文件。支持带单位的写法（B、KiB、MiB、KB 等），不带引号和单位时按字节数解释。若设置为负数，则语义反转：只统计小于该值绝对值的文件（见 filecount.go）。例如size = "-100"表示只统计小于 100 字节的文件。配置类型为config.Size（底层是int64，定义见 config/types.go）。

mtime：按修改时间过滤

mtime默认"0s"，只统计“在此时间段内未被修改过”的文件（即至少 mtime 时长未动过的旧文件）。若为负数则反转语义：只统计在此时间段内被修改过的新文件（见 filecount.go）。例如mtime = "1h"表示只统计超过 1 小时未修改的文件，常用于识别"陈旧文件"；mtime = "-24h"表示只统计最近 24 小时内更新的文件。配置类型为config.Duration（底层为time.Duration，定义见 config/types.go）。

timeout：遍历超时

timeout默认关闭（"0s"）。开启后，整个Gather周期的目录遍历共享该超时（见 filecount.go）：超时后停止遍历并记录 Warn 日志"Timeout exceeded, stopping further directory traversal"。对于文件量极大的目录树，设置合理的timeout可以避免阻塞采集周期。相关行为有专门的测试覆盖（TestTimeoutExceeded、TestTimeoutSharedAcrossDirectories 等）。

输出指标（Metrics）

插件输出名为filecount的指标，指标类型为 Gauge，含一个 tag 和四个字段：

指标通过acc.AddGauge("filecount", ...)上报（见 filecount.go）。当recursive = true时，父目录的 count、size 及最老/最新时间戳还会逐层累加子目录的结果（见 filecount.go），因此在测试样例中，顶层目录的count会包含其所有子目录的文件。

示例输出

配置directories = ["/var/cache/apt", "/tmp"]时的输出形如（来自 README.md）：

filecount,directory=/var/cache/apt count=7i,size_bytes=7438336i,oldest_file_timestamp=1507152973123456789i,newest_file_timestamp=1507152973123456789i 1530034445000000000 filecount,directory=/tmp count=17i,size_bytes=28934786i,oldest_file_timestamp=1507152973123456789i,newest_file_timestamp=1507152973123456789i 1530034445000000000

其中i表示整型，行尾为纳秒级时间戳。时间戳字段使用 Unix 纳秒，在 InfluxDB 等后端展示时需注意单位换算。

底层实现原理

过滤器链

插件将name、regular_only、size、mtime四个过滤条件编译为过滤器函数链（fileFilterFunc），在遍历时对每个文件逐一执行，任一条件不满足即剔除（见 filecount.go 与 filecount.go）。取默认值时对应的过滤器会被置空跳过，避免无谓开销。

目录树遍历与统计

核心统计逻辑在count方法中：使用godirwalk.Walk以“子节点先于父节点”的PostChildrenCallback顺序遍历目录树，用四个 map 分别累积每个目录的 count、size、最老/最新时间戳；遍历完成后，若该目录命中 glob 模式则输出一条 Gauge 指标，随后将本目录结果合并进父目录（当recursive = true时），并删除本目录的临时数据以控制内存占用（见 filecount.go）。遍历时遇到权限不足的目录会记录 Debug 日志并跳过该节点继续，而非中断整个扫描（见 filecount.go）。

文件系统抽象与跨平台测试

为了在不同平台（尤其是目录 size 报告不一致的 Windows）上获得一致的测试结果，插件通过fileSystem接口封装了open、stat、lstat三个文件系统操作（见 filesystem_helpers.go），测试中使用fakeFileSystem注入虚拟目录结构，从而精确断言过滤逻辑（见 filecount_test.go）。测试文件顶部注明了 Windows 上超级星号（**）存在已知问题（issue #6248），相关测试目前仅在非 Windows 平台运行（见 filecount_test.go）。

插件的测试数据目录为 plugins/inputs/filecount/testdata，其中包含foo、bar、baz、qux等文件与嵌套子目录，读者可以对照fileCountEquals辅助函数（filecount_test.go）理解各过滤组合下的预期计数结果。

实战建议

• 监控缓存目录：对/var/cache/apt、/tmp等目录设置name = "*"并配合size/mtime阈值，可以及时发现缓存膨胀或临时文件堆积；
• 识别陈旧文件：mtime = "7d"可统计超过一周未变化的文件，oldest_file_timestamp字段则直接给出目录中最老文件的修改时间；
• 控制扫描开销：对超大目录树开启timeout，避免单次采集耗时过长；同时按需调整recursive，非必要时关闭递归可显著减少遍历范围；
• 注意 glob 语义：**与普通*的语义差异较大（前者逐目录产出指标，后者匹配单层），配置前务必阅读 sample.conf 中的三条注释示例。

关于插件支持的全局配置（如 metric 过滤、别名、采样等），可进一步阅读 docs/CONFIGURATION.md。

【免费下载链接】telegrafAgent for collecting, processing, aggregating, and writing metrics, logs, and other arbitrary data.项目地址: https://gitcode.com/GitHub_Trending/te/telegraf