Components on Grafana Labs

Configure components

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

Configure components

Components are the defining feature of Alloy. They’re reusable pieces of business logic that perform a single task, such as retrieving secrets or collecting Prometheus metrics. You can wire them together to form programmable pipelines of telemetry data.

To build effective configurations, you need to understand how to define components, set their arguments, and connect them using exports.

Basic component syntax

You create components by defining a top-level block with a component name and a user-specified label.

COMPONENT_NAME "LABEL" {
  // Component configuration goes here
}

For example, this creates a local.file component with the label “config”:

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

The component controller schedules components, reports their health and debug status, re-evaluates their arguments, and provides their exports.

Arguments and exports

Most user interactions with components center around two basic concepts: arguments and exports.

Arguments

Arguments are settings that modify a component’s behavior. They can include attributes or nested unlabeled blocks, some of which you must provide and others that are optional. Optional arguments that aren’t set use their default values.

local.file "targets" {
  filename = "/etc/alloy/targets"  // Required argument

  // Optional arguments
  poll_frequency = "1m"
  is_secret = false
}

Exports

Exports are zero or more output values that other components can refer to. They can be of any Alloy type.

The local.file.targets component from the previous example exposes the file content as a string in its exports. You’ll learn how to reference these exports in Expressions.

Configuration blocks

Some components use nested blocks to organize related settings.

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

    basic_auth {
      username = "metrics"
      password_file = "/etc/secrets/password"
    }
  }

  queue_config {
    capacity = 10000
    batch_send_deadline = "5s"
  }
}

In this example:

endpoint is a block that configures the remote endpoint
basic_auth is a nested block within endpoint
queue_config is another top-level block within the component

Component references

To wire components together, use the exports of one as the arguments to another by using references. References can only appear in component arguments.

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 to component export
    }
  }
}

Each time the file contents change, the local.file component updates its exports. The component sends the updated value to the prometheus.remote_write component’s password field.

Reference syntax

To reference a component export, combine three parts with periods:

Component name: local.file
Component label: api_key
Export name: content
Result: local.file.api_key.content

Each argument and exported field has an underlying type. Alloy checks the expression type before assigning a value to an attribute.

Multiple component instances

You can create multiple instances of the same component type by using different labels:

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

Both scrape configurations send metrics to the same prometheus.remote_write component.

Component rules

Components can’t form cycles. This means that a component can’t reference itself directly or indirectly. This prevents infinite loops from forming in your configuration.

// INVALID: Component can't reference itself
local.file "self_reference" {
  filename = local.file.self_reference.content
}

// INVALID: Cyclic reference between components
local.file "a" {
  filename = local.file.b.content
}

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

Next steps

Now that you understand how to configure components, learn about more advanced topics:

Build data pipelines - Connect components together to create data processing workflows
Component controller - Understand how Alloy manages components at runtime
Expressions - Write dynamic configuration using component references and functions
Component reference - Explore all available components and their arguments and exports

For practical examples, try the tutorials to build complete data collection pipelines.

Build data pipelines

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

Build data pipelines

You learned about components in the previous section. They’re building blocks that perform tasks such as reading files, collecting metrics, or processing data. Now you’ll learn how to connect components to create pipelines that collect, transform, and send telemetry data.

What are pipelines?

A pipeline forms when components reference each other’s exports. You learned about component exports in the previous section. These are the values that running components make available to other components.

// Simple constant value
log_level = "debug"

// Expression that references a component export
api_key = local.file.secret.content

When you use an expression like local.file.secret.content in a component’s arguments, you create a dependency. Alloy automatically re-evaluates the dependent component whenever the referenced component updates its exports.

Your first pipeline

This pipeline reads a password from a file and uses it to authenticate with a remote system:

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

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

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

This pipeline has two components:

local.file reads a file and exports its content.
prometheus.remote_write uses that content as a password.

The key configuration elements are:

Component exports: local.file.api_key.content exports the file’s content.
Component references: The password attribute references the export from another component.
Automatic updates: When the file changes, Alloy automatically updates the password used by the remote write component.

Multi-stage pipelines

You can chain multiple components together to create more complex pipelines. This example shows a complete metrics collection pipeline:

// Discover Kubernetes pods to scrape
discovery.kubernetes "pods" {
  role = "pod"
}

// Scrape metrics from the discovered pods
prometheus.scrape "app_metrics" {
  targets    = discovery.kubernetes.pods.targets
  forward_to = [prometheus.remote_write.production.receiver]
}

// Send metrics to remote storage
prometheus.remote_write "production" {
  endpoint {
    url = "https://prometheus.example.com/api/v1/write"

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

// Read API key from file
local.file "api_key" {
  filename = "/etc/secrets/api-key"
  is_secret = true
}

This pipeline demonstrates several key concepts:

Service discovery: discovery.kubernetes finds targets to monitor.
Data collection: prometheus.scrape collects metrics from those targets.
Data forwarding: The forward_to attribute connects components by sending data from one to another.
Authentication: The remote write component uses credentials from a file.

The forward_to attribute is a special configuration element that creates data flow connections between components. It accepts a list of component receivers that process the data.

Log processing pipeline

Here’s a more complex example that processes log data through multiple transformation stages:

// Read log files using glob patterns
loki.source.file "local_files" {
    targets    = [{__path__ = "/var/log/app/*.log"}]
    forward_to = [loki.process.add_labels.receiver]

    file_match {
        enabled = true
        sync_period = "10s"
    }
}

// Extract data from log messages and add labels
loki.process "add_labels" {
    stage.logfmt {
        mapping = {
            "extracted_level" = "level",
            "extracted_service" = "service",
        }
    }

    stage.labels {
        values = {
            "level" = "extracted_level",
            "service" = "extracted_service",
        }
    }

    forward_to = [loki.write.grafana_cloud.receiver]
}

// Send processed logs to Loki
loki.write "grafana_cloud" {
    endpoint {
        url = "https://logs-prod.grafana.net/loki/api/v1/push"

        basic_auth {
            username = "12345"
            password = local.file.api_key.content
        }
    }
}

// Read API credentials
local.file "api_key" {
    filename = "/etc/secrets/loki-key"
    is_secret = true
}

This pipeline shows how data flows through multiple processing stages:

Discovery: Find log files to monitor.
Collection: Read log entries from files.
Transformation: Parse log messages and extract metadata.
Enrichment: Add structured labels to log entries.
Output: Send processed logs to remote storage.

Pipeline patterns

Use these common patterns to build effective data processing workflows.

Fan-out pattern

Send data from one component to multiple destinations. This uses the forward_to attribute with multiple receivers:

prometheus.scrape "app_metrics" {
  targets = [{"__address__" = "app:8080"}]
  forward_to = [
    prometheus.remote_write.production.receiver,
    prometheus.remote_write.staging.receiver,
  ]
}

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

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

This pattern is useful for:

Testing changes in staging before production.
Sending different datasets to different systems.
Creating redundant data storage for reliability.

Chain processing pattern

Transform data through multiple stages:

loki.source.file "raw_logs" {
  targets = [{"__path__" = "/var/log/app.log"}]
  forward_to = [loki.process.parse.receiver]
}

loki.process "parse" {
  stage.json {
    expressions = {
      level = "level",
      message = "msg",
    }
  }
  forward_to = [loki.process.filter.receiver]
}

loki.process "filter" {
  stage.match {
    selector = "{level=\"error\"}"
    action   = "keep"
  }
  forward_to = [loki.write.alerts.receiver]
}

loki.write "alerts" {
  endpoint {
    url = "https://loki.example.com/loki/api/v1/push"
  }
}

This pattern demonstrates progressive data refinement:

Parse: Extract structured data from raw logs.
Filter: Keep only relevant log entries (error level).
Output: Send filtered logs to alerting system.

Best practices

Follow these guidelines to build maintainable and efficient pipelines.

Keep pipelines focused

Break complex pipelines into logical stages. Each component should have a clear, single responsibility.

Use descriptive labels

Choose component labels that describe their purpose:

// Good: Descriptive labels
prometheus.scrape "api_metrics" { }
prometheus.scrape "database_metrics" { }

// Avoid: Generic labels
prometheus.scrape "scraper1" { }
prometheus.scrape "scraper2" { }

Handle secrets securely

Mark sensitive components appropriately:

local.file "database_password" {
  filename = "/etc/secrets/db-password"
  is_secret = true  // Prevents value from appearing in UI
}

Test incrementally

Build pipelines step by step. Start with basic data collection, then add processing and forwarding components.

Debug pipelines

When pipelines don’t work as expected:

Check component health in the Alloy UI. Unhealthy components appear in red.
Verify component exports contain expected data. Use the UI to inspect export values.
Review component dependencies to ensure proper data flow. Check that forward_to references match receiver exports.
Check for reference cycles - components can’t reference themselves directly or indirectly.
Validate configuration syntax - ensure you spell component and export names correctly.

The Alloy UI provides detailed information about component state, exports, and health status to help troubleshoot pipeline issues.

Next steps

Now that you understand how to build pipelines, learn more about component management and dynamic configurations:

Component controller - Learn how Alloy manages component execution
Expressions - Create dynamic configurations using functions and references

For hands-on learning:

Tutorials - Follow step-by-step guides to build complete monitoring solutions

Component controller

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

Component controller

You learned how to build pipelines by connecting components through their exports and references in the previous section. Now you’ll learn how the component controller manages these components at runtime to make your pipelines work.

The component controller is the core part of Alloy responsible for:

Reading and validating the configuration file.
Managing the lifecycle of defined components.
Evaluating the arguments used to configure components.
Reporting the health of defined components.

Component graph

When you create pipelines, you establish relationships between components by referencing one component’s exports in another component’s arguments. The component controller uses these relationships to build a Directed Acyclic Graph (DAG) that represents all components and their dependencies.

This graph serves two critical purposes:

Validation: Ensures that component references are valid and don’t create circular dependencies.
Evaluation order: Determines the correct sequence for evaluating components so that dependencies are resolved before dependent components run.

For a configuration file to be valid, components can’t reference themselves or create circular dependencies.

// INVALID: local.file.some_file can't reference itself:
local.file "self_reference" {
  filename = local.file.self_reference.content
}

// INVALID: cyclic reference between local.file.a and local.file.b:
local.file "a" {
  filename = local.file.b.content
}
local.file "b" {
  filename = local.file.a.content
}

Component evaluation

Component evaluation is the process of computing expressions in a component’s arguments into concrete values. These values configure the component’s runtime behavior.

The component controller follows a strict evaluation order:

Dependency resolution: The controller evaluates a component only after evaluating all its dependencies.
Parallel evaluation: Components without dependencies can be evaluated in parallel during the initial startup.
Component creation: After successful evaluation, the controller creates and starts the component instance.

The component controller is fully loaded once it evaluates, configures, and starts all components.

Component reevaluation

Components are dynamic and can update their exports multiple times during their lifetime. For example, a local.file component updates its exports whenever the file content changes.

When a component updates its exports, the component controller triggers a reevaluation process:

Identify dependents: The controller finds all components that reference the changed component’s exports.
Cascade evaluation: The controller reevaluates those dependent components with the new export values.
Propagate changes: If any dependent component also updates its exports, the process continues until all affected components are reevaluated.

This automatic reevaluation ensures that your pipelines stay current with changing data and conditions.

Component health

Every component has a health state that indicates whether it’s working properly. The component controller tracks health to help you monitor and troubleshoot your pipelines.

Components can be in one of these health states:

Unknown: The default state when a component is created but not yet started.
Healthy: The component is working as expected.
Unhealthy: The component encountered an error or isn’t working as expected.
Exited: The component has stopped and is no longer running.

The component controller determines health by combining multiple factors:

Evaluation health: Whether the component’s arguments evaluated successfully.
Runtime health: Whether the component is running without errors.
Component-specific health: Some components report their own health status (for example, local.file reports unhealthy if its target file is deleted).

A component’s health is independent of the health of components it references. A component can be healthy even if it references exports from an unhealthy component.

Evaluation failures

When a component fails to evaluate its arguments (for example, due to invalid configuration or missing dependencies), the component controller marks it as unhealthy and logs the failure reason.

Critically, the component continues operating with its last valid configuration. This prevents failures from cascading through your entire pipeline.

For example:

If a local.file component watching an API key file encounters a temporary file access error, dependent components continue using the last successfully read API key.
If a discovery.kubernetes component temporarily loses connection to the API server, scrapers continue monitoring the last discovered targets.

This graceful degradation keeps your monitoring operational even when individual components encounter temporary issues.

In-memory traffic

Some components that expose HTTP endpoints, such as prometheus.exporter.unix, support in-memory communication for improved performance. When components within the same Alloy process communicate, they can bypass the network stack entirely.

Benefits of in-memory traffic:

Performance: Eliminates network overhead for local component communication.
Security: No need for network-level authentication or TLS since communication stays within the process.
Reliability: Avoids potential network-related failures between components.

The internal address defaults to alloy.internal:12345. If this conflicts with a real network address, you can change it using the --server.http.memory-addr flag when running Alloy.

Components must explicitly support in-memory traffic to use this feature. Check individual component documentation to see if it’s available.

Configuration file updates

The /-/reload HTTP endpoint and the SIGHUP signal notify the component controller to reload the configuration file. When reloading, the controller synchronizes the running components with the configuration file. It removes components no longer defined and creates additional ones added to the file. After reloading, the controller reevaluates all managed components.

Next steps

Now that you understand how the component controller works, explore advanced component topics and monitoring:

Configure components - Learn how to write components the controller can manage
Expressions - Create dynamic configurations using functions and component references

For monitoring and troubleshooting:

Monitor the component controller - Track component health and performance
Alloy run command - Configuration options that affect the controller

Custom components

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

Custom components

You learned how the component controller manages the lifecycle of components in the previous section. Now you’ll learn how to create your own reusable components by combining existing components into custom components.

Custom components allow you to package a pipeline of built-in and other custom components into a single, reusable unit. This makes it easier to share common patterns across your configurations and across teams.

A custom component includes:

Arguments: Settings that configure the custom component’s behavior.
Exports: Values the custom component exposes to consumers.
Components: Built-in and custom components that run as part of the custom component.

Create custom components

Use the declare configuration block to create a custom component. The block’s label becomes the custom component’s name, which you can then use like any built-in component.

Inside a declare block, you can use these configuration blocks:

argument: Defines a named input parameter that users must provide when using your custom component. Access the value with argument.NAME.value.
export: Defines a named output value that your custom component exposes to other components.
Built-in and custom components: The actual pipeline logic that processes data.

The component controller treats custom components the same as built-in components:

Evaluation: Arguments are evaluated and passed to the internal pipeline.
Execution: The internal components run and process data.
Export updates: When internal components update their exports, the custom component can update its own exports.
Health reporting: The custom component’s health reflects the health of its internal components.

Custom components are particularly useful for packaging common pipeline patterns that you want to reuse across multiple configurations.

Example

This example creates a custom component called add that demonstrates the key concepts:

declare "add" {
    argument "a" {
        comment = "First number to add"
        optional = false
    }

    argument "b" {
        comment = "Second number to add"
        optional = false
    }

    export "sum" {
        value = argument.a.value + argument.b.value
    }
}

add "example" {
    a = 15
    b = 17
}

// Reference the export: add.example.sum == 32

This custom component:

Declares two required arguments: a and b with descriptive comments.
Exports one value: sum that computes the addition of the two arguments.
Can be instantiated: Create an instance labeled example by providing values for a and b.
Exposes computed results: Other components can reference add.example.sum to use the result.

For more complex examples that combine multiple built-in components, refer to the declare block reference.

Next steps

Now that you understand custom components, explore related topics and advanced usage:

Configuration blocks reference - Learn about declare, argument, and export blocks in detail
Configure components - Use custom components in your pipelines

For sharing and organizing:

Modules - Share custom components across multiple configuration files

Community components

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

Community components

You learned how to create custom components by combining existing components in the previous section. Now you’ll learn about community components. These are specialized components that the Alloy community develops and maintains.

Community components extend Alloy’s capabilities with vendor-specific integrations and specialized functionality that may not be suitable for core components. They follow the same component architecture you’ve learned about but have different support and stability characteristics.

What are community components?

Community components are components that community members implement and maintain rather than the core Alloy team. They’re particularly useful for:

Vendor-specific integrations: Components for services that Grafana Labs doesn’t offer commercial support for.
Specialized functionality: Components that serve specific use cases or niche requirements.
Experimental features: New capabilities that need community validation before potential inclusion in core components.

Key characteristics of community components:

Community ownership: The community implements, maintains, and supports them.
No commercial support: Grafana Labs doesn’t provide commercial support for these components.
Review process: The Alloy development team reviews and accepts them before adding them to the repository.
Stability level: They don’t have defined stability levels and aren’t covered by the backward compatibility strategy.

Enable community components

Community components are disabled by default. To use them, you must explicitly enable them when running Alloy:

alloy run --feature.community-components.enabled config.alloy

This flag ensures that you consciously choose to use components that have different support characteristics than core components. After enabling community components, you can use them the same way as any built-in component in your configuration.

Warning
Grafana Labs may disable or remove community components without a maintainer if they block or prevent the development of Alloy.

Next steps

Now that you understand community components, explore how to find and use components in your configurations:

Component reference - Browse all available components including community components
Configure components - Learn how to use components in your configuration

For component selection guidance:

Choose a component - Get guidance on selecting the right component for your needs