feat: Collection offset implementation

[srebhan]

• Updated associated README.md.
• Wrote appropriate unit tests.
• Pull request title or commits are in conventional commit format

resolves #1319
resolves #10406

related to #10530

This PR addresses a long standing feature-request to be able to define an offset from the collection interval. This can be helpful in order to manually schedule data collection between agents, if the global option is used with multiple agents, or, if the plugin option is used, between plugins. The new collection_offset allows to define a time offset from the (rounded and unaligned) collection time. The option is valid in either the agent section or in any input-plugin section (as other interval parameters).

[telegraf-tiger]

☺️ This pull request doesn't significantly change the Telegraf binary size (less than 1%)

📦 Looks like new artifacts were built from this PR.

Expand this list to get them here ! 🐯

Artifact URLs

DEB	RPM	TAR GZ	ZIP
amd64.deb	aarch64.rpm	darwin_amd64.tar.gz	windows_amd64.zip
arm64.deb	armel.rpm	darwin_arm64.tar.gz	windows_i386.zip
armel.deb	armv6hl.rpm	freebsd_amd64.tar.gz
armhf.deb	i386.rpm	freebsd_armv7.tar.gz
i386.deb	ppc64le.rpm	freebsd_i386.tar.gz
mips.deb	riscv64.rpm	linux_amd64.tar.gz
mipsel.deb	s390x.rpm	linux_arm64.tar.gz
ppc64el.deb	x86_64.rpm	linux_armel.tar.gz
riscv64.deb		linux_armhf.tar.gz
s390x.deb		linux_i386.tar.gz
		linux_mips.tar.gz
		linux_mipsel.tar.gz
		linux_ppc64le.tar.gz
		linux_riscv64.tar.gz
		linux_s390x.tar.gz
		static_linux_amd64.tar.gz

[sjwang90]

Tested the artifacts and everything works as expect. Awesome work @srebhan 😄

[poulhs]

I have tested a few different scenarios and it works exactly as expected. Very nice and very useful.

My only comment is about the comment... I think that "manually scheduling" may be a bit obfuscating - it does not require anyone to hit return to continue... ;-)

[reimda]

Hi Sven, it seems like 1319 and 10406 are requesting exact timing based on the system clock, kind of like cron can trigger on x minute of the hour. In those issues the use case is to have telegraf instances on multiple machines have synchronized intervals. (for example machine 1 gathers on the first minute of every hour and machine 2 gathers on the 30th minute of every hour)

10530 and this PR add an offset to telegraf's current interval. This doesn't seem to be the same thing as synchronizing the interval to the clock. Am I missing something? Maybe you intend people to use external tools like cron or at to start telegraf at an exact time?

[poulhs]

I think you missed something, @reimda - To get exact timing you must control more configurations.
Assume you want to telegraf to perform a check every 10 seconds, at :05, :15, :25, ... you do:

• interval = "10s" # every 10 seconds
• collection_jitter = "0s" # "unrandom" - doing exact timing:
• round_interval = true # relative to systemclock - not starttime:
• collection_offset = "5s" ` # and changing from :00, :10, :20, etc, to 05, :15, :25, etc:

That will do the trick - having the servers with different collection_offsets makes it possible to control this (one server as above, another with `collection_offset = "0s"``)

On a single telegraf, this can be used to ensure that multiple checks are started at different times "don't step on my toes" - just apply same interval and different collection_offsets

And I guess there exist several other use-cases.... (time will show ☺)

[reimda]

Thanks @poulhs for the clarification. I misunderstood how round_interval works. This looks very useful to me now!

[kaunix]

so are these changes available in 1.26?

[powersj]

so are these changes available in 1.26?

Yes

[kaunix]

so I tried to use them in the conf file (see below) and telegraf wouldn't start:

[[inputs.exec]]
commands=["/usr/bin/iperf3 -O 7 -c 192.168.1.1 --json"]
#interval = "1783s"
interval = "1800s"
collection_jitter= "0s"
round_interval = true
collection_offset = "54s"
timeout = "40s"
data_format = "json"
json_query = "end"
name_override = "server.example.com-write"

[[inputs.exec]]
commands=["/usr/bin/iperf3 -O 7 -c 192.168.1.1 -R --json"]
#interval = "1801s"
interval = "1800s"
collection_jitter= "0s"
round_interval = true
collection_offset = "1"
timeout = "40s"
data_format = "json"
json_query = "end"
name_override = "server.example.com-read"

[[inputs.exec]]
commands=["/usr/bin/iperf3 -O 7 -c 192.168.1.2 --json"]
#interval = "1831s"
interval = "1800s"
collection_jitter= "0s"
round_interval = true
collection_offset = "15"
timeout = "40s"
data_format = "json"
json_query = "end"
name_override = "server2.example.com-write"

[[inputs.exec]]
commands=["/usr/bin/iperf3 -O 7 -c 192.168.1.2 -R --json"]
#interval = "1867s"
interval = "1800s"
collection_jitter= "0s"
round_interval = true
collection_offset = "35"
timeout = "40s"
data_format = "json"
json_query = "end"
name_override = "server2.example.com-read"

[powersj]

File a bug please, asking on a closed PR isn't the place