Menu

Caution

Grafana Alloy is the new name for our distribution of the OTel collector. Grafana Agent has been deprecated and is in Long-Term Support (LTS) through October 31, 2025. Grafana Agent will reach an End-of-Life (EOL) on November 1, 2025. Read more about why we recommend migrating to Grafana Alloy.
Beta

import.file

BETA: This is a beta component. Beta components are subject to breaking changes, and may be replaced with equivalent functionality that cover the same use case.

The import.file block imports custom components from a file or a directory and exposes them to the importer. import.file blocks must be given a label that determines the namespace where custom components are exposed.

Imported directories are treated as single modules to support composability. That means that you can define a custom component in one file and use it in another custom component in another file in the same directory.

Usage

river
import.file "NAMESPACE" {
  filename = PATH_NAME
}

Arguments

The following arguments are supported:

NameTypeDescriptionDefaultRequired
filenamestringPath of the file or directory on disk to watch.yes
detectorstringWhich file change detector to use (fsnotify, poll)."fsnotify"no
poll_frequencydurationHow often to poll for file changes."1m"no

File change detectors

File change detectors detect when the file needs to be re-read from disk. local.file supports two detectors: fsnotify and poll.

fsnotify

The fsnotify detector subscribes to filesystem events, which indicate when the watched file is updated. This detector requires a filesystem that supports events at the operating system level. Network-based filesystems like NFS or FUSE won’t work.

The component re-reads the watched file when a filesystem event is received. This re-read happens for any filesystem event related to the file, including a permissions change.

fsnotify also polls for changes to the file with the configured poll_frequency as a fallback.

fsnotify stops receiving filesystem events if the watched file has been deleted, renamed, or moved. The subscription is re-established on the next poll once the watched file exists again.

poll

The poll file change detector causes the watched file to be re-read every poll_frequency, regardless of whether the file changed.

Example

This example imports a module from a file and instantiates a custom component from the import that adds two numbers: