local on Grafana Labs

local.file

Mon, 30 Mar 2026 15:47:22 +0000

`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

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

Arguments

You can use the following arguments with local.file:

Name	Type	Description	Default	Required
`filename`	`string`	Path of the file on disk to watch.		yes
`detector`	`string`	Which file change detector to use, `fsnotify` or `poll`.	`"fsnotify"`	no
`is_secret`	`bool`	Marks the file as containing a secret.	`false`	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.

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:

Name	Type	Description
`content`	`string` or `secret`	The 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.

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
}

local.file_match

Mon, 30 Mar 2026 15:47:22 +0000

`local.file_match`

local.file_match discovers files on the local filesystem using glob patterns and the doublestar library.

Note
Use the built-in file_match block in loki.source.file whenever possible. This provides better performance by integrating file discovery directly into the component, eliminating the overhead of a separate component. The performance benefit is especially noticeable in environments with many files to watch.

Use the local.file_match component only when you need to share discovered targets across multiple components, reuse file discovery results in different parts of your configuration, or accept targets from other discovery components, for example, discovery.relabel before file matching.

Usage

local.file_match "LABEL" {
  path_targets = [{"__path__" = DOUBLESTAR_PATH}]
}

Arguments

You can use the following arguments with local.file_match:

Name	Type	Description	Default	Required
`path_targets`	`list(map(string))`	Targets to expand; looks for glob patterns on the `__path__` and `__path_exclude__` keys.		yes
`ignore_older_than`	`duration`	Ignores files with modification times before this duration.	`"0s"`	no
`sync_period`	`duration`	How often to sync filesystem and targets.	`"10s"`	no

`path_targets` structure

Each target in path_targets is a map that can contain the following keys:

Key	Description	Required
`__path__`	doublestar glob pattern specifying which files to discover.	Yes
`__path_exclude__`	doublestar glob pattern specifying which files to exclude from the `__path__` matches.	No
additional keys	Any other labels to attach to discovered files. The component preserves these labels in the exported targets.	No

The __path__ field uses doublestar style glob patterns:

/tmp/**/*.log matches all subdirectories of tmp and include any files that end in *.log.
/tmp/apache/*.log matches only files in /tmp/apache/ that end in *.log.
/tmp/** matches all subdirectories of tmp, tmp itself, and all files.
/tmp/*.{log,txt,json} matches files with .log, .txt, or .json extensions in /tmp/.
/var/log/{nginx,apache}/*.log matches .log files in either the nginx or apache subdirectories.

local.file_match doesn’t ignore files when you set ignore_older_than to the default, 0s.

When you provide __path_exclude__, the component excludes any files matching the __path__ pattern that also match the __path_exclude__ pattern from the exported list.

The component preserves any additional labels you provide in the path_targets map and includes them in the exported targets alongside the discovered paths. This enables you to add metadata such as service names, instance identifiers, or other contextual information to the discovered files.

Blocks

The local.file_match 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:

Name	Type	Description
`targets`	`list(map(string))`	The set of targets discovered from the filesystem.

Each target includes the following labels:

__path__: Absolute path to the discovered file.
All additional labels from the corresponding entry in path_targets with original values preserved.

Component health

local.file_match is only reported as unhealthy when given an invalid configuration. In those cases, exported fields retain their last healthy values.

Debug information

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

Debug metrics

local.file_match doesn’t expose any component-specific debug metrics.

Examples

The following examples show you how to use local.file_match to find and send log files to Loki

Send `/tmp/logs/*.log` files to Loki

This example discovers all files and folders under /tmp/logs except for files in the /tmp/logs/excluded directory. loki.source.file.files targets use absolute paths in the __path__ label.

local.file_match "tmp" {
  path_targets = [{"__path__" = "/tmp/logs/**/*.log", "__path_exclude__" = "/tmp/logs/excluded/*.log"}]
}

loki.source.file "files" {
  targets    = local.file_match.tmp.targets
  forward_to = [loki.write.endpoint.receiver]
}

loki.write "endpoint" {
  endpoint {
      url = <LOKI_URL>
      basic_auth {
          username = <USERNAME>
          password = <PASSWORD>
      }
  }
}

Replace the following:

<LOKI_URL>: The URL of the Loki server to send logs to.
<USERNAME>: The username to use for authentication to the Loki API.
<PASSWORD>: The password to use for authentication to the Loki API.

Send files with additional labels

This example shows how to include additional labels with discovered files. The component preserves the additional labels in the exported targets and you can use them for filtering or enrichment. It attaches the additional labels instance, job, and service to each discovered file. Downstream components like loki.source.file can access these labels for processing and enrichment.

local.file_match "labeled_logs" {
  path_targets = [
    {
      "__path__"    = "/var/log/apache2/*.log",
      "__address__" = "localhost",
      "instance"    = "web-server-01", 
      "job"         = "apache",
      "service"     = "web",
    },
    {
      "__path__"       = "/var/log/nginx/*.log",
      "__path_exclude__" = "/var/log/nginx/*.gz",
      "__address__"    = "localhost",
      "instance"       = "web-server-01",
      "job"            = "nginx", 
      "service"        = "web",
    },
  ]
}

loki.source.file "web_logs" {
  targets    = local.file_match.labeled_logs.targets
  forward_to = [loki.write.endpoint.receiver]
}

loki.write "endpoint" {
  endpoint {
    url = "<LOKI_URL>"
    basic_auth {
      username = "<USERNAME>"
      password = "<PASSWORD>"
    }
  }
}

Replace the following:

<LOKI_URL>: The URL of the Loki server to send logs to.
<USERNAME>: The username to use for authentication to the Loki API.
<PASSWORD>: The password to use for authentication to the Loki API.

Match multiple patterns

This example shows how to use the {a,b,c} pattern syntax to match multiple file extensions, multiple directories, and exclude multiple file types in a single configuration.

local.file_match "logs" {
  path_targets = [
    // Match .log, .txt, and .json files from nginx, apache, or caddy directories
    // Exclude compressed and backup files
    {
      "__path__"         = "/var/log/{nginx,apache,caddy}/*.{log,txt,json}",
      "__path_exclude__" = "/var/log/{nginx,apache,caddy}/*.{gz,zip,bak,old}",
      "job"              = "webserver",
    },
  ]
}

loki.source.file "logs" {
  targets    = local.file_match.logs.targets
  forward_to = [loki.write.endpoint.receiver]
}

loki.write "endpoint" {
  endpoint {
    url = "<LOKI_URL>"
  }
}

Send Kubernetes Pod logs to Loki

This example finds all the logs on Pods and monitors them.

discovery.kubernetes "k8s" {
  role = "pod"
}

discovery.relabel "k8s" {
  targets = discovery.kubernetes.k8s.targets

  rule {
    source_labels = ["__meta_kubernetes_namespace", "__meta_kubernetes_pod_label_name"]
    target_label  = "job"
    separator     = "/"
  }

  rule {
    source_labels = ["__meta_kubernetes_pod_uid", "__meta_kubernetes_pod_container_name"]
    target_label  = "__path__"
    separator     = "/"
    replacement   = "/var/log/pods/*$1/*.log"
  }
}

local.file_match "pods" {
  path_targets = discovery.relabel.k8s.output
}

loki.source.file "pods" {
  targets = local.file_match.pods.targets
  forward_to = [loki.write.endpoint.receiver]
}

loki.write "endpoint" {
  endpoint {
      url = "<LOKI_URL>"
      basic_auth {
          username = "<USERNAME>"
          password = "<PASSWORD>"
      }
  }
}

Replace the following:

<LOKI_URL>: The URL of the Loki server to send logs to.
<USERNAME>: The username to use for authentication to the Loki API.
<PASSWORD>: The password to use for authentication to the Loki API.

Compatible components

local.file_match can accept arguments from the following components:

Components that export Targets

local.file_match has exports that can be consumed by the following components:

Components that consume Targets

Note
Connecting some components may not be sensible or components may require further configuration to make the connection work correctly. Refer to the linked documentation for more details.

local on Grafana Labs

local.file

local.file

Usage

Arguments

File change detectors

fsnotify

poll

Blocks

Exported fields

Component health

Debug information

Debug metrics

Example

local.file_match

local.file_match

Usage

Arguments

path_targets structure

Blocks

Exported fields

Component health

Debug information

Debug metrics

Examples

Send /tmp/logs/*.log files to Loki

Send files with additional labels

Match multiple patterns

Send Kubernetes Pod logs to Loki

Compatible components

`local.file`

`fsnotify`

`poll`

`local.file_match`

`path_targets` structure

Send `/tmp/logs/*.log` files to Loki