Troubleshoot an Integration installation on Linux using Grafana Agent

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

Common errors when executing the Agent 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 the Agent on Linux supports RPM and DEB packages. Other package systems are not supported. Make sure you have either of those available in your environment.

`Failed to download package`

The script was not able to download the Agent package. This is probably due to networking errors or the unavailability of an internet connection in your environment.

`Failed sha256sum check`

The script was not able to check the Agent 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, the Agent does not 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.

Any other error

Other errors might occur during installation, like exceptions when creating the systemd unit for the Agent. Check the error message for more details. If you need help, contact us using one of the options available on our official Help page, or contact us using the Feedback form if you think there is a problem with the integration.

Common errors when configuring the Agent for Integrations - Test Data Connection button

You can use the Test Data Connection button on the integration setup page to verify that you configured your Agent 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 Agent service by running the following command in a terminal window:

sudo systemctl restart grafana-agent.service

You can check the Alloy logs issuing the following command:

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

If you selected Other Distribution as your platform, the agent has been installed using the binary package. In that case rerun the binary file to restart the agent 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 the Agent is not able to contact your Grafana Cloud Prometheus endpoint. This can happen for several reasons, not limited to:

Agent is not starting correctly due to problems in your configuration file syntax or indentation
Agent is not being able to connect to your Grafana Cloud Prometheus endpoint (networking or configuration issues)

To understand the reasons for this problem, please check the Agent logs, issuing the following command on a terminal:

journalctl -u grafana-agent.service -n 100 --no-pager

If you find errors in the logs about loading the YAML configuration file, make sure you have placed the snippets in the correct sections and with the right YAML indentation and syntax. Make sure you have placed metrics snippets under metrics.configs.scrape_configs, logs snippets under logs.configs.scrape_configs, and integrations (exporters) snippets under integrations.

If you find errors in the logs about connecting to your Grafana Cloud Prometheus endpoint, make sure you didn’t change the prometheus_remote_write URL or authentication details. You can verify your endpoint and create new keys under the Cloud Portal, or contact us using the Feedback form if you think there is a problem with the integration.

Agent was not able to reach your application prometheus metrics endpoint.

This message means that the Agent 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, please check the Agent logs, issuing the following command on a terminal:

journalctl -u grafana-agent.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....

Agent was not able to collect your application logs

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

There are no logs available
The logs path is incorrect
Agent does not have the necessary permissions to access your application logs
Agent is not being able to connect to your Grafana Cloud Loki endpoint (networking or configuration issues)

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

journalctl -u grafana-agent.service -n 100 --no-pager

If you find that there are permission errors, make sure you have followed the steps under 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 logs URL or authentication details. You can verify your endpoint and create new keys under the Cloud Portal, or contact us using the Feedback form if you think there is a problem with the integration.