[DOCUMENTATION] Improve Documentation of Scraping Behaviour

[zachary-povey]

Right now, if you're coming to YACE without any context it's pretty difficult to work out how the scraping actually takes place and what this means for the data you get back. Working out how to set delay, length, period and other related options, is very difficult without basically going back to source code and old pull requests.

At present the best reference for how to set these values is actually a user question. Obviously it's not ideal for the best reference to be an issue anyway but also this is out of date now and misses some key gotchas.

One key thing that caught me out recently is that discovery jobs round to the most recent previous period (even though static jobs don't do this). So, if you have a period of 10 minutes and a scrape_interval of 5 minutes it can be up to 15 minutes before you are aware of an event captured in the metrics. The only place this is hinted to in the docs is in the blurb for roundingPeriod here.

I then thought I could get my desired behaviour (rolling period of 10 minutes evaluated every 5) by using roundingPeriod, but the docs here failed to mention that roundingPeriod now actually doesn't do anything, I think since this commit released in v0.61.0 (think this breaking change was missed off of the release notes).

So my suggestion would be:

• update documentation for roundingPeriod explaining it doesn't do anything
• if I'm correct about when that happened, update release notes for v0.61.0 to indicate the breaking change for roundingPeriod
• create a new dedicated page in /docs with some pictures explaining how the different parameters interact and how they differ between job types

Happy to help on the last one there if you guys agree, would help cement it in my head also!

Love the project, keep up the good work.

Cheers!