This is documentation for the next version of Grafana Alloy Documentation. For the latest stable release, go to the latest version.

Documentation Grafana Alloy Get started Expressions Types and values

Types and values

You learned about the main types of expressions in the previous section. These are literals, component references, functions, and arithmetic operations. Now you’ll learn about the types and values that these expressions work with and how Alloy uses them to ensure your configurations work correctly.

Understanding types helps you write expressions that work reliably and helps you understand why certain combinations of components and values are compatible while others aren’t.

Value types

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.

Names and naming conventions

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.

text 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 +.

Alloy interprets a multiline raw string exactly as written.

Alloy Copy

`Hello,
"world"!`

Alloy interprets the preceding multiline raw string as a string with the following value.

string Copy

Hello,
"world"!

Boolean values

The symbols true and false represent boolean values.

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 symbol null represents the null value.

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 appears 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. Components that use or export capsules document the specific capsule type they expect.

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

Next steps

Now that you understand types and values, learn how to use them in expressions:

• Component exports - Reference data from other components and understand how types ensure compatibility
• Operators - Learn how operators work with different value types and handle type compatibility

For advanced expression features:

• Function calls - Transform data using standard library functions that work with these types