Install Telegraf on VPS to Collect Metrics for InfluxDB

June 2026 · 8 min read

Telegraf is a lightweight agent that collects system metrics from your VPS such as CPU, memory, disk, and network information, then sends them to InfluxDB for time-series storage. Combined with Grafana for visualization, this powerful monitoring stack allows you to track system performance, diagnose issues, and plan capacity expansion. Telegraf uses minimal resources and supports numerous plugins for monitoring MySQL, Nginx, Docker, and much more.

What is Telegraf and Why Use It

Telegraf is a plugin-driven metrics collection agent written in Go. It is extremely lightweight and fast, capable of gathering metrics from various sources including system resources (CPU, memory, disk, network), database servers, web servers, containers, and custom applications. The collected data is sent to time-series databases like InfluxDB where it can be stored, queried, and visualized.

Key benefits of using Telegraf include:

• Time-series data collection: Metrics are recorded with precise timestamps, enabling analysis of system behavior over time and trend detection.
• Troubleshooting: Historical metric data helps identify the root causes of performance issues and anomalies.
• Capacity planning: Metrics provide insights into resource usage patterns, helping predict when upgrades are needed.
• Alerting: Set up automated alerts when metrics exceed predefined thresholds.

Installation Steps for Telegraf

Since Telegraf is distributed by InfluxData, we need to add their official repository first. This guide covers Ubuntu and Debian-based systems.

1. Add InfluxDB Repository

Open a terminal and run the following commands to add the GPG key and repository:

curl -s https://repos.influxdata.com/influxdata-archive_compat.key | gpg --dearmor | sudo tee /usr/share/keyrings/influxdata-archive-compat.gpg > /dev/null
echo 'deb [signed-by=/usr/share/keyrings/influxdata-archive-compat.gpg] https://repos.influxdata.com/debian stable main' | sudo tee /etc/apt/sources.list.d/influxdata.list

2. Update Package List and Install Telegraf

sudo apt-get update
sudo apt-get install -y telegraf

During installation, the system may ask for confirmation. Press y and Enter to proceed.

3. Start Telegraf Service

sudo systemctl start telegraf
sudo systemctl enable telegraf

The enable command ensures Telegraf starts automatically when your VPS reboots.

Basic Telegraf Configuration

The main Telegraf configuration file is located at /etc/telegraf/telegraf.conf. This file is well-organized and contains three main sections: global tags, agent settings, input plugins (data collection), and output plugins (where to send data).

Viewing the Configuration File

sudo cat /etc/telegraf/telegraf.conf | head -50

Editing Configuration to Set InfluxDB Output

Open the configuration file using nano or vim:

sudo nano /etc/telegraf/telegraf.conf

Find the section labeled [[outputs.influxdb]] (around lines 90-110) and modify it as follows:

[[outputs.influxdb]]
  urls = ["http://localhost:8086"]
  database = "telegraf"
  username = "telegraf"
  password = "telegraf_password"
  retention_policy = ""
  write_consistency = "any"
  timeout = "5s"

In this configuration, Telegraf will send metrics to InfluxDB running on the local machine at port 8086, authenticating with the username telegraf and password telegraf_password, and storing data in the database named telegraf.

Configuring Input Plugins for Different Services

Telegraf includes many input plugins that can be selectively enabled. Below are examples of configuring popular plugins for monitoring different aspects of your system.

CPU, Memory, and Disk Usage Plugins (Enabled by Default)

The plugins cpu, mem, disk, diskio, and net are typically enabled in the default configuration. Look for their sections in the config file:

[[inputs.cpu]]
  percpu = true
  totalcpu = true
  collect_cpu_time = false

[[inputs.mem]]

[[inputs.disk]]
  ignore_fs = ["tmpfs", "devtmpfs", "devfs"]

[[inputs.net]]

MySQL Monitoring Plugin

To monitor MySQL database performance, find the [[inputs.mysql]] section and configure it:

[[inputs.mysql]]
  servers = ["user:password@tcp(127.0.0.1:3306)/"]
  metric_collection_interval = "30s"
  gather_global_variables = true
  gather_slave_status = false
  gather_table_io_waits = false
  gather_index_io_waits = false
  gather_event_waits = false

Replace user and password with the actual MySQL credentials that have appropriate privileges.

Nginx Monitoring Plugin

For Nginx web server monitoring, locate the [[inputs.nginx]] section:

[[inputs.nginx]]
  urls = ["http://localhost:8080/nginx_status"]

Before using this plugin, ensure that Nginx has the stub_status module enabled in /etc/nginx/nginx.conf:

server {
  listen 8080;
  location /nginx_status {
    stub_status on;
    access_log off;
    allow 127.0.0.1;
    deny all;
  }
}

Docker Monitoring Plugin

If your VPS runs Docker containers, enable the Docker plugin:

[[inputs.docker]]
  endpoint = "unix:///var/run/docker.sock"
  gather_services = false
  container_names = []
  container_name_include = []
  container_name_exclude = []
  timeout = "5s"
  perdevice = true
  total = true

Ensure that the telegraf user has permission to access the Docker socket:

sudo usermod -aG docker telegraf

Saving Changes and Restarting Telegraf

After making changes to the configuration file, save your modifications (in nano, press Ctrl+O then Enter; press Ctrl+X to exit). Then restart the Telegraf service:

sudo systemctl restart telegraf

Check the status to ensure it started successfully:

sudo systemctl status telegraf

Verify Telegraf is Working

Use the following commands to verify that Telegraf is running and successfully sending metrics to InfluxDB.

Check Service Status

sudo systemctl status telegraf

You should see active (running) in the output. If it shows failed, there is likely a configuration error.

View Real-time Logs

sudo journalctl -u telegraf -f

This command displays live logs from Telegraf. Watch for any error messages. Press Ctrl+C to exit.

Test Configuration and Output

telegraf --config /etc/telegraf/telegraf.conf --test 2>&1 | head -100

If the configuration is correct, this command will display a sample of the metrics Telegraf will collect and send.

Troubleshooting Common Issues

Error: Connection Refused to InfluxDB

Symptom: Logs show the message failed to write to InfluxDB: connection refused

Cause: InfluxDB service is not running, or the port number is incorrect.

Solution:

# Check if InfluxDB is running
sudo systemctl status influxdb

# Verify port 8086 is listening
sudo netstat -tulpn | grep 8086

# Start InfluxDB if it's not running
sudo systemctl start influxdb

Error: MySQL Permission Denied

Symptom: Error in plugin [inputs.mysql]: Error opening MySQL connection: access denied for user

Cause: Incorrect MySQL username or password, or the user lacks necessary privileges.

Solution:

# Log into MySQL
mysql -u root -p

# Create a new user for Telegraf
CREATE USER 'telegraf'@'localhost' IDENTIFIED BY 'telegraf_password';
GRANT PROCESS, REPLICATION CLIENT ON *.* TO 'telegraf'@'localhost';
FLUSH PRIVILEGES;
EXIT;

Update telegraf.conf with the new credentials and restart:

sudo systemctl restart telegraf

Error: Docker Socket Permission Denied

Symptom: Error in plugin [inputs.docker]: Cannot connect to Docker daemon socket

Cause: The telegraf user does not have permission to access the Docker socket.

Solution:

sudo usermod -aG docker telegraf
sudo systemctl restart telegraf

Error: Configuration File Syntax Error

Symptom: Error loading config file: error parsing telegraf.conf

Cause: Syntax error in the configuration file after editing.

Solution:

# Test the configuration
telegraf --config /etc/telegraf/telegraf.conf --test

# Open and review the configuration file
sudo nano /etc/telegraf/telegraf.conf

# Common issues are mismatched brackets or unclosed quotes

Frequently Asked Questions

How long can I store metric data?

The data retention period depends on the retention policy configured in InfluxDB. By default, most configurations retain data for 30 days. To store data longer, modify the retention policy in InfluxDB's admin interface or via the CLI command line tool.

How much CPU and memory does Telegraf use?

Telegraf is very lightweight. It typically uses less than 1% CPU and around 30-50 MB of RAM. Resource consumption depends on the number of enabled plugins and the data collection frequency. To reduce resource usage, disable unnecessary plugins or increase the collection interval.

How frequently are metrics sent to InfluxDB?

By default, Telegraf collects and sends metrics every 10 seconds. This interval can be adjusted in the configuration file by modifying the interval and flush_interval parameters. For more frequent collection, decrease these values, but be aware this increases bandwidth and CPU usage.