From ccd4289e773e7fe122bbd1172e415372648ecd1c Mon Sep 17 00:00:00 2001 From: Dominik Eisenberg <64131471+Dominik-esb@users.noreply.github.com> Date: Mon, 6 Apr 2026 21:11:57 +0200 Subject: [PATCH] docs: improve file collector docs with pattern cardinality guidance and query examples (#2381) Co-authored-by: dominik_esb --- docs/collector.file.md | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/docs/collector.file.md b/docs/collector.file.md index 5da32dcf..b8ec1a78 100644 --- a/docs/collector.file.md +++ b/docs/collector.file.md @@ -22,6 +22,8 @@ See https://github.com/bmatcuk/doublestar#patterns for an extended description o | `windows_file_mtime_timestamp_seconds` | File modification time | gauge | `file`, `pattern` | | `windows_file_size_bytes` | File size | gauge | `file`, `pattern` | +> Warning: if a very large number of files are matched, the combination of `file` and `pattern` labels can increase cardinality significantly. Use narrow patterns where possible. + ### Example metric ``` @@ -34,7 +36,12 @@ windows_file_size_bytes{file="C:\\Users\\admin\\Desktop\\Dashboard.lnk",pattern= ``` ## Useful queries -_This collector does not yet have any useful queries added, we would appreciate your help adding them!_ +When the same file matches multiple patterns, the `pattern` label makes each sample unique. This also allows aggregation by pattern instead of introducing a separate count metric. + +```promql +sum(windows_file_size_bytes) by (pattern) +count(windows_file_size_bytes) by (pattern) +``` ## Alerting examples _This collector does not yet have alerting examples, we would appreciate your help adding them!_