Reading Alloy configuration on Grafana Labs

Configuration file anatomy

Fri, 14 Aug 2026 09:40:11 -0500

Configuration file anatomy

To read an Alloy configuration, start by recognizing its parts. An Alloy configuration file is made of attributes, expressions, and blocks. These elements describe the settings and behavior that Alloy loads.

Attributes

Attributes are key = value pairs that configure individual settings:

url = "http://localhost:9090"

Here, url is the attribute name. The value on the right side of = comes from an expression.

Expressions

Expressions compute the values that attributes use. An expression can be:

A constant, such as "localhost:9090"
A calculation, such as (1 + 2) * 3
A standard library call, such as sys.env("HOME")

Alloy evaluates an expression before assigning its result to an attribute. There is a fourth kind of expression, a reference to another component’s export, that you trace later in this section.

Blocks

Blocks group related attributes and nested blocks between { and }. Most blocks you read define components. A component block has a name and a label:

local.file "example" {
  filename = "/tmp/example.txt"
}

Here, local.file is the component name, "example" is the label, and filename is an attribute inside the block.

Arguments and exports

Fri, 14 Aug 2026 09:40:11 -0500

Arguments and exports

Every component has two main parts:

Arguments configure the component’s behavior. They are the attributes and nested blocks you write inside the component block.
Exports are values that the running component makes available for other components to reference. You don’t write exports in the configuration; the component type provides them.

A component can have zero or more exports, and optional arguments can have defaults.

Recall the local.file example:

local.file "example" {
  filename = "/tmp/example.txt"
}

Here, filename is an argument that tells local.file which file to read. The local.file component also provides a content export, which holds the latest contents of that file.

Connecting components

When one component uses another component’s export as an argument, that reference connects the two. These connections are how components become the pipelines that collect, process, and send telemetry.

Trace a component reference

Fri, 14 Aug 2026 09:40:11 -0500

Trace a component reference

References are how components connect, so reading one is a core skill. The following example shows how one component’s export supplies another component’s argument. You don’t need to run it.

local.file "example" {
  filename = sys.env("HOME") + "/file.txt"
}

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

    basic_auth {
      username = "admin"
      password = local.file.example.content
    }
  }
}

This example has two components. You already met local.file, which reads a file and exports its contents. prometheus.remote_write sends metrics to a Prometheus-compatible endpoint. Inside it, endpoint and basic_auth are nested argument blocks that group related settings.

Read the source component

Start with the local.file "example" block. You already know the name and label. What’s new here is the filename expression: sys.env("HOME") + "/file.txt" builds the path at runtime.

As before, this component type also provides a content export. That export isn’t written in the block. Other components reference it.

Find and read the reference

Now find where that export is used. The password argument inside basic_auth is set to local.file.example.content. Read that expression from left to right:

local.file identifies the component type.
example identifies the labeled instance.
content identifies the export.

The component type and label together, local.file.example, are the component’s fully qualified name.

The reference means Alloy evaluates local.file.example first, then supplies its content export as the password argument. This single reference creates a dependency: prometheus.remote_write.local_prom depends on local.file.example.

Circular dependencies

Fri, 14 Aug 2026 09:40:11 -0500

Circular dependencies

In the previous slide, a reference created a dependency: prometheus.remote_write.local_prom depended on local.file.example. Alloy uses dependencies like that to decide which components to evaluate first. Because it needs a clear order, those dependencies can’t form a circle.

Invalid examples

A component can’t reference itself:

// Invalid: direct self-reference.
local.file "self_reference" {
  filename = local.file.self_reference.content
}

Components also can’t reference each other in a loop:

// Invalid: circular dependency.
local.file "a" {
  filename = local.file.b.content
}

local.file "b" {
  filename = local.file.a.content
}

Here, a depends on b, while b depends on a. Neither can be evaluated first.

How to spot a loop

When you read component references, follow each dependency in its direction. If following the references brings you back to a component you already visited, the configuration has a circular dependency and is invalid.

Reading Alloy configuration on Grafana Labs

Configuration file anatomy

Configuration file anatomy

Attributes

Expressions

Blocks

Arguments and exports

Arguments and exports

Connecting components

Trace a component reference

Trace a component reference

Read the source component

Find and read the reference

Circular dependencies

Circular dependencies

Invalid examples

How to spot a loop

Resources

Resources

Documentation