Grafana Agent FlowConfiguration languageExpressionsTypes and values

Types and values

Types

River uses the following types for its values:

  • number: Any numeric value, like 3 or 3.14.
  • string: A sequence of Unicode characters representing text, like "Hello, world!".
  • bool: A boolean value, either true or false.
  • 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 which are identified by named labels, like { name = "John" }.
  • function: A value representing a routine which can be executed with arguments to compute another value, like env("HOME"). Functions take zero or more arguments as input and always return a single value as output.
  • null: A type that has no value.

Numbers

River handles integers, unsigned integers and floating-point values as a single ’number’ type which simplifies 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 supported escape sequences are as follows:

SequenceReplacement
\aThe alert or bell character U+0007
\bThe backspace character U+0008
\fThe formfeed character U+000C
\nThe newline character U+000A
\rThe carriage return character U+000D
\tThe horizontal tab character U+0009
\vThe vertical tab character U+000B
\'The ' character U+0027
\"The " character U+0022, which prevents terminating the string
\NNNA literal byte (NNN is three octal digits)
\xNNA literal byte (NN is two hexadecimal digits)
\uNNNNA Unicode character from the basic multilingual plane (NNNN is four hexadecimal digits)
\UNNNNNNNNA Unicode character from supplementary planes (NNNNNNNN is eight hexadecimal digits)

Bools

Bools are represented by the symbols true and false.

Arrays

Array values are constructed by a sequence of comma separated values surrounded by square brackets []:

[0, 1, 2, 3]

Values in array elements may be placed on separate lines for readability. A comma after the final value must be present if the closing bracket ] is on a different line as the final value:

[
  0,
  1,
  2,
]

Objects

Object values are constructed by a sequence of comma separated key-value pairs surrounded by curly braces {}:

{
  first_name = "John",
  last_name = "Doe",
}

A comma after the final key-value pair may be omitted if the closing curly brace } is on the same line as the final pair:

{ name = "John" }

Functions

Function values cannot be constructed by users, but can be called from the standard library or when exported by a component.

Null

The null value is represented by the symbol null.

Special Types

Secrets

A secret is a special type of string which is never displayed to the user. string values may be assigned to an attribute expecting a secret, but never the inverse; it is not possible to convert a secret to a string or assign a secret to an attribute expecting a string.

Capsules

River has a special type called a capsule, which represents a category of internal types used by Flow. Each capsule type has a unique name and will be represented to the user as capsule("SOME_INTERNAL_NAME"). Capsule values cannot be constructed by the user, but can be used in expressions as any other type. Capsules are not inter-compatible and an attribute expecting a capsule can only be given a capsule of the same internal type. That means, if an attribute expects a capsule("prometheus.Receiver"), it can only be assigned a capsule("prometheus.Receiver") type. The specific type of capsule expected is explicitly documented for any component which uses or exports them.

In the following example, the prometheus.remote_write component exports a receiver, which is a capsule("prometheus.Receiver") type. This can then be used in the forward_to attribute of prometheus.scrape, which expects an array of capsule("prometheus.Receiver")s:

prometheus.remote_write "default" {
  endpoint {
    url = "http://localhost:9090/api/v1/write"
  }
}

prometheus.scrape "default" {
  targets    = [/* ... */]
  forward_to = [prometheus.remote_write.default.receiver]
}