Forge Home

Modules

Puppet

Resources

PuppetEcosystemPuppet CommunityUpdates

telegraf

Configuration and management of InfluxData's Telegraf metrics collection agent
Project URLRSS FeedReport issues

318,141 downloads

3,711 latest version

4.7 quality score

We run a couple of automated
scans to help you access a
module's quality. Each module is
given a score based on how well
the author has formatted their
code and documentation and
modules are also checked for
malware using VirusTotal.

Please note, the information below
is for guidance only and neither of
these methods should be considered
an endorsement by Puppet.

Version information

  • 5.4.0 (latest)
  • 5.3.0
  • 5.2.0
  • 5.1.0
  • 5.0.0
  • 4.3.1
  • 4.3.0
  • 4.2.0
  • 4.1.0
  • 4.0.0
  • 3.1.0
  • 3.0.0
  • 2.1.0
released Feb 28th 2024
This version is compatible with:
  • Puppet Enterprise 2023.8.x, 2023.7.x, 2023.6.x, 2023.5.x, 2023.4.x, 2023.3.x, 2023.2.x, 2023.1.x, 2023.0.x, 2021.7.x, 2021.6.x, 2021.5.x, 2021.4.x, 2021.3.x, 2021.2.x, 2021.1.x, 2021.0.x
  • Puppet >= 7.0.0 < 9.0.0
  • , , , , , , , , , , ,

Start using this module

  • r10k or Code Manager
  • Bolt
  • Manual installation
  • Direct download

Add this module to your Puppetfile:

mod 'puppet-telegraf', '5.4.0'
Learn more about managing modules with a Puppetfile

Add this module to your Bolt project:

bolt module add puppet-telegraf
Learn more about using this module with an existing project

Manually install this module globally with Puppet module tool:

puppet module install puppet-telegraf --version 5.4.0

Direct download is not typically how you would use a Puppet module to manage your infrastructure, but you may want to download the module in order to inspect the code.

Download
Tags: influxdb, telegraf, influxdata

Documentation

puppet/telegraf — version 5.4.0 Feb 28th 2024

telegraf puppet module

Build Status Release Puppet Forge Puppet Forge - downloads Puppet Forge - endorsement Puppet Forge - scores puppetmodule.info docs GPL v3 License

Table of Contents

  1. Overview
  2. Setup
  3. Usage
  4. Limitations
  5. Development

Overview

A reasonably simple yet flexible Puppet module to manage configuration of InfluxData's Telegraf metrics collection agent.

Setup

This module has the following dependencies:

NB: On some apt-based distributions you'll need to ensure you have support for TLS-enabled repos in place. This can be achieved by installing the apt-transport-https package.

Up to version v4.3.1 this module requires the toml-rb gem. Either install the gem using puppet's native gem provider, puppetserver_gem, pe_gem, pe_puppetserver_gem, or manually using one of the following methods:

  # apply or puppet-master
  gem install toml-rb
  # PE apply
  /opt/puppetlabs/puppet/bin/gem install toml-rb
  # AIO or PE puppetserver
  /opt/puppet/bin/puppetserver gem install toml-rb

The toml-rb gem got replaced with stdlib::to_toml. This requires puppetlabs/stdlib 9.

In addition, for Windows, the following dependencies must be met:

Usage

Telegraf's configuration is split into four main sections - global tags, options specific to the agent, input plugins, and output plugins. The documentation for these sections is here, and this module aims to be flexible enough to handle configuration of any of these stanzas.

To get started, Telegraf can be installed with a very basic configuration by just including the class:

include telegraf

However, to customise your configuration you'll want to do something like the following:

class { 'telegraf':
    hostname => $facts['hostname'],
    outputs  => {
        'influxdb' => [
            {
                'urls'     => [ "http://influxdb0.${facts['domain']}:8086", "http://influxdb1.${facts['domain']}:8086" ],
                'database' => 'telegraf',
                'username' => 'telegraf',
                'password' => 'metricsmetricsmetrics',
            }
        ]
    },
    inputs   => {
        'cpu' => [
            {
                'percpu'   => true,
                'totalcpu' => true,
            }
        ]
    }
}

Or here's a Hiera-based example (which is the recommended approach):

---
telegraf::global_tags:
  role: "%{::role}"
  hostgroup: "%{::hostgroup}"
  domain: "%{::domain}"
telegraf::inputs:
  cpu:
    - percpu: true
      totalcpu: true
  exec:
    - commands:
        - who | wc -l
    - commands:
        - cat /proc/uptime | awk '{print $1}'
  mem: [{}]
  io: [{}]
  net: [{}]
  disk: [{}]
  swap: [{}]
  system: [{}]
telegraf::outputs:
  influxdb:
    - urls:
        - "http://influxdb0.%{::domain}:8086"
        - "http://influxdb1.%{::domain}:8086"
      database: 'influxdb'
      username: 'telegraf'
      password: 'telegraf'
telegraf::processors:
  replace_disk_type:
    plugin_type: regex
    options:
      - namepass: ['diskio']
        order: 1
        tags:
          - key: 'disk_type'
            pattern: '^dos$'
            replacement: 'FAT'

telegraf::inputs accepts a hash of any inputs that you'd like to configure. However, you can also optionally define individual inputs using the telegraf::input type - this suits installations where, for example, a core module sets the defaults and other modules import it.

Example 1:

telegraf::input { 'my_exec':
  plugin_type => 'exec',
  options     => [
    {
      'commands'    => ['/usr/local/bin/my_input.py',],
      'name_suffix' => '_my_input',
      'data_format' => 'json',
    }
  ],
  require     => File['/usr/local/bin/my_input.py'],
}

Will create the file /etc/telegraf/telegraf.d/my_exec.conf:

[[inputs.exec]]
commands = ["/usr/local/bin/my_input.py"]
data_format = "json"
name_suffix = "_my_input"

Example 2:

telegraf::input { 'influxdb-dc':
  plugin_type => 'influxdb',
  options     => [
    {
      'urls' => ['http://remote-dc:8086',],
    }
  ],
}

Will create the file /etc/telegraf/telegraf.d/influxdb-dc.conf:

[[inputs.influxdb]]
urls = ["http://remote-dc:8086"]

Example 3:

telegraf::input { 'my_snmp':
  plugin_type    => 'snmp',
  options        => [
    {
      'interval' => '60s',
      'host' => [
        {
          'address'   => 'snmp_host1:161',
          'community' => 'read_only',
          'version'   => 2,
          'get_oids'  => ['1.3.6.1.2.1.1.5',],
        }
      ],
      'tags' => {
        'environment' => 'development',
      },
    }
  ],
}

Will create the file /etc/telegraf/telegraf.d/snmp.conf:

[[inputs.snmp]]
interval = "60s"
[inputs.snmp.tags]
environment = "development"
[[inputs.snmp.host]]
address = "snmp_host1:161"
community = "read_only"
get_oids = ["1.3.6.1.2.1.1.5"]
version = 2

Example 4:

Outputs, Processors and Aggregators are available in the same way:

telegraf::output { 'my_influxdb':
  plugin_type => 'influxdb',
  options     => [
    {
      'urls'     => [ "http://influxdb.example.come:8086"],
      'database' => 'telegraf',
      'username' => 'telegraf',
      'password' => 'metricsmetricsmetrics',
    }
  ],
}

telegraf::processor { 'my_regex':
  plugin_type => 'regex',
  options     => [
    {
      tags => [
        {
          key         => 'foo',
          pattern     => String(/^a*b+\d$/),
          replacement => 'c${1}d',
        }
      ],
    }
  ],
}

telegraf::aggregator { 'my_basicstats':
  plugin_type => 'basicstats',
  options     => [
    {
      period        => '30s',
      drop_original => false,
    }
  ],
}

Example 5:

class { 'telegraf':
    ensure              => '1.0.1',
    hostname            => $facts['hostname'],
    windows_package_url => 'http://internal_repo:8080/chocolatey',
}

Will install telegraf version 1.0.1 on Windows using an internal chocolatey repo

Hierarchical configuration from multiple files

Hiera YAML and JSON backends support deep hash merging which is needed for inheriting configuration from multiple files.

First of all, make sure that the deep_merge gem is installed on your Puppet Master.

An example of hiera.yaml:

---
:hierarchy:
    - "roles/%{role}"
    - "type/%{virtual}"
    - "domain/%{domain}"
    - "os/%{osfamily}"
    - "common"
:backends:
    - yaml
:yaml:
    :datadir: /etc/puppet/hiera
:merge_behavior: deeper

Then you can define configuration shared for all physical servers and place it into type/physical.yaml:

telegraf::inputs:
  cpu:
    - percpu: true
      totalcpu: true
  mem: [{}]
  io: [{}]
  net: [{}]
  disk: [{}]

Specific roles will include some extra plugins, e.g. role/frontend.yaml:

telegraf::inputs:
  nginx:
    - urls: ["http://localhost/server_status"]

Limitations

The latest version (2.0) of this module requires Puppet 4 or newer. If you're looking for support under Puppet 3.x, then you'll want to make use of an older release.

Furthermore, the introduction of toml-rb means that Ruby 1.9 or newer is also a requirement.

This module has been developed and tested against the operating systems and their version in metadata.json

Support for other distributions / operating systems is planned. Feel free to assist with development in this regard!

The configuration generated with this module is only compatible with newer releases of Telegraf, i.e 0.11.x. It won't work with the 0.2.x series.

Development

Please fork this repository, hack away on your branch, run the tests:

$ bundle exec rake beaker

And then submit a pull request. Succinct, well-described and atomic commits preferred.