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: