feat(docs): add v2 metrics reference for backwards compatibility tracking by hharshhsaini · Pull Request #1071 · jaegertracing/documentation

hharshhsaini · 2026-03-11T03:40:44Z

Which problem is this PR solving?

Doccumentation Part of Implement framework to validate backwards compatibility of metrics jaeger#6278

Description of the changes

Added scripts/fetch_metrics_reference.py a script that fetches the CI-generated metrics reports from jaegertracing/jaeger and extracts the current Jaeger v2 metric names and their labels into a single reference page.
Added a fetch-metrics Makefile target so the page can be regenerated easily when a new Jaeger v2 release is made.
Created content/docs/v2/_dev/operations/metrics-reference.md as a new documentation page listing all v2 metrics for backwards-compatibility tracking across Jaeger v2 releases.
Registered the page in the Operations section sidebar navigation.

How was this change tested?

Ran make fetch-metrics locally to verify the script correctly pulls and parses the upstream metrics reports, outputting only v2 metric names and label dimensions.
Verified CI checks pass: npm run check:spelling and npm run check:links:all both pass locally.

Checklist

I have read https://github.com/jaegertracing/jaeger/blob/main/CONTRIBUTING_GUIDELINES.md
I have signed all commits
I have added unit tests for the new functionality
I have run lint and test steps successfully: make lint test

AI Usage in this PR (choose one)

See AI Usage Policy.

None: No AI tools were used in creating this PR
Light: AI provided minor assistance (formatting, simple suggestions)
Moderate: AI helped with code generation or debugging specific parts
Heavy: AI generated most or all of the code changes

Copilot

Pull request overview

Integrates an auto-generated Jaeger v2 metrics reference into the documentation site by fetching upstream-generated markdown tables and adding a dedicated docs page linked from the Operations section.

Changes:

Added scripts/fetch_metrics_reference.py to download and assemble metrics mapping tables from jaegertracing/jaeger.
Added fetch-metrics Makefile target to generate the Hugo-compatible metrics reference page.
Added a new Operations nav entry and the generated metrics-reference.md page under v2 docs.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 6 comments.

File	Description
`scripts/fetch_metrics_reference.py`	New generator script that downloads upstream markdown and stitches it into a single Hugo page.
`Makefile`	Adds `fetch-metrics` target to run the generator script.
`content/docs/v2/_dev/operations/metrics-reference.md`	New generated metrics reference page content.
`content/docs/v2/_dev/operations/_index.md`	Adds “Metrics Reference (v2)” to the Operations sidebar navigation.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot

Pull request overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated 5 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

hharshhsaini · 2026-03-11T12:40:51Z

@yurishkuro @jkowall

This PR implements Task 5 of issue #6278 integrating the auto-generated Jaeger v1 → v2 metrics reference into the documentation website.

Here's a quick summary of what's been done:

Added scripts/fetch_metrics_reference.py a script that dynamically pulls the CI-generated metrics markdown tables from the main jaegertracing/jaeger repo
Added a fetch-metrics Makefile target for easy regeneration
Created content/docs/v2/_dev/operations/metrics-reference.md as the new docs page
Registered the page in the Operations section navigation

All CI checks are passing. All Copilot review suggestions have been addressed. I believe this PR is ready for merge.

yurishkuro · 2026-03-11T14:58:27Z

Please explain what this is trying to achieve. The linked ticket is not asking for comparison with v1 metrics - v1 is deprecated.

hharshhsaini · 2026-03-11T15:47:52Z

Thanks for the feedback.

Looking at the linked issue and the merged PRs (#5941, #6310, #6330, #7376), those PRs introduced an automated CI pipeline that generates markdown tables mapping Jaeger v1 metric names to their Jaeger v2 / OpenTelemetry equivalents (for the purpose of helping users migrating from v1 to v2).

Task 5 of issue #6278 specifically says:

"incorporate the report into the documentation website"

I interpreted "the report" as those auto-generated migration comparison tables. My goal was to surface them in the docs site so users migrating from v1 can find the mapping.

If this is not the right interpretation, I'd appreciate clarification -> should this PR focus only on documenting the new v2/OTEL metrics (without any v1 comparison), or is the entire premise of this PR incorrect? Happy to adjust the direction based on your feedback.

yurishkuro · 2026-03-11T16:44:36Z

The whole issue is about maintaining backwards compatibility of metrics when new v2 releases are done. It has nothing to do with v1 metrics which are already not compatible.

Copilot

Pull request overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated 4 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot

Pull request overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated 4 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

hharshhsaini · 2026-03-12T03:29:43Z

The whole issue is about maintaining backwards compatibility of metrics when new v2 releases are done. It has nothing to do with v1 metrics which are already not compatible.

@yurishkuro

I've updated the approach accordingly. The page now documents only the current Jaeger v2 metrics and their labels, with the description clearly stating its purpose: tracking backwards compatibility across v2 releases (i.e. ensuring metric names and labels don't change unexpectedly between v2 versions).

The v1-related framing has been completely removed. Updated commit: feat(docs): add v2 metrics reference for backwards compatibility tracking

Please take another look .

Copilot

Pull request overview

Copilot reviewed 5 out of 5 changed files in this pull request and generated 2 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

hharshhsaini · 2026-03-16T17:16:51Z

@yurishkuro

I've addressed all the feedback from your latest review:

Removed unnecessary cspell words - the metric-specific terms (inuse, mallocs, memstats, etc.) are no longer needed since the checked-in file is now a placeholder.
Removed "all-in-one" section heading - updated to reflect that Jaeger v2 is just Jaeger with different extensions, not a separate binary.
Replaced generated content with a placeholder as you suggested - actual metrics data is meant to be built during the release process, not checked in under _dev.
Made the git ref configurable via JAEGER_METRICS_REF env var (as suggested by Copilot) so the script can be pinned to a specific release tag for reproducible output.
Would appreciate another look when you get a chance

Copilot

Pull request overview

Copilot reviewed 5 out of 5 changed files in this pull request and generated 4 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot

Pull request overview

Copilot reviewed 5 out of 5 changed files in this pull request and generated 3 comments.

…king Signed-off-by: hharshhsaini <sainiharsh3311@gmail.com>

- Fix in_table state machine: exit on non-pipe non-empty line so tables not followed by blank lines don't drop remaining document content - Update copyright year 2024 -> 2026 as suggested by yurishkuro - Clarify script comments to accurately describe source files as v1-to-v2 mapping tables under cmd/jaeger/docs/migration/ - Add note to pin JAEGER_METRICS_REF to a specific release tag - Add missing newline at end of operations/_index.md Signed-off-by: hharshhsaini <sainiharsh3311@gmail.com>

hharshhsaini · 2026-06-07T13:11:37Z

@yurishkuro Sir
I have updated the PR to resolve all review feedback and address the parser script suggestions:

Updated the copyright year to 2026 and clarified the source file comments.
Added the missing newline at the end of _index.md.
Fixed the parser script bug to correctly handle tables not followed by blank lines and improved download error handling.
Rebased onto the latest upstream/main to resolve conflicts.

Please review it once.

Copilot AI review requested due to automatic review settings March 11, 2026 03:40

Copilot started reviewing on behalf of hharshhsaini March 11, 2026 03:41 View session

hharshhsaini force-pushed the feat/add-metrics-summary branch from d8aafd5 to 9696dbe Compare March 11, 2026 03:45

Copilot AI reviewed Mar 11, 2026

View reviewed changes

hharshhsaini force-pushed the feat/add-metrics-summary branch from 9696dbe to fe8ec86 Compare March 11, 2026 03:54

Copilot AI review requested due to automatic review settings March 11, 2026 09:54

hharshhsaini force-pushed the feat/add-metrics-summary branch from fe8ec86 to 1343775 Compare March 11, 2026 09:54

Copilot started reviewing on behalf of hharshhsaini March 11, 2026 09:55 View session

Copilot AI reviewed Mar 11, 2026

View reviewed changes

Comment thread scripts/fetch_metrics_reference.py

Comment thread scripts/fetch_metrics_reference.py Outdated

Comment thread scripts/fetch_metrics_reference.py Outdated

Comment thread .htmltest.yml

Comment thread scripts/fetch_metrics_reference.py

hharshhsaini force-pushed the feat/add-metrics-summary branch from 1343775 to 7fa0df0 Compare March 11, 2026 10:59

Copilot AI review requested due to automatic review settings March 11, 2026 16:52

hharshhsaini force-pushed the feat/add-metrics-summary branch from 7fa0df0 to ba7b19a Compare March 11, 2026 16:52

Copilot AI reviewed Mar 11, 2026

View reviewed changes

Comment thread scripts/fetch_metrics_reference.py

Comment thread scripts/fetch_metrics_reference.py Outdated

Comment thread scripts/fetch_metrics_reference.py Outdated

Comment thread content/docs/v2/_dev/operations/metrics-reference.md Outdated

Copilot started reviewing on behalf of hharshhsaini March 11, 2026 17:00 View session

hharshhsaini changed the title ~~feat(docs): integrate auto-generated metrics reference for v2 migration~~ feat(docs): add v2 metrics reference for backwards compatibility tracking Mar 11, 2026

hharshhsaini force-pushed the feat/add-metrics-summary branch from ba7b19a to d31cae8 Compare March 11, 2026 17:05

Copilot AI review requested due to automatic review settings March 11, 2026 17:08

hharshhsaini force-pushed the feat/add-metrics-summary branch from d31cae8 to 05f539e Compare March 11, 2026 17:08

Copilot AI reviewed Mar 11, 2026

View reviewed changes

Comment thread content/docs/v2/_dev/operations/metrics-reference.md Outdated

Comment thread scripts/fetch_metrics_reference.py Outdated

Comment thread scripts/fetch_metrics_reference.py Outdated

Comment thread scripts/fetch_metrics_reference.py

Copilot started reviewing on behalf of hharshhsaini March 11, 2026 17:15 View session

hharshhsaini force-pushed the feat/add-metrics-summary branch from 05f539e to b9f7993 Compare March 12, 2026 02:50

yurishkuro reviewed Mar 15, 2026

View reviewed changes

Comment thread .cspell/project-words.txt Outdated

yurishkuro requested changes Mar 15, 2026

View reviewed changes

Comment thread content/docs/v2/_dev/operations/metrics-reference.md Outdated

Comment thread content/docs/v2/_dev/operations/metrics-reference.md

Comment thread scripts/fetch_metrics_reference.py Outdated

Copilot AI review requested due to automatic review settings March 15, 2026 07:15

hharshhsaini force-pushed the feat/add-metrics-summary branch from b9f7993 to d7d76ec Compare March 15, 2026 07:15

Copilot started reviewing on behalf of hharshhsaini March 15, 2026 07:15 View session

Copilot AI reviewed Mar 15, 2026

View reviewed changes

Comment thread scripts/fetch_metrics_reference.py Outdated

Comment thread content/docs/v2/_dev/operations/metrics-reference.md Outdated

hharshhsaini force-pushed the feat/add-metrics-summary branch from d7d76ec to a984206 Compare March 16, 2026 08:33

yurishkuro reviewed Mar 16, 2026

View reviewed changes

Comment thread scripts/fetch_metrics_reference.py Outdated

Copilot AI review requested due to automatic review settings March 16, 2026 17:41

hharshhsaini force-pushed the feat/add-metrics-summary branch from a984206 to 732007b Compare March 16, 2026 17:41

Copilot started reviewing on behalf of hharshhsaini March 16, 2026 17:41 View session

Copilot AI reviewed Mar 16, 2026

View reviewed changes

Comment thread scripts/fetch_metrics_reference.py Outdated

Comment thread content/docs/v2/_dev/operations/metrics-reference.md Outdated

Comment thread content/docs/v2/_dev/operations/metrics-reference.md Outdated

Comment thread scripts/fetch_metrics_reference.py Outdated

hharshhsaini force-pushed the feat/add-metrics-summary branch from 732007b to c62cdec Compare March 16, 2026 17:58

yurishkuro requested changes May 15, 2026

View reviewed changes

Comment thread scripts/fetch_metrics_reference.py Outdated

Comment thread scripts/fetch_metrics_reference.py

Copilot AI review requested due to automatic review settings June 7, 2026 12:13

Copilot AI reviewed Jun 7, 2026

View reviewed changes

Comment thread scripts/fetch_metrics_reference.py

Comment thread scripts/fetch_metrics_reference.py

Comment thread scripts/fetch_metrics_reference.py

hharshhsaini added 2 commits June 7, 2026 18:19

feat(docs): add v2 metrics reference for backwards compatibility trac…

e7155c9

…king Signed-off-by: hharshhsaini <sainiharsh3311@gmail.com>

hharshhsaini force-pushed the feat/add-metrics-summary branch from 913bbed to 4ed1f34 Compare June 7, 2026 12:53

Uh oh!

Conversation

hharshhsaini commented Mar 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Which problem is this PR solving?

Description of the changes

How was this change tested?

Checklist

AI Usage in this PR (choose one)

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

hharshhsaini commented Mar 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

yurishkuro commented Mar 11, 2026

Uh oh!

hharshhsaini commented Mar 11, 2026

Uh oh!

yurishkuro commented Mar 11, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

hharshhsaini commented Mar 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

hharshhsaini commented Mar 16, 2026

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

hharshhsaini commented Mar 11, 2026 •

edited

Loading

hharshhsaini commented Mar 11, 2026 •

edited

Loading

hharshhsaini commented Mar 12, 2026 •

edited

Loading