Install Grafana Agent on EC2: A Step-by-Step Guide

In this article, we’ll walk you through the process of installing Grafana Agent on an Amazon EC2 instance. The Grafana Agent is a lightweight, flexible telemetry collector that gathers metrics, logs, and traces from your systems and applications, forwarding them to Grafana Cloud or your own Grafana instance. This is super useful for monitoring your infrastructure and applications, giving you insights into performance and helping you troubleshoot issues quickly.

Prerequisites

Before we dive in, make sure you have the following:

• An active AWS account.
• An EC2 instance up and running. I recommend using Ubuntu or Amazon Linux 2 for this guide, but most Linux distributions will work.
• SSH access to your EC2 instance.
• Basic knowledge of Linux command-line operations.
• A Grafana Cloud account (or your own Grafana instance).

Step 1: Connect to Your EC2 Instance

First things first, you need to connect to your EC2 instance using SSH. Open your terminal and use the following command, replacing your_key.pem with the path to your SSH key and your_instance_public_ip with the public IP address of your EC2 instance:

ssh -i "your_key.pem" ubuntu@your_instance_public_ip

If you’re using a different user or a different operating system, adjust the command accordingly. For example, if you’re using Amazon Linux 2, the user might be ec2-user instead of ubuntu .

Once you’re connected, you’re ready to start installing the Grafana Agent.

Step 2: Download the Grafana Agent

Next, you’ll need to download the Grafana Agent package. Grafana provides pre-built packages for various operating systems and architectures. To find the correct package for your system, head over to the official Grafana Agent downloads page. As of writing this, the latest version is something like v0.39.2, but always check for the newest release.

On your EC2 instance, use wget to download the appropriate package. For example, to download the Linux AMD64 package, you might use a command like this (but replace the version number with the latest):

wget https://github.com/grafana/agent/releases/download/v0.39.2/grafana-agent-linux-amd64.zip

If you don’t have wget installed, you can install it with:

sudo apt update
sudo apt install wget

Adjust the wget command based on the specific package URL for your architecture and OS.

Step 3: Extract the Package

After downloading the package, you need to extract it. Since we downloaded a ZIP file, you can use the unzip command:

sudo apt install unzip
unzip grafana-agent-linux-amd64.zip

This will extract the grafana-agent executable to the current directory. If you prefer using tar.gz archives, the process is similar, just use tar -xvzf <filename.tar.gz> instead. Make sure you have tar installed ( sudo apt install tar if needed).

Step 4: Move the Executable to /usr/local/bin

To make the grafana-agent executable easily accessible, it’s a good practice to move it to /usr/local/bin . This directory is typically included in the system’s PATH, so you can run the agent from any location.

sudo mv grafana-agent /usr/local/bin/

After moving the executable, make it executable:

sudo chmod +x /usr/local/bin/grafana-agent

Now, you can verify that the agent is installed correctly by running:

grafana-agent --version

This should print the version of the Grafana Agent.

Step 5: Create a Grafana Agent Configuration File

The Grafana Agent is configured using a YAML file. Create a new file named agent.yaml in a suitable directory, such as /etc/grafana-agent/ . You might need to create the directory first:

sudo mkdir /etc/grafana-agent
sudo nano /etc/grafana-agent/agent.yaml

Now, let’s add a basic configuration. Here’s an example agent.yaml :

server:
  log_level: info

metrics:
  wal_directory: /tmp/grafana-agent-wal
  configs:
  - name: default
    remote_write:
    - url: "YOUR_GRAFANA_CLOUD_REMOTE_WRITE_URL"
      basic_auth:
        username: "YOUR_GRAFANA_CLOUD_USERNAME"
        password: "YOUR_GRAFANA_CLOUD_API_KEY"

logs:
  configs:
  - name: default
    clients:
    - url: "YOUR_GRAFANA_CLOUD_LOGS_URL"
      basic_auth:
        username: "YOUR_GRAFANA_CLOUD_USERNAME"
        password: "YOUR_GRAFANA_CLOUD_API_KEY"
    scrape_configs:
    - job_name: system
      static_configs:
      - targets:
        - localhost
        labels:
          job: varlogs
          __path__: /var/log/*log

Replace YOUR_GRAFANA_CLOUD_REMOTE_WRITE_URL , YOUR_GRAFANA_CLOUD_USERNAME , and YOUR_GRAFANA_CLOUD_API_KEY with your Grafana Cloud details. You can find these details in your Grafana Cloud account under the “Metrics” and “Logs” sections.

This configuration tells the agent to collect metrics and logs and send them to your Grafana Cloud instance. The wal_directory specifies where the agent will store temporary data in case of network issues, ensuring no data is lost. The scrape_configs section under logs defines how logs are collected, in this case, it’s set up to collect all *.log files from /var/log/ .

Step 6: Create a Systemd Service File

To run the Grafana Agent as a service, you’ll need to create a systemd service file. This allows the agent to start automatically on boot and be managed using systemctl .

Create a new file named grafana-agent.service in /etc/systemd/system/ :

sudo nano /etc/systemd/system/grafana-agent.service

Add the following content to the file:

[Unit]
Description=Grafana Agent
Wants=network-online.target
After=network-online.target

[Service]
User=root
Group=root
Type=simple
ExecStart=/usr/local/bin/grafana-agent -config.file=/etc/grafana-agent/agent.yaml
Restart=on-failure

[Install]
WantedBy=multi-user.target

This service file specifies that the Grafana Agent should be run as the root user (you can change this if you prefer), and it points to the configuration file we created earlier. The Restart=on-failure setting ensures that the agent will automatically restart if it crashes.

Step 7: Start and Enable the Grafana Agent Service

Now that you’ve created the service file, you can start and enable the Grafana Agent service.

First, reload the systemd daemon to recognize the new service file:

sudo systemctl daemon-reload

Then, start the Grafana Agent service:

sudo systemctl start grafana-agent

Check the status of the service to make sure it’s running correctly:

sudo systemctl status grafana-agent

If the service is running without errors, you can enable it to start automatically on boot:

sudo systemctl enable grafana-agent

Step 8: Verify Data in Grafana Cloud

Finally, log in to your Grafana Cloud account and navigate to the Metrics and Logs dashboards. You should see data coming in from your EC2 instance. It might take a few minutes for the data to appear, so be patient.

If you don’t see any data, double-check your configuration file and make sure your Grafana Cloud credentials are correct. You can also check the Grafana Agent logs for any errors:

sudo journalctl -u grafana-agent

This command will show you the logs from the Grafana Agent service, which can help you troubleshoot any issues.

Conclusion

Alright, guys, you’ve successfully installed and configured the Grafana Agent on your EC2 instance! Now you can monitor your system’s metrics and logs in Grafana Cloud, giving you valuable insights into its performance and health. Remember to customize the configuration file to collect the specific metrics and logs that are important to you. Happy monitoring!