Configuration language on Grafana Labs

Files

Wed, 29 Jan 2025 11:00:55 +0000

Files

River files are plain text files with the .river file extension. You can refer to each River file as a “configuration file” or a “River configuration.”

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

Syntax

Wed, 29 Jan 2025 11:00:55 +0000

Syntax

The River syntax is easy to read and write. It has only two high-level elements, Attributes and Blocks.

River is a declarative language used to build programmable pipelines. The order of blocks and attributes within the River configuration file isn’t important. The language considers all direct and indirect dependencies between elements to determine their relationships.

Comments

River configuration files support single-line // and 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

You use Attributes 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 (for example, a string, boolean, number), or an expression to represent or compute more complex attribute values.

Blocks

You use Blocks to configure the Grafana Agent’s behavior as well as Grafana Agent 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.

Some blocks can be defined more than once.

Examples

You can use the following pattern to create an unlabeled block.

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

  NESTED_BLOCK_NAME {
    // Nested block body
  }
}

You can use the following pattern to create 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 Grafana Agent Flow as either a valid component name or a special block for configuring global settings. If the BLOCK_LABEL must be set, it must be a valid River identifier wrapped in double quotes. In these cases, you use the label 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 filename to the content 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 a terminator when it follows any expression, ], ), or }. River ignores other newlines and you can can enter as many newlines as you want.

Components configuration language

Wed, 29 Jan 2025 11:00:55 +0000

Components configuration language

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

The component controller is responsible for scheduling components, reporting their health and debug status, re-evaluating their arguments, and providing their exports.

Configuring components

You create components by defining a top-level River block. All components are identified by their name, describing what the component is responsible for, and a user-specified label.

Arguments and exports

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

Arguments are settings that modify the behavior of a component. They can be any number of attributes or nested unlabeled blocks, some required and some optional. Any optional arguments that aren’t set take on their default values.
Exports are zero or more output values that other components can refer to and can be of any River type.

The following block defines a local.file component labeled “targets”. The local.file.targets component exposes the file content as a string in its exports.

The filename attribute is a required argument. You can also define a number of optional arguments, in this case, detector, poll_frequency, and is_secret, that configure how and how often the file should be polled and whether its contents are sensitive.

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 target 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"
  }
}

Each time the file contents change, the local.file updates its exports. The new value is sent to the prometheus.scrape targets field.

Each argument and exported field has an underlying type. River checks the expression type before assigning a value to an attribute. The documentation of each component provides more information about how to wire components together.

In the previous example, the contents of the local.file.targets.content expression is evaluated to a concrete value. The value is type-checked and substituted into prometheus.scrape.default, where you can configure it.

Expressions

Wed, 29 Jan 2025 11:00:55 +0000

Expressions

Expressions represent or compute values you can assign 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.

You use expressions when you configure any component. All component arguments have an underlying type. River checks the expression type before assigning the result to an attribute.