local.file
General availability (GA)

local.file

local.file exposes the contents of a file on disk to other components. The file is watched for changes so that its latest content is always exposed.

The most common use of local.file is to load secrets (for example, API keys) from files.

You can specify multiple local.file components by giving them different labels.

Usage

alloy
local.file "<LABEL>" {
  filename = "<FILE_NAME>"
}

Arguments

You can use the following arguments with local.file:

NameTypeDescriptionDefaultRequired
filenamestringPath of the file on disk to watch.yes
detectorstringWhich file change detector to use, fsnotify or poll."fsnotify"no
is_secretboolMarks the file as containing a secret.falseno
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.

Blocks

The local.file component doesn’t support any blocks. You can configure this component with arguments.

Exported fields

The following fields are exported and can be referenced by other components:

NameTypeDescription
contentstring or secretThe contents of the file from the most recent read.

The content field has the secret type only if the is_secret argument is true.

You can use local.file.LABEL.content to access the contents of the file.

Component health

local.file is reported as healthy whenever if the watched file was read successfully.

Failing to read the file whenever an update is detected (or after the poll period elapses) causes the component to be reported as unhealthy. When unhealthy, exported fields is kept at the last healthy value. The read error is exposed as a log message and in the debug information for the component.

Debug information

local.file doesn’t expose any component-specific debug information.

Debug metrics

  • local_file_timestamp_last_accessed_unix_seconds (gauge): The timestamp, in Unix seconds, that the file was last successfully accessed.

Example

The following example shows a simple local.file configuration that watches a passwords text file and uses the exported content field.

alloy
local.file "secret_key" {
  filename  = "/var/secrets/password.txt"
  is_secret = true
}
grafana_cloud.stack "receivers" {
  stack_name = "mystack"
  token = local.file.secret_key.content
}