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.
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
import.file "NAMESPACE" {
filename = PATH_NAME
}Arguments
The following arguments are supported:
| Name | Type | Description | Default | Required |
|---|---|---|---|---|
filename | string | Path of the file or directory on disk to watch. | yes | |
detector | string | Which file change detector to use (fsnotify, poll). | "fsnotify" | no |
poll_frequency | duration | How 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:
declare "add" {
argument "a" {}
argument "b" {}
export "sum" {
value = argument.a.value + argument.b.value
}
}import.file "math" {
filename = "module.river"
}
math.add "default" {
a = 15
b = 45
}
