influxdata / influxdata/telegraf

Broken core product promise: missing documentation how to setup more than one input stream

Open
#16,004 7 comments 0 reactions 0 assignees View on GitHub
feature request
Dominant language
Go
Stars
17.8k
Forks
5.8k
Avg merge
1d 20h
Merged PRs (30d)
161

Description

### Use Case

- rely on telegraf documentation
- Aggregation of multiple sensor data streams into different buckets
- slowly build up system and experience
- experiment with new streams in running environment

e.g. my home automation scenario on a farm:
- weather (a local and a remote station)
- energy
- grain store (multiple temp/hum sensors)
- maybe some machines in the future

### Expected behavior

After reading the documentation, I can install and configure telegraf to deliver its promised functions

### Actual behavior

- documentation is incomprehensible
- with autogenerated template (by influx), manual edit and loads of educated guess I managed my first productive stream
(reading grid power from mqtt traffic and merge it via Influx and Grafana with evcc data)
- when I tried test data from Influx generated template, I found my productive stream clobbered
- when I tried to test another stream (pull weather data from a mysql database) telegraf screwed up (details not important here)

### Additional info

Thank you, friends, for delivering this maybe great product. :bow:
But - sorry to say - imho largely inappropriate [documentation](https://docs.influxdata.com/telegraf/v1/) (really sorry) is prone to spoil all your diligent work. :sweat:
Please allow me some humble feedback to assist you in improving it.

Quick fix ahead: :pray:
Put a "further reading"-Link to this blog post onto every documentation page that contains anything related to "config*"
https://www.influxdata.com/blog/telegraf-best-practices/

Make clear in the documentation
- that by default, **all input streams are lumped together** to all output streams
- that skd of **"routing"** exists and how to avoid mixing up streams by implementing it
- that for mixing of experimental and productive streams, **multiple telegraf instances** are considered good practice, (not evil hack, as with most other server software)

"somewhere on the internet" I remember a **chart with input / processing / aggregation / output streams,** but even searching twice, I can't find it in the documentation any more. Would be a good start, though.

I'd consider moving `/lib/systemd/system/telegraf.service` to `/etc/systemd/system`, since that **where I'd expect service files intended to be fiddled with**. Anything in `/lib/..` imho commonly is considered "only to be fiddled with by brave developers on a testing environment"

In particular, I found this section **completely misleading**
https://docs.influxdata.com/telegraf/v1/configuration/#telegraf-doesnt-support-partial-configurations

- what is a **"valid" configuration?** From context, _I inferred to expect an independent stream (globals, input, output)_
It was only by hard experience and mentioned "best practice" blog to learn otherwise.
- "**effective configuration is the union** of all the files" - I had to learn the hard way that this means lumping all input streams together
- obviously the `[global tags]` | `[agent]` section is nevertheless allowed only once

Putting `[global tags]` into every config file (as one might infer from "valid configuration"), yields the misleading
`W! Overlapping settings in multiple agent tables are not supported: may cause undefined behavior`

This is short to end up in _"Following the official documentation causes undefined behaviour"._ Not really what I expect for a celebrated product... :face_with_spiral_eyes:

Searching the internet for e.g. this message or for "telegraf multiple config files" yield loads of other victims crying for the same problem. Most of them only partially answered - or not at all. Some gracefully "send my your configs and I, the Master, will savior you". Well, fine, for one.

Only after hours of searching, dozens of config changes and restart, buckets & api-tokens deleted and recreated, **short of thrashing** your great piece of work and reverting to good old PERL demons, I **luckily encontered said "best practice"** article.

So why not teaching telegraf users how to do fishing instead giving them a piece of fish?

Contributor guide

Open the contributing guide

Research direction

Start with the Telegraf configuration documentation at the linked configuration page and review the linked best-practices article. Clarify how multiple input and output streams are combined, how routing works, when to use multiple instances, and how partial configurations and global settings behave. Done means a newcomer can configure separate experimental and productive streams without relying on guesswork.

Written by the indexing model from the issue text.

Assessment

Tech stack
grafana, mysql
Domain
devops, documentation
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
38/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.