Menu

This is documentation for the next version of Grafana Alloy Documentation. For the latest stable release, go to the latest version.

General availability (GA) Open source

import.file

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.

You can use the keyword module_path in combination with the stdlib function file.path_join to import a module relative to the current module’s path. The module_path keyword works for modules that are imported via import.file, import.git, and import.string.

Usage

alloy
import.file "<NAMESPACE>" {
  filename = <PATH_NAME>
}

Arguments

You can use the following arguments with import.file:

NameTypeDescriptionDefaultRequired
filenamestringPath of the file or directory on disk to watch.yes
detectorstringWhich file change detector to use, fsnotify or 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.

Examples

Import a module from a local file

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

main.alloy

alloy
import.file "math" {
  filename = "module.alloy"
}

math.add "default" {
  a = 15
  b = 45
}

module.alloy

alloy
declare "add" {
  argument "a" {}
  argument "b" {}

  export "sum" {
    value = argument.a.value + argument.b.value
  }
}

Import a module in a module imported via import.git

This example imports a module from a file inside of a module that’s imported via import.git:

main.alloy

alloy
import.git "math" {
  repository = "https://github.com/wildum/module.git"
  path       = "relative_math.alloy"
  revision   = "master"
}

math.add "default" {
  a = 15
  b = 45
}

relative_math.alloy

alloy
import.file "lib" {
  filename = file.path_join(module_path, "lib.alloy")
}

declare "add" {
  argument "a" {}
  argument "b" {}

  lib.plus "default" {
    a = argument.a.value
    b = argument.b.value
  }

  export "output" {
    value = lib.plus.default.sum
  }
}

lib.alloy

alloy
declare "plus" {
  argument "a" {}
  argument "b" {}

  export "sum" {
    value = argument.a.value + argument.b.value
  }
}

Import a module in a module imported via import.file

This example imports a module from a file inside of a module that’s imported via another import.file:

main.alloy

alloy
import.file "math" {
  filename = "path/to/module/relative_math.alloy"
}

math.add "default" {
  a = 15
  b = 45
}

relative_math.alloy

alloy
import.file "lib" {
  filename = file.path_join(module_path, "lib.alloy")
}

declare "add" {
  argument "a" {}
  argument "b" {}

  lib.plus "default" {
    a = argument.a.value
    b = argument.b.value
  }

  export "output" {
    value = lib.plus.default.sum
  }
}

lib.alloy

alloy
declare "plus" {
  argument "a" {}
  argument "b" {}

  export "sum" {
    value = argument.a.value + argument.b.value
  }
}