1668547 - Include the original metric name in a comment next to the generated code for that metric

Status: RESOLVED FIXED

(Data Platform and Tools :: Glean: SDK, defect, P1)

Description

[Michael Droettboom [:mdroettboom]]

Metrics in the metrics.yaml are specified using snake_case. However, to comply with coding standards in various languages, that may be adapted to camelCase or something casing variant.

For Glean Dictionary and other tools to examine metrics, we'd like to be able to provide searchfox links to search for all the places that the metric is used. However, with the different case variants in play, a single search string won't work. We could search for all possible case variants of a metric name, but that likely will turn up too many false positives, and may still miss things if symbol-renaming features like C++'s using keyword are used. Alternatively, if we include the original metric name in a comment next to the generated metric code, a search on the original metric name will reveal that, and it is one click away to showing all uses of that metric, with reasonably accuracy.

We should: Update all of the code generation templates so the original name of the metric is included in a comment on the same line as the metric definition. (This includes both "core" templates in glean_parser and FOG templates).

Comment 1

[Chris H-C :chutten]

(In reply to Michael Droettboom [:mdroettboom] from comment #0)

Alternatively, if we include the original metric name in a comment next to the generated metric code, a search on the original metric name will reveal that, and it is one click away to showing all uses of that metric, with reasonable accuracy.

This is because searchfox indexes generated code and can search using symbols (e.g. this search on A11Y_THEME).

This may not 100% help out other codesearch tools that don't understand symbols or don't index generated code, but it'll help Firefox Desktop's searchfox workflow quite a bit (solving some weaknesses we have in e.g. Scalars (try to find uses of the a11y.theme without knowing that search link above)).

Comment 2

[Michael Droettboom [:mdroettboom]]

Also note that this approach doesn't work for projects where searchfox doesn't index generated code (glean itself, Fenix). Searchfox probably can be updated to index generated code for those projects, so the approach in this bug probably makes sense nonetheless -- it just may not work fully until indexing generated code is also resolved.

Comment 3

[GitHub Bugzilla PR Linker]

Attachment: Link to GitHub pull-request: https://github.com/mozilla/glean_parser/pull/235

Comment 4

[Michael Droettboom [:mdroettboom]]

Fixed in the glean_parser templates. I'm going to untake this now and leave it for someone else to do the same in FOG.

Comment 5

[Jan-Erik Rediger [:janerik]]

(unintentionally closed this)

Comment 6

[Jan-Erik Rediger [:janerik]]

We landed this as part of the MLA in the linked bug. See https://searchfox.org/mozilla-central/source/__GENERATED__/toolkit/components/glean/api/src/metrics.rs#37 for example.