Skip to main content

Troubleshooting Alloy Installation

This guide provides common commands and solutions for troubleshooting a Grafana Alloy installation on Linux, specifically focusing on service health, configuration errors, and eBPF profiling issues.

1. Quick Service Health Check​

The first step in troubleshooting is verifying that the Alloy service is active and running.

# Check the status of the service
sudo systemctl status alloy

Common Status Indicators:​

  • Active (running): Everything is normal.
  • Inactive (dead): The service was manually stopped. Use sudo systemctl start alloy.
  • Failed: The service crashed, likely due to a configuration error or permission issue.

2. Inspecting Logs​

Alloy writes all its logs to stderr. On Linux, these are captured by the systemd journal.

# View the last 50 lines of logs
sudo journalctl -u alloy -n 50

# Follow logs in real-time (useful for debugging live scripts)
sudo journalctl -u alloy -f

What to look for:​

  • level=error: Indicates a critical failure (e.g., authentication or network).
  • level=warn: Indicates non-critical issues (e.g., failed to scrape one specific target).
  • msg="eBPF tracer loaded": Confirms that profiling is working correctly.

3. Configuration Validation​

If Alloy fails to start, it is usually because of a syntax error in your .alloy files.

# Validate your config without restarting the service
alloy validate /etc/alloy/config.alloy

Note: If your configuration is split into multiple files in a directory, point the command to the directory: alloy validate /etc/alloy/

4. Common eBPF & Profiling Issues​

401 Unauthorized​

Sympton: Logs show server returned HTTP status 401 Unauthorized. Fix: Verify your Grafana Cloud Username and API Key in your pyroscope.write or prometheus.remote_write blocks. Ensure environment variables are loaded if you are using sys.env().

Permission Denied (eBPF)​

Symptom: Logs show cannot create bpf perf link: permission denied. Fix: eBPF components require root privileges. By default, the Alloy systemd service runs as root. If you have modified the service to run as a non-root user, eBPF profiling will fail.

No Data in Grafana​

If the logs look clean but no data appears:

  1. Check the URL: Ensure your endpoint includes the correct suffix (e.g., /otlp for Pyroscope).
  2. Verify Targets: Check the Alloy UI at http://localhost:12345 to see if your discovery.process component is actually finding any targets.

5. Uninstallation & Cleanup​

If you need to start over with a fresh installation:

# 1. Stop the service
sudo systemctl stop alloy

# 2. Remove the package
sudo apt-get remove alloy

# 3. (Optional) Purge all configs and data
sudo apt-get purge alloy
sudo rm -rf /etc/alloy
sudo rm -rf /var/lib/alloy