Menu

Caution

Grafana Alloy is the new name for our distribution of the OTel collector. Grafana Agent has been deprecated and is in Long-Term Support (LTS) through October 31, 2025. Grafana Agent will reach an End-of-Life (EOL) on November 1, 2025. Read more about why we recommend migrating to Grafana Alloy.

Important: This documentation is about an older version. It's relevant only to the release noted, many of the features and functions have been updated or replaced. Please view the current version.

Documentationbreadcrumb arrow Grafana Agentbreadcrumb arrow Flow modebreadcrumb arrow Conceptsbreadcrumb arrow Configuration language concepts
Open source

Configuration language concepts

The Grafana Agent Flow configuration language refers to the language used in configuration files which define and configure components to run.

The configuration language is called River, a Terraform/HCL-inspired language:

river
prometheus.scrape "default" {
  targets = [{
    "__address__" = "demo.robustperception.io:9090",
  }]
  forward_to = [prometheus.remote_write.default.receiver]
}

prometheus.remote_write "default" {
  endpoint {
    url = "http://localhost:9009/api/prom/push"
  }
}

River was designed with the following requirements in mind:

  • Fast: The configuration language must be fast so the component controller can evaluate changes as quickly as possible.
  • Simple: The configuration language must be easy to read and write to minimize the learning curve.
  • Debuggable: The configuration language must give detailed information when there’s a mistake in the config file.

Attributes

Attributes are used to configure individual settings. They always take the form of ATTRIBUTE_NAME = ATTRIBUTE_VALUE.

river
log_level = "debug"

This sets the log_level attribute to "debug".

Expressions

Expressions are used to compute the value of an attribute. The simplest expressions are constant values like "debug", 32, or [1, 2, 3, 4]. River supports more complex expressions, such as:

  • Referencing the exports of components: local.file.password_file.content
  • Mathematical operations: 1 + 2, 3 * 4, (5 * 6) + (7 + 8)
  • Equality checks: local.file.file_a.content == local.file.file_b.content
  • Calling functions from River’s standard library: env("HOME") (retrieve the value of the HOME environment variable)

Expressions may be used for any attribute inside a component definition.

Referencing component exports

The most common expression is to reference the exports of a component like local.file.password_file.content. A reference to a component’s exports is formed by merging the component’s name (e.g., local.file), label (e.g., password_file), and export name (e.g., content), delimited by period.

For components that don’t use labels, like prometheus.exporter.unix, only combine the component name with export name: prometheus.exporter.unix.targets.

Blocks

Blocks are used to configure components and groups of attributes. Each block can contain any number of attributes or nested blocks.

river
prometheus.remote_write "default" {
  endpoint {
    url = "http://localhost:9009/api/prom/push"
  }
}

This file has two blocks:

  • prometheus.remote_write "default": A labeled block which instantiates a prometheus.remote_write component. The label is the string "default".

  • endpoint: An unlabeled block inside the component which configures an endpoint to send metrics to. This block sets the url attribute to specify what the endpoint is.

More information

River is documented in detail in Configuration language section of the Grafana Agent Flow docs.