Documentation Grafana Agent Flow mode Reference Components reference loki.source.file

loki.source.file

loki.source.file reads log entries from files and forwards them to other loki.* components.

Multiple loki.source.file components can be specified by giving them different labels.

Usage

river Copy

loki.source.file "LABEL" {
  targets    = TARGET_LIST
  forward_to = RECEIVER_LIST
}

Arguments

The component starts a new reader for each of the given targets and fans out log entries to the list of receivers passed in forward_to.

loki.source.file supports the following arguments:

The encoding argument must be a valid IANA encoding name. If not set, it defaults to UTF-8.

You can use the tail_from_end argument when you want to tail a large file without reading its entire content. When set to true, only new logs will be read, ignoring the existing ones.

Blocks

The following blocks are supported inside the definition of loki.source.file:

decompression block

The decompression block contains configuration for reading logs from compressed files. The following arguments are supported:

If you compress a file under a folder being scraped, loki.source.file might try to ingest your file before you finish compressing it. To avoid it, pick an initial_delay that is enough to avoid it.

Currently supported compression formats are:

• gz - for gzip
• z - for zlib
• bz2 - for bzip2

The component can only support one compression format at a time, in order to handle multiple formats, you will need to create multiple components.

file_watch block

The file_watch block configures how often log files are polled from disk for changes. The following arguments are supported:

If no file changes are detected, the poll frequency doubles until a file change is detected or the poll frequency reaches the max_poll_frequency.

If file changes are detected, the poll frequency is reset to min_poll_frequency.

Exported fields

loki.source.file does not export any fields.

Component health

loki.source.file is only reported as unhealthy if given an invalid configuration.

Debug information

loki.source.file exposes some target-level debug information per reader:

• The tailed path.
• Whether the reader is currently running.
• What is the last recorded read offset in the positions file.

Debug metrics

• loki_source_file_read_bytes_total (gauge): Number of bytes read.
• loki_source_file_file_bytes_total (gauge): Number of bytes total.
• loki_source_file_read_lines_total (counter): Number of lines read.
• loki_source_file_encoding_failures_total (counter): Number of encoding failures.
• loki_source_file_files_active_total (gauge): Number of active files.

Component behavior

If the decompression feature is deactivated, the component will continuously monitor and ’tail’ the files. In this mode, upon reaching the end of a file, the component remains active, awaiting and reading new entries in real-time as they are appended.

Each element in the list of targets as a set of key-value pairs called labels. The set of targets can either be static, or dynamically provided periodically by a service discovery component. The special label __path__ must always be present and must point to the absolute path of the file to read from.

The __path__ value is available as the filename label to each log entry the component reads. All other labels starting with a double underscore are considered internal and are removed from the log entries before they’re passed to other loki.* components.

The component uses its data path, a directory named after the domain’s fully qualified name, to store its positions file. The positions file is used to store read offsets, so that if a component or Grafana Agent restarts, loki.source.file can pick up tailing from the same spot.

The data path is inside the directory configured by the --storage.path command line argument.

If a file is removed from the targets list, its positions file entry is also removed. When it’s added back on, loki.source.file starts reading it from the beginning.

Examples

Static targets

This example collects log entries from the files specified in the targets argument and forwards them to a loki.write component to be written to Loki.

river Copy

loki.source.file "tmpfiles" {
  targets    = [
    {__path__ = "/tmp/foo.txt", "color" = "pink"},
    {__path__ = "/tmp/bar.txt", "color" = "blue"},
    {__path__ = "/tmp/baz.txt", "color" = "grey"},
  ]
  forward_to = [loki.write.local.receiver]
}

loki.write "local" {
  endpoint {
    url = "loki:3100/api/v1/push"
  }
}

File globbing

This example collects log entries from the files matching *.log pattern using local.file_match component. When files appear or disappear, the list of targets will be updated accordingly.

river Copy

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

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

loki.write "local" {
  endpoint {
    url = "loki:3100/api/v1/push"
  }
}

Decompression

This example collects log entries from the compressed files matching *.gz pattern using local.file_match component and the decompression configuration on the loki.source.file component.

river Copy

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

loki.source.file "tmpfiles" {
  targets    = local.file_match.logs.targets
  forward_to = [loki.write.local.receiver]
  decompression {
    enabled       = true
    initial_delay = "10s"
    format        = "gz"
  }
}

loki.write "local" {
  endpoint {
    url = "loki:3100/api/v1/push"
  }
}

Compatible components

loki.source.file can accept arguments from the following components:

• Components that export Targets
• Components that export Loki LogsReceiver