Menu
Grafana Cloud Data configuration Grafana Agent Manage Grafana Agent with systemd
Grafana Cloud

Manage Grafana Agent with systemd

This guide is for users who download the Grafana Agent binary directly or build it from source and even in those cases is completely optional. Most users get started by downloading the agent and running it directly, as instructed to do in the Grafana Cloud walkthrough inside the application.

Running the agent as a systemd service creates a long-living process that can automatically restart when killed or when the host is rebooted.

In this page we describe a way to create, manage, and enable a systemd service to automatically start at host boot time and restart. For more complex configuration possibilities, see the systemd documentation. This process requires admin rights to the host via sudo or root to create the .service file and to manage systemd.

To begin, take note of the location on the host where you installed the agent binary and the agent-config.yaml file. Note: For simplicity, we recommend you put both in the same directory.

Create a service file

We put our downloaded binary in /usr/local/bin, so our service definition will use this binary path. For this example, we renamed the downloaded binary to grafana-agent.

Create a file in /etc/systemd/system called grafana-agent.service.

You may name it something else if you like, but you must end the file with .service.

Insert the following into the file, and as you do, change the:

  • ExecStart value to match the location and name of the binary; if you put the agent-config.yaml file anywhere else, modify the location in the last part of that line
  • grafana-agent value to match the username on your host that will run the agent; we recommend creating a user specifically for the agent and running the agent as the new user, which we have intentionally named to match the service it will run
Note: To create a user, use sudo useradd --no-create-home --shell /bin/false grafana-agent, where --no-create-home and --shell /bin/false prevent the new user account from logging in directly to the server.

Contents of grafana-agent.service:

[Unit]
Description=Grafana Agent

[Service]
User=grafana-agent
ExecStart=/usr/local/bin/grafana-agent --config.file=agent-config.yaml
Restart=always

[Install]
WantedBy=multi-user.target

Restart=always tells systemd to watch this service and restart it should it cease running.

WantedBy=multi-user.target tells systemd to load this service during boot at at time after the system is running, when all network services are started and the system is available for users to log in (but before the activation of a local GUI, which doesn’t matter on a server system that doesn’t run a GUI). If this is not included, the service will not start at system boot.

Save the file and move to Step 2.

Manage your new service

Anytime you add or modify a .service file in /etc/systemd/system, you must reload the service files. To do so, enter:

sudo systemctl daemon-reload

To start the service:

sudo systemctl start grafana-agent.service

To check the status of the service:

sudo systemctl status grafana-agent.service

Checking the status will let you know whether everything is configured and running correctly, and if not, provide an error message to help you troubleshoot.

To stop the service:

sudo systemctl stop grafana-agent.service

To enable to service to run automatically on every reboot:

sudo systemctl enable grafana-agent.service

To stop the service from running automatically on every reboot:

sudo systemctl disable grafana-agent.service