Add metrics annotations and generate docs #1152
Assignees
Labels
Comments
This was referenced Sep 25, 2024
VinozzZ
added a commit
that referenced
this issue
Sep 26, 2024
…able easier documentation generation (#1350) ## Which problem is this PR solving? - part 1 for: #1152 This PR prepares us to have a consistent metrics registration pattern so that in a later PR we can use https://pkg.go.dev/golang.org/x/tools/go/packages to automatically generate metrics documentation. - part 2 is implemented in #1351 ## Short description of the changes - Introduce a new struct type `metrics.Metadata` to represent all information needed for a Refinery metric - Change `metrics.Register` signature to accept `metrics.Metadata` as its argument - Refactor metrics registration calls in each packages so that we declare metrics we want to register first in a package level variable first - Set zero value for each OTel metrics during registration - set Unit and Description for each OTel metrics
VinozzZ
added a commit
that referenced
this issue
Sep 26, 2024
## Which problem is this PR solving? This PR implements the logic to parse out all metrics defined in the Refinery code base and generates a markdown table for them. - part 2 of #1152 ## Short description of the changes - add two new commands to the `convert` tool to generate the metricsMeta.yaml file and a metrics.md file
TylerHelmuth
pushed a commit
that referenced
this issue
Oct 16, 2024
…able easier documentation generation (#1350) ## Which problem is this PR solving? - part 1 for: #1152 This PR prepares us to have a consistent metrics registration pattern so that in a later PR we can use https://pkg.go.dev/golang.org/x/tools/go/packages to automatically generate metrics documentation. - part 2 is implemented in #1351 ## Short description of the changes - Introduce a new struct type `metrics.Metadata` to represent all information needed for a Refinery metric - Change `metrics.Register` signature to accept `metrics.Metadata` as its argument - Refactor metrics registration calls in each packages so that we declare metrics we want to register first in a package level variable first - Set zero value for each OTel metrics during registration - set Unit and Description for each OTel metrics
TylerHelmuth
pushed a commit
that referenced
this issue
Oct 16, 2024
## Which problem is this PR solving? This PR implements the logic to parse out all metrics defined in the Refinery code base and generates a markdown table for them. - part 2 of #1152 ## Short description of the changes - add two new commands to the `convert` tool to generate the metricsMeta.yaml file and a metrics.md file
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Is your feature request related to a problem? Please describe.
Refinery has lots of metrics. It's not always obvious what they do, what type they are, or how they differ from other, similar metrics.
Describe the solution you'd like
Refinery's original (legacy) metrics were just simple events, but now we support OTel, and OTel supports extra things like unit, description, datatype. We can and should add those elements to the Register call for metrics so that OTel metrics can include them in the metric attributes.
Also, doing this would allow us to identify these calls and extract them automatically and use that to generate a
metrics.mddocument that would describe the metrics refinery emits. Customers would find this helpful.It could be either:
In either case, this data could then be fed to a template that writes out the metrics.md file.
Describe alternatives you've considered
Doing this all once, by hand, and then trying to remember to keep it up to date. Given the positive experience we've had with documentation generation for configuration, I think it would be worth extending the concept to metrics.
The text was updated successfully, but these errors were encountered: