[tor-bugs] #31493 [Circumvention/Snowflake]: Add a version to the metrics output

[Tor Bug Tracker & Wiki]

#31493: Add a version to the metrics output
-------------------------------------+------------------------------
 Reporter:  cohosh                   |          Owner:  cohosh
     Type:  defect                   |         Status:  needs_review
 Priority:  Medium                   |      Milestone:
Component:  Circumvention/Snowflake  |        Version:
 Severity:  Normal                   |     Resolution:
 Keywords:                           |  Actual Points:
Parent ID:                           |         Points:
 Reviewer:                           |        Sponsor:  Sponsor28
-------------------------------------+------------------------------

Comment (by cohosh):

 Replying to [comment:5 karsten]:
 > In dir-spec, lines starting with `@` are treated as annotations that
 ''precede'' a descriptor and that can be stripped off without changing the
 descriptor. Including such a line inside a descriptor might be
 problematic.
 >
 > But after reading this ticket and #29461, I wonder if my suggestion to
 add a version number was bad advice. After all, we already have
 `snowflake-stats-end` in the first line as unique identifier of this
 descriptor type. And if something in the data format changes, there will
 be a specification update introducing new lines anyway. It's probably not
 worth the effort to update existing specification, implementation, and
 data to add something that we probably won't need. Can I take this
 suggestion back and we leave the format unchanged? (Sorry!!)

 Thanks karsten and no worries, it's best to figure out how to make our
 lives easier in the future and plan for changes now. So if we do end up
 changing the specification later, will leaving out a version annotation be
 okay to deal with? I suppose we can archive old versions of the spec in
 the snowflake repo and make a note of when the change to the new spec was
 made. I agree now that I'm looking into the annotations more that it's
 best to leave it out of the descriptor itself.

 I'm looking at `https://metrics.torproject.org/collector.html` now and if
 the snowflake metrics are going to be archived there, it probably does
 make sense for them to have an annotation similar to all of the other
 archived metrics. Just to clarify how the annotations typically work,
 would we simply move the `"@type snowflake-stats 1.0"` line to before
 `snowflake-stats-end`? Do these other collected metrics provide
 annotations to CollecTor along with the metrics data in the GET request?
 Or are they added on your end?

--
Ticket URL: <https://trac.torproject.org/projects/tor/ticket/31493#comment:6>
Tor Bug Tracker & Wiki <https://trac.torproject.org/>
The Tor Project: anonymity online