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.
Important: This documentation is about an older version. It's relevant only to the release noted, many of the features and functions have been updated or replaced. Please view the current version.
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
}