Standard library on Grafana Labs

array

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

array

The array namespace contains functions related to arrays.

array.concat

The array.concat function concatenates one or more lists of values into a single list. Each argument to array.concat must be a list value. Elements within the list can be any type.

Examples

> array.concat([])
[]

> array.concat([1, 2], [3, 4])
[1, 2, 3, 4]

> array.concat([1, 2], [], [bool, null])
[1, 2, bool, null]

> array.concat([[1, 2], [3, 4]], [[5, 6]])
[[1, 2], [3, 4], [5, 6]]

array.combine_maps

EXPERIMENTAL: This is an experimental feature. Experimental features are subject to frequent breaking changes, and may be removed with no equivalent replacement. To enable and use an experimental feature, you must set the stability.level flag to experimental.

The array.combine_maps function allows you to join two arrays of maps if certain keys have matching values in both maps. It’s particularly useful when combining labels of targets coming from different prometheus.discovery.* or prometheus.exporter.* components. It takes three arguments:

The first two arguments are a of type list(map(string)). The keys of the map are strings. The value for each key could be of any Alloy type such as a string, integer, map, or a capsule.
The third input is an array containing strings. The strings are the keys whose value has to match for maps to be combined.
(optional) The fourth input is a boolean which defaults to false. When it is set to true, each item from the first argument will be passed through even if there is no match. This is helpful if you want to enrich the first list with attributes from the second list, without losing any of the information from the first list.

The maps that don’t contain all the keys provided in the third argument will be discarded. When maps are combined and both contain the same keys, the last value from the second argument will be used.

Pseudo function code:

for every map in arg1:
  for every map in arg2:
    if the condition key matches in both:
       merge maps and add to result

Examples

> array.combine_maps([{"instance"="1.1.1.1", "team"="A"}], [{"instance"="1.1.1.1", "cluster"="prod"}], ["instance"])
[{"instance"="1.1.1.1", "team"="A", "cluster"="prod"}]

// Second map overrides the team in the first map
> array.combine_maps([{"instance"="1.1.1.1", "team"="A"}], [{"instance"="1.1.1.1", "team"="B"}], ["instance"])
[{"instance"="1.1.1.1", "team"="B"}]

// If multiple maps from the first argument match with multiple maps from the second argument, different combinations will be created.
> array.combine_maps([{"instance"="1.1.1.1", "team"="A"}, {"instance"="1.1.1.1", "team"="B"}], [{"instance"="1.1.1.1", "cluster"="prod"}, {"instance"="1.1.1.1", "cluster"="ops"}], ["instance"])
[{"instance"="1.1.1.1", "team"="A", "cluster"="prod"}, {"instance"="1.1.1.1", "team"="A", "cluster"="ops"}, {"instance"="1.1.1.1", "team"="B", "cluster"="prod"}, {"instance"="1.1.1.1", "team"="B", "cluster"="ops"}]

Examples using discovery and exporter components:

> array.combine_maps(prometheus.exporter.postgres.example.targets, discovery.kubernetes.k8s_pods.targets, ["instance"], true)

> array.combine_maps(prometheus.exporter.redis.default.targets, [{"instance"="1.1.1.1", "testLabelKey" = "testLabelVal"}], ["instance"], true)

In the examples above the fourth argument is set to true so that the original targets from the exporters will still be preserved and scraped even if they cannot be enriched with values from the second argument.

You can find more examples in the tests.

Note
array.combine_maps can be useful for enriching Prometheus service discovery targets prior to a Prometheus scrape. It cannot be used to enrich Prometheus metrics with labels from service discovery components. You can use the [prometheus.enrich][] component for this purpose.

prometheus.enrich

array.group_by

EXPERIMENTAL: This is an experimental feature. Experimental features are subject to frequent breaking changes, and may be removed with no equivalent replacement. To enable and use an experimental feature, you must set the stability.level flag to experimental.

The array.group_by function groups an array of objects by a given key.

The first argument is an array of objects.
The second argument is a string that is the key to group by. The value of the key must be a string and should be present at the top level of the object.
The third argument is a boolean that indicates whether the elements that don’t match the key should be dropped (true) or added to the empty group (false).

Examples

> array.group_by([{"type" = "fruit", "name" = "apple"}, {"type" = "fruit", "name" = "banana"}, {"type" = "vegetable", "name" = "carrot"}, {"name" = "rock"}], "type", false)
[{"type" = "fruit", "items" = [{"type" = "fruit", "name" = "apple"}, {"type" = "fruit", "name" = "banana"}]}, {"type" = "vegetable", "items" = [{"type" = "vegetable", "name" = "carrot"}]}, {"type" = "", "items" = [{"name" = "rock"}]}]

> array.group_by([{"type" = "fruit", "name" = "apple"}, {"type" = "fruit", "name" = "banana"}, {"type" = "vegetable", "name" = "carrot"}, {"name" = "rock"}], "type", true)
[{"type" = "fruit", "items" = [{"type" = "fruit", "name" = "apple"}, {"type" = "fruit", "name" = "banana"}]}, {"type" = "vegetable", "items" = [{"type" = "vegetable", "name" = "carrot"}]}]

The following example shows how to use the array.group_by function with a foreach block to group targets by match labels and create a prometheus.scrape component for each group dynamically. The targets in this example should have a label “match” that contains instant vector selectors separated by slash (refer to Federation for more information on the match parameter).

foreach "federation" {
 collection = array.group_by(discovery.file.example.targets, "match", false)
 var = "each"
 id  = "match"

 template {
   prometheus.scrape "default" {
     targets    = each["items"]
     honor_labels = true
     metrics_path = "/federate"
     params = {
       "match[]" = string.split(coalesce(each["match"], "{__name__!=\"\"}"), "/"),
     }
     forward_to = [prometheus.remote_write.default.receiver]
   }
 }
}

coalesce

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

coalesce

coalesce takes any number of arguments and returns the first one that isn’t null, an empty string, empty list, or an empty object. It’s useful for obtaining a default value, such as if an environment variable isn’t defined. If no argument is non-empty or non-zero, the last argument is returned.

Examples

> coalesce("a", "b")
a
> coalesce("", "b")
b
> coalesce(sys.env("DOES_NOT_EXIST"), "c")
c

constants

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

constants

The constants object exposes a list of constant values about the system Alloy is running on:

constants.hostname: The hostname of the machine Alloy is running on.
constants.os: The operating system Alloy is running on.
constants.arch: The architecture of the system Alloy is running on.
constants.version : The version of the Alloy instance if the binary was built with the version information, otherwise it’s an empty string.

Examples

> constants.hostname
"my-hostname"

> constants.os
"linux"

> constants.arch
"amd64"

convert

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

convert

The convert namespace contains conversion functions.

nonsensitive

convert.nonsensitive converts a secret value back into a string.

Warning
Only use convert.nonsensitive when you are positive that the value converted back to a string isn’t a sensitive value.

Strings resulting from calls to convert.nonsensitive are displayed in plain text in the UI and internal API calls.

Examples

// Assuming `sensitive_value` is a secret:

> sensitive_value
(secret)
> convert.nonsensitive(sensitive_value)
"Hello, world!"

encoding

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

encoding

The encoding namespace contains encoding and decoding functions.

encoding.from_base64

The encoding.from_base64 function decodes a RFC4648-compliant Base64-encoded string into the original string.

encoding.from_base64 fails if the provided string argument contains invalid Base64 data.

Example

> encoding.from_base64("dGFuZ2VyaW5l")
tangerine

encoding.from_URLbase64

The encoding.from_URLbase64 function decodes a RFC4648-compliant Base64 URL safe encoded string into the original string.

encoding.from_URLbase64 fails if the provided string argument contains invalid Base64 data.

Example

> encoding.from_URLbase64("c3RyaW5nMTIzIT8kKiYoKSctPUB-")
string123!?$*&()'-=@~

encoding.to_base64

The encoding.to_base64 function encodes the original string into RFC4648-compliant Base64 encoded string.

Example

> encoding.to_base64("string123!?$*&()'-=@~")
c3RyaW5nMTIzIT8kKiYoKSctPUB+

encoding.to_URLbase64

The encoding.to_base64 function encodes the original string into RFC4648-compliant URL safe Base64 encoded string.

Example

> encoding.to_URLbase64("string123!?$*&()'-=@~")
c3RyaW5nMTIzIT8kKiYoKSctPUB-

encoding.url_encode

The encoding.url_encode function encodes the original string into a RFC3986 “percent encoding” compliant string.

Example

> encoding.url_encode("string123!?$*&()'-=@~")
string123%21%3F%24%2A%26%28%29%27-%3D%40~

encoding.url_decode

The encoding.url_decode function decodes a RFC3986 “percent encoding” compliant string. encoding.url_decode fails if input string is not RFC3986 “percent encoding” compliant.

Example

> encoding.url_decode("string123%21%3F%24%2A%26%28%29%27-%3D%40~")
string123!?$*&()'-=@~

encoding.to_json

The encoding.to_json function encodes the map into a JSON string. encoding.to_json fails if the input argument provided can’t be parsed as a JSON string.

A common use case for encoding.to_json is to encode a configuration of component which is expected to be a JSON string. For example, config argument of prometheus.exporter.blackbox.

Examples

> encoding.to_json({"modules"={"http_2xx"={"prober"="http","timeout"="5s","http"={"headers"={"Authorization"=sys.env("TEST_VAR")}}}}})
"{\"modules\":{\"http_2xx\":{\"http\":{\"headers\":{\"Authorization\":\"Hello!\"}},\"prober\":\"http\",\"timeout\":\"5s\"}}}"

encoding.from_json

The encoding.from_json function decodes a string representing JSON into an Alloy value. encoding.from_json fails if the string argument provided can’t be parsed as JSON.

A common use case of encoding.from_json is to decode the output of a local.file component to an Alloy value.

Note
Remember to escape double quotes when passing JSON string literals to encoding.from_json.

For example, the JSON value {"key": "value"} is properly represented by the string "{\"key\": \"value\"}".

Examples

> encoding.from_json("15")
15

> encoding.from_json("[1, 2, 3]")
[1, 2, 3]

> encoding.from_json("null")
null

> encoding.from_json("{\"key\": \"value\"}")
{
  key = "value",
}

> encoding.from_json(local.file.some_file.content)
"Hello, world!"

encoding.from_yaml

The encoding.from_yaml function decodes a string representing YAML into an Alloy value. encoding.from_yaml fails if the string argument provided can’t be parsed as YAML.

A common use case of encoding.from_yaml is to decode the output of a local.file component to an Alloy value.

Note
Remember to escape double quotes when passing YAML string literals to encoding.from_yaml.

For example, the YAML value key: "value" is properly represented by the string "key: \"value\"".

Examples

> encoding.from_yaml("15")
15
> encoding.from_yaml("[1, 2, 3]")
[1, 2, 3]
> encoding.from_yaml("null")
null
> encoding.from_yaml("key: value")
{
  key = "value",
}
> encoding.from_yaml(local.file.some_file.content)
"Hello, world!"

file

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

file

The file namespace contains functions related to files.

file.path_join

The file.path_join function joins any number of path elements into a single path, separating them with an OS-specific separator.

Examples

> file.path_join()
""

> file.path_join("this/is", "a/path")
"this/is/a/path"

json_path

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

json_path

The json_path function lookup values using jsonpath syntax.

The function expects two strings. The first string is the JSON string used look up values. The second string is the JSONPath expression.

json_path always returns a list of values. If the JSONPath expression doesn’t match any values, an empty list is returned.

A common use case of json_path is to decode and filter the output of a local.file or remote.http component to an Alloy syntax value.

Remember to escape double quotes when passing JSON string literals to json_path.

For example, the JSON value {"key": "value"} is properly represented by the string "{\"key\": \"value\"}".

Examples

> json_path("{\"key\": \"value\"}", ".key")
["value"]


> json_path("[{\"name\": \"Department\",\"value\": \"IT\"},{\"name\":\"TestStatus\",\"value\":\"Pending\"}]", "[?(@.name == \"Department\")].value")
["IT"]

> json_path("{\"key\": \"value\"}", ".nonexists")
[]

> json_path("{\"key\": \"value\"}", ".key")[0]
value

string

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

string

The string namespace contains functions related to strings.

string.format

The string.format function produces a string by formatting a number of other values according to a specification string. It’s similar to the printf function in C, and other similar functions in other programming languages.

string.format(spec, values...)

Examples

> string.format("Hello, %s!", "Ander")
"Hello, Ander!"
> string.format("There are %d lights", 4)
"There are 4 lights"

The string.format function is most useful when you use more complex format specifications.

Specification Syntax

The specification is a string that includes formatting verbs that are introduced with the % character. The function call must then have one additional argument for each verb sequence in the specification. The verbs are matched with consecutive arguments and formatted as directed, as long as each given argument is convertible to the type required by the format verb.

By default, % sequences consume successive arguments starting with the first. Introducing a [n] sequence immediately before the verb letter, where n is a decimal integer, explicitly chooses a particular value argument by its one-based index. Subsequent calls without an explicit index will then proceed with n+1, n+2, etc.

The function produces an error if the format string requests an impossible conversion or accesses more arguments than are given. An error is also produced for an unsupported format verb.

Verbs

The specification may contain the following verbs.

Verb	Result
`%%`	Literal percent sign, consuming no value.
`%t`	Convert to boolean and produce `true` or `false`.
`%b`	Convert to integer number and produce binary representation.
`%d`	Convert to integer and produce decimal representation.
`%o`	Convert to integer and produce octal representation.
`%x`	Convert to integer and produce hexadecimal representation with lowercase letters.
`%X`	Like `%x`, but use uppercase letters.
`%e`	Convert to number and produce scientific notation, like `-1.234456e+78`.
`%E`	Like `%e`, but use an uppercase `E` to introduce the exponent.
`%f`	Convert to number and produce decimal fraction notation with no exponent, like `123.456`.
`%g`	Like `%e` for large exponents or like `%f` otherwise.
`%G`	Like `%E` for large exponents or like `%f` otherwise.
`%s`	Convert to string and insert the string’s characters.
`%q`	Convert to string and produce a JSON quoted string representation.

When using the string.format function with a secret value, you must first convert it to a non-sensitive string using the convert.nonsensitive function. If the resulting value must be a secret, you can use string concatenation with the + operator instead of the string.format function.

string.join

string.join all items in an array into a string, using a character as separator.

string.join(list, separator)

Examples

> string.join(["foo", "bar", "baz"], "-")
"foo-bar-baz"
> string.join(["foo", "bar", "baz"], ", ")
"foo, bar, baz"
> string.join(["foo"], ", ")
"foo"

string.replace

string.replace searches a string for a substring, and replaces each occurrence of the substring with a replacement string.

string.replace(string, substring, replacement)

Examples

> string.replace("1 + 2 + 3", "+", "-")
"1 - 2 - 3"

string.split

string.split produces a list by dividing a string at all occurrences of a separator.

split(list, separator)

Examples

> string.split("foo,bar,baz", "," )
["foo", "bar", "baz"]

> string.split("foo", ",")
["foo"]

> string.split("", ",")
[""]

string.to_lower

string.to_lower converts all uppercase letters in a string to lowercase.

Examples

> string.to_lower("HELLO")
"hello"

string.to_upper

string.to_upper converts all lowercase letters in a string to uppercase.

Examples

> string.to_upper("hello")
"HELLO"

string.trim

string.trim removes the specified set of characters from the start and end of a string.

string.trim(string, str_character_set)

Examples

> string.trim("?!hello?!", "!?")
"hello"

> string.trim("foobar", "far")
"oob"

> string.trim("   hello! world.!  ", "! ")
"hello! world."

string.trim_prefix

string.trim_prefix removes the prefix from the start of a string. If the string doesn’t start with the prefix, the string is returned unchanged.

Examples

> string.trim_prefix("helloworld", "hello")
"world"

string.trim_suffix

string.trim_suffix removes the suffix from the end of a string.

Examples

> string.trim_suffix("helloworld", "world")
"hello"

string.trim_space

string.trim_space removes any whitespace characters from the start and end of a string.

Examples

> string.trim_space("  hello\n\n")
"hello"

sys

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

sys

The sys namespace contains functions related to the system.

sys.env

The sys.env function gets the value of an environment variable from the system Alloy is running on. If the environment variable doesn’t exist, sys.env returns an empty string.

Examples

> sys.env("HOME")
"/home/alloy"

> sys.env("DOES_NOT_EXIST")
""