Documentation Grafana Cloud Instrument and send data Grafana Alloy Reference Configuration blocks import.file

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 Copy

import.file "NAMESPACE" {
  filename = PATH_NAME
}

Arguments

The following arguments are supported:

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 Copy

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

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

module.alloy

alloy Copy

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 Copy

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 Copy

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 Copy

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 Copy

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

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

relative_math.alloy

alloy Copy

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 Copy

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

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