Menu
Open source

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

otelcol.receiver.file_stats supports the following arguments:

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

The following blocks are supported inside the definition of otelcol.receiver.file_stats:

HierarchyBlockDescriptionRequired
metricsmetricsConfigures which metrics will be sent to downstream components.no
metrics > file.atimefile.atimeConfigures the file.atime metric.no
metrics > file.countfile.countConfigures the file.count metric.no
metrics > file.ctimefile.ctimeConfigures the file.ctime metric.no
metrics > file.mtimefile.mtimeConfigures the file.mtime metric.no
metrics > file.sizefile.sizeConfigures the file.size metric.no
resource_attributesresource_attributesConfigures resource attributes for metrics sent to downstream components.no
resource_attributes > file.namefile.nameConfigures the file.name resource attribute.no
resource_attributes > file.name > metrics_includemetrics_includeMetrics to include the file.name resource attribute in.no
resource_attributes > file.name > metrics_excludemetrics_excludeMetrics to exclude the file.name resource attribute from.no
resource_attributes > file.pathfile.pathConfigures the file.path resource attribute.no
resource_attributes > file.path > metrics_includemetrics_includeMetrics to include the file.path resource attribute in.no
resource_attributes > file.path > metrics_excludemetrics_excludeMetrics to exclude the file.path resource attribute from.no
debug_metricsdebug_metricsConfigures the metrics that this component generates to monitor its state.no
outputoutputConfigures where to send received telemetry data.yes

metrics block

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 block

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 block

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 block

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 block

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 block

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 block

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 block

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_include block

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.

metrics_exclude block

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.

file.path block

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.

debug_metrics block

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
levelstringControls the level of detail for metrics emitted by the wrapped collector."detailed"no

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.

level is the Alloy equivalent to the telemetry.metrics.level feature gate in the OpenTelemetry Collector. Possible values are "none", "basic", "normal" and "detailed".

output block

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.

Exported fields

otelcol.receiver.file_stats does not export any fields.

Component health

otelcol.receiver.file_stats is reported as unhealthy when:

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

Debug information

otelcol.receiver.file_stats does not 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.