Vector: Add code comments for metrics internals

Created on 23 Jul 2020 · 4Comments · Source: timberio/vector

While reviewing #3094, I noticed it's hard to figure out what's going on, in particular around event::metric::MetricValue, mainly because the intent of the code is not clear from the code itself, and it's difficult to assert correctness. It would be great if we add doc-comments for those core structures.

P.S. Maybe it's just me, if so we can close this.

observability tech debt

Source

MOZGIII

Most helpful comment

Sure. @lukesteensen was involved, but I think a previous contractor wrote the initial parts (@loony-bean). Given that you're about to get into metrics via https://github.com/timberio/vector-product/issues/19, it's a good opportunity to pair with @lukesteensen and learn how it works and document it along the way. I'm sure @loony-bean would be happy to clarify things as well.

binarylogic on 1 Aug 2020

👍2

All 4 comments

Yep, we're actively working through and will have a full catalog of Vector's metrics and events.

binarylogic on 23 Jul 2020

I'm in particular worried about interpreting this conversion: https://github.com/timberio/vector/blob/349ad526c8e86b3b271ee7bb04134d15a2c1566f/src/sources/internal_metrics.rs#L100

I figured it out since, but code doc at https://github.com/timberio/vector/blob/349ad526c8e86b3b271ee7bb04134d15a2c1566f/src/event/metric.rs#L37 would save me some time.

I feel like metrics themselves are far less trivial than events since math (statistics) is involved, and we should to the very least leave pointers the wiki pages on the matter in the documentation for the contributors that aren't familiar with it.

P.S. Sorry for only providing this concrete example now, should've started with it.

MOZGIII on 23 Jul 2020

👍1

I believe @lukesteensen wrote this one. Would this one be better assigned to him? I can tackle documenting the tricky parts, but I too will be figuring it out from the code.