Install Telegraf
This page provides directions for installing, starting, and configuring Telegraf. To install Telegraf, do the following:
Requirements
Installation of the Telegraf package may require root
or administrator privileges to complete successfully.
Networking
Telegraf offers multiple service input plugins that may
require custom ports.
Modify port mappings through the configuration file (telegraf.conf
).
For Linux distributions, this file is located at /etc/telegraf
for default installations.
For Windows distributions, the configuration file is located in the directory where you unzipped the Telegraf ZIP archive.
The default location is C:\InfluxData\telegraf
.
NTP
Telegraf uses a host’s local time in UTC to assign timestamps to data. Use the Network Time Protocol (NTP) to synchronize time between hosts. If hosts’ clocks aren’t synchronized with NTP, the timestamps on the data might be inaccurate.
Download and install Telegraf
Recommended:: Before you open and install packages and downloaded files, use SHA checksum verification and GPG signature verification to ensure the files are intact and authentic.
SHA checksum and GPG signature verification are complementary checks.
For some Linux platforms, the installation instructions include steps to verify downloaded packages and binaries.
For more information, see the following:
Ubuntu & Debian RedHat & CentOS SLES & openSUSE FreeBSD/PC-BSD Linux binaries (AMD) Linux binaries (ARM) macOS Windows
Debian and Ubuntu users can install the latest stable version of Telegraf using
the apt-get
package manager.
Install from the InfluxData repository
Run the following commands using apt-get
to install Telegraf from the InfluxData
repository:
curl --silent --location -O \
https://repos.influxdata.com/influxdata-archive.key \
&& echo "943666881a1b8d9b849b74caebf02d3465d6beb716510d86a39f6c8e8dac7515 influxdata-archive.key" \
| sha256sum -c - && cat influxdata-archive.key \
| gpg --dearmor \
| sudo tee /etc/apt/trusted.gpg.d/influxdata-archive.gpg > /dev/null \
&& 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
sudo apt-get update && sudo apt-get install telegraf
# influxdata-archive_compat.key GPG Fingerprint: 9D539D90D3328DC7D6C8D3B9D8FF8E1F7DF8B07E
curl --silent --location -O \
https://repos.influxdata.com/influxdata-archive_compat.key \
&& echo "393e8779c89ac8d958f81f942f9ad7fb82a25e133faddaf92e15b16e6ac9ce4c influxdata-archive_compat.key" \
| sha256sum -c - \
&& cat influxdata-archive_compat.key \
| gpg --dearmor \
| sudo tee /etc/apt/trusted.gpg.d/influxdata-archive_compat.gpg > /dev/null
echo 'deb [signed-by=/etc/apt/trusted.gpg.d/influxdata-archive_compat.gpg] https://repos.influxdata.com/debian stable main' \
| sudo tee /etc/apt/sources.list.d/influxdata.list
sudo apt-get update && sudo apt-get install telegraf
Install from a .deb
file
To manually install the Debian package from a .deb
file:
Download the latest Telegraf
.deb
release from the downloads page.Run the following command (making sure to supply the correct version number for the downloaded file):
sudo dpkg -i telegraf_1.32.3-1_amd64.deb
To learn how to manually install the RPM package from a file, see the downloads page.
To use the yum
package manager to install the latest stable version of Telegraf, follow these steps:
In your terminal, enter the following command to add the InfluxData repository to the
yum
configuration:cat <<EOF | sudo tee /etc/yum.repos.d/influxdata.repo [influxdata] name = InfluxData Repository - Stable baseurl = https://repos.influxdata.com/stable/$basearch/main enabled = 1 gpgcheck = 1 gpgkey = file:///etc/pki/rpm-gpg/RPM-GPG-KEY-influxdata EOF
Enter the following command to install
telegraf
from the repository.sudo yum install telegraf
The telegraf
configuration file is installed at /etc/telegraf/telegraf.conf
.
The openSUSE Build Service provides RPM packages for SUSE Linux.
To use the zypper
package manager to install the latest stable version of Telegraf, follow these steps:
In your terminal, enter the following command to add the Go repository to the
zypper
configuration:# add go repository zypper ar -f obs://devel:languages:go/ go
Enter the following command to install
telegraf
.# install latest telegraf zypper in telegraf
Telegraf is part of the FreeBSD package system.
To use the pkg
package manager to install the latest stable version of Telegraf, enter the following command:
sudo pkg install telegraf
The telegraf
configuration file is installed at /usr/local/etc/telegraf.conf
.
Examples are installed at /usr/local/etc/telegraf.conf.sample
.
Choose from the following options to install Telegraf binary files for Linux AMD:
- To install on Linux AMD32, see the downloads page.
- Download and install on Linux AMD64
Download and install on Linux AMD64
curl -s --location -O \
https://dl.influxdata.com/telegraf/releases/telegraf-1.32.3_linux_amd64.tar.gz \
&& echo "260bc3170dbd6cce67575c1215a0b89b8447945106e2943d74e617d06b750c03 telegraf-1.32.3_linux_amd64.tar.gz" \
| sha256sum -c -
Replace the following:
260bc3170dbd6cce67575c1215a0b89b8447945106e2943d74e617d06b750c03
: the SHA checksum from the downloads page
Choose from the following options to install Telegraf binary files for Linux ARM:
- To install on Linux ARMv7(32-bit), see the downloads page.
- Download and install on Linux ARMv8 (64-bit)
Download and install on Linux ARMv8
curl -s --location -O \
https://dl.influxdata.com/telegraf/releases/telegraf-1.32.3_linux_arm64.tar.gz \
&& echo "f0d8ccae539afa04b171d5268dbab21eef58bc51b5437689e347619e2097c824 telegraf-1.32.3_linux_arm64.tar.gz" \
| sha256sum -c -
Replace the following:
f0d8ccae539afa04b171d5268dbab21eef58bc51b5437689e347619e2097c824
: the SHA checksum from the downloads page
Choose from the following options to install Telegraf for macOS:
- To manually install Telegraf from a file, see the downloads page.
- Install using Homebrew
Install using Homebrew
Users of macOS 10.8 and higher can install Telegraf using the Homebrew package manager.
The telegraf
binary installed by Homebrew differs from the macOS .dmg
builds available from the downloads page.
telegraf
(Homebrew) isn’t a static binary.telegraf
(Homebrew) works with the Telegraf CPU plugin (due to Homebrew support for Cgo). The.dmg
builds available on the downloads page don’t support the CPU plugin.
To install using Homebrew, do the following:
If you haven’t already, follow the instructions to install the Homebrew package manager.
Enter the following commands to update brew and install Telegraf:
brew update && brew install telegraf
The path where
brew
installs thetelegraf.conf
configuration file depends on your system architecture:- ARM-based (Apple Silicon) systems:
/opt/homebrew/etc/telegraf.conf
- Intel-based (x86_64) systems:
/usr/local/etc/telegraf.conf
- ARM-based (Apple Silicon) systems:
Choose one of the following methods to start Telegraf and begin collecting and processing metrics:
Run Telegraf in your terminal
To run telegraf
in your terminal (in the foreground and not as a service), enter the following command:
telegraf -config /opt/homebrew/etc/telegraf.conf
telegraf -config /usr/local/etc/telegraf.conf
Run Telegraf as a background service
In your terminal, enter the following command to add telegraf
to your system’s LaunchAgents
:
ln -sfv /opt/homebrew/opt/telegraf/*.plist ~/Library/LaunchAgents
ln -sfv /usr/local/opt/telegraf/*.plist ~/Library/LaunchAgents
The next time you login, launchd starts the telegraf
service.
To immediately start the telegraf
service, enter the following command:
launchctl load ~/Library/LaunchAgents/homebrew.mxcl.telegraf.plist
Download and run Telegraf as a Windows service
Installing a Windows service requires administrative permissions. To run PowerShell as an administrator, see Launch PowerShell as administrator.
In PowerShell as an administrator, do the following:
Use the following commands to download the Telegraf Windows binary and extract its contents to
C:\Program Files\InfluxData\telegraf\
:wget ` https://dl.influxdata.com/telegraf/releases/telegraf-1.32.3_windows_amd64.zip ` -UseBasicParsing ` -OutFile telegraf-1.32.3_windows_amd64.zip Expand-Archive .\telegraf-1.32.3_windows_amd64.zip ` -DestinationPath 'C:\Program Files\InfluxData\telegraf\'
Choose one of the following steps to place your
telegraf.exe
andtelegraf.conf
files inC:\Program Files\InfluxData\telegraf
:Move the
telegraf.exe
andtelegraf.conf
files fromC:\Program Files\InfluxData\telegraf\telegraf-1.32.3
to the parent directoryC:\Program Files\InfluxData\telegraf
–for example:cd "C:\Program Files\InfluxData\telegraf"; mv .\telegraf-1.32.3\telegraf.* .
Or, create a Windows symbolic link (Symlink) for
C:\Program Files\InfluxData\telegraf
that points to the extracted directory.
The remaining instructions assume that telegraf.exe
and telegraf.conf
files are stored in
C:\Program Files\InfluxData\telegraf
or that you created a Symlink to point to this directory.
Optional: Enable a plugin to collect Windows-specific metrics–for example, uncomment the
inputs.win_services
plugin configuration line:... # # Input plugin to report Windows services info. # # This plugin ONLY supports Windows [[inputs.win_services]] ...
Run the following command to install Telegraf and the configuration as a Windows service. For the
--config
option, pass the absolute path of thetelegraf.conf
configuration file..\telegraf.exe --service install ` --config "C:\Program Files\InfluxData\telegraf\telegraf.conf"
To test that the installation works, enter the following command:
.\telegraf.exe ` --config C:\"Program Files"\InfluxData\telegraf\telegraf.conf --test
When run in test mode (using the
--test
flag), Telegraf runs once, collects metrics, outputs them to the console, and then exits. It doesn’t run processors, aggregators, or output plugins.To start collecting data, run:
.\telegraf.exe --service start
Logging and troubleshooting
When Telegraf runs as a Windows service, Telegraf logs messages to Windows event logs. If the Telegraf service fails to start, view error logs by selecting Event Viewer→Windows Logs→Application.
Windows service commands
The following commands are available:
Command | Effect |
---|---|
telegraf.exe --service install | Install telegraf as a service |
telegraf.exe --service uninstall | Remove the telegraf service |
telegraf.exe --service start | Start the telegraf service |
telegraf.exe --service stop | Stop the telegraf service |
Generate a configuration file
The telegraf config
command lets you generate a configuration file from
Telegraf’s plugin list.
- Create a configuration file with default input and output plugins
- Create a configuration with specific input and output plugins
Create a configuration file with default input and output plugins
To generate a configuration file with default input and output plugins enabled, enter the following command in your terminal:
Create a configuration file with specific input and output plugins
To generate a configuration file that contains settings for only specific plugins,
use the --input-filter
and --output-filter
options to
specify input plugins
and output plugins–for example:
telegraf \
--input-filter cpu:http \
--output-filter influxdb_v2:file \
config > telegraf.conf
.\telegraf.exe `
--input-filter cpu:http `
--output-filter influxdb_v2:file `
config > telegraf.conf
For more advanced configuration details, see the configuration documentation.
Custom-compile Telegraf
Use the Telegraf custom builder tool to compile Telegraf with only the plugins you need and reduce the Telegraf binary size.
Prerequisites
- Follow the instructions to install Go for your system.
- Create your Telegraf configuration file with the plugins you want to use.
Build the custom builder tool
Clone the Telegraf repository and then change into the repository directory–for example, enter the following command in your terminal:
git clone https://github.com/influxdata/telegraf.git && cd ./telegraf
To build the Telegraf custom builder tool, enter the following command:
make build_tools
Run the custom builder to create a telegraf
binary
The custom builder builds a telegraf
binary with only the plugins included in
the specified configuration files or directories.
Run the custom_builder
tool with at least one --config
or --config-directory
flag to specify Telegraf configuration files to build from.
--config
: accepts local file paths and URLs.--config-dir
: accepts local directory paths.
You can include multiple --config
and --config-dir
flags.
Examples
Single Telegraf configuration
./tools/custom_builder/custom_builder --config /etc/telegraf.conf
Single Telegraf configuration and Telegraf configuration directory
./tools/custom_builder/custom_builder \
--config /etc/telegraf.conf \
--config-dir /etc/telegraf/telegraf.d
Remote Telegraf configuration
./tools/custom_builder/custom_builder \
--config http://url-to-remote-telegraf/telegraf.conf
After a successful build, you can view your customized telegraf
binary within the top level of your Telegraf repository.
Update your custom binary
To add or remove plugins from your customized Telegraf build, edit your configuration file, and then run the custom builder to regenerate the Telegraf binary.
Was this page helpful?
Thank you for your feedback!
Support and feedback
Thank you for being part of our community! We welcome and encourage your feedback and bug reports for Telegraf and this documentation. To find support, use the following resources:
Customers with an annual or support contract can contact InfluxData Support.