Documentation

Install Telegraf

This page documents an earlier version of Telegraf. Telegraf v1.16 is the latest stable version. View this page in the v1.16 documentation.

This page provides directions for installing, starting, and configuring Telegraf.

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 can be inaccurate.

Installation

Debian and Ubuntu users can install the latest stable version of Telegraf using the apt-get package manager.

Ubuntu: Add the InfluxData repository with the following commands:

wget -qO- https://repos.influxdata.com/influxdb.key | sudo apt-key add -
source /etc/lsb-release
echo "deb https://repos.influxdata.com/${DISTRIB_ID,,} ${DISTRIB_CODENAME} stable" | sudo tee /etc/apt/sources.list.d/influxdb.list
curl -sL https://repos.influxdata.com/influxdb.key | sudo apt-key add -
source /etc/lsb-release
echo "deb https://repos.influxdata.com/${DISTRIB_ID,,} ${DISTRIB_CODENAME} stable" | sudo tee /etc/apt/sources.list.d/influxdb.list

Debian: Add the InfluxData repository with the following commands:

# Before adding Influx repository, run this so that apt will be able to read the repository.

sudo apt-get update && sudo apt-get install apt-transport-https

# Add the InfluxData key

wget -qO- https://repos.influxdata.com/influxdb.key | sudo apt-key add -
source /etc/os-release
test $VERSION_ID = "7" && echo "deb https://repos.influxdata.com/debian wheezy stable" | sudo tee /etc/apt/sources.list.d/influxdb.list
test $VERSION_ID = "8" && echo "deb https://repos.influxdata.com/debian jessie stable" | sudo tee /etc/apt/sources.list.d/influxdb.list
test $VERSION_ID = "9" && echo "deb https://repos.influxdata.com/debian stretch stable" | sudo tee /etc/apt/sources.list.d/influxdb.list
test $VERSION_ID = "10" && echo "deb https://repos.influxdata.com/debian buster stable" | sudo tee /etc/apt/sources.list.d/influxdb.list
# Before adding Influx repository, run this so that apt will be able to read the repository.

sudo apt-get update && sudo apt-get install apt-transport-https

# Add the InfluxData key

curl -sL https://repos.influxdata.com/influxdb.key | sudo apt-key add -
source /etc/os-release
test $VERSION_ID = "7" && echo "deb https://repos.influxdata.com/debian wheezy stable" | sudo tee /etc/apt/sources.list.d/influxdb.list
test $VERSION_ID = "8" && echo "deb https://repos.influxdata.com/debian jessie stable" | sudo tee /etc/apt/sources.list.d/influxdb.list
test $VERSION_ID = "9" && echo "deb https://repos.influxdata.com/debian stretch stable" | sudo tee /etc/apt/sources.list.d/influxdb.list

Then, install and start the Telegraf service:

sudo apt-get update && sudo apt-get install telegraf
sudo service telegraf start

Or if your operating system is using systemd (Ubuntu 15.04+, Debian 8+):

sudo apt-get update && sudo apt-get install telegraf
sudo systemctl start telegraf

Install from a .deb file:

To manually install the Debian package from a .deb file:

  1. Download the latest Telegraf .deb release from the Telegraf section of the downloads page.
  2. Run the following command (making sure to supply the correct version number for the downloaded file):

    sudo sudo dpkg -i telegraf_1.<version>_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.)

  1. Download and import InfluxData’s public key:

    curl -sL https://repos.influxdata.com/influxdb.key | gpg --import
    
  2. 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.14.1_linux_amd64.tar.gz.asc
    
  3. Verify the signature with gpg --verify:

    gpg --verify telegraf-1.14.1_linux_amd64.tar.gz.asc telegraf-1.14.1_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 = InfluxDB Repository - RHEL \$releasever
baseurl = https://repos.influxdata.com/rhel/\$releasever/\$basearch/stable
enabled = 1
gpgcheck = 1
gpgkey = https://repos.influxdata.com/influxdb.key
EOF

Once repository is added to the yum configuration, install and start the Telegraf service by running:

sudo yum install telegraf
sudo service telegraf start

Or if your operating system is using systemd (CentOS 7+, RHEL 7+):

sudo yum install telegraf
sudo systemctl start 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.)

  1. Download and import InfluxData’s public key:

    curl -sL https://repos.influxdata.com/influxdb.key | gpg --import
    
  2. 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.14.1_linux_amd64.tar.gz.asc
    
  3. Verify the signature with gpg --verify:

    gpg --verify telegraf-1.14.1_linux_amd64.tar.gz.asc telegraf-1.14.1_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.)

  1. Download and import InfluxData’s public key:

    curl -sL https://repos.influxdata.com/influxdb.key | gpg --import
    
  2. 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.14.1_linux_amd64.tar.gz.asc
    
  3. Verify the signature with gpg --verify:

    gpg --verify telegraf-1.14.1_linux_amd64.tar.gz.asc telegraf-1.14.1_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.)

  1. Download and import InfluxData’s public key:

    curl -sL https://repos.influxdata.com/influxdb.key | gpg --import
    
  2. 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.14.1_linux_amd64.tar.gz.asc
    
  3. Verify the signature with gpg --verify:

    gpg --verify telegraf-1.14.1_linux_amd64.tar.gz.asc telegraf-1.14.1_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

To have launchd start telegraf at next login:

ln -sfv /usr/local/opt/telegraf/*.plist ~/Library/LaunchAgents

To load telegraf now:

launchctl load ~/Library/LaunchAgents/homebrew.mxcl.telegraf.plist

Or, if you don’t want/need launchctl, you can just run:

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.)

  1. Download and import InfluxData’s public key:

    curl -sL https://repos.influxdata.com/influxdb.key | gpg --import
    
  2. 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.14.1_linux_amd64.tar.gz.asc
    
  3. Verify the signature with gpg --verify:

    gpg --verify telegraf-1.14.1_linux_amd64.tar.gz.asc telegraf-1.14.1_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.

Installation

Download the Telegraf ZIP archive for Windows from the InfluxData downloads page.

Extract the contents of the ZIP archive to C:\Program Files\InfluxData\Telegraf.

Verify the integrity of the downloaded Telegraf binary (optional)

To obtain the SHA256 hash for the Windows Telegraf download, use the following PowerShell command:

CertUtil -hashfile <path to your download>/telegraf-1.<version>_windows_amd64.zip SHA256

Compare the output from this command to the hash listed on the downloads page to ensure the integrity of the download.

Configure an input plugin

The Telegraf ZIP archive contains a default configuration file (telegraf.conf). In this file, the input plugin for capturing basic Windows system metrics is already activated. With this plugin, Telegraf monitors the following defined Windows Operating System objects:

  • Processor
  • LogicalDisk
  • PhysicalDisk
  • Network Interface
  • System
  • Memory
  • Paging File

Telegraf can capture metrics and log information from a wide variety of sources. For more advanced configuration details, see the configuration documentation.

Configure an output plugin

Before you start the Telegraf agent, configure an output plugin to send data to InfluxDB. Choose the appropriate plugin based on the version of InfluxDB you are using.

The telegraf.conf file included in the ZIP archive contains sections for configuring both the InfluxDB v1 and InfluxDB v2 output plugins.

Writing data to InfluxDB 1.x

Open telegraf.conf in a text editor and fill in the database field under [[outputs.influxdb]].

Writing data to InfluxDB 2.0

Open telegraf.conf in a text editor and comment out the InfluxDB v1 plugin by placing a # in front of [[outputs.influxdb]]. Then remove the # in front of [[outputs.influxdb_v2]].

For detailed instructions on configuring Telegraf to write to InfluxDB 2.0, see Enable and configure the InfluxDB v2 output plugin.

Start the agent

Once configured, run the following commands in PowerShell to begin sending metrics with Telegraf:

> cd C:\Program Files\InfluxData\Telegraf        # path to extracted Telegraf directory
> .\telegraf.exe -config <path_to_telegraf.conf>

Install Telegraf as a Windows Service

See Running Telegraf as a Windows service.


New! Cloud or OSS?

InfluxDB OSS 2.0 release candidate

InfluxDB OSS v2.0.rc includes breaking changes that require a manual upgrade from all alpha and beta versions. For information, see:

Upgrade to InfluxDB OSS v2.0.rc