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.
Types and values
River uses the following types for its values:
number
: Any numeric value, like3
or3.14
.string
: A sequence of Unicode characters representing text, like"Hello, world!"
.bool
: A boolean value, eithertrue
orfalse
.array
: A sequence of values, like[1, 2, 3]
. Elements within the list are indexed by whole numbers, starting with zero.object
: A group of values identified by named labels, like{ name = "John" }
.function
: A value representing a routine that runs with arguments to compute another value, likeenv("HOME")
. Functions take zero or more arguments as input and always return a single value as output.null
: A type that has no value.
Naming convention
In addition to the preceding types, the [component reference][] documentation uses the following conventions for referring to types:
any
: A value of any type.map(T)
: anobject
with the value typeT
. For example,map(string)
is an object where all the values are strings. The key type of an object is always a string or an identifier converted into a string.list(T)
: anarray
with the value typeT
. For example,list(string)
is an array where all the values are strings.duration
: astring
denoting a duration of time, such as"1d"
,"1h30m"
,"10s"
. Valid units are:d
for days.h
for hours.m
for minutes.s
for seconds.ms
for milliseconds.ns
for nanoseconds.
You can combine values of descending units to add their values together. For example,
"1h30m"
is the same as"90m"
.
Numbers
River handles integers, unsigned integers, and floating-point values as a single ’number’ type, simplifying writing and reading River configuration files.
3 == 3.00 // true
5.0 == (10 / 2) // true
1e+2 == 100 // true
2e-3 == 0.002 // true
Strings
Strings are represented by sequences of Unicode characters surrounded by double quotes ""
.
"Hello, world!"
A \
in a string starts an escape sequence to represent a special character.
The following table shows the supported escape sequences.
Sequence | Replacement |
---|---|
\\ | The \ character U+005C |
\a | The alert or bell character U+0007 |
\b | The backspace character U+0008 |
\f | The formfeed character U+000C |
\n | The newline character U+000A |
\r | The carriage return character U+000D |
\t | The horizontal tab character U+0009 |
\v | The vertical tab character U+000B |
\' | The ' character U+0027 |
\" | The " character U+0022 , which prevents terminating the string |
\NNN | A literal byte (NNN is three octal digits) |
\xNN | A literal byte (NN is two hexadecimal digits) |
\uNNNN | A Unicode character from the basic multilingual plane (NNNN is four hexadecimal digits) |
\UNNNNNNNN | A Unicode character from supplementary planes (NNNNNNNN is eight hexadecimal digits) |
Raw strings
Raw strings are represented by sequences of Unicode characters surrounded by backticks ``
.
Raw strings don’t support any escape sequences.
`Hello, "world"!`
Within the backticks, any character may appear except a backtick.
You can include a backtick by concatenating a double-quoted string that contains a backtick using +
.
A multiline raw string is interpreted exactly as written.
`Hello,
"world"!`
The preceding multiline raw string is interpreted as a string with the following value.
Hello,
"world"!
Bools
Bools are represented by the symbols true
and false
.
Arrays
You construct arrays with a sequence of comma-separated values surrounded by square brackets []
.
[0, 1, 2, 3]
You can place values in array elements on separate lines for readability.
A comma after the final value must be present if the closing bracket ]
is on a different line than the final value.
[
0,
1,
2,
]
Objects
You construct objects with a sequence of comma-separated key-value pairs surrounded by curly braces {}
.
{
first_name = "John",
last_name = "Doe",
}
You can omit the comma after the final key-value pair if the closing curly brace }
is on the same line as the final pair.
{ name = "John" }
If the key isn’t a valid identifier, you must wrap it in double quotes like a string.
{
"app.kubernetes.io/name" = "mysql",
"app.kubernetes.io/instance" = "mysql-abcxyz",
namespace = "default",
}
Note
Don’t confuse objects with blocks.
Functions
You can’t construct function values. You can call functions from the standard library or export them from a component.
Null
The null value is represented by the symbol null
.
Special types
Secrets
A secret
is a special type of string that’s never displayed to the user.
You can assign string
values to an attribute expecting a secret
, but never the inverse.
It’s impossible to convert a secret to a string or assign a secret to an attribute expecting a string.
Capsules
A capsule
is a special type that represents a category of internal types used by Grafana Agent Flow.
Each capsule type has a unique name and is represented to the user as capsule("<SOME_INTERNAL_NAME>")
.
You can’t construct capsule values. You can use capsules in expressions as any other type.
Capsules aren’t inter-compatible, and an attribute expecting a capsule can only be given a capsule of the same internal type.
If an attribute expects a capsule("prometheus.Receiver")
, you can only assign a capsule("prometheus.Receiver")
type.
The specific type of capsule expected is explicitly documented for any component that uses or exports them.
In the following example, the prometheus.remote_write
component exports a receiver
, which is a capsule("prometheus.Receiver")
type.
You can use this capsule in the forward_to
attribute of prometheus.scrape
, which expects an array of capsule("prometheus.Receiver")
.
prometheus.remote_write "default" {
endpoint {
url = "http://localhost:9090/api/v1/write"
}
}
prometheus.scrape "default" {
targets = [/* ... */]
forward_to = [prometheus.remote_write.default.receiver]
}