OS Agent - Configuration

The Configuration tab is where you choose which OS metrics Telegraf should collect, and where you download the ready-to-paste setup files.

For now, only Telegraf is supported. The dropdown is here for future agent types.

Each checkbox maps to a Telegraf input plugin. Tick the inputs you want and click Save - the Collector regenerates the setup files on the fly.

Note: The process checkbox is labelled process in the UI but it maps to Telegraf's procstat plugin. The internal measurement name stays procstat.

CPU, mem, disk, swap, net, system, processes are checked by default. This covers the most common monitoring needs without producing too much data.

Linux-only plugins (swap, system, processes, kernel, temp) do not error on Windows - they simply produce no metrics. You can leave them enabled in the same config for both Linux and Windows hosts.

When process is enabled, the Collector tracks per-process metrics: CPU usage, memory (RSS), disk read/write, thread count.

By default, only the top 20 processes by CPU, memory, read bytes and write bytes are pushed every 30 seconds. This is done with Telegraf's topk processor:

[[processors.topk]]
  period = 30
  k = 20
  group_by = ["host"]
  fields = ["cpu_usage", "memory_rss", "read_bytes", "write_bytes"]
  namepass = ["procstat"]

This keeps the volume reasonable: even on a busy host with 1000 processes, the Collector receives at most ~80 process metrics per push (20 per field, with overlap when the same process tops in several fields).

If you really want every process on the host, tick the List all processes checkbox. This removes the topk filter from the generated config. Use with care:

• Volume can be 50-100x higher
• Each unique process_name + pid pair is a distinct series in storage
• On hosts that spawn many short-lived processes (CI agents, build hosts…) the cardinality grows fast

After ticking and saving, redeploy the agent (run the setup script again) so Telegraf picks up the new config.

Per-process disk I/O (read_bytes, write_bytes) needs special permissions:

• Linux baremetal as root: works out of the box
• Linux Docker without privileges: Docker hides /proc/<pid>/io from non-root readers - the field is empty even when telegraf runs as root inside the container. Add –cap-add SYS_PTRACE or –privileged when starting the container if you need it.
• Windows admin: works out of the box

If your host shows process names but no I/O numbers, check the Telegraf user's permissions.

At the bottom of the tab, the Collector shows a ready-to-paste wget command that downloads and runs the install script on a Linux host:

wget https://collector.example.com/api/v1/os-agent/generate?format=sh -O setup.sh && chmod +x setup.sh && sudo ./setup.sh

• The URL is built from the request URL - so it works even if your Collector is behind a reverse proxy, as long as users open the modal through the public URL
• If your Collector is not on HTTPS or uses a different port, edit the URL before pasting - the hint under the field tells you so

Three formats are available for download:

A bash script that:

1. Detects apt-get or yum
2. Adds the InfluxData repository
3. Installs the telegraf package
4. Writes /etc/telegraf/telegraf.conf from the current configuration (with the API key already filled in)
5. Enables and starts the telegraf service

Run with sudo ./setup.sh.

The Telegraf configuration file alone, without any install logic. Use it if you already have Telegraf installed and just need the right config:

• Linux: copy to /etc/telegraf/telegraf.conf and sudo systemctl restart telegraf
• Windows: copy to C:\Program Files\Telegraf\telegraf.conf and Restart-Service telegraf

A PowerShell script that:

1. Tries to fetch the latest Telegraf version from the GitHub API (5-second timeout, falls back to a built-in version)
2. Downloads the Telegraf zip from dl.influxdata.com
3. Extracts to C:\Program Files\Telegraf\
4. Writes telegraf.conf
5. Installs and starts the Windows service

Run as Administrator in PowerShell

You can generate a setup for a specific System by selecting it in the Target System dropdown. The X-API-Key embedded in the script will be the System's override key (if any), or the global key

If you do not link the host to any System, the global key is used and the host is auto-registered as standalone (it can still be linked later from the Monitor tab)

The Save button:

• Updates the in-memory config in the Collector
• Does not push the new config to the deployed agents - they keep running with their previous config until you redeploy

To apply a config change to a deployed agent, run the setup script again on the host (or just download and copy the new telegraf.conf and restart Telegraf)