Install Telegraf
This page provides directions for installing, starting, and configuring Telegraf. To install Telegraf, do the following:
Download
Download the latest Telegraf release at the InfluxData download page.
Requirements
Installation of the Telegraf package may require root
or administrator privileges in order 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.
Installation
Debian and Ubuntu users can install the latest stable version of Telegraf using the apt-get
package manager.
Ubuntu & Debian
Install Telegraf from the InfluxData repository with the following commands:
# influxdata-archive_compat.key GPG Fingerprint: 9D539D90D3328DC7D6C8D3B9D8FF8E1F7DF8B07E
wget -q 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
# influxdata-archive_compat.key GPG Fingerprint: 9D539D90D3328DC7D6C8D3B9D8FF8E1F7DF8B07E
curl -s https://repos.influxdata.com/influxdata-archive_compat.key > 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 Telegraf section of the downloads page.Run the following command (making sure to supply the correct version number for the downloaded file):
sudo dpkg -i telegraf_1.28.1-1_amd64.deb
Verify the authenticity of downloaded binary (optional)
InfluxData cryptographically signs each Telegraf binary release.
For added security, follow these steps to verify the signature of your download with gpg
.
(Most operating systems include the gpg
command by default.
If gpg
is not available, see the GnuPG homepage for installation instructions.)
Download and import InfluxData’s public key:
curl -sL https://repos.influxdata.com/influxdata-archive_compat.key | gpg --import
Download the signature file for the release by adding
.asc
to the download URL. For example:wget https://dl.influxdata.com/telegraf/releases/telegraf-1.<nil>_linux_amd64.tar.gz.asc
Verify the signature with
gpg --verify
:gpg --verify telegraf-1.<nil>_linux_amd64.tar.gz.asc telegraf-1.<nil>_linux_amd64.tar.gz
The output from this command should include the following:
gpg: Good signature from "InfluxDB Packaging Service <support@influxdb.com>" [unknown]
Configuration
Create a configuration file with default input and output plugins.
Every plugin will be in the file, but most will be commented out.
telegraf config > telegraf.conf
Create a configuration file with specific inputs and outputs
telegraf --input-filter <pluginname>[:<pluginname>] --output-filter <outputname>[:<outputname>] config > telegraf.conf
For more advanced configuration details, see the configuration documentation.
For instructions on how to manually install the RPM package from a file, please see the downloads page.
RedHat and CentOS: Install the latest stable version of Telegraf using the yum
package manager:
cat <<EOF | sudo tee /etc/yum.repos.d/influxdb.repo
[influxdb]
name = InfluxData Repository - Stable
baseurl = https://repos.influxdata.com/stable/\$basearch/main
enabled = 1
gpgcheck = 1
gpgkey = https://repos.influxdata.com/influxdata-archive_compat.key
EOF
Install telegraf once the repository is added to the yum
configuration:
sudo yum install telegraf
Verify the authenticity of downloaded binary (optional)
InfluxData cryptographically signs each Telegraf binary release.
For added security, follow these steps to verify the signature of your download with gpg
.
(Most operating systems include the gpg
command by default.
If gpg
is not available, see the GnuPG homepage for installation instructions.)
Download and import InfluxData’s public key:
curl -sL https://repos.influxdata.com/influxdata-archive_compat.key | gpg --import
Download the signature file for the release by adding
.asc
to the download URL. For example:wget https://dl.influxdata.com/telegraf/releases/telegraf-1.<nil>_linux_amd64.tar.gz.asc
Verify the signature with
gpg --verify
:gpg --verify telegraf-1.<nil>_linux_amd64.tar.gz.asc telegraf-1.<nil>_linux_amd64.tar.gz
The output from this command should include the following:
gpg: Good signature from "InfluxDB Packaging Service <support@influxdb.com>" [unknown]
Configuration
Create a configuration file with default input and output plugins
Every plugin will be in the file, but most will be commented out.
telegraf config > telegraf.conf
Create a configuration file with specific inputs and outputs
telegraf --input-filter <pluginname>[:<pluginname>] --output-filter <outputname>[:<outputname>] config > telegraf.conf
For more advanced configuration details, see the configuration documentation.
There are RPM packages provided by openSUSE Build Service for SUSE Linux users:
# add go repository
zypper ar -f obs://devel:languages:go/ go
# install latest telegraf
zypper in telegraf
Verify the authenticity of downloaded binary (optional)
InfluxData cryptographically signs each Telegraf binary release.
For added security, follow these steps to verify the signature of your download with gpg
.
(Most operating systems include the gpg
command by default.
If gpg
is not available, see the GnuPG homepage for installation instructions.)
Download and import InfluxData’s public key:
curl -sL https://repos.influxdata.com/influxdata-archive_compat.key | gpg --import
Download the signature file for the release by adding
.asc
to the download URL. For example:wget https://dl.influxdata.com/telegraf/releases/telegraf-1.<nil>_linux_amd64.tar.gz.asc
Verify the signature with
gpg --verify
:gpg --verify telegraf-1.<nil>_linux_amd64.tar.gz.asc telegraf-1.<nil>_linux_amd64.tar.gz
The output from this command should include the following:
gpg: Good signature from "InfluxDB Packaging Service <support@influxdb.com>" [unknown]
Configuration
Create a configuration file with default input and output plugins
Every plugin will be in the file, but most will be commented out.
telegraf config > telegraf.conf
Create a configuration file with specific inputs and outputs
telegraf --input-filter <pluginname>[:<pluginname>] --output-filter <outputname>[:<outputname>] config > telegraf.conf
For more advanced configuration details, see the configuration documentation.
Telegraf is part of the FreeBSD package system. It can be installed by running:
sudo pkg install telegraf
The configuration file is located at /usr/local/etc/telegraf.conf
with examples in /usr/local/etc/telegraf.conf.sample
.
Verify the authenticity of downloaded binary (optional)
InfluxData cryptographically signs each Telegraf binary release.
For added security, follow these steps to verify the signature of your download with gpg
.
(Most operating systems include the gpg
command by default.
If gpg
is not available, see the GnuPG homepage for installation instructions.)
Download and import InfluxData’s public key:
curl -sL https://repos.influxdata.com/influxdata-archive_compat.key | gpg --import
Download the signature file for the release by adding
.asc
to the download URL. For example:wget https://dl.influxdata.com/telegraf/releases/telegraf-1.<nil>_linux_amd64.tar.gz.asc
Verify the signature with
gpg --verify
:gpg --verify telegraf-1.<nil>_linux_amd64.tar.gz.asc telegraf-1.<nil>_linux_amd64.tar.gz
The output from this command should include the following:
gpg: Good signature from "InfluxDB Packaging Service <support@influxdb.com>" [unknown]
Configuration
Create a configuration file with default input and output plugins.
Every plugin will be in the file, but most will be commented out.
telegraf config > telegraf.conf
Create a configuration file with specific inputs and outputs
telegraf --input-filter <pluginname>[:<pluginname>] --output-filter <outputname>[:<outputname>] config > telegraf.conf
For more advanced configuration details, see the configuration documentation.
Users of macOS 10.8 and higher can install Telegraf using the Homebrew package manager.
Once brew
is installed, you can install Telegraf by running:
brew update
brew install telegraf
Run one of the following commands to start Telegraf and begin collecting and processing metrics:
To have launchd start Telegraf as a service after the next login:
ln -sfv /usr/local/opt/telegraf/*.plist ~/Library/LaunchAgents
Start Telegraf as a launchd service:
launchctl load ~/Library/LaunchAgents/homebrew.mxcl.telegraf.plist
To run telegraf
directly (and not as a launchd service):
telegraf -config /usr/local/etc/telegraf.conf
Verify the authenticity of downloaded binary (optional)
InfluxData cryptographically signs each Telegraf binary release.
For added security, follow these steps to verify the signature of your download with gpg
.
(Most operating systems include the gpg
command by default.
If gpg
is not available, see the GnuPG homepage for installation instructions.)
Download and import InfluxData’s public key:
curl -sL https://repos.influxdata.com/influxdata-archive_compat.key | gpg --import
Download the signature file for the release by adding
.asc
to the download URL. For example:wget https://dl.influxdata.com/telegraf/releases/telegraf-1.<nil>_linux_amd64.tar.gz.asc
Verify the signature with
gpg --verify
:gpg --verify telegraf-1.<nil>_linux_amd64.tar.gz.asc telegraf-1.<nil>_linux_amd64.tar.gz
The output from this command should include the following:
gpg: Good signature from "InfluxDB Packaging Service <support@influxdb.com>" [unknown]
Configuration
Create a configuration file with default input and output plugins.
Every plugin will be in the file, but most will be commented out.
telegraf config > telegraf.conf
The output telegraf.conf
contains all available plugins–some are enabled and the rest are commented out.
Create a configuration file with specific inputs and outputs
telegraf --input-filter <pluginname>[:<pluginname>] --output-filter <outputname>[:<outputname>] config > telegraf.conf
For more advanced configuration details, see the configuration documentation.
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.28.1_windows_amd64.zip ` -UseBasicParsing ` -OutFile telegraf-1.28.1_windows_amd64.zip ` Expand-Archive .\telegraf-1.28.1_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.28.1
to the parent directoryC:\Program Files\InfluxData\telegraf
–for example:cd "C:\Program Files\InfluxData\telegraf"; mv .\telegraf-1.28.1\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: Disable the
inputs.processes
plugin. This plugin doesn’t support Windows and returns an error when run with the--test
flag. Opentelegraf.conf
in your editor and comment theinputs.processes
configuration lines.... # This plugin ONLY supports non-Windows # [[inputs.processes]] ... # # use_sudo = false ...
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 |
Custom-compile Telegraf
Use the Telegraf custom builder tool to compile Telegraf with only the plugins you need and reduce the Telegraf binary size.
Requirements
- Ensure you’ve installed Go version is 1.18.0 or later.
- Create your Telegraf configuration file with the plugins you want to use. For details, see Configuration options.
Build and run the custom builder
Clone the Telegraf repository:
git clone https://github.com/influxdata/telegraf.git
Change directories into the top-level of the Telegraf repository:
cd telegraf
Build the Telegraf custom builder tool by entering the following command:
make build_tools
Run the
custom_builder
utility 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. The custom builder builds atelegraf
binary with only the plugins included in the specified configuration files or directories:- 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
- Single Telegraf configuration:
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 rerun the command from step 4 above.
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.