Skip to main content

Installing and Configuring Grafana Alloy

Now that you understand what Grafana Alloy is and how its component-based architecture works, it's time to install Alloy and run your first configuration.

By the end of this lesson, you will be able to:

  • Install Grafana Alloy on Linux, macOS, or Windows.
  • Create a basic configuration file that starts the agent.
  • Run Alloy and validate its configuration.
  • Understand the structure of a minimal Alloy configuration.

Installation Methods​

Grafana Alloy can be installed using several methods. We'll cover the most common ones: using a pre-built binary and using Docker.

Method 1: Installing via the package manager​

Install via package manager
sudo apt install gpg
sudo mkdir -p /etc/apt/keyrings/
wget -q -O - https://apt.grafana.com/gpg.key | gpg --dearmor | sudo tee /etc/apt/keyrings/grafana.gpg > /dev/null
echo "deb [signed-by=/etc/apt/keyrings/grafana.gpg] https://apt.grafana.com stable main" | sudo tee /etc/apt/sources.list.d/grafana.list
sudo apt-get update
sudo apt-get install alloy
sudo systemctl enable alloy
sudo systemctl start alloy

After running the script, verify the installation:

alloy --version
tip

The install script defaults to installing Alloy for the current user. To install it system-wide (e.g., in /usr/local/bin), you may need to run it with sudo. The script will prompt you if it needs elevated privileges.

Method 2: Using Docker​

For containerized environments, you can use the official Alloy Docker image.

config.alloy
logging {
  level  = "info"
  format = "logfmt"
}
Run Alloy with Docker
docker run --rm -p 12345:12345 \
  -v $(pwd)/config.alloy:/etc/alloy/config.alloy \
  grafana/alloy:latest run --server.http.listen-addr=0.0.0.0:12345 --storage.path=/var/lib/alloy/data \
  /etc/alloy/config.alloy

This command:

  • Runs the latest grafana/alloy image.
  • Maps port 12345 from the container to your host (Alloy's default HTTP port).
  • Mounts a local file called config.alloy into the container and runs it.

Method 3: Manual Download​

You can manually download the appropriate binary for your platform (Linux, macOS, Windows) from the Grafana Alloy releases page on GitHub. Extract the archive and place the alloy binary in a directory included in your system's PATH.

Download and extract for Linux
# Example for Linux AMD64
wget https://github.com/grafana/alloy/releases/latest/download/alloy-linux-amd64.zip
unzip alloy-linux-amd64.zip
sudo mv alloy-linux-amd64 /usr/local/bin/alloy

Managing Alloy Services​

Alloy services can be managed using systemd on Linux. The service definition file is typically automatically created at the following location: /usr/lib/systemd/system/alloy.service

[Unit]
Description=Grafana Alloy
Documentation=https://grafana.com/docs/alloy
Wants=network-online.target
After=network-online.target

[Service]
Restart=always
User=root

Environment=HOSTNAME=%H
Environment=ALLOY_DEPLOY_MODE=deb
# Pointing to the directory enables multi-file mode
Environment=CONFIG_FILE=/etc/alloy

EnvironmentFile=-/etc/default/alloy

WorkingDirectory=/var/lib/alloy

# Note: Arguments come before the $CONFIG_FILE path
ExecStart=/usr/bin/alloy run $CUSTOM_ARGS --storage.path=/var/lib/alloy/data $CONFIG_FILE
ExecReload=/bin/kill -HUP $MAINPID
KillMode=process
TimeoutStopSec=20s

[Install]
WantedBy=multi-user.target

You can manage the service using the standard systemctl tool:

systemctl status alloy

Set credentials or other sensitive stuff as the environment variables​

You can set the credentials of other sensitive stuff at the following location /etc/systemd/system/alloy.service.d/env.conf

typical content of the file is

/etc/systemd/system/alloy.service.d/env.conf
[Service]
Environment=GCLOUD_RW_API_KEY=glc_eyJvIjoiM==
Environment=GCLOUD_FM_COLLECTOR_ID=vikasjha001
Environment=GITHUB_TOKEN=ghp_

these environment variables then can be referred as sys.env("GCLOUD_RW_API_KEY") in the alloy configuration file(s).

Creating Your First Configuration​

Alloy uses the River configuration language, and configuration files commonly use the .alloy extension.

Let's create a minimal configuration that scrapes Alloy's own metrics and sends them to a Prometheus remote_write endpoint:

config.alloy
logging {
  level = "info"
}

prometheus.exporter.self "self" {}

prometheus.scrape "self" {
  targets    = prometheus.exporter.self.self.targets
  forward_to = [prometheus.remote_write.default.receiver]
}

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

Update the url to a real Prometheus-compatible remote_write endpoint (for example, Grafana Cloud Metrics). This lesson assumes you have a running receiver. In the next section, we'll use the course's Grafana Cloud example.

Course Example: Global Outputs and Auth​

The course examples are stored in docs/grafanaalloy/examples. Most lessons rely on a shared global configuration that defines outputs and auth. This is docs/grafanaalloy/examples/01-global.alloy:

docs/grafanaalloy/examples/01-global.alloy
livedebugging {
  enabled = true
}


// 01-global.alloy

remotecfg {
  url = "https://fleet-management-prod-008.grafana.net"
  id  = "vikasjha001"

  attributes = {
    "os"       = "linux",
    "env"      = "production",
    "hostname" = constants.hostname,
  }

  basic_auth {
    username = "1064633"
    password = sys.env("GCLOUD_RW_API_KEY")
  }
}

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

  endpoint {
    url = "https://prometheus-prod-13-prod-us-east-0.grafana.net/api/prom/push"

    basic_auth {
      username = "1846252"
      // Use the API Key you provided
      password = sys.env("GCLOUD_RW_API_KEY")
    }
  }
}

// Update your relabeler to forward to the Cloud destination
prometheus.relabel "common_labels" {
  forward_to = [prometheus.remote_write.grafana_cloud.receiver]

  rule {
    target_label = "env"
    replacement  = "production"
  }
}

loki.write "grafana_cloud_loki" {
  endpoint {
    url = "https://logs-prod-006.grafana.net/loki/api/v1/push"

    basic_auth {
      username = "1022411"
      password = sys.env("GCLOUD_RW_API_KEY")
    }
  }
}


otelcol.auth.basic "grafana_cloud" {
  username = "1016726"
  password = sys.env("GCLOUD_RW_API_KEY")
}

otelcol.exporter.otlp "grafana_cloud" {
  client {
    endpoint = "tempo-prod-04-prod-us-east-0.grafana.net:443"
    auth     = otelcol.auth.basic.grafana_cloud.handler
  }
}
tip

This file expects the GCLOUD_RW_API_KEY environment variable to be set. If you're not using Grafana Cloud, update the endpoints and auth blocks accordingly.

Running Grafana Alloy​

Alloy commands accept either a file path or a directory. If you pass a directory, Alloy loads all *.alloy files in that folder (non-recursive) as a single configuration source.

Validate a config file
alloy validate config.alloy
Run a config file
alloy run config.alloy
Validate and run the course examples
alloy validate docs/grafanaalloy/examples
alloy run docs/grafanaalloy/examples
note

The docs/grafanaalloy/examples directory contains multiple optional integrations. If you only want to run a subset, create a new folder and copy 01-global.alloy plus the specific example files you want to test.

Verifying the Agent is Working​

  1. Check the logs: The terminal output shows the agent is running.
  2. Check the HTTP endpoint: By default, Alloy exposes metrics about itself on http://localhost:12345/metrics. 
    curl http://localhost:12345/metrics | head -5
  3. Check your backend: Confirm that your remote-write destination (Grafana Cloud or Prometheus) is receiving metrics.

To stop the agent, go back to the terminal and press Ctrl+C.

Uninstalling Alloy Agent​

First, stop the running service and then use apt to remove the binary.

  • Stop the service
sudo systemctl stop alloy
sudo systemctl disable alloy
  • Uninstall the package
sudo apt-get remove alloy
  • Remove all config files and data directories
sudo apt-get purge alloy
sudo rm -rf /etc/alloy
sudo rm -rf /var/lib/alloy
sudo rm -rf /var/log/alloy

Common Pitfalls​

  • Missing config path: alloy run expects a file or directory path. If you omit it, Alloy exits with an error.
  • Wrong file extension: The examples use .alloy. If you used .river, update your tooling or rename the file.
  • Missing env vars: 01-global.alloy reads GCLOUD_RW_API_KEY from the environment. If it's missing, auth will fail.
  • Port already in use: If 127.0.0.1:12345 is occupied, set --server.http.listen-addr when running Alloy.

Summary​

In this lesson, you installed Grafana Alloy and created a minimal configuration. You also reviewed the shared 01-global.alloy file that powers the course examples. Next, we'll dive into the Alloy configuration language in depth.

Installing Grafana Alloy - Quick Check

What is the typical file extension for an Alloy configuration file?

Question 1/4