> ## Documentation Index
> Fetch the complete documentation index at: https://notes.kodekloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Demo Installing the Grafana Alloy Agent

> Guide to install and configure Grafana Alloy on a node to tail local log files and forward them to a Loki instance for viewing in Grafana

This guide shows how to install and configure the Grafana Alloy agent on Node 2 so it tails local log files and forwards them to a Loki instance on Node 1 (node01:3100). Follow the steps below in order: connect to Node 2, install prerequisites and Alloy, create the Alloy configuration that discovers and tails `/var/log/*.log`, and verify logs in Grafana Explore (Loki).

## 1. SSH into Node 2

Start by SSHing into Node 2:

```bash theme={null}
bob@node01 ~ ➜ ssh node02
Welcome to Ubuntu 20.04.3 LTS (GNU/Linux 6.8.0-124-generic x86_64)

* Documentation:    https://help.ubuntu.com
* Management:       https://landscape.canonical.com
* Support:          https://ubuntu.com/advantage

This system has been minimized by removing packages and content that are
not required on a system that users do not log into.

To restore this content, you can run the 'unminimize' command.
Last login: Sun Jul 26 13:59:37 2026 from 10.244.51.183

bob@node02 ~ ➜
```

## 2. Prerequisites and adding Grafana's apt repository (Debian/Ubuntu)

Install basic utilities (GPG + wget), add the Grafana keyring, and register the apt repository:

```bash theme={null}
# Update and install GPG/wget if missing
sudo apt update
sudo apt install -y gnupg wget

# Create keyrings dir and fetch Grafana's signing key
sudo mkdir -p /etc/apt/keyrings
sudo wget -O /etc/apt/keyrings/grafana.asc https://apt.grafana.com/gpg-full.key
sudo chmod 644 /etc/apt/keyrings/grafana.asc

# Add Grafana apt repository
echo "deb [signed-by=/etc/apt/keyrings/grafana.asc] https://apt.grafana.com stable main" | sudo tee /etc/apt/sources.list.d/grafana.list

# Update and install Alloy
sudo apt-get update
sudo apt-get install -y alloy
```

### Sample installation output (trimmed)

```text theme={null}
Get:1 https://apt.grafana.com stable/main amd64 alloy amd64 1.18.0-1 [121 MB]
Fetched 121 MB in 5s (26.6 MB/s)
Selecting previously unselected package alloy.
Preparing to unpack .../alloy_1.18.0-1_amd64.deb ...
Unpacking alloy (1.18.0-1) ...
Setting up alloy (1.18.0-1) ...
bob@node02 ~ ▶
```

## 3. Inspect the default Alloy sample config

The package ships a sample config at `/etc/alloy/config.alloy`. A trimmed excerpt looks like:

```hcl theme={null}
// Sample config for Alloy.
// For a full configuration reference, see https://grafana.com/docs/alloy
logging {
  level = "warn"
}

prometheus.exporter.unix "default" {
  include_exporter_metrics = true
  disable_collectors = ["mdadm"]
}

prometheus.scrape "default" {
  targets = array.concat(
    prometheus.exporter.unix.default.targets,
    [{
      // Self-collect metrics
      job        = "alloy",
      __address__ = "127.0.0.1:12345",
    }],
  )
}

forward_to = []
```

## 4. Configure Alloy to tail /var/log/\*.log and forward to Loki

We will add three blocks to the Alloy config:

* `local.file_match` — discover files under `/var/log/*.log`
* `loki.source.file` — create a file source that tails those files
* `loki.write` — forward scraped logs to the Loki endpoint

Create or replace `/etc/alloy/config.alloy` with the following content. This example tails files under `/var/log/*.log` and forwards them to the Loki instance at `http://node01:3100/loki/api/v1/push`:

```hcl theme={null}
// Alloy configuration to scrape /var/log/*.log and forward to Loki

logging {
  level = "warn"
}

local.file_match "local_files" {
  path_targets = [{"__path__" = "/var/log/*.log"}]
  sync_period  = "5s"
}

loki.source.file "log_scrape" {
  targets       = local.file_match.local_files.targets
  forward_to    = [loki.write.grafana_loki.receiver]
  tail_from_end = true
}

loki.write "grafana_loki" {
  endpoint {
    url = "http://node01:3100/loki/api/v1/push"
  }
  # If Loki requires basic auth, uncomment and set credentials:
  # basic_auth {
  #   username = "admin"
  #   password = "admin"
  # }
}
```

Note: `tail_from_end = true` prevents Alloy from ingesting the entire previous file history; it starts tailing new lines from the end of each file.

If you need to filter noisy log lines before sending to Loki, insert a processing stage (for example, `loki.process "filter_logs"` using `stage.drop`) and forward from `loki.source.file` to `loki.process.filter_logs.receiver` instead of directly to the write receiver.

Ensure network connectivity and access control: Alloy must be able to reach `node01:3100`. If Loki is protected, configure `basic_auth` or other auth methods in `loki.write`. Also verify any firewall rules between Node 2 and Node 1 allow port 3100.

## 5. Reload/Restart Alloy and check status

After saving `/etc/alloy/config.alloy`, reload the systemd units and restart Alloy:

```bash theme={null}
sudo systemctl daemon-reload
sudo systemctl restart alloy

# Check status
sudo systemctl status alloy --no-pager
```

Verify the files present on the node (example):

```bash theme={null}
ls /var/log/
# alternatives.log  apt  btmp  dpkg.log  journal  lastlog  private  wtmp
```

Once Alloy is running with the updated configuration, it will discover files matching `/var/log/*.log`, tail new lines, and push them to the configured Loki endpoint on node01.

## 6. Verify logs in Grafana Explore (Loki)

Open Grafana and go to Explore → Loki to query logs. Example LogQL to select logs from `/var/log/dpkg.log`:

```logql theme={null}
{filename="/var/log/dpkg.log"} |= ""
```

Refresh the Explore view and click Run. You should see streaming log lines from Node 2 for matched files.

![A dark-themed Grafana Explore screen showing the Loki log query builder with label filters and a "Select value" field, plus a left sidebar of navigation items. The query area shows "No data" in the results panel.](https://mintcdn.com/kodekloud-c4ac6d9a/dEcIUoAxuol-3ZBK/images/Grafana-Loki/Grafana-Loki-Essentials/Demo-Installing-the-Grafana-Alloy-Agent/grafana-explore-loki-query-no-data.jpg?fit=max\&auto=format\&n=dEcIUoAxuol-3ZBK\&q=85\&s=bf384e40fada1e7dfad584e5db221b76)

If no logs appear, check Alloy's journal logs and network reachability from Node 2 to Node 1.

## Troubleshooting checklist

* Verify Alloy service is active:
  * `sudo systemctl status alloy`
* Inspect Alloy logs live:
  * `sudo journalctl -u alloy -f`
* Confirm Loki is reachable from Node 2:
  * `curl -sS http://node01:3100/ready`
  * `curl -sS http://node01:3100/loki/api/v1/labels --fail`
* If Loki requires authentication, configure it in `loki.write` and ensure credentials are correct.
* If no labels appear, confirm `local.file_match` path patterns match existing files and that `tail_from_end` behavior is understood (it won't send historical lines).

## Quick Reference

| Item | Command / Location | Notes |
| - | - | - |
| Alloy config file | `/etc/alloy/config.alloy` | Update to add `local.file_match`, `loki.source.file`, and `loki.write` |
| Restart Alloy | `sudo systemctl restart alloy` | Also use `daemon-reload` after config changes if needed |
| Verify logs | Grafana Explore (Loki) | Use LogQL like `{filename="/var/log/dpkg.log"} \|= ""` |
| Check connectivity | `curl -sS http://node01:3100/ready` | Ensures Loki server is reachable |

## Links and references

* Grafana Alloy docs: [https://grafana.com/docs/alloy](https://grafana.com/docs/alloy)
* Grafana Loki docs: [https://grafana.com/docs/loki](https://grafana.com/docs/loki)
* Grafana Explore (Loki tutorial): [https://learn.kodekloud.com/user/courses/grafana-loki](https://learn.kodekloud.com/user/courses/grafana-loki)

> **[Watch Video](https://learn.kodekloud.com/user/courses/grafana-loki/module/d9262c89-9213-4e21-8599-d54b9c773885/lesson/7a94e3fc-c5f5-4844-9b44-d88c2098388b)**


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.