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.

DocumentationGrafana AgentFlow modeConfiguration language

Configuration language

Grafana Agent Flow dynamically configures and connects components with a custom configuration language called River.

River aims to reduce errors in configuration files by making configurations easier to read and write. River configurations use blocks that can be easily copied and pasted from the documentation to help you get started as quickly as possible.

A River configuration file tells Grafana Agent Flow which components to launch and how to bind them together into a pipeline.

The River syntax uses blocks, attributes, and expressions.

river Copy

// Create a local.file component labeled my_file.
// This can be referenced by other components as local.file.my_file.
local.file "my_file" {
  filename = "/tmp/my-file.txt"
}

// Pattern for creating a labeled block, which the above block follows:
BLOCK_NAME "BLOCK_LABEL" {
  // Block body
  IDENTIFIER = EXPRESSION // Attribute
}

// Pattern for creating an unlabeled block:
BLOCK_NAME {
  // Block body
  IDENTIFIER = EXPRESSION // Attribute
}

River is similar to HCL, the language Terraform and other Hashicorp projects use. It’s a distinct language with custom syntax and features, such as first-class functions.

• Blocks are a group of related settings and usually represent creating a component. Blocks have a name that consists of zero or more identifiers separated by ., an optional user label, and a body containing attributes and nested blocks.
• Attributes appear within blocks and assign a value to a name.
• Expressions represent a value, either literally or by referencing and combining other values. You use expressions to compute a value for an attribute.

River is declarative, so ordering components, blocks, and attributes within a block isn’t significant. The relationship between components determines the order of operations.

Tooling

You can use one or all of the following tools to help you write configuration files in River.

• Experimental editor support for
  • vim
  • VSCode
  • river-mode for Emacs
• Code formatting using the agent fmt command

You can also start developing your own tooling using the Grafana Agent repository as a go package or use the tree-sitter grammar with other programming languages.