Introduction to Grafana Alloy and Its Architecture

Welcome to the first lesson of our Grafana Alloy course. In this lesson, we'll explore what Grafana Alloy is, why it was created, and how its architecture enables you to build powerful observability pipelines. By the end of this lesson, you'll understand Alloy's core concepts and how it fits into the modern observability landscape.

Learning Goals:

• Understand what Grafana Alloy is and its purpose
• Learn the key architectural components of Alloy
• Differentiate between Alloy and its predecessor, Grafana Agent
• Identify common use cases for Alloy
• Recognize the flow of telemetry data through Alloy

What is Grafana Alloy?

Grafana Alloy is a vendor-neutral, open-source telemetry collector for processing and forwarding metrics, logs, and traces. It is Grafana's distribution of the OpenTelemetry Collector with Prometheus and Loki-compatible components, and it uses a declarative configuration language designed for observability pipelines.

Alloy serves as a unified agent that can collect telemetry data from various sources, process it, and ship it to multiple destinations including Prometheus, Loki, Tempo, and other compatible backends.

tip

Think of Alloy as a "Swiss Army knife" for observability data. Instead of running separate agents for metrics, logs, and traces, you can use Alloy to handle all three types of telemetry data through a single, cohesive pipeline.

Why Grafana Alloy?

Before Alloy, many organizations used Grafana Agent (or multiple specialized agents) alongside other collectors. This approach had several challenges:

1. Configuration complexity - Different agents used different configuration formats
2. Resource overhead - Running multiple agents consumed more memory and CPU
3. Data correlation difficulties - Connecting related metrics, logs, and traces was harder
4. Operational complexity - More components to monitor and maintain

Alloy addresses these challenges by providing:

• A single binary for all telemetry types
• A unified configuration language
• Built-in data correlation capabilities
• Better performance and resource efficiency

Alloy Architecture Overview

Alloy's architecture consists of several key components that work together to process telemetry data:

1. Components

Components are the building blocks of Alloy configurations. Each component performs a specific function, such as collecting data, processing it, or exporting it. Components connect to form data pipelines.

Basic component structure

// A component definition in Alloy
prometheus.scrape "app_metrics" {
  targets = [
    { "__address__" = "localhost:8080", "job" = "myapp" },
  ]
  forward_to = [prometheus.remote_write.default.receiver]
}

prometheus.remote_write "default" {
  endpoint {
    url = "http://prometheus:9090/api/v1/write"
  }
}

2. The Alloy Configuration Language (River)

Alloy uses a custom configuration language called River. River is declarative, meaning you describe what you want to achieve rather than how to achieve it. Configuration files commonly use the .alloy extension.

River features:

• Strong typing with type inference
• Component-based architecture
• Built-in functions and operators
• Module system for reusable configurations

3. Data Flow

Telemetry data flows through Alloy in a directed graph:

Sources -> Processors -> Exporters

For example, a complete flow might look like:

Application Metrics -> Prometheus Scrape -> Relabeling -> Remote Write -> Prometheus
Application Logs -> Loki Source -> Processing -> Loki Write -> Loki
Traces -> OTLP Receiver -> Batch -> Export -> Tempo

Alloy vs. Grafana Agent

It's important to understand how Alloy differs from its predecessor:

alloy

Alloy configuration example

loki.source.docker "containers" {
  host = "unix:///var/run/docker.sock"
  forward_to = [loki.write.default.receiver]
}

loki.write "default" {
  endpoint {
    url = "http://loki:3100/loki/api/v1/push"
  }
}

agent

Grafana Agent configuration example

loki:
  configs:
  - name: default
    clients:
      - url: http://loki:3100/loki/api/v1/push
    scrape_configs:
    - job_name: docker
      docker_sd_configs:
      - host: unix:///var/run/docker.sock

Key differences:

• Configuration language: Alloy uses River (HCL-like), Agent uses YAML
• Architecture: Alloy uses components, Agent uses static config sections
• Extensibility: Alloy has a module system for custom components
• Lifecycle: Grafana Agent is in long-term support (LTS); Alloy is the recommended successor

Core Use Cases

1. Unified Telemetry Collection

Collect metrics, logs, and traces from your applications and infrastructure using a single agent.

2. Edge Monitoring

Alloy's efficiency makes it suitable for resource-constrained environments like edge devices or IoT deployments.

3. Multi-Tenant Environments

Process and route telemetry data for multiple teams or customers with isolation and different processing rules.

4. Data Transformation

Clean, filter, and enrich telemetry data before it reaches your observability backend.

Multi-source collection example

// Collect from multiple sources
prometheus.scrape "node" {
  targets = [
    { "__address__" = "node-exporter:9100", "job" = "node" },
  ]
  forward_to = [prometheus.relabel.node.receiver]
}

prometheus.scrape "app" {
  targets = [
    { "__address__" = "myapp:8080", "job" = "application" },
  ]
  forward_to = [prometheus.relabel.app.receiver]
}

// Process differently based on source
prometheus.relabel "node" {
  rule {
    source_labels = ["job"]
    target_label = "source_type"
    replacement = "infrastructure"
  }
  forward_to = [prometheus.remote_write.default.receiver]
}

prometheus.relabel "app" {
  rule {
    source_labels = ["job"]
    target_label = "source_type"
    replacement = "application"
  }
  forward_to = [prometheus.remote_write.default.receiver]
}

Common Pitfalls

When starting with Grafana Alloy, watch out for these common issues:

• Configuration syntax errors: River is strict about syntax. Missing commas or incorrect indentation will cause failures.
• Component connection issues: Forgetting to connect components with forward_to will result in data not flowing through your pipeline.
• Type mismatches: River is strongly typed. Passing a string where a number is expected will cause validation errors.
• Resource limits: While efficient, Alloy still needs appropriate CPU and memory allocations, especially for high-volume workloads.
• Missing components: Referencing a component that isn't loaded (for example, defined in another file you didn't include) will cause validation errors.

warning

Always validate your Alloy configuration before deploying it to production. Use the alloy validate command to check for syntax errors and type mismatches. This can save you from runtime failures and data loss.

Summary

In this lesson, we've introduced Grafana Alloy as a unified telemetry collector that simplifies observability pipelines. We've covered:

• Alloy's purpose as a vendor-neutral collector for metrics, logs, and traces
• Its component-based architecture using the River configuration language
• How it improves upon Grafana Agent with better performance and unified configuration
• Common use cases including unified collection, edge monitoring, and data transformation
• Key architectural concepts like components, data flow, and the River language

Alloy provides a powerful foundation for building robust observability pipelines. In the next lesson, we'll dive into installing and configuring Alloy in your environment.

Quiz

Grafana Alloy Architecture - Quick Check

What is the primary purpose of Grafana Alloy?

Question 1/5