Menu
General availability (GA) Open source Grafana Cloud

otelcol.receiver.file_stats

otelcol.receiver.file_stats collects metrics from files and folders specified with a glob pattern.

Note

otelcol.receiver.file_stats is a wrapper over the upstream OpenTelemetry Collector filestats receiver from the otelcol-contrib distribution. Bug reports or feature requests will be redirected to the upstream repository, if necessary.

Multiple otelcol.receiver.file_stats components can be specified by giving them different labels.

Warning

otelcol.receiver.file_stats only works on macOS, Linux, and Windows.

Usage

alloy
otelcol.receiver.file_stats "<LABEL>" {
  include = "GLOB_PATTERN"

  output {
    metrics = [...]
  }
}

Arguments

You can use the following arguments with otelcol.receiver.file_stats:

NameTypeDescriptionDefaultRequired
includestringGlob path for paths to collect stats from.yes
collection_intervaldurationHow often to collect statistics."1m"no
initial_delaydurationInitial time to wait before collecting statistics."1s"no
timeoutdurationTimeout for a collection; 0s means no timeout."0s"no

include is a glob pattern that specifies which paths (files and folders) to collect stats from. A * character matches entries in a directory, while ** includes subdirectories. For example, /var/log/**/*.log matches all files and directories ending in .log recursively inside /var/log.

The timeout argument controls the timeout for each collection specified by the collection_interval. The timeout applies to the entire collection process across all paths matched by the include argument.

Blocks

You can use the following blocks with otelcol.receiver.file_stats:

BlockDescriptionRequired
outputConfigures where to send received telemetry data.yes
debug_metricsConfigures the metrics that this component generates to monitor its state.no
metricsConfigures which metrics will be sent to downstream components.no
metrics > file.atimeConfigures the file.atime metric.no
metrics > file.countConfigures the file.count metric.no
metrics > file.ctimeConfigures the file.ctime metric.no
metrics > file.mtimeConfigures the file.mtime metric.no
metrics > file.sizeConfigures the file.size metric.no
resource_attributesConfigures resource attributes for metrics sent to downstream components.no
resource_attributes > file.nameConfigures the file.name resource attribute.no
resource_attributes > file.name > metrics_excludeMetrics to exclude the file.name resource attribute from.no
resource_attributes > file.name > metrics_includeMetrics to include the file.name resource attribute in.no
resource_attributes > file.pathConfigures the file.path resource attribute.no
resource_attributes > file.path > metrics_excludeMetrics to exclude the file.path resource attribute from.no
resource_attributes > file.path > metrics_includeMetrics to include the file.path resource attribute in.no

output

Required

The output block configures a set of components to forward resulting telemetry data to.

The following arguments are supported:

NameTypeDescriptionDefaultRequired
logslist(otelcol.Consumer)List of consumers to send logs to.[]no
metricslist(otelcol.Consumer)List of consumers to send metrics to.[]no
traceslist(otelcol.Consumer)List of consumers to send traces to.[]no

You must specify the output block, but all its arguments are optional. By default, telemetry data is dropped. Configure the metrics, logs, and traces arguments accordingly to send telemetry data to other components.

debug_metrics

The debug_metrics block configures the metrics that this component generates to monitor its state.

The following arguments are supported:

NameTypeDescriptionDefaultRequired
disable_high_cardinality_metricsbooleanWhether to disable certain high cardinality metrics.trueno

disable_high_cardinality_metrics is the Grafana Alloy equivalent to the telemetry.disableHighCardinalityMetrics feature gate in the OpenTelemetry Collector. It removes attributes that could cause high cardinality metrics. For example, attributes with IP addresses and port numbers in metrics about HTTP and gRPC connections are removed.

Note

If configured, disable_high_cardinality_metrics only applies to otelcol.exporter.* and otelcol.receiver.* components.

metrics

The metrics block configures the set of metrics that will be sent to downstream components. It accepts no arguments, but contains other blocks for individual metrics:

Refer to the documentation of individual metric blocks for whether that metric is enabled by default.

file.atime

The file.atime block configures the file.atime metric. file.atime tracks the elapsed time since the last access of the file or folder in Unix seconds since the epoch.

NameTypeDescriptionDefaultRequired
enabledbooleanWhether to collect the file.atime metric.falseno

file.count

The file.count block configures the file.count metric. file.count tracks the number of files and folders in the specified glob pattern.

NameTypeDescriptionDefaultRequired
enabledbooleanWhether to collect the file.count metric.falseno

file.ctime

The file.ctime block configures the file.ctime metric. file.ctime tracks the elapsed time since the last change of the file or folder in Unix seconds since the epoch. Changes include permissions, ownership, and timestamps.

NameTypeDescriptionDefaultRequired
enabledbooleanWhether to collect the file.ctime metric.falseno

file.mtime

The file.mtime block configures the file.mtime metric. file.mtime tracks the elapsed time since the last modification of the file or folder in Unix seconds since the epoch.

NameTypeDescriptionDefaultRequired
enabledbooleanWhether to collect the file.mtime metric.trueno

file.size

The file.size block configures the file.size metric. file.size tracks the size of the file or folder in bytes.

NameTypeDescriptionDefaultRequired
enabledbooleanWhether to collect the file.size metric.trueno

resource_attributes

The resource_attributes block configures resource attributes for metrics sent to downstream components. It accepts no arguments, but contains other blocks for configuring individual resource attributes:

Refer to the documentation of individual resource attribute blocks for whether that resource attribute is enabled by default.

file.name

The file.name block configures the file.name resource attribute.

NameTypeDescriptionDefaultRequired
enabledbooleanWhether to include the file.name resource attribute.trueno

When enabled is true, the file.name attribute is included in all metrics.

The children blocks metrics_include and metrics_exclude can be used to further filter which metrics are given the file.name attribute. If a given metric matches all the metrics_include blocks and none of the metrics_exclude blocks, the file.name attribute is added.

metrics_exclude

The metrics_exclude block configures a filter for excluding metrics. The metrics_exclude block may be specified multiple times.

NameTypeDescriptionDefaultRequired
strictstringThe exact name of the metric to exclude.yes*
regexpstringA regular expression for the metrics to exclude.yes*

Exactly one of strict or regexp must be specified.

metrics_include

The metrics_include block configures a filter for matching metrics. The metrics_include block may be specified multiple times.

NameTypeDescriptionDefaultRequired
strictstringThe exact name of the metric to include.yes*
regexpstringA regular expression for the metrics to include.yes*

Exactly one of strict or regexp must be specified.

file.path

The file.path block configures the file.path resource attribute.

NameTypeDescriptionDefaultRequired
enabledbooleanWhether to include the file.path resource attribute.falseno

When enabled is true, the file.path attribute is included in all metrics. The children blocks metrics_include and metrics_exclude can be used to further filter which metrics are given the file.path attribute. If a given metric matches all the metrics_include blocks and none of the metrics_exclude blocks, the file.path attribute is added.

Exported fields

otelcol.receiver.file_stats doesn’t export any fields.

Component health

otelcol.receiver.file_stats is reported as unhealthy when:

  • It’s given an invalid configuration.
  • It runs on an unsupported operating system.

Debug information

otelcol.receiver.file_stats doesn’t expose any component-specific debug information.

Example

This example forwards file stats of files and folders with the .log extension in /var/log through a batch processor before finally sending it to an OTLP-capable endpoint:

alloy
otelcol.receiver.file_stats "default" {
  include = "/var/log/**/*.log"

  output {
    metrics = [otelcol.processor.batch.default.input]
  }
}

otelcol.processor.batch "default" {
  output {
    metrics = [otelcol.exporter.otlp.default.input]
  }
}

otelcol.exporter.otlp "default" {
  client {
    endpoint = sys.env("OTLP_ENDPOINT")
  }
}

Compatible components

otelcol.receiver.file_stats can accept arguments from the following components:

Note

Connecting some components may not be sensible or components may require further configuration to make the connection work correctly. Refer to the linked documentation for more details.