Documentation Grafana Cloud Instrument and send data Grafana Alloy Get started Configuration syntax Expressions Types and values

Types and values

The Alloy syntax supports the following value types:

• number: Any numeric value, such as 3 or 3.14.
• string: A sequence of Unicode characters representing text, such as "Hello, world!".
• bool: A boolean value, either true or false.
• array: A sequence of values, such as [1, 2, 3]. Index array elements using whole numbers starting from zero.
• object: A group of values identified by named labels, such as { name = "John" }.
• function: A value representing a routine that runs with arguments to compute another value, such as sys.env("HOME"). Functions take zero or more arguments as input and always return a single value as output.
• null: A type that represents 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 where all values are of type T. For example, map(string) is an object where all values are strings. The key type of an object is always a string or an identifier converted into a string.

• list(T): An array where all values are of type T. For example, list(string) is an array where all values are strings.

• duration: A string that denotes a duration of time, such as "100ms", "1h30m", or "10s". Valid units include:

  • 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 equivalent to "90m".

Numbers

The Alloy syntax treats integers, unsigned integers, and floating-point values as a single number type. This simplifies 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 sequences of Unicode characters enclosed in double quotes "".

alloy Copy

"Hello, world!"

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

Raw strings

Raw strings are sequences of Unicode characters enclosed in backticks ``. Raw strings don’t support escape sequences.

alloy Copy

`Hello, "world"!`

Within backticks, any character can appear except a backtick. Include a backtick by concatenating a double-quoted string containing 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

Construct arrays using a sequence of comma-separated values enclosed in square brackets [].

alloy Copy

[0, 1, 2, 3]

You can place values on separate lines for readability. Include a comma after the final value if the closing bracket ] is on a different line.

alloy Copy

[
  0,
  1,
  2,
]

Objects

Construct objects using a sequence of comma-separated key-value pairs enclosed in curly braces {}.

alloy Copy

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

Include a comma after the final key-value pair if the closing curly brace } is on a different line.

alloy Copy

{ name = "John" }

Wrap keys in double quotes if they aren’t valid identifiers.

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 not the inverse. You can use convert.nonsensitive to convert a secret to a string. You can’t 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 as capsule("<SOME_INTERNAL_NAME>"). You can’t construct capsule values. Use capsules in expressions like any other type. Capsules aren’t inter-compatible. An attribute expecting a capsule can only accept 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 capsule type expected is 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]
}