Configuration language on Grafana Labs

Files

Sun, 08 Mar 2026 02:10:29 +0000

Files

River files are plaintext files with the .river file extension. Each River file may be referred to as a “configuration file,” or a “River configuration.”

River files are required to be UTF-8 encoded, and are permitted to contain Unicode characters. River files can use both Unix-style line endings (LF) and Windows-style line endings (CRLF), but formatters may replace all line endings with Unix-style ones.

Community tooling

There is experimental support for River in vim and in VSCode.

Syntax

Sun, 08 Mar 2026 02:10:29 +0000

Syntax

The River syntax is designed to be easy to read and write. Essentially, there are just two high-level elements to it: Attributes and Blocks.

River is a declarative language used to build programmable pipelines. As such, the ordering of blocks and attributes within the River configuration file is not important; the language will consider all direct and indirect dependencies between elements to determine their relationships.

Comments

River configuration files support single-line // as well as block /* */ comments.

Identifiers

River considers an identifier as valid if it consists of one or more UTF-8 letters (A through Z, both upper- and lower-case), digits or underscores, but doesn’t start with a digit.

Attributes and Blocks

Attributes

Attributes are used to configure individual settings. They always take the form of ATTRIBUTE_NAME = ATTRIBUTE_VALUE. They can appear either as top-level elements or nested within blocks.

The following example sets the log_level attribute to "debug".

log_level = "debug"

The ATTRIBUTE_NAME must be a valid River identifier.

The ATTRIBUTE_VALUE can be either a constant value of a valid River type (eg. string, boolean, number) or an expression to represent or compute more complex attribute values.

Blocks

Blocks are used to configure the Agent behavior as well as Flow components by grouping any number of attributes or nested blocks using curly braces. Blocks have a name, an optional label and a body that contains any number of arguments and nested unlabeled blocks.

Pattern for creating an unlabeled block

BLOCK_NAME {
  // Block body can contain attributes and nested unlabeled blocks
  IDENTIFIER = EXPRESSION // Attribute

  NESTED_BLOCK_NAME {
    // Nested block body
  }
}

Pattern for creating a labeled block

// Pattern for creating a labeled block:
BLOCK_NAME "BLOCK_LABEL" {
  // Block body can contain attributes and nested unlabeled blocks
  IDENTIFIER = EXPRESSION // Attribute

  NESTED_BLOCK_NAME {
    // Nested block body
  }
}

Block naming rules

The BLOCK_NAME has to be recognized by Flow as either a valid component name or a special block for configuring global settings. If the BLOCK_LABEL has to be set, it must be a valid River identifier wrapped in double quotes. In these cases the label will be used to disambiguate between multiple top-level blocks of the same name.

The following snippet defines a block named local.file with its label set to “token”. The block’s body sets the to the contents of the TOKEN_FILE_PATH environment variable by using an expression and the is_secret attribute is set to the boolean true, marking the file content as sensitive.

local.file "token" {
  filename  = env("TOKEN_FILE_PATH") // Use an expression to read from an env var.
  is_secret = true
}

Terminators

All block and attribute definitions are followed by a newline, which River calls a terminator, as it terminates the current statement.

A newline is treated as terminator when it follows any expression, ], ) or }. Other newlines are ignored by River and and a user can enter as many newlines as they want.

Components

Sun, 08 Mar 2026 02:10:29 +0000

Components

Components are the defining feature of Grafana Agent Flow. They are small, reusable pieces of business logic that perform a single task (like retrieving secrets or collecting Prometheus metrics) and can be wired together to form programmable pipelines of telemetry data.

Under the hood, components are orchestrated via the component controller, which is responsible for scheduling them, reporting their health and debug status, re-evaluating their arguments and providing their exports.

Configuring components

Components are created by defining a top-level River block. All components are identified by their name, describing what the component is responsible for, while some allow or require to provide an extra user-specified label.

The components docs contain a list of all available components. Each one has a complete reference page, so getting a component to work for you should be as easy as reading its documentation and copy/pasting from an example.

Arguments and exports

Most user interactions with components will center around two basic concepts; arguments and exports.

Arguments are settings which modify the behavior of a component. They can be any number of attributes or nested unlabeled blocks, some of them being required and some being optional. Any optional arguments that are not set will take on their default values.
Exports are zero or more output values that can be referred to by other components, and can be of any River type.

Here’s a quick example; the following block defines a local.file component labeled “targets”. The local.file.targets component will then expose the file content as a string in its exports.

The filename attribute is a required argument; the user can also define a number of optional ones, in this case detector, poll_frequency and is_secret, which configure how and how often the file should be polled as well as whether its contents are sensitive or not.

local.file "targets" {
  // Required argument
  filename = "/etc/agent/targets"

  // Optional arguments: Components may have some optional arguments that
  // do not need to be defined.
  //
  // The optional arguments for local.file are is_secret, detector, and
  // poll_frequency.

  // Exports: a single field named `content`
  // It can be referred to as `local.file.targets.content`
}

Referencing components

To wire components together, one can use the exports of one as the arguments to another by using references. References can only appear in components.

For example, here’s a component that scrapes Prometheus metrics. The targets field is populated with two scrape targets; a constant one localhost:9001 and an expression that ties the target to the value of local.file.targets.content.

prometheus.scrape "default" {
  targets = [
    { "__address__" = local.file.targets.content }, // tada!
    { "__address__" = "localhost:9001" },
  ]

  forward_to = [prometheus.remote_write.default.receiver]
  scrape_config {
    job_name = "default"
  }
}

Every time the file contents change, the local.file will update its exports, so the new value will provided to prometheus.scrape targets field.

Each argument and exported field has an underlying type. River will type-check expressions before assigning a value to an attribute; the documentation of each component will have more information about the ways that you can wire components together.

In the previous example, the contents of the local.file.targets.content expression must first be evaluated in a concrete value then type-checked and substituted into prometheus.scrape.default for it to be configured in turn.

Expressions

Sun, 08 Mar 2026 02:10:29 +0000

Expressions

Expressions represent or compute values that can be assigned to attributes within a configuration.

Basic expressions are literal values, like "Hello, world!" or true. Expressions may also do things like refer to values exported by components, perform arithmetic, or call functions.

Expressions can be used when configuring any component. As all component arguments have an underlying type, River will type-check expressions before assigning the result to an attribute.