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.

scripts/fetch_metrics_reference.py

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

Makefile

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.

scripts/fetch_metrics_reference.py

.htmltest.yml

scripts/fetch_metrics_reference.py

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.

scripts/fetch_metrics_reference.py

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

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.

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

scripts/fetch_metrics_reference.py

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 .

yurishkuro · 2026-03-15T04:10:04Z

.cspell/project-words.txt

 ingester
 ingester's
 ingesters
+inuse


why do we need to add new words?

These words (inuse, mallocs, mcache, memstats, memtable, mspan, valueloggc) were added to silence spellcheck errors originating from Go runtime metrics in the old generated content. Since the metrics-reference.md is now only a placeholder (actual data generated at release time), none of those runtime terms appear in the checked files anymore. Removed all of them.

yurishkuro · 2026-03-15T04:11:39Z

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

+
+> **Note:** This page is auto-generated. Run `make fetch-metrics` to update it.
+
+## All-in-One Component Metrics


there is no need to reference all-in-one, there is just Jaeger that has different extensions.

The section title in the script has been updated from All-in-One Component to simply Jaeger.

yurishkuro · 2026-03-15T04:12:15Z

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

@@ -0,0 +1,141 @@
+---


we do not need to check this in under _dev (can check a placeholder if necessary). The actual metrics summary must be built during the release process.

The fully-generated content has been replaced with a placeholder page that explains the purpose and how to regenerate it (make fetch-metrics). The script is now clearly documented as a release-time tool, not something that generates committed content during development

yurishkuro · 2026-03-15T04:13:13Z

scripts/fetch_metrics_reference.py

+logger = logging.getLogger(__name__)
+
+# Base URL for the raw markdown files generated by the jaeger E2E workflow
+BASE_RAW_URL = "https://raw.githubusercontent.com/jaegertracing/jaeger/main/cmd/jaeger/docs/migration/"


these are stale files that do not reflect the current state of Jaeger metrics.

The cmd/jaeger/docs/migration/ files are the v1→v2 one-time migration artifacts. The script comment has been updated to clarify this and notes that during an actual release, a specific release tag ref should be passed for reproducible output. I understand the longer-term goal is for the CI to generate fresh metrics snapshots per release and have the documentation updated from those happy to align this script with whatever that release workflow looks like once it's in place.

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.

scripts/fetch_metrics_reference.py

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

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

yurishkuro · 2026-03-16T17:34:58Z

scripts/fetch_metrics_reference.py

+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+# Base URL template for the metrics reports generated by the Jaeger E2E integration tests.


metrics reports generated by the Jaeger E2E integration tests

CI does not store reports in the repository as docs, it stores them as GH artifacts.

Fixed, @yurishkuro Updated the comment to accurately state that CI stores metrics reports as GitHub artifacts, not as docs committed to the repository. The comment now reads: "CI stores metrics reports as GitHub artifacts, not as docs in the repository."

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.

scripts/fetch_metrics_reference.py

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

scripts/fetch_metrics_reference.py

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

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

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

scripts/fetch_metrics_reference.py Show resolved Hide resolved

scripts/fetch_metrics_reference.py Outdated Show resolved Hide resolved

scripts/fetch_metrics_reference.py Outdated Show resolved Hide resolved

content/docs/v2/_dev/operations/metrics-reference.md Outdated Show resolved Hide resolved

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

content/docs/v2/_dev/operations/metrics-reference.md Outdated Show resolved Hide resolved

scripts/fetch_metrics_reference.py Outdated Show resolved Hide resolved

scripts/fetch_metrics_reference.py Outdated Show resolved Hide resolved

scripts/fetch_metrics_reference.py Show resolved Hide resolved

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

yurishkuro requested changes Mar 15, 2026

View reviewed changes

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

scripts/fetch_metrics_reference.py Outdated Show resolved Hide resolved

content/docs/v2/_dev/operations/metrics-reference.md Outdated Show resolved Hide resolved

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

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

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

c62cdec

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

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


		> Note: This page is auto-generated. Run `make fetch-metrics` to update it.

		## All-in-One Component Metrics

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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

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

hharshhsaini commented Mar 11, 2026 •

edited

Loading

hharshhsaini commented Mar 11, 2026 •

edited

Loading

hharshhsaini commented Mar 12, 2026 •

edited

Loading