dj-wasabi.telegraf

• dj-wasabi.telegraf
  • Build status:
  • Requirements
    • Supported systems
    • InfluxDB
    • Docker
  • Upgrade
    • 0.7.0
  • Role Variables
    • Ansible role specific variables
      • Telegraf Package
    • Telegraf agent process configuration.
    • Docker specific role variables:
  • Extra information
    • ansible_fqdn problematic for getting hostname
    • Setting tags
    • Docker specifics
      • Docker image
      • Docker mounts
      • Example Docker configuration
  • Windows specific Variables
  • Extra information
    • telegraf_plugins_default
    • telegraf_plugins_extra
  • Dependencies
  • Example Playbook
  • Molecule
  • License
  • Author Information

Build status:

This role installs and configures Telegraf.

Telegraf is an agent written in Go that collects metrics from its system or other services and sends them to InfluxDB.

The goal is to keep memory usage low and provide a way for developers to add support for collecting metrics from common services (like Hadoop, Postgres, or Redis) and third-party APIs (like Mailchimp, AWS CloudWatch, or Google Analytics).

(https://github.com/influxdb/telegraf)

Requirements

Supported systems

This role works with these systems:

• Red Hat
• Debian
• Ubuntu
• Docker containers
• (Open)Suse
• Windows (Best effort)
• FreeBSD (Best effort)
• Archlinux (only "online" mode)

You need one of these systems. Please submit Pull Requests or suggestions if you want to use this role with other systems.

InfluxDB

An InfluxDB instance needs to be up and running on your network or another output type found on https://github.com/influxdata/telegraf/#output-plugins.

Docker

Docker must be installed on the target machine. Recommended roles for installing Docker are:

• jgeusebroek.docker
• geerlingguy.docker

This is only necessary if the configuration is for a Telegraf instance inside a Docker container (when telegraf_agent_docker: True).

Upgrade

0.7.0

An issue was found:

If I set `telegraf_plugins_extra`, run ansible, remove the plugin, and run ansible again, the plugin still exists on the machine.

Role Variables

Ansible role specific variables

To specify which version to install:

• telegraf_agent_version: Version of Telegraf to install. If telegraf_agent_package_state is set to latest, this will be ignored. Default: 1.10.0

You can install Telegraf using four different methods:

• Via package managers like yum, apt, or zypper ("repo");
• Direct download from https://dl.influxdata.com/ ("online");
• Already available on the target host, but not installed/configured ("offline");
• Already installed, but not configured ("manual").

Set telegraf_agent_package_method to the one that fits your situation (repo, online, offline, or manual).

Telegraf Package

These variables determine how and what package will be installed.

• telegraf_agent_package: Telegraf package name to install. For online or offline, provide the full file path. Ex: telegraf_agent_package: /tmp/telegraf.rpm. Default: telegraf_agent_package: telegraf.
• telegraf_agent_package_method: Method to use for installation: repo, offline, or online.
• telegraf_agent_package_state: Whether to keep the package present or latest. latest will ignore telegraf_agent_version. Default: present.

Telegraf agent process configuration.

• telegraf_agent_interval: Interval for sending data to the server. Default: 10
• telegraf_agent_debug: Run Telegraf in debug mode. Default: False
• telegraf_agent_round_interval: Round the collection interval to 'interval'. Default: True
• telegraf_agent_flush_interval: Default data flushing interval. Default: 10
• telegraf_agent_flush_jitter: Random deviation for flush interval. Default: 0
• telegraf_agent_aws_tags: Include AWS EC2 tags in Telegraf. Default: False
• telegraf_agent_aws_tags_prefix: Prefix for AWS EC2 tags. Default: ""
• telegraf_agent_collection_jitter: Random deviation for collection timing. Default: 0
• telegraf_agent_metric_batch_size: Size of the metric batch. Default: 1000
• telegraf_agent_metric_buffer_limit: Limit for metric buffer. Default: 10000
• telegraf_agent_quiet: Run in quiet mode (only errors). Default: False
• telegraf_agent_logfile: Log file name. Default: '' (logs to stdout).
• telegraf_agent_hostname: Agent hostname. Default: ansible_fqdn.
• telegraf_agent_omit_hostname: Skip setting the "host" tag in the agent. Default: False.

Docker specific role variables:

• telegraf_agent_docker: Install Telegraf as a Docker container. Default: False.
• telegraf_agent_docker_name: Docker container name. Default: telegraf.
• telegraf_agent_docker_network_mode: Docker container networking mode. Default: bridge.
• telegraf_agent_docker_restart_policy: Docker container restart policy. Default: unless-stopped.
• telegraf_agent_docker_image_version: Docker Telegraf image version. Defaults to telegraf_agent_version. Set to latest for the latest tag.
• telegraf_uid_docker: Override user ID. Default: 995.
• telegraf_gid_docker: Override group ID. Default: 998.

For full agent settings, refer to: Telegraf Configuration Reference.

Extra information

ansible_fqdn problematic for getting hostname

This issue is related to getting accurate hostnames with ansible_fqdn.

• Describe the bug: Some nodes show unexpected hostnames like localhost.localdomain, even when hostnamectl shows the correct name. ansible_fqdn and ansible_hostname can produce different results.
• Fix proposal: In my playbook, I added:

  telegraf_agent_hostname: "{{ ansible_nodename }}"
  

Setting tags

You can set tags for the Telegraf host:

telegraf_global_tags:
  - tag_name: some_name
    tag_value: some_value

Specify the output server. The default is localhost, but you'll need to set your InfluxDB server:

telegraf_agent_output:
  - type: influxdb
    config:
      - urls = ["http://localhost:8086"]
      - database = "telegraf"
    tagpass:
      - cpu = ["cpu0"]

Configurations can be printed as comments in the config file:

config:
    - # This is a config line

Docker specifics

Docker image

The official Influxdata Telegraf image is used. The telegraf_agent_version will correspond to the image tag.

Docker mounts

The Docker container mounts the entire system (read-only) to monitor the Docker host from within the container. These are the mounts:

- /etc/telegraf:/etc/telegraf:ro
- /:/hostfs:ro
- /etc:/hostfs/etc:ro
- /proc:/hostfs/proc:ro
- /sys:/hostfs/sys:ro
- /var/run:/var/run:ro

More information: Telegraf FAQs.

Example Docker configuration

telegraf_agent_docker: True
# Use host networking mode for gathering metrics.
telegraf_agent_docker_network_mode: host
# Specify a specific image tag.
telegraf_agent_version: 1.10.0-alpine

telegraf_plugins_default:
  - plugin: cpu
    config:
      - percpu = true
  - plugin: disk
    tagpass:
      - fstype = [ "ext4", "xfs" ]
    tagdrop:
      - path = [ "/etc", "/etc/telegraf", "/etc/hostname", "/etc/hosts", "/etc/resolv.conf" ]
  - plugin: io
  - plugin: mem
  - plugin: system
  - plugin: swap
  - plugin: netstat
  - plugin: processes
  - plugin: docker
    config:
      - endpoint = "unix:///var/run/docker.sock"
      - timeout = "5s"

Windows specific Variables

NOTE

Support for Windows is a best effort (I can't test on all possible Windows versions). PRs for Windows changes are welcome!

• telegraf_win_install_dir: Directory for Telegraf installation.
• telegraf_win_logfile: Telegraf log file location.
• telegraf_win_include: Directory for all plugin configurations.

openSUSE specific Variables

• telegraf_zypper_baseurl: URL for the openSUSE repository hosting Telegraf (e.g., "http://download.opensuse.org/repositories/devel:/languages:/go/openSUSE_Leap_{{ ansible_distribution_version }}/"). Default repository will be used if unspecified.

MacOS specific Variables

NOTE

Support for MacOS is similar to Windows support and not officially recognized.

• telegraf_mac_user: User Telegraf will run as (important as running services under different users using brew can be tricky).

Extra information

There are two properties that seem similar but are used differently:

• telegraf_plugins_default
• telegraf_plugins_extra

telegraf_plugins_default

This property sets the default Telegraf plugins. You can override it by adding more plugins that should be enabled by default.

telegraf_plugins_default:
  - plugin: cpu
    config:
      - percpu = true
  - plugin: disk
  - plugin: io
  - plugin: mem
  - plugin: system
  - plugin: swap
  - plugin: netstat

These plugins are the default configuration for every Telegraf agent.

telegraf_plugins_extra

The second parameter telegraf_plugins_extra allows you to add server-specific plugins. It's a hash instead of a list for merging values from multiple var files, like so:

cat group_vars/mysql_database
telegraf_plugins_extra:
  mysql:
    config:
      - servers = ["root:{{ mysql_root_password }}@tcp(localhost:3306)/"]

You can remove extra plugin files from /etc/telegraf/telegraf.d that aren't generated by this playbook using the telegraf_plugins_extra_exclusive variable.

Telegraf plugin options:

• tags: Key/value tags for a specific input's measurements, useful for filtering.
• tagpass: Define tag names and string arrays to filter metrics. Only matching metrics are emitted.
• tagdrop: The opposite of tagpass. If a tag matches, the metric is not emitted.
• interval: Frequency of metric gathering. Adjust for specific plugins if needed.
• filter.name: Include a filter for additional configuration.
• filter.config: Extra configuration for the specified filter.
• sub_inputs: If input requires sub-inputs, add them here.

Example configuration:

telegraf_plugins_default:
  - plugin: disk
    interval: 12
    tags:
      - diskmetrics = "true"
    tagpass:
      - fstype = [ "ext4", "xfs" ]
      - path = [ "/opt", "/home" ]

To define processors, use the telegraf_processors variable:

telegraf_processors:
  - processor: rename
  - processor: rename.replace
    config:
        - tag = "level"
        - dest = "LogLevel"

To use the grok filter for a logparser:

telegraf_plugins_extra:
    logparser:
    plugin: logparser
    config:
        - files = ["/var/log/messages"]
        - from_beginning = false
    filter:
        name: grok
        config:
        - patterns = ["invoked oom-killer"]

To include sub-inputs with their configuration:

sqs:
  plugin: cloudwatch
  config:
    - region = "eu-west-1"
    - access_key = "foo"
    - secret_key = "bar"
    - period = "1m"
    - delay = "2m"
    - interval = "1m"
    - namespace = "AWS/SQS"
    - statistic_include = ["average"]
  sub_inputs:
    metrics:
      - names = [
          "ApproximateAgeOfOldestMessage",
          "ApproximateNumberOfMessagesVisible",
        ]
    metrics.dimensions:
      - name = "QueueName"
      - value = "*"

Dependencies

This role has no dependencies.

Example Playbook

- hosts: servers
  roles:
     - { role: dj-wasabi.telegraf }

Molecule

This role is set up for testing with Molecule. More information about Molecule can be found here: Molecule Testing

License

BSD

Author Information

If you encounter any issues, please let me know. Pull requests are always welcome! :-)

Email: ikben [ at ] werner-dijkerman . nl