DEBOPS.TELEGRAF(5)

NAME
debops.telegraf - Manage Telegraf instance using Ansible

SYNOPSIS

debops run service/telegraf [--limit group,host,...] [--diff] [--check] [--tags tag1,tag2,...] [--skip-tags tag1,tag2,...] [<ansible-playbook options>] ...

DESCRIPTION

Use Telegraf <https://www.influxdata.com/time-series-platform/telegraf/> to collect and write metrics into InfluxDB and other supported outputs. Telegraf is the open source server agent to help you collect metrics from your stacks, sensors and systems.

The debops.telegraf role installs and configures Telegraf.

GETTING STARTED

REAL WORLD USE

Telegraf requires at least one input and output defined. Default debops.telegraf configuration will include a few basic input plugins (cpu, mem, disk, etc.) but output will be discarded by default using the outputs.discard plugin.

You can check the /etc/telegraf/telegraf.conf.sample file on a host with installed Telegraf for many examples of input and output plugins available as well as documentation of the supported configuration options. The configuration is written using TOML format, however it's very easy to convert it to a format usable in DebOps, either directly including it as YAML text blocks, or converting it into a YAML format.

  Example inventory

To install a Telegraf agent on a host, you need to add it to [debops_service_telegraf] Ansible group:

[debops_service_telegraf]
agent-host

This will install telegraf package and create basic configuration required by the service.

You can also configure Telegraf to be installed on all DebOps hosts in the inventory:

[debops_all_hosts]
hostname1
hostname2
hostname3
[debops_service_telegraf:children]
debops_all_hosts

  Example playbook

Here's an example Ansible playbook that uses the debops.telegraf role:

---
  collections: [ 'debops.debops', 'debops.roles01',
                 'debops.roles02', 'debops.roles03' ]
  hosts: [ 'debops_service_telegraf' ]
  become: True
  environment: '{{ inventory__environment | d({})
                   | combine(inventory__group_environment | d({}))
                   | combine(inventory__host_environment  | d({})) }}'
  roles:
    - role: keyring
      tags: [ 'role::keyring', 'skip::keyring', 'role::influxdata' ]
      keyring__dependent_apt_keys:
        - '{{ influxdata__keyring__dependent_apt_keys }}'
    - role: influxdata
      tags: [ 'role::influxdata', 'skip::influxdata' ]
      influxdata__dependent_packages:
        - '{{ telegraf__influxdata__dependent_packages }}'
    - role: telegraf
      tags: [ 'role::telegraf', 'skip::telegraf' ]

  Ansible tags

You can use Ansible --tags or --skip-tags parameters to limit what tasks are performed during Ansible run. This can be used after a host was first configured to speed up playbook execution, when you are sure that most of the configuration is already in the desired state.

Available role tags:

role::telegraf
    Main role tag, should be used in the playbook to execute all of the role tasks as well as role dependencies.

  Other resources

List of other useful resources related to the debops.telegraf Ansible role:

•   Official Telegraf documentation page <https://docs.influxdata.com/telegraf/>

DEFAULT VARIABLE DETAILS

Some of debops.telegraf default variables have more extensive configuration than simple strings or lists, here you can find documentation and examples for them.

  telegraf__configuration

The telegraf__configuration variables define the contents of the /etc/telegraf/telegraf.conf configuration file. The entire file is based on a YAML configuration converted to TOML using a custom Jinja filter, therefore the contents are limited - there's no way to add comments or comment out sections of the file. For a more advanced configuration, you should use the telegraf__plugins variables instead.

WARNING: Keep in mind that the main configuration file is world-readable. Use plugin files for sensitive configuration like passwords for external services - plugin configuration is readable only by the Telegraf UNIX account.

  Examples

The default configuration includes settings for the agent itself. To remove them from the file and rely only on separate plugins directory, add in the inventory:

telegraf__configuration:
  - name: 'agent'
    state: 'absent'

Change the agent's collection interval without modifying other parameters (note a different name parameter which permits recursive merging of the configuration):

telegraf__configuration:
  - name: 'agent_interval'
    config:
      agent:
        interval: '30s'
        round_interval: False

Add a set of global tags to all Telegraf instances:

telegraf__configuration:
  - name: 'global_tags'
    config:
      global_tags:
        rack: '1a'
        user: '$USER'

You can see the default list of configuration options in the telegraf__default_configuration variable.

  Syntax

name
    Required. Name of a particular configuration entry, not used otherwise. Configuration entries with the same name parameter are merged together an can affect each other.

state
    Optional. If not specified or present, a given configuration entry will be included in the generated config file. If absent, a given configuration entry will not be included in the configuration file.

config
    YAML dictionary with Telegraf configuration options, which will be converted to TOML on generation. The config parameters from multiple entries with the same name parameter override each other in order of appearance.

    The config parameters from different entries are combined together recursively, this allows modification of specific parameters in a larger section of the configuration file.

  telegraf__plugins

The telegraf__plugins variables define the contents of the /etc/telegraf/telegraf.d/ configuration directory. Each configuration entry is a separate file which can be created or removed as needed.

  Examples

The default configuration includes a output.discard output sink since the service will not start correctly without any output configured. To comment it out on in the generated configuration file, you can add in the inventory:

telegraf__plugins:
  - name: 'output_discard'
    state: 'comment'

Add an Elasticsearch output which uses DebOps secrets for access (you might want to use a different account than elastic though):

- name: 'output_elasticsearch'
  config:
    outputs:
      elasticsearch:
        urls: [ 'https://es1.example.org:9200' ]
        timeout: '5s'
        enable_sniffer: False
        enable_gzip: False
        health_check_interval: '10s'
        username: 'elastic'
        password: '{{ lookup("password", secret + "/elasticsearch/"
                      + "credentials/built-in/elastic/password") }}'
        index_name: 'telegraf-%Y.%m.%d'
        manage_template: True
        template_name: 'telegraf'

This example shows real world case of defining an input plugin which receives stream of UDP data from Collectd and forwards it into InfluxDB 2.0 instance:

telegraf__plugins:
  - name: 'telegraf2influxdb'
    raw: |
      [[outputs.influxdb_v2]]
        urls = ["http://127.0.0.1:8086"]
        token = "4bwv8cXllnYz7KXakKMz173YPSaSOH5_E70FE01PkXf3a7IC-IrzP-zCqjOtU1NGJiZycLguRhuDl8cUpz9QFw=="
        organization = "DebOps"
        bucket_tag = "bucket4debops"
        exclude_bucket_tag = true
    state: 'present'
  - name: 'udp4collectd'
    raw: |
      [[inputs.socket_listener]]
        service_address = "udp4://:25826"
        data_format = "collectd"
        content_encoding = "identity"
        ## Authentication file for cryptographic security levels
        collectd_auth_file = "/etc/collectd/passwd"
        ## One of none (default), sign, or encrypt
        collectd_security_level = "encrypt"
        ## Path of to TypesDB specifications
        collectd_typesdb = ["/usr/share/collectd/types.db"]
        collectd_parse_multivalue = "join"
        [inputs.socket_listener.tags]
          bucket4debops = "collectd"
    state: 'present'

This example defines several system monitoring input plugins which are assigned to a particular host only:

telegraf__host_plugins:
    # Override the default configuration
  - name: 'input_system'
    raw: |
      [[inputs.system]]
    state: 'present'
  - name: 'input_diskio'
    raw: |
      [[inputs.diskio]]
        devices = ["nvme0n1", "nvme1n1", "md10"]
    state: 'present'
  - name: 'input_net'
    raw: |
      [[inputs.net]]
        interfaces = ["eth0", "bridge0"]
    state: 'present'
  - name: 'input_zfs'
    raw: |
      [[inputs.zfs]]
        poolMetrics = true
        datasetMetrics = true
    state: 'present'

You can see the default list of configured plugins in the telegraf__default_plugins variable.

  Syntax

The role uses Universal Configuration system to manage Telegraf plugin configuration files. The telegraf__combined_plugins variable defines the merge order of the plugin lists. Each variable is a list of YAML dictionaries with specific parameters:

name
    Required. Name of the configuration file (the .conf extension will be added automatically). Multiple entries with the same name parameter will be merged together and can affect each other.

state
    Optional. If not specified or present, the configuration file will be generated on the host. If absent, the configuration file will be removed from the host. If comment, the file will be generated but the configuration itself will be commented out. If ignore, a given configuration entry will not be processed during role execution.

comment
    Optional. String or YAML text block with comments about a given configuration file.

config
    YAML dictionary with Telegraf configuration options, which will be converted to TOML on generation. The config parameters from multiple entries with the same name parameter override each other in order of appearance.

raw YAML text block with Telegraf configuration in the TOML format. The raw parameters from multiple entries with the same name parameter override each other in order of appearance. If both config and raw parameters are present, the latter takes precedence.

COPYRIGHT
2014-2024, Maciej Delmanowski, Nick Janetakis, Robin Schneider and others