Documentation Grafana Alloy Get started Configuration syntax Expressions Types and values

Types and values

The Alloy syntax 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 sys.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 "100ms", "1h30m", "10s". Valid units are:

  • 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

The Alloy syntax handles integers, unsigned integers, and floating-point values as a single ’number’ type, simplifying writing and reading Alloy configuration files.

alloy Copy

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 "".

alloy Copy

"Hello, world!"

A \ in a string starts an escape sequence to represent a special character. The following table shows the supported escape sequences.

Raw strings

Raw strings are represented by sequences of Unicode characters surrounded by backticks ``. Raw strings don’t support any escape sequences.

alloy Copy

`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.

alloy Copy

`Hello,
"world"!`

The preceding multiline raw string is interpreted as a string with the following value.

string Copy

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 [].

alloy Copy

[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.

alloy Copy

[
  0,
  1,
  2,
]

Objects

You construct objects with a sequence of comma-separated key-value pairs surrounded by curly braces {}.

alloy Copy

{
  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.

alloy Copy

{ name = "John" }

If the key isn’t a valid identifier, you must wrap it in double quotes like a string.

alloy Copy

{
  "app.kubernetes.io/name"     = "mysql",
  "app.kubernetes.io/instance" = "mysql-abcxyz",
  namespace                    = "default",
}

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 Alloy. 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").

alloy Copy

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

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