Expressions on Grafana Labs

Types and values

Mon, 30 Mar 2026 15:47:22 +0000

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.

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

"Hello, world!"

A \ in a string starts an escape sequence to represent a special character. The following table lists 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 form feed 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 sequences of Unicode characters enclosed in backticks ``. Raw strings don’t support escape sequences.

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

`Hello,
"world"!`

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

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

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

[
  0,
  1,
  2,
]

Objects

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

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

{ name = "John" }

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

{
  "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. Use commas between key-value pairs on separate lines.

A Block is a named structural element composed of multiple attributes. Don’t 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 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").

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

Component exports

Mon, 30 Mar 2026 15:47:22 +0000

Component exports

You learned about expressions and how the component controller evaluates them in the previous topics. Now you’ll learn how to use component references. These are expressions that connect components by referencing their exports.

Component references create the connections that make Alloy pipelines work. When you reference one component’s exports in another component’s arguments, you establish a dependency relationship that the component controller manages automatically.

References can only appear in component arguments or configuration block fields. Components can’t reference themselves.

Use references

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

For example, you can refer to 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 as prometheus.remote_write.onprem.receiver.

The following example demonstrates references:

local.file "target" {
  filename = "/etc/alloy/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 created a pipeline by writing a few Alloy expressions:

The local.file component reads a file and exports its content.
The prometheus.scrape component references that content in its targets field.
The prometheus.scrape component exports a receiver for scraped metrics.
The prometheus.remote_write component receives and forwards those metrics to a remote endpoint.

When the component controller evaluates these components, it:

Evaluates the local.file component first because it has no dependencies.
Evaluates the prometheus.scrape component next, using the file content for its targets.
Evaluates the prometheus.remote_write component last, connecting it to receive metrics.

Each time the file content changes, the component controller automatically reevaluates the prometheus.scrape component with the new target value.

The component controller evaluates component references during the component evaluation process. When you reference another component’s export, the component controller ensures that:

The referenced component is evaluated first.
The reference resolves to the correct export value.
The resolved value’s type is compatible with the target field.

After a reference resolves, the value must match the type of the attribute it’s assigned to. While you can only configure attributes using the basic Alloy types, component exports can use special internal Alloy types, such as Secrets or Capsules, which provide additional functionality.

Next steps

Now that you understand component references, continue learning about expressions:

Types and values - Learn how the type system ensures references work correctly with different data types
Function calls - Use built-in functions to transform values from referenced exports
Operators - Combine referenced values with other expressions using mathematical and logical operators

Operators

Mon, 30 Mar 2026 15:47:22 +0000

Operators

You learned how to reference component exports to connect your pipelines in the previous topic. Now you’ll learn how to use operators to manipulate, transform, and combine values in your expressions.

Operators are essential for creating dynamic configurations that can:

Calculate values: Perform arithmetic operations on component exports and literals.
Compare data: Make decisions based on component states or configuration values.
Combine strings: Build dynamic identifiers, paths, or configuration strings.
Access nested data: Extract values from complex objects and arrays.

The component controller evaluates all operators following 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 a number to the specified power.

String operators

Operator	Description
`+`	Concatenate two strings or two secrets, or a string and a secret.

String concatenation is particularly useful for building dynamic values from component exports:

prometheus.scrape "app" {
  targets = [{ "__address__" = local.file.host.content + ":" + local.file.port.content }]
  job_name = "app-" + sys.env("ENVIRONMENT")
}

Comparison operators

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

You can use the equality operators == and != with any operands.

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

Boolean values are equal if both are either true or false.
Numerical (integer and floating-point) values follow the usual ordering.
String values follow lexical ordering, byte-wise.
Objects are equal if all their fields are equal.
Arrays are equal if their corresponding elements are equal.

Comparison operators are commonly used for conditional configuration:

// Check if environment matches
remote_write_enabled = sys.env("ENVIRONMENT") == "production"

Logical operators

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

Logical operators work with boolean values and return a boolean result.

Assignment operator

The Alloy configuration syntax uses = as the assignment operator.

An assignment statement can 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.

The component controller performs type checking during evaluation to ensure assignments are valid before configuring components.

Brackets

Brackets	Description
`{ }`	Define blocks and objects.
`( )`	Group and prioritize expressions.
`[ ]`	Define arrays.

For example, the following code uses curly braces and square brackets to define an object and an array.

obj = { app = "alloy", 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 use the Alloy access operators to retrieve nested values. Use square brackets to access zero-indexed array elements or object fields by enclosing the field name in double quotes. Use the dot operator to access object fields without double quotes or component exports.

// Access array elements and object fields
obj["app"]
arr[1]

// Access object fields and component exports
obj.app
local.file.token.content
discovery.kubernetes.endpoints.targets[0]["__address__"]

// Build complex expressions with nested access
prometheus.scrape "dynamic" {
  targets = discovery.kubernetes.endpoints.targets
  job_name = discovery.kubernetes.endpoints.targets[0]["job"] + "-scraper"
}

If you use the [ ] operator to access a non-existent object member, the result is null.

If you use the . operator to access a non-existent named member of an object, an error occurs.

Next steps

Now that you understand operators, continue learning about expressions:

Types and values - Learn how the type system works with operators to ensure expressions evaluate correctly
Function calls - Use operators inside function calls and with function return values

For building complete configurations:

Component exports - Combine operators with component references to create dynamic pipelines

Function calls

Mon, 30 Mar 2026 15:47:22 +0000

Function calls

You learned how to use operators to manipulate and combine values in your expressions in the previous topic. Now you’ll learn how to use function calls to transform data, interact with the system, and create more sophisticated dynamic configurations.

Functions are essential building blocks that extend what you can accomplish with expressions:

Transform data: Parse JSON, decode Base64, format strings, and convert between data types.
Access system information: Read environment variables, paths, and system properties.
Process collections: Combine arrays, group data, and extract specific elements.
Enhance component logic: Use functions within component arguments alongside operators and references.

The component controller evaluates function calls as part of expression evaluation, ensuring that function results integrate seamlessly with operators and component references.

How functions work

Functions take zero or more arguments as input and always return a single value as output. The component controller evaluates function calls during expression evaluation, following these steps:

Evaluate arguments: All function arguments are evaluated first, from left to right.
Type checking: The function validates that arguments match expected types.
Execute function: The function performs its operation and returns a result.
Integration: The result becomes available for use with operators or assignment to component attributes.

Alloy provides functions through two sources:

Standard library functions: Built-in functions available in any configuration.
Component exports: Functions exported by components in your configuration.

You can’t create your own functions in Alloy configuration files.

If a function fails during evaluation, Alloy stops processing the expression and reports an error. This fail-fast behavior prevents invalid data from propagating through your configuration and helps you identify issues quickly.

Standard library functions

The Alloy configuration syntax includes a standard library of functions organized into namespaces. These functions fall into several categories:

System functions: Interact with the host system, like reading environment variables.
Encoding functions: Transform data between different formats like JSON and YAML.
String functions: Manipulate and format text values.
Array functions: Work with lists of values and perform collection operations.
Convert functions: Transform data between different types.

Common examples

The following examples show frequently used standard library functions combined with component references and operators:

// System functions - get environment variables
log_level = sys.env("LOG_LEVEL")
data_dir = sys.env("DATA_PATH") + "/metrics"

// Encoding functions - parse configuration data
config_data = encoding.from_json(local.file.config.content)
metrics_config = encoding.from_yaml(local.file.metrics.content)

// Extract and combine values
service_name = config_data["service"]["name"]
full_address = config_data["host"] + ":" + string.format("%d", config_data["port"])

// String functions - format dynamic values
job_name = string.format("%s-%s", service_name, sys.env("ENVIRONMENT"))
log_file = string.join(["/var/log", service_name, "app.log"], "/")

// Array functions - combine target lists
all_targets = array.concat(
  discovery.kubernetes.services.targets,
  discovery.file.local.targets,
  [{ "__address__" = "localhost:9090" }]
)

Component export functions

Components can export functions that other components can call. This creates reusable logic and enables sharing computed values across your configuration.

Component-exported functions work the same way as standard library functions:

Discovery and referencing: Use component references to access exported functions.
Function calls: Call the functions with appropriate arguments.
Result integration: Use function results in expressions with operators and other components.

For example, a custom component might export functions that:

Validate data: Check if configuration values meet specific criteria.
Transform metrics: Convert metric formats or apply mathematical operations.
Generate dynamic values: Create timestamps, UUIDs, or computed identifiers.
Process collections: Filter, sort, or group data for downstream components.

// Example: Using a function exported by a custom component
processed_targets = data_processor.custom.transform_targets(
  discovery.kubernetes.services.targets,
  { "environment" = sys.env("ENV"), "region" = "us-west-2" }
)

// Combine function results with operators and references
final_config = {
  "targets" = processed_targets,
  "labels" = custom_labeler.instance.generate_labels(service_name) + base_labels,
  "enabled" = validator.config.is_valid(processed_targets) && sys.env("MONITORING_ENABLED") == "true"
}

Next steps

Now that you understand function calls, continue learning about expressions:

Types and values - Learn how the type system ensures function arguments and return values work correctly

For building complete configurations:

Component exports - Use function calls with component references to create sophisticated pipelines
Operators - Combine function results with operators for complex expressions

For detailed function reference:

Standard library reference - Complete documentation of all available functions and their usage