Menu
Documentationbreadcrumb arrow Grafana Cloudbreadcrumb arrow Monitor infrastructurebreadcrumb arrow Grafana integrationsbreadcrumb arrow Troubleshoot installationsbreadcrumb arrow On Linux using Alloy
Grafana Cloud

Troubleshoot an Integration installation on Linux using Grafana Alloy

When installing an Integration, you can experience errors when executing Grafana Alloy installation script and errors when configuring Alloy to work with the Integration.

Common errors when executing Alloy installation script

The installation script will return an error message if there is a problem during installation. You can use these messages to identify and correct the errors.

Could not detect curl. Please install curl and re-run this script.

The script uses curl to download the Alloy installation package, so this is a pre-requisit to execute it. Curl installation method varies depending on your linux distribution, but tutorials are broadly available online.

Could not detect unzip. Please install unzip and re-run this script.

The script uses gzip to decompress the Alloy installation package, so this is a pre-requisit to execute it. Gzip installation method varies depending on your linux distribution, but tutorials are broadly available online.

Could not detect a valid Package Management System. Must be either RPM or dpkg

The script provided to install Alloy on Linux supports RPM and DEB packages. Other package systems are not supported. Make sure you have one of these packages available in your environment.

Failed to download package

The script couldn’t download the Alloy package. This is probably due to networking errors or the unavailability of an internet connection in your environment.

Failed sha256sum check

The script wasn’t able to check the Alloy package content. This can be due to networking problems during the package file download. Try again, and if the error persists, contact us using one of the options available on our official Help page.

macOS not supported

On Step 1 Select Platform of the integration installation page, select MacOS as your platform.

Unknown unsupported OS: ${uname}

Unfortunately, Alloy doesn’t yet support your Linux distribution. If you think we should support it, you can contact us using one of the options available on our official Help page or using the Feedback form.

Alloy is installed, but data doesn’t appear in Grafana Cloud

Refer to the following troubleshooting techniques if you installed Alloy, but don’t see data in Grafana Cloud.

Check that Alloy is running

  • Run systemctl status alloy and validate that Alloy is running. You should see it listed as Active: active (running). If it’s not running, run the following command systemctl start alloy and check again.

    If Alloy is running but still can’t connect to Grafana Cloud, refer to Check for errors in the Alloy log.

  • If you see Active: inactive (dead), the Alloy service has been stopped. Run systemctl start alloy and check again.

  • If you see Active: failed, Alloy has encountered a startup error. Refer to Check for errors in the Alloy log for additional troubleshooting tips.

Check for errors in the Alloy log

Run journalctl -u alloy (you may want to run this as journalctl -u alloy --no-pager if the lines are cut off). Review the output for errors.

Common errors include:

  • server returned HTTP status 401 Unauthorized: {\"status\":\"error\",\"error\":\"authentication error: invalid token\"}

    This error indicates that your access token isn’t correct. Check the password field in /etc/alloy/config.alloy and verify that it’s correct. If required, create a new token and paste it in the configuration file.

  • Error: reading config path "/etc/alloy/config.alloy": stat /etc/alloy/config.alloy: no such file or directory

    This error indicates that the Alloy configuration file isn’t present. Verify that it hasn’t been renamed, moved, or deleted. To recreate a default Alloy config, reinstall Alloy.

Any other error

Other errors might occur during installation, like exceptions when creating the systemd unit for Alloy. Check the error message for more details. If you need help, you can contact us using one of the options available on our official Help page. To give us direct feedback, use the Feedback form.

Common errors when configuring Alloy for Integrations - Test Data Connection button

You can use the Test Data Connection button on the integration setup page to verify that you configured Alloy correctly and that it is sending the expected data.

A few things can cause a check failure. Before going into detail, make sure you have restarted your Alloy service by running the following command in a terminal window:

shell 
sudo systemctl restart alloy.service

You can check the Alloy logs issuing the following command:

shell 
journalctl -u alloy.service -n 100 --no-pager

If you selected Other Distribution as your platform, Alloy has been installed using the binary package. In that case rerun the binary file to restart Alloy process. Logs are written to stdout and stderror, so the log location might change based on your setup.

If the test still fails, check the error message for more information.

No metrics were found for this integration

This message indicates that Alloy isn’t able to contact your Grafana Cloud Prometheus endpoint. This can happen for several reasons, not limited to:

  • It is still starting up. Give it a few moments to start sending data
  • It is not starting correctly due to problems in your configuration file
  • It is not able to connect to your Grafana Cloud Prometheus endpoint (networking or configuration issues)

To understand the reasons for this problem, check the Alloy logs:

shell 
journalctl -u alloy.service -n 100 --no-pager

If there are component configuration error logs, make sure you have followed all instructions provided. You can check Alloy components reference documentation for help or contact us using the Feedback form if you think there is a problem with the integration.

If you find errors about connecting to your Grafana Cloud Prometheus endpoint, make sure you didn’t change the URL or authentication details. You can verify your endpoint and create new keys under the Cloud Portal.

Alloy was not able to reach your application Prometheus metrics endpoint.

This message means that Alloy started and connected to your Grafana Cloud Prometheus endpoint, but failed to scrape your application Prometheus metrics endpoint. This can happen for several reasons, not limited to:

  • The endpoint address is incorrect
  • The endpoint is protected, and no authentication details were provided
  • The endpoint is not online

To understand the reasons for this problem, check the Alloy logs:

shell 
journalctl -u alloy.service -n 100 --no-pager

If you find that the endpoint is not online or there are authentication errors, make sure you have followed the steps under the first section of the Integration setup page, Check prerequisites specific to....

Alloy was not able to collect your application logs

This message is displayed when Alloy can’t collect logs and send them to your Grafana Cloud Loki endpoint. This can happen for several reasons, not limited to:

  • It is still starting up. Give it a few moments to start sending data
  • There are no logs available
  • The logs path is incorrect
  • Alloy does not have the necessary permissions to access your application logs
  • Alloy is not able to connect to your Grafana Cloud Loki endpoint (networking or configuration issues)

To understand the reasons for this error, check Alloy logs by running the following command in a terminal:

shell 
journalctl -u alloy.service -n 100 --no-pager

If you find permission errors, make sure you have followed the steps in the first section of the Integration setup page, Check prerequisites specific to....

If you find errors in the logs about connecting to your Grafana Cloud Loki endpoint, make sure you didn’t change the URL or authentication details. You can verify your endpoint and create new keys under the Cloud Portal.

The Alloy configuration file is empty.

The Alloy configuration file should be populated. If the Alloy configuration file is empty, check the following:

  • Verify that you’ve opened the correct file. The default Alloy configuration file is /etc/alloy/config.alloy.
  • Ensure that you have permission to edit the configuration file as it’s not readable by non-root users. You must be logged into the Linux machine as a root user or use a sudo command to edit the file, for example, sudo vi /etc/alloy/config.alloy.
  • Verify that the configuration file was correctly created during the Alloy installation. Run sudo cat /etc/alloy/config.alloy and verify that you see configuration data. If you don’t see configuration data, reinstall Alloy.

Data appears in Grafana Cloud, but hostname is incorrect or it appears as “localhost”

  1. Edit /etc/alloy/config.alloy.

    rule {
  target_label = "instance"
  replacement  = <HOSTNAME>
}


rule {
  target_label = "alloy_hostname"
  replacement  = <HOSTNAME>
}

  2. Replace <HOSTNAME with the hostname you want to see in Grafana Cloud.

    • To use a custom hostname, enclose it quotation marks, for example “my_hostname”.
    • To use the Linux system hostname, replace <HOSTNAME> with constants.hostname, with no quotation marks.

Alloy isn’t running after a reboot

If the Alloy service runs when started manually but doesn’t run after a reboot, run the following command to enable the service at boot: sudo systemctl enable alloy.