Telegraf is an open-source, plugin-driven server agent built by InfluxData for collecting, processing, and writing metrics. It is part of the TICK stack (Telegraf, InfluxDB, Chronograf, Kapacitor) and supports over 300 input and output plugins out of the box. If you run infrastructure at any reasonable scale, Telegraf is one of the most practical tools for getting system and application metrics into a time-series database like InfluxDB, then visualizing them in Grafana.<\/p>\n\n\n\n
This guide walks through installing Telegraf on Debian 13 (Trixie) or Debian 12 (Bookworm) from the official InfluxData repository, configuring it to collect system and application metrics, shipping those metrics to InfluxDB v2, and building a Grafana dashboard on top of the data.<\/p>\n\n\n\n
Telegraf runs as a lightweight agent on your servers. It pulls metrics from configured inputs (CPU, memory, disk, network, Docker, Nginx, PostgreSQL, and hundreds more), applies optional processing or aggregation, and pushes the results to one or more output destinations. The most common setup pairs Telegraf with InfluxDB for storage and Grafana for visualization.<\/p>\n\n\n\n
Key characteristics:<\/p>\n\n\n\n
Before you begin, make sure you have the following in place:<\/p>\n\n\n\n
Update your system packages first:<\/p>\n\n\n\n
sudo apt update && sudo apt upgrade -y<\/code><\/pre>\n\n\n\nStep 1 – Add the InfluxData Repository<\/h2>\n\n\n\n
Telegraf is not in the default Debian repositories. You need to add the official InfluxData apt repository to get the latest stable release.<\/p>\n\n\n\n
Install the prerequisite packages:<\/p>\n\n\n\n
sudo apt install -y curl gnupg2 apt-transport-https software-properties-common<\/code><\/pre>\n\n\n\nImport the InfluxData GPG key:<\/p>\n\n\n\n
curl -fsSL https:\/\/repos.influxdata.com\/influxdata-archive_compat.key | sudo gpg --dearmor -o \/etc\/apt\/trusted.gpg.d\/influxdata-archive.gpg<\/code><\/pre>\n\n\n\nAdd the InfluxData repository:<\/p>\n\n\n\n
echo \"deb [signed-by=\/etc\/apt\/trusted.gpg.d\/influxdata-archive.gpg] https:\/\/repos.influxdata.com\/debian stable main\" | sudo tee \/etc\/apt\/sources.list.d\/influxdata.list<\/code><\/pre>\n\n\n\nVerify<\/strong> the repository file was created:<\/p>\n\n\n\ncat \/etc\/apt\/sources.list.d\/influxdata.list<\/code><\/pre>\n\n\n\nYou should see the repository line pointing to https:\/\/repos.influxdata.com\/debian stable main<\/code>.<\/p>\n\n\n\nStep 2 – Install Telegraf<\/h2>\n\n\n\n
Update the package index and install Telegraf:<\/p>\n\n\n\n
sudo apt update\nsudo apt install -y telegraf<\/code><\/pre>\n\n\n\nVerify<\/strong> the installation:<\/p>\n\n\n\ntelegraf --version<\/code><\/pre>\n\n\n\nExpected output (version number may differ):<\/p>\n\n\n\n
Telegraf 1.33.x (git: HEAD xxxxxxxx)<\/code><\/pre>\n\n\n\nStep 3 – Enable and Start Telegraf<\/h2>\n\n\n\n
Enable Telegraf to start on boot and start the service:<\/p>\n\n\n\n
sudo systemctl enable --now telegraf<\/code><\/pre>\n\n\n\nVerify<\/strong> the service is running:<\/p>\n\n\n\nsudo systemctl status telegraf<\/code><\/pre>\n\n\n\nYou should see active (running)<\/code> in the output. If it shows a failure, check the logs:<\/p>\n\n\n\nsudo journalctl -u telegraf --no-pager -n 50<\/code><\/pre>\n\n\n\nStep 4 – Configure Telegraf (telegraf.conf)<\/h2>\n\n\n\n
The main configuration file lives at \/etc\/telegraf\/telegraf.conf<\/code>. The default file is heavily commented and contains examples for every plugin. For a production setup, I recommend starting with a clean configuration and adding only what you need.<\/p>\n\n\n\nBack up the original configuration:<\/p>\n\n\n\n
sudo cp \/etc\/telegraf\/telegraf.conf \/etc\/telegraf\/telegraf.conf.bak<\/code><\/pre>\n\n\n\nGenerate a fresh config with specific plugins:<\/p>\n\n\n\n
sudo telegraf --input-filter cpu:mem:disk:diskio:net:system:docker:nginx:postgresql --output-filter influxdb_v2 config | sudo tee \/etc\/telegraf\/telegraf.conf<\/code><\/pre>\n\n\n\nThis gives you a config file with only the input and output plugins you actually need. Now edit it to match your environment:<\/p>\n\n\n\n
sudo nano \/etc\/telegraf\/telegraf.conf<\/code><\/pre>\n\n\n\nGlobal Tags and Agent Settings<\/h3>\n\n\n\n
Set global tags to identify this host in your metrics. These tags get appended to every metric Telegraf collects:<\/p>\n\n\n\n
[global_tags]\n environment = \"production\"\n datacenter = \"eu-west-1\"\n\n[agent]\n interval = \"10s\"\n round_interval = true\n metric_batch_size = 1000\n metric_buffer_limit = 10000\n collection_jitter = \"0s\"\n flush_interval = \"10s\"\n flush_jitter = \"0s\"\n precision = \"\"\n hostname = \"\"\n omit_hostname = false<\/code><\/pre>\n\n\n\nThe interval<\/code> setting controls how often Telegraf collects metrics. 10 seconds is a good default for most setups. Reduce it to 5s if you need higher resolution, but be aware of the increased load on InfluxDB.<\/p>\n\n\n\nConfigure the InfluxDB v2 Output<\/h3>\n\n\n\n
This is the output section that ships metrics to InfluxDB v2. Replace the placeholder values with your actual InfluxDB details:<\/p>\n\n\n\n
[[outputs.influxdb_v2]]\n urls = [\"http:\/\/127.0.0.1:8086\"]\n token = \"your-influxdb-api-token\"\n organization = \"your-org\"\n bucket = \"telegraf\"<\/code><\/pre>\n\n\n\nTo generate an API token in InfluxDB v2, use the InfluxDB UI or the CLI:<\/p>\n\n\n\n
influx auth create --org your-org --description \"Telegraf write token\" --write-buckets<\/code><\/pre>\n\n\n\nMake sure the bucket exists. Create it if it does not:<\/p>\n\n\n\n
influx bucket create --name telegraf --org your-org --retention 30d<\/code><\/pre>\n\n\n\nConfigure Input Plugins<\/h3>\n\n\n\n
Here are the input plugin configurations for each data source.<\/p>\n\n\n\n
CPU metrics:<\/strong><\/p>\n\n\n\n[[inputs.cpu]]\n percpu = true\n totalcpu = true\n collect_cpu_time = false\n report_active = false<\/code><\/pre>\n\n\n\nMemory metrics:<\/strong><\/p>\n\n\n\n[[inputs.mem]]\n # No additional configuration needed<\/code><\/pre>\n\n\n\nDisk metrics:<\/strong><\/p>\n\n\n\n[[inputs.disk]]\n ignore_fs = [\"tmpfs\", \"devtmpfs\", \"devfs\", \"iso9660\", \"overlay\", \"aufs\", \"squashfs\"]\n\n[[inputs.diskio]]\n # Collect I\/O stats for all devices<\/code><\/pre>\n\n\n\nNetwork metrics:<\/strong><\/p>\n\n\n\n[[inputs.net]]\n interfaces = [\"eth0\", \"ens*\"]\n ignore_protocol_stats = false<\/code><\/pre>\n\n\n\nSystem metrics<\/strong> (uptime, load, etc.):<\/p>\n\n\n\n[[inputs.system]]\n # Collects load averages, uptime, number of users<\/code><\/pre>\n\n\n\nDocker metrics<\/strong> (requires the telegraf user to be in the docker group):<\/p>\n\n\n\n[[inputs.docker]]\n endpoint = \"unix:\/\/\/var\/run\/docker.sock\"\n gather_services = false\n container_names = []\n timeout = \"5s\"\n perdevice = true\n total = false<\/code><\/pre>\n\n\n\nAdd the telegraf user to the docker group so it can access the Docker socket:<\/p>\n\n\n\n
sudo usermod -aG docker telegraf\nsudo systemctl restart telegraf<\/code><\/pre>\n\n\n\nNginx metrics<\/strong> (requires the stub_status module):<\/p>\n\n\n\n[[inputs.nginx]]\n urls = [\"http:\/\/127.0.0.1\/nginx_status\"]<\/code><\/pre>\n\n\n\nMake sure your Nginx configuration includes a stub_status location block:<\/p>\n\n\n\n
server {\n listen 127.0.0.1:80;\n location \/nginx_status {\n stub_status on;\n allow 127.0.0.1;\n deny all;\n }\n}<\/code><\/pre>\n\n\n\nPostgreSQL metrics:<\/strong><\/p>\n\n\n\n[[inputs.postgresql]]\n address = \"host=localhost user=telegraf password=yourpassword dbname=postgres sslmode=disable\"\n databases = [\"postgres\"]<\/code><\/pre>\n\n\n\nCreate a dedicated PostgreSQL user for Telegraf with read-only access:<\/p>\n\n\n\n
sudo -u postgres psql -c \"CREATE USER telegraf WITH PASSWORD 'yourpassword';\"\nsudo -u postgres psql -c \"GRANT pg_monitor TO telegraf;\"<\/code><\/pre>\n\n\n\nStep 5 – Test the Configuration<\/h2>\n\n\n\n
Before restarting Telegraf with the new config, validate it:<\/p>\n\n\n\n
sudo telegraf --config \/etc\/telegraf\/telegraf.conf --test<\/code><\/pre>\n\n\n\nThe --test<\/code> flag runs all configured input plugins once and prints the collected metrics to stdout without sending them to the output. This is the single most useful debugging command for Telegraf.<\/p>\n\n\n\nYou should see output like this:<\/p>\n\n\n\n
> cpu,cpu=cpu-total,host=debian-server usage_idle=98.5,usage_system=0.8,usage_user=0.7 1710000000000000000\n> mem,host=debian-server available=6442450944i,total=8589934592i,used=2147483648i 1710000000000000000\n> disk,device=sda1,fstype=ext4,host=debian-server,path=\/ free=42949672960i,total=107374182400i,used=64424509440i 1710000000000000000<\/code><\/pre>\n\n\n\nIf a specific input plugin has errors (for example, Docker socket permission denied), the error will show up clearly in the test output. Fix it before proceeding.<\/p>\n\n\n\n
You can also test a single input plugin in isolation:<\/p>\n\n\n\n
sudo telegraf --config \/etc\/telegraf\/telegraf.conf --input-filter cpu --test<\/code><\/pre>\n\n\n\nStep 6 – Restart Telegraf and Verify Metrics Collection<\/h2>\n\n\n\n
Apply the new configuration:<\/p>\n\n\n\n
sudo systemctl restart telegraf<\/code><\/pre>\n\n\n\nVerify<\/strong> the service restarted cleanly:<\/p>\n\n\n\nsudo systemctl status telegraf\nsudo journalctl -u telegraf --no-pager -n 20<\/code><\/pre>\n\n\n\nCheck that metrics are arriving in InfluxDB. Use the InfluxDB CLI to query:<\/p>\n\n\n\n
influx query 'from(bucket: \"telegraf\") |> range(start: -5m) |> filter(fn: (r) => r._measurement == \"cpu\") |> limit(n: 5)' --org your-org<\/code><\/pre>\n\n\n\nIf you see results, Telegraf is successfully collecting and shipping metrics to InfluxDB.<\/p>\n\n\n\n
Step 7 – View Metrics in Grafana<\/h2>\n\n\n\n
With metrics flowing into InfluxDB, you can now build Grafana dashboards to visualize the data.<\/p>\n\n\n\n
Add InfluxDB as a Data Source in Grafana<\/h3>\n\n\n\n
Open Grafana in your browser (default: http:\/\/your-server:3000<\/code>), then:<\/p>\n\n\n\n\n- Go to Connections<\/strong> – Data Sources<\/strong> – Add data source<\/strong><\/li>\n\n\n\n
- Select InfluxDB<\/strong><\/li>\n\n\n\n
- Set the query language to Flux<\/strong><\/li>\n\n\n\n
- Enter the InfluxDB URL:
http:\/\/127.0.0.1:8086<\/code><\/li>\n\n\n\n- Enter your organization name, API token, and default bucket (
telegraf<\/code>)<\/li>\n\n\n\n- Click Save & Test<\/strong> to verify the connection<\/li>\n<\/ol>\n\n\n\n
Import a Pre-built Dashboard<\/h3>\n\n\n\n
Rather than building panels from scratch, import a community dashboard. Grafana dashboard ID 928<\/strong> (Telegraf System Dashboard) works well as a starting point:<\/p>\n\n\n\n\n- Go to Dashboards<\/strong> – Import<\/strong><\/li>\n\n\n\n
- Enter dashboard ID
928<\/code> and click Load<\/strong><\/li>\n\n\n\n- Select your InfluxDB data source<\/li>\n\n\n\n
- Click Import<\/strong><\/li>\n<\/ol>\n\n\n\n
This gives you panels for CPU usage, memory usage, disk I\/O, network traffic, and system load out of the box.<\/p>\n\n\n\n
Build a Custom Panel<\/h3>\n\n\n\n
To create a custom panel, for example CPU usage over the last hour, use a Flux query like this:<\/p>\n\n\n\n
from(bucket: \"telegraf\")\n |> range(start: -1h)\n |> filter(fn: (r) => r._measurement == \"cpu\")\n |> filter(fn: (r) => r._field == \"usage_idle\")\n |> filter(fn: (r) => r.cpu == \"cpu-total\")\n |> aggregateWindow(every: 1m, fn: mean, createEmpty: false)\n |> map(fn: (r) => ({ r with _value: 100.0 - r._value }))<\/code><\/pre>\n\n\n\nThis query calculates CPU usage by subtracting idle percentage from 100, aggregated in 1-minute windows.<\/p>\n\n\n\n
Step 8 – Custom Input Plugins<\/h2>\n\n\n\n
Telegraf supports drop-in configuration files. Instead of packing everything into the main telegraf.conf<\/code>, put custom plugin configs in \/etc\/telegraf\/telegraf.d\/<\/code>. Telegraf loads all .conf<\/code> files from this directory automatically.<\/p>\n\n\n\nHTTP Response Check<\/h3>\n\n\n\n
Monitor whether your web application is responding:<\/p>\n\n\n\n
sudo tee \/etc\/telegraf\/telegraf.d\/http_response.conf <<'EOF'\n[[inputs.http_response]]\n urls = [\"https:\/\/example.com\", \"https:\/\/api.example.com\/health\"]\n response_timeout = \"5s\"\n method = \"GET\"\n follow_redirects = true\n response_string_match = \"ok\"\n [inputs.http_response.tags]\n check = \"uptime\"\nEOF<\/code><\/pre>\n\n\n\nExec Plugin – Custom Script Output<\/h3>\n\n\n\n
Run a custom script and collect its output as metrics:<\/p>\n\n\n\n
sudo tee \/etc\/telegraf\/telegraf.d\/custom_script.conf <<'EOF'\n[[inputs.exec]]\n commands = [\"\/usr\/local\/bin\/custom_metrics.sh\"]\n timeout = \"10s\"\n data_format = \"influx\"\n name_suffix = \"_custom\"\nEOF<\/code><\/pre>\n\n\n\nThe script should output data in InfluxDB line protocol format:<\/p>\n\n\n\n
#!\/bin\/bash\n# \/usr\/local\/bin\/custom_metrics.sh\necho \"app_queue_depth,queue=email value=$(wc -l < \/var\/spool\/mail\/queue 2>\/dev\/null || echo 0)\"<\/code><\/pre>\n\n\n\nPrometheus Input<\/h3>\n\n\n\n
Scrape any Prometheus-compatible metrics endpoint:<\/p>\n\n\n\n
sudo tee \/etc\/telegraf\/telegraf.d\/prometheus.conf <<'EOF'\n[[inputs.prometheus]]\n urls = [\"http:\/\/localhost:9090\/metrics\", \"http:\/\/localhost:8080\/metrics\"]\n metric_version = 2\nEOF<\/code><\/pre>\n\n\n\nAfter adding any new plugin configs, restart Telegraf:<\/p>\n\n\n\n
sudo systemctl restart telegraf\nsudo telegraf --config \/etc\/telegraf\/telegraf.conf --config-directory \/etc\/telegraf\/telegraf.d --test<\/code><\/pre>\n\n\n\nStep 9 – Monitoring System Services<\/h2>\n\n\n\n
Telegraf can monitor the state of systemd services, which is useful for alerting when a service goes down.<\/p>\n\n\n\n
sudo tee \/etc\/telegraf\/telegraf.d\/systemd_services.conf <<'EOF'\n[[inputs.systemd_units]]\n unittype = \"service\"\n pattern = \"nginx* postgresql* docker* influxdb* grafana*\"\n timeout = \"5s\"\nEOF<\/code><\/pre>\n\n\n\nThis plugin reports the active state, load state, and sub state of each matched service. You can then set up Grafana alerts to notify you when any service leaves the “running” state.<\/p>\n\n\n\n
Verify<\/strong> the systemd service monitoring is working:<\/p>\n\n\n\nsudo telegraf --config \/etc\/telegraf\/telegraf.d\/systemd_services.conf --test<\/code><\/pre>\n\n\n\nTroubleshooting<\/h2>\n\n\n\n
Here are the most common issues you will run into and how to fix them.<\/p>\n\n\n\n
Telegraf fails to start<\/h3>\n\n\n\n
Check the journal for the exact error:<\/p>\n\n\n\n
sudo journalctl -u telegraf --no-pager -n 100<\/code><\/pre>\n\n\n\nMost startup failures come from syntax errors in the config file. Validate the configuration:<\/p>\n\n\n\n
sudo telegraf --config \/etc\/telegraf\/telegraf.conf --test 2>&1 | head -20<\/code><\/pre>\n\n\n\nPermission denied on Docker socket<\/h3>\n\n\n\n
The telegraf user needs to be in the docker group:<\/p>\n\n\n\n
sudo usermod -aG docker telegraf\nsudo systemctl restart telegraf<\/code><\/pre>\n\n\n\nVerify group membership:<\/p>\n\n\n\n
groups telegraf<\/code><\/pre>\n\n\n\nMetrics not appearing in InfluxDB<\/h3>\n\n\n\n
Check the following in order:<\/p>\n\n\n\n
\n- Is Telegraf running?<\/strong> –
sudo systemctl status telegraf<\/code><\/li>\n\n\n\n- Is the output config correct?<\/strong> – Verify the URL, token, org, and bucket in the
[[outputs.influxdb_v2]]<\/code> section<\/li>\n\n\n\n- Can Telegraf reach InfluxDB?<\/strong> –
curl -s http:\/\/127.0.0.1:8086\/health<\/code><\/li>\n\n\n\n- Is the API token valid?<\/strong> – Check for 401 errors in the Telegraf logs<\/li>\n\n\n\n
- Does the bucket exist?<\/strong> –
influx bucket list --org your-org<\/code><\/li>\n<\/ol>\n\n\n\nNginx input plugin returns connection refused<\/h3>\n\n\n\n
Make sure the stub_status module is enabled and the URL in Telegraf matches the Nginx config:<\/p>\n\n\n\n
curl http:\/\/127.0.0.1\/nginx_status<\/code><\/pre>\n\n\n\nIf this returns “Active connections” and connection stats, Nginx is configured correctly. If not, check your Nginx configuration and reload it:<\/p>\n\n\n\n
sudo nginx -t && sudo systemctl reload nginx<\/code><\/pre>\n\n\n\nPostgreSQL authentication failure<\/h3>\n\n\n\n
Verify the telegraf database user can connect:<\/p>\n\n\n\n
psql -h localhost -U telegraf -d postgres -c \"SELECT 1;\"<\/code><\/pre>\n\n\n\nIf this fails, check pg_hba.conf<\/code> for local authentication rules and make sure the password is correct in the Telegraf config.<\/p>\n\n\n\nHigh memory usage<\/h3>\n\n\n\n
If Telegraf is using too much memory, reduce the buffer sizes in the agent section:<\/p>\n\n\n\n
[agent]\n metric_batch_size = 500\n metric_buffer_limit = 5000<\/code><\/pre>\n\n\n\nAlso check if any input plugin is collecting an unexpectedly large number of series (common with Docker or Kubernetes plugins on busy hosts).<\/p>\n\n\n\n
Debug mode<\/h3>\n\n\n\n
For detailed debugging, run Telegraf in the foreground with debug logging:<\/p>\n\n\n\n
sudo telegraf --config \/etc\/telegraf\/telegraf.conf --debug<\/code><\/pre>\n\n\n\nThis prints every metric collected and every write to the output, which makes it straightforward to identify where things break down.<\/p>\n\n\n\n
Conclusion<\/h2>\n\n\n\n
You now have Telegraf running on Debian 13 or Debian 12, collecting system metrics (CPU, memory, disk, network), application metrics (Docker, Nginx, PostgreSQL), and shipping everything to InfluxDB v2. With Grafana connected to InfluxDB, you have a full monitoring pipeline from data collection through visualization.<\/p>\n\n\n\n
The drop-in config directory at \/etc\/telegraf\/telegraf.d\/<\/code> makes it easy to add new data sources as your infrastructure grows. Add a new .conf<\/code> file, restart Telegraf, and the metrics start flowing. For a full list of available plugins, check the official Telegraf plugin documentation<\/a>.<\/p>\n\n","protected":false},"excerpt":{"rendered":"Telegraf is an open-source, plugin-driven server agent built by InfluxData for collecting, processing, and writing metrics. It is part of the TICK stack (Telegraf, InfluxDB, Chronograf, Kapacitor) and supports over 300 input and output plugins out of the box. If you run infrastructure at any reasonable scale, Telegraf is one of the most practical tools … Read more<\/a><\/p>\n","protected":false},"author":3,"featured_media":35857,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[165,26,299,50],"tags":[342,393],"class_list":["post-35808","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-monitoring","category-debian","category-how-to","category-linux-tutorials","tag-monitoring","tag-telegraf"],"_links":{"self":[{"href":"https:\/\/computingforgeeks.com\/wp-json\/wp\/v2\/posts\/35808","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/computingforgeeks.com\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/computingforgeeks.com\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/computingforgeeks.com\/wp-json\/wp\/v2\/users\/3"}],"replies":[{"embeddable":true,"href":"https:\/\/computingforgeeks.com\/wp-json\/wp\/v2\/comments?post=35808"}],"version-history":[{"count":2,"href":"https:\/\/computingforgeeks.com\/wp-json\/wp\/v2\/posts\/35808\/revisions"}],"predecessor-version":[{"id":164142,"href":"https:\/\/computingforgeeks.com\/wp-json\/wp\/v2\/posts\/35808\/revisions\/164142"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/computingforgeeks.com\/wp-json\/wp\/v2\/media\/35857"}],"wp:attachment":[{"href":"https:\/\/computingforgeeks.com\/wp-json\/wp\/v2\/media?parent=35808"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/computingforgeeks.com\/wp-json\/wp\/v2\/categories?post=35808"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/computingforgeeks.com\/wp-json\/wp\/v2\/tags?post=35808"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}