Expressions on Grafana Labs

Types and values

Wed, 12 Mar 2025 11:45:31 +0100

Types and values

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 identified by named labels, like { name = "John" }.
function: A value representing a routine that runs 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.

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): an object with the value type T. 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): an array with the value typeT. For example, list(string) is an array where all the values are strings.
duration: a string 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.

An object is a value assigned to an Attribute. You must use commas between key-value pairs on separate lines.

A Block is a named structural element composed of multiple attributes. You must not use commas between attributes.

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]
}

Referencing component exports

Fri, 31 May 2024 15:06:20 +0000

Referencing component exports

Referencing exports enables River to configure and connect components dynamically using expressions. While components can work in isolation, they’re more useful when one component’s behavior and data flow are bound to the exports of another, building a dependency relationship between the two.

Such references can only appear as part of another component’s arguments or a configuration block’s fields. Components can’t reference themselves.

Using references

You build references by combining the component’s name, label, and named export with dots.

For example, you can reference the contents of a file exported by the local.file component labeled target as local.file.target.content. Similarly, a prometheus.remote_write component instance labeled onprem exposes its receiver for metrics on prometheus.remote_write.onprem.receiver.

The following example shows some references.

local.file "target" {
  filename = "/etc/agent/target"
}

prometheus.scrape "default" {
  targets    = [{ "__address__" = local.file.target.content }]
  forward_to = [prometheus.remote_write.onprem.receiver]
}

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

In the preceding example, you wired together a very simple pipeline by writing a few River expressions.

After the value is resolved, it must match the type of the attribute it is assigned to. While you can only configure attributes using the basic River types, the exports of components can take on special internal River types, such as Secrets or Capsules, which expose different functionality.

Operators

Fri, 31 May 2024 15:06:20 +0000

Operators

River uses a common set of operators. All operations follow the standard PEMDAS order of mathematical operations.

Arithmetic operators

Operator	Description
`+`	Adds two numbers.
`-`	Subtracts two numbers.
`*`	Multiplies two numbers.
`/`	Divides two numbers.
`%`	Computes the remainder after dividing two numbers.
`^`	Raises the number to the specified power.

String operators

Operator	Description
`+`	Concatenate two strings.

Comparison operators

Operator	Description
`==`	`true` when two values are equal.
`!=`	`true` when two values aren’t equal.
`<`	`true` when the left value is less than the right value.
`<=`	`true` when the left value is less than or equal to the right value.
`>`	`true` when the left value is greater than the right value.
`>=`	`true` when the left value is greater or equal to the right value.

You can apply the equality operators == and != to any operands.

The two operands in ordering operators < <= > and >= must both be orderable and of the same type. The results of the comparisons are:

Boolean values are equal if they’re either both true or both false.
Numerical (integer and floating-point) values are orderable in the usual way.
String values are orderable lexically byte-wise.
Objects are equal if all their fields are equal.
Array values are equal if their corresponding elements are equal.

Logical operators

Operator	Description
`&&`	`true` when the both left and right value are `true`.
`\|\|`	`true` when the either left or right value are `true`.
`!`	Negates a boolean value.

Logical operators apply to boolean values and yield a boolean result.

Assignment operator

River uses = as its assignment operator.

An assignment statement may only assign a single value. Each value must be assignable to the attribute or object key.

You can assign null to any attribute.
You can assign numerical, string, boolean, array, function, capsule, and object types to attributes of the corresponding type.
You can assign numbers to string attributes with an implicit conversion.
You can assign strings to numerical attributes if they represent a number.
You can’t assign blocks.

Brackets

Brackets	Description
`{ }`	Defines blocks and objects.
`( )`	Groups and prioritizes expressions.
`[ ]`	Defines arrays.

The following example uses curly braces and square brackets to define an object and an array.

obj = { app = "agent", namespace = "dev" }
arr = [1, true, 7 * (1+1), 3]

Access operators

Operator	Description
`[ ]`	Access a member of an array or object.
`.`	Access a named member of an object or an exported field of a component.

You can access arbitrarily nested values with River’s access operators. You can use square brackets to access zero-indexed array indices and object fields by enclosing the field name in double quotes. You can use the dot operator to access object fields without double quotes and component exports.

obj["app"]
arr[1]

obj.app
local.file.token.content

If you use the [ ] operator to access a member of an object where the member doesn’t exist, the resulting value is null.

If you use the . operator to access a named member of an object where the named member doesn’t exist, an error is generated.

Function calls

Fri, 31 May 2024 15:06:20 +0000

Function calls

You can use River function calls to build richer expressions.

Functions take zero or more arguments as their input and always return a single value as their output. You can’t construct functions. You can call functions from River’s standard library or export them from a component.

If a function fails, the expression isn’t evaluated, and an error is reported.

Standard library functions

River contains a standard library of functions. Some functions enable interaction with the host system, for example, reading from an environment variable. Some functions allow for more complex expressions, for example, concatenating arrays or decoding JSON strings into objects.

env("HOME")
json_decode(local.file.cfg.content)["namespace"]