Get started with Grafana Alloy on Grafana Labs

Components

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

Components

Components are the building blocks of Alloy. Each component performs a single task, such as retrieving secrets, collecting metrics, or processing data.

You learned about blocks, attributes, and expressions in the previous section. Components use the same syntax structure. They’re special blocks that Alloy knows how to execute. When you define a component block in your configuration, Alloy creates a running instance that performs the component’s specific task.

Components are the key to the flexibility of Alloy. You can combine them to create data pipelines that collect, transform, and send telemetry data exactly how you need.

Component structure

Every component has two main parts:

Arguments: Settings that configure the component’s behavior. These are the attributes and blocks you define inside the component block.
Exports: Values that the component makes available to other components. The running component generates these exports and they can change over time.

When Alloy loads your configuration:

It reads the arguments you provided in each component block.
It creates a running instance of the component with those arguments.
The component starts its work and may update its exports as it runs.
Other components can reference these exports in their arguments.

Component syntax

Components use the block syntax you learned about earlier. The general pattern is:

COMPONENT_NAME "LABEL" {
  // Arguments (attributes and nested blocks)
  attribute_name = "value"

  nested_block {
    setting = "value"
  }
}

The COMPONENT_NAME tells Alloy which type of component to create. The "LABEL" is a unique identifier you choose to distinguish between multiple instances of the same component type.

Component names

Each component has a name that describes its purpose. For example:

local.file retrieves file contents from disk.
prometheus.scrape collects Prometheus metrics.
loki.write sends log data to Loki.

You define components by specifying the component name with a user-defined label:

local.file "my_config" {
  filename = "/etc/app/config.yaml"
}

prometheus.scrape "api_metrics" {
  targets = [{"__address__" = "localhost:8080"}]
  forward_to = [prometheus.remote_write.default.receiver]
}

Component references

You reference components by combining their name with their label. For example, you can reference the local.file component labeled my_config as local.file.my_config.

The combination of component name and label must be unique in your configuration. This allows you to define multiple instances of the same component type:

prometheus.scrape "api" {
  targets = [{"__address__" = "api.example.com:8080"}]
  forward_to = [prometheus.remote_write.production.receiver]
}

prometheus.scrape "database" {
  targets = [{"__address__" = "db.example.com:9090"}]
  forward_to = [prometheus.remote_write.production.receiver]
}

Component exports

Components can share data through exports. When one component references another component’s export, it creates a connection between them. You’ll learn more about these component references in Expressions.

local.file "api_key" {
  filename = "/etc/secrets/api.key"
}

prometheus.remote_write "production" {
  endpoint {
    url = "https://prometheus.example.com/api/v1/write"

    basic_auth {
      username = "metrics"
      password = local.file.api_key.content  // Reference the file content
    }
  }
}

In this example:

The local.file component reads a file and exports its content.
The prometheus.remote_write component uses that content as a password.
When the file changes, Alloy automatically updates the local.file component’s exports.
This causes Alloy to re-evaluate the prometheus.remote_write component with the new password.

You’ll learn the details of how to write these references in Expressions.

Next steps

Now that you understand what components are and how they work, learn how to use them effectively:

Configure components - Learn how to define and configure components with arguments and blocks
Build data pipelines - Connect components together to create data processing workflows
Component controller - Understand how Alloy manages components at runtime

To extend component functionality:

Custom components - Create reusable custom components for your specific needs
Community components - Use components shared by the Alloy community

For hands-on learning:

Tutorials - Build complete data collection pipelines step by step

For reference:

Expressions - Use component exports in dynamic configurations
Alloy syntax - Explore advanced syntax features and patterns
Component reference - Browse all available components and their options

Expressions

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

Expressions

You learned about components and how they work together in pipelines in the previous sections. Now you’ll learn about expressions. These are the mechanism that makes your configurations dynamic by computing values and connecting components together.

Expressions are the key to Alloy’s flexibility. They let you reference data from other components, transform values using functions, and create dynamic configurations that respond to changing conditions.

How expressions work

Expressions compute values that you assign to component arguments. The component controller evaluates expressions when components start and whenever their dependencies change.

Basic expressions are literal values like "Hello, world!" or true. More powerful expressions can reference component exports, call functions, or perform calculations.

All component arguments have an underlying type. Alloy checks the expression type during evaluation to ensure compatibility before assigning the result to an attribute. This type checking prevents configuration errors and ensures your pipelines work correctly.

Expression types

The four main types of expressions you’ll use are:

Literal values: Constants like "debug", 8080, or true.
Component references: Values from other components like local.file.config.content.
Function calls: Built-in functions like sys.env("HOME") or encoding.from_json(local.file.data.content).
Arithmetic operations: Mathematical calculations like 1 + 2 or port_base + offset.

You can combine these types to create complex expressions that transform data and connect components in sophisticated ways.

Next steps

Now that you understand how expressions work, learn to write different types of expressions:

Component exports - Reference data from other components to connect your pipeline
Types and values - Understand data types and how they work with expressions

For advanced expression features:

Function calls - Transform and compute values using built-in functions
Operators - Combine and manipulate values using mathematical and logical operators

Alloy syntax

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

Alloy syntax

You learned about components, expressions, and basic configuration elements in the previous sections. Now you’ll learn the detailed syntax rules that govern how to write Alloy configuration files.

Understanding the syntax ensures your configurations are:

Correctly parsed: Follow rules that the Alloy parser expects.
Maintainable: Use consistent patterns and formatting.
Readable: Structure code clearly for yourself and your team.
Error-free: Avoid common syntax mistakes that prevent successful evaluation.

The Alloy configuration syntax is declarative, meaning you describe what you want rather than how to achieve it. The parser evaluates all dependencies between elements automatically, so the order of blocks and attributes doesn’t matter.

Comments

Alloy configuration files support single-line // comments and block /* */ comments.

// This is a single-line comment

/*
This is a block comment
that can span multiple lines
*/

Identifiers

An identifier in Alloy syntax is valid if it contains one or more UTF-8 letters, digits, or underscores. Identifiers can’t start with a digit.

The parser uses identifiers for:

Attribute names: Keys in key-value pairs.
Component names: Parts of block names like prometheus in prometheus.scrape.
Component labels: User-defined names to distinguish component instances.
Variable references: Names used in expressions and function calls.

Valid identifiers:

my_component
Component123
_private
métrica_café (Unicode letters are supported)

Invalid identifiers:

123component (starts with digit)
my-component (contains hyphen)
my component (contains space)
my.component (contains dot, which has special meaning)

Attributes and Blocks

Alloy configurations are built using two main syntax elements: attributes and blocks. Attributes set individual values, while blocks group related configuration and create component instances.

Attributes

Attributes configure individual settings using the format ATTRIBUTE_NAME = ATTRIBUTE_VALUE. The parser evaluates attributes during component configuration to determine runtime behavior.

You can place attributes as:

Top-level settings: Global Alloy configuration.
Component arguments: Settings within component blocks.
Nested block settings: Configuration within nested blocks.

Examples of different attribute contexts:

// Top-level attribute
log_level = "debug"

// Component block with attributes
prometheus.scrape "app" {
  targets    = [{ "__address__" = "localhost:9090" }]
  scrape_interval = "15s"

  // Nested block with attributes
  basic_auth {
    username = "admin"
    password = sys.env("ADMIN_PASSWORD")
  }
}

The ATTRIBUTE_NAME must be a valid Alloy identifier.

The ATTRIBUTE_VALUE can be:

Constant values: Strings, numbers, booleans, arrays, or objects.
Expressions: Function calls, component references, or calculations that compute dynamic values.

Blocks

Blocks configure Alloy components and organize related settings using curly braces. The parser processes blocks to create and configure component instances.

Block structure:

Block name: Identifies the component type (required).
Block label: User-defined identifier to distinguish multiple instances (optional).
Block body: Contains attributes and nested blocks (required).

Some blocks can appear multiple times in your configuration when they have different labels:

// Multiple instances of the same component type
prometheus.scrape "frontend" {
  targets = [{ "__address__" = "frontend:8080" }]
}

prometheus.scrape "backend" {
  targets = [{ "__address__" = "backend:9090" }]
}

Nested blocks provide structured configuration:

prometheus.remote_write "production" {
  endpoint {
    url = "https://prometheus.example.com/api/v1/write"

    basic_auth {
      username = "metrics"
      password = local.file.credentials.content
    }
  }

  queue_config {
    capacity = 10000
    max_samples_per_send = 2000
  }
}

Examples

Use the following pattern to create an unlabeled block.

BLOCK_NAME {
  // Block body can contain attributes and nested unlabeled blocks
  IDENTIFIER = EXPRESSION // Attribute

  NESTED_BLOCK_NAME {
    // Nested block body
  }
}

Use the following pattern to create a labeled block.

// Pattern for creating a labeled block:
BLOCK_NAME "BLOCK_LABEL" {
  // Block body can contain attributes and nested unlabeled blocks
  IDENTIFIER = EXPRESSION // Attribute

  NESTED_BLOCK_NAME {
    // Nested block body
  }
}

Block naming rules

The parser enforces specific rules for block names and labels:

Block names must be either:

Valid component names: Dot-separated identifiers like prometheus.scrape or local.file.
Special configuration blocks: Built-in blocks for global settings like logging or tracing.

Block labels (when required) must be:

Valid identifiers: Follow the same rules as attribute names.
Double-quoted strings: Wrapped in double quotes, not single quotes.
Unique within scope: No two blocks of the same type can have identical labels.

Example showing proper block naming:

// Component name: "local.file", Label: "api_key"
local.file "api_key" {
  filename  = sys.env("API_KEY_PATH")
  is_secret = true
}

// Component name: "prometheus.scrape", Label: "web_servers"
prometheus.scrape "web_servers" {
  targets = discovery.kubernetes.services.targets
  metrics_path = "/metrics"
}

The parser validates that:

Component names exist: The component type must be available in Alloy.
Labels are unique: Within the same component type.
Syntax is correct: Follows the identifier and quoting rules.

Terminators

The parser requires terminators to separate statements and determine where expressions end. All block and attribute definitions must end with a newline, which Alloy calls a terminator.

A newline acts as a terminator when it follows:

Complete expressions: After any value, calculation, or function call.
Closing delimiters: After ], ), or }.
Statement endings: After attribute assignments or block definitions.

The parser ignores newlines in other contexts, allowing flexible formatting:

// This formatting is valid - extra newlines are ignored
local.file "example" {
  filename = "/path/to/file"


  is_secret = true


  // Comments can also have extra spacing
}

// Expressions can span multiple lines
targets = [
  { "__address__" = "server1:9090" },
  { "__address__" = "server2:9090" },
  { "__address__" = "server3:9090" }
]

Formatting

Alloy provides a built-in formatter to ensure consistent code style. Use the alloy fmt command to format your configuration files.

The formatter:

Standardizes indentation
Removes unnecessary whitespace
Ensures consistent line endings
Validates syntax

Next steps

Now that you understand the syntax fundamentals, learn how to use these elements to build working configurations:

Components - Learn about the building blocks that collect, transform, and send data
Expressions - Create dynamic configurations using functions and component references

For advanced configuration techniques:

Formatting - Use alloy fmt to automatically format your configuration files

Modules

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

Modules

You learned about components, expressions, and the configuration syntax in the previous sections. Now you’ll learn about modules, the organizational structure that lets you package and reuse Alloy configurations.

Modules enable powerful configuration management capabilities:

Code reuse: Package common pipeline patterns into reusable custom components.
Organization: Structure complex configurations into maintainable units.
Sharing: Distribute configurations across teams and projects.
Composition: Combine multiple modules to build sophisticated data collection systems.

Note
Most Alloy users don’t need modules when they first get started. You can collect, process, and export metrics, logs, traces, and profiles using built-in components directly in your configuration. Modules don’t add capabilities to Alloy or enable signal types, they’re purely a way to organize and reuse configuration. Think of a module as a function in programming: it packages logic you already have so you can reuse it cleanly.

If you’re just getting started, you can skip modules for now and return to them when your configuration grows or you need reuse. However, if you plan to use Fleet Management to manage multiple collectors, understanding modules helps you create reusable configurations that can be distributed across your fleet.

A module is a unit of Alloy configuration that contains components, custom component definitions, and import statements. The module you pass to the run command becomes the main configuration that Alloy executes.

You can import modules to reuse custom components defined by that module.

When to use a module

Create a module when you want to:

Reuse the same pipeline pattern multiple times
Reduce duplicated configuration
Hide complex pipelines behind a single interface
Standardize pipelines across teams or environments
Make large Alloy configurations easier to maintain

If your configuration is small and each pipeline is unique, you probably don’t need a module. If you find yourself copying and pasting the same group of components with small changes, a module can help.

Why modules help

Without modules, repeated pipelines can look like this:

otelcol.receiver.otlp "app1" { ... }
otelcol.processor.batch "app1" { ... }
otelcol.exporter.otlp "app1" { ... }

otelcol.receiver.otlp "app2" { ... }
otelcol.processor.batch "app2" { ... }
otelcol.exporter.otlp "app2" { ... }

With a module, you define the pipeline once and reuse it:

import.file "pipeline" {
  filename = "pipeline.alloy"
}

pipeline.app "app1" { ... }
pipeline.app "app2" { ... }

This reduces duplication, improves readability, and makes updates safer because you only change the logic in one place.

Example

This example demonstrates how modules integrate with the component and expression concepts you learned earlier. The module defines a reusable log filtering component that showcases:

Custom component definition: Using declare to create reusable logic.
Arguments: Accepting configuration from component users.
Exports: Exposing values for other components to reference.
Internal pipeline: Using built-in components within the custom component.

Module definition helpers.alloy:

declare "log_filter" {
  // argument.write_to is a required argument that specifies where filtered
  // log lines are sent.
  //
  // The value of the argument is retrieved in this file with
  // argument.write_to.value.
  argument "write_to" {
    optional = false
  }

  // loki.process.filter is our component which executes the filtering,
  // passing filtered logs to argument.write_to.value.
  loki.process "filter" {
    // Drop all debug- and info-level logs.
    stage.match {
      selector = `{job!=""} |~ "level=(debug|info)"`
      action   = "drop"
    }

    // Send processed logs to our argument.
    forward_to = argument.write_to.value
  }

  // export.filter_input exports a value to the module consumer.
  export "filter_input" {
    // Expose the receiver of loki.process so the module importer can send
    // logs to our loki.process component.
    value = loki.process.filter.receiver
  }
}

Use the module main.alloy:

// Import our helpers.alloy module, exposing its custom components as
// helpers.COMPONENT_NAME.
import.file "helpers" {
  filename = "helpers.alloy"
}

loki.source.file "self" {
  targets = LOG_TARGETS

  // Forward collected logs to the input of our filter.
  forward_to = [helpers.log_filter.default.filter_input]
}

helpers.log_filter "default" {
  // Configure the filter to forward filtered logs to loki.write below.
  write_to = [loki.write.default.receiver]
}

loki.write "default" {
  endpoint {
    url = LOKI_URL
  }
}

This example shows how:

Modules encapsulate logic: The filtering logic is contained within the module.
Arguments provide flexibility: The write_to argument lets users specify where filtered logs go.
Exports enable connections: The filter_input export allows other components to send data to the filter.
Component references work across modules: The main configuration references exports from the imported module using helpers.log_filter.default.filter_input.

Import modules

To use modules in your configuration, you import them using one of the import configuration blocks. The component controller processes import statements during configuration loading to make custom components available in the importing module’s namespace.

import.file: Imports a module from a file on disk.
import.git: Imports a module from a file in a Git repository.
import.http: Imports a module from an HTTP request response.
import.string: Imports a module from a string.

Warning
You can’t import a module that contains top-level blocks other than declare or import.

You import modules into a namespace. This exposes the top-level custom components of the imported module to the importing module. The label of the import block specifies the namespace of an import.

For example, if a configuration contains a block called import.file "my_module", then custom components defined by that module appear as my_module.CUSTOM_COMPONENT_NAME. Namespaces for imports must be unique within a given importing module.

Warning
If you use a label for an import or declare block that matches a built-in component namespace, such as prometheus or mimir, the built-in namespace becomes shadowed and unavailable in your configuration. For example, if you use the label import.file "mimir", you can’t use components starting with mimir, such as mimir.rules.kubernetes, because the label refers to the imported module.

Security

Since modules can load arbitrary configurations from potentially remote sources, you must carefully consider the security implications. The component controller executes all module content with the same privileges as the main Alloy process.

Best practices for secure module usage:

Protect main configuration: Ensure attackers can’t modify the Alloy configuration files.
Secure remote sources: Protect modules fetched from remote locations, such as Git repositories or HTTP servers.
Validate module content: Review imported modules for malicious or unintended behavior.
Use authentication: When fetching modules over HTTP or Git, use appropriate authentication mechanisms.
Network security: Restrict network access for Alloy processes that load remote modules.
File permissions: Set appropriate file system permissions for module files and directories.

Next steps

To learn more about modules, explore these resources:

Custom components - Learn how to create reusable components that you can package in modules
Component configuration - Understand how built-in components work within module contexts
Import configuration blocks - Detailed reference for different module import methods
Run command reference - Module configuration and execution options

Clustering

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

Clustering

You learned about components, expressions, syntax, and modules in the previous sections. Now you’ll learn about clustering, which allows multiple Alloy deployments to work together for distributed data collection.

Clustering provides workload distribution and high availability. It enables horizontally scalable deployments with minimal resource and operational overhead.

Alloy uses an eventually consistent model with a gossip protocol to achieve clustering. This model assumes all participating Alloy deployments are interchangeable and use identical configurations. The cluster uses a consistent hashing algorithm to distribute work among nodes.

A standalone, non-clustered Alloy behaves the same as a single-node cluster.

You configure clustering by passing --cluster.* command-line flags to the alloy run command. Cluster-enabled components must explicitly enable clustering through a clustering block in their configuration.

Use cases

Clustering serves several purposes in Alloy deployments, with the primary focus being workload distribution and scalability.

Target auto-distribution

Target auto-distribution is the most common use case of clustering. It lets scraping components running on all peers distribute the scrape load among themselves.

For target auto-distribution to work:

All Alloy deployments in the same cluster must access the same service discovery APIs.
All deployments must scrape the same targets.

You must explicitly enable target auto-distribution on components by defining a clustering block. This integrates with the component system you learned about in previous sections:

prometheus.scrape "default" {
    targets = discovery.kubernetes.pods.targets

    clustering {
        enabled = true
    }

    forward_to = [prometheus.remote_write.default.receiver]
}

prometheus.remote_write "default" {
    endpoint {
        url = "https://prometheus.example.com/api/v1/write"
    }
}

When a cluster detects state changes (when a node joins or leaves), all participating components locally recalculate target ownership using a consistent hashing algorithm. Components re-balance the targets they’re scraping without explicitly communicating ownership over the network. Each node uses 512 tokens in the hash ring for optimal load distribution.

Target auto-distribution lets you dynamically scale the number of Alloy deployments to handle workload peaks. It also provides resiliency because remaining node peers automatically pick up targets if a node leaves the cluster.

Alloy uses a local consistent hashing algorithm to distribute targets. When the cluster size changes, this algorithm redistributes only approximately 1/N of the targets, minimizing disruption.

Refer to the component reference documentation to check if a component supports clustering, such as:

Best practices

Follow these guidelines to ensure effective clustering in your Alloy deployments.

Avoid issues with disproportionately large targets

When your environment has a mix of very large and average-sized targets, avoid running too many cluster instances. While clustering generally does a good job of sharding targets to achieve balanced workload distribution, significant target size disparity can lead to uneven load distribution. When you have a few disproportionately large targets among many instances, the nodes assigned these large targets experience much higher load compared to others, for example samples per second for Prometheus metrics, potentially causing uneven load balancing or hitting resource limitations. In these scenarios, it’s often better to scale vertically rather than horizontally to reduce the impact of outlier large targets. This approach ensures more consistent resource utilization across your deployment and prevents overloading specific instances.

Use `--cluster.wait-for-size`, but with caution

When you use clustering in a deployment where a single instance can’t handle the entire load, use the --cluster.wait-for-size flag to ensure a minimum cluster size before accepting traffic. However, leave a significant safety margin when you configure this value by setting it significantly smaller than your typical expected operational number of instances. When this condition isn’t met, the instances stop processing traffic in cluster-enabled components, so it’s important to leave room for any unexpected events.

For example, if you’re using Horizontal Pod Autoscalers (HPA) or PodDisruptionBudgets (PDB) in Kubernetes, set the --cluster.wait-for-size flag to a value well below what your HPA and PDB minimums allow. This prevents traffic from stopping when Kubernetes instance counts temporarily drop below these thresholds during normal operations like Pod termination or rolling updates.

It’s recommended to use the --cluster.wait-timeout flag to set a reasonable timeout for the waiting period to limit the impact of potential misconfiguration. You can base the timeout duration on how quickly you expect your orchestration or incident response team to provision the required number of instances. Be aware that when the timeout passes, the cluster may be too small to handle traffic and can run into further issues.

Don’t enable clustering if you don’t need it

While clustering scales to very large numbers of instances, it introduces additional overhead in the form of logs, metrics, potential alerts, and processing requirements. If you’re not using components that specifically support and benefit from clustering, it’s best to not enable clustering at all. A particularly common mistake is enabling clustering on logs collecting DaemonSets. Collecting logs from Pods on the mounted node doesn’t benefit from having clustering enabled since each instance typically collects logs only from Pods on its own node. In such cases, enabling clustering only adds unnecessary complexity and resource usage without providing functional benefits.

Cluster monitoring and troubleshooting

You can monitor your cluster status using the Alloy UI clustering page. Refer to Debug clustering issues for additional troubleshooting information.

Next steps

Now that you understand how clustering works with Alloy components, explore these topics:

Deploy Alloy - Set up clustered deployments in production environments.
Monitor Alloy - Learn about monitoring cluster health and performance.
Troubleshooting - Debug clustering issues and interpret cluster metrics.

For detailed configuration:

alloy run command reference - Configure clustering using command-line flags.
Component reference - Explore clustering-enabled components like prometheus.scrape and pyroscope.scrape.

Get started with Grafana Alloy on Grafana Labs

Components

Components

Component structure

Component syntax

Component names

Component references

Component exports

Next steps

Expressions

Expressions

How expressions work

Expression types

Next steps

Alloy syntax

Alloy syntax

Comments

Identifiers

Attributes and Blocks

Attributes

Blocks

Examples

Block naming rules

Terminators

Formatting

Next steps

Modules

Modules

When to use a module

Why modules help

Example

Import modules

Security

Next steps

Clustering

Clustering

Use cases

Target auto-distribution

Best practices

Avoid issues with disproportionately large targets

Use --cluster.wait-for-size, but with caution

Don’t enable clustering if you don’t need it

Cluster monitoring and troubleshooting

Next steps

Use `--cluster.wait-for-size`, but with caution