From e7155c98b415610a4a61edfdef24f6bd44f93be5 Mon Sep 17 00:00:00 2001 From: hharshhsaini Date: Wed, 11 Mar 2026 09:06:54 +0530 Subject: [PATCH 1/2] feat(docs): add v2 metrics reference for backwards compatibility tracking Signed-off-by: hharshhsaini --- .htmltest.yml | 8 +- Makefile | 3 + content/docs/v2/_dev/operations/_index.md | 2 + .../v2/_dev/operations/metrics-reference.md | 13 ++ scripts/fetch_metrics_reference.py | 168 ++++++++++++++++++ 5 files changed, 190 insertions(+), 4 deletions(-) create mode 100644 content/docs/v2/_dev/operations/metrics-reference.md create mode 100755 scripts/fetch_metrics_reference.py diff --git a/.htmltest.yml b/.htmltest.yml index 352750ed..a0c782e5 100644 --- a/.htmltest.yml +++ b/.htmltest.yml @@ -1,4 +1,4 @@ -# cSpell:ignore cse github +# cSpell:ignore github CacheExpires: 13300h # ~ 18 months DirectoryPath: public IgnoreAltMissing: true @@ -9,9 +9,9 @@ IgnoreURLs: - ^/docs/latest(/?|/architecture/)$ - /livereload.js # cSpell:disable-line - ^https://www.jaegertracing.io/js/lunr - - ^https://cse.google.com/cse.js - # Ignore Docsy-generated GitHub links (view-page, edit-source, create-child) - - ^https?://github\.com/jaegertracing/documentation/(tree|edit|new)/ + # Ignore Docsy-generated GitHub links for now + - ^https?://github\.com/.*?/.*?/(new|edit)/ # view-page, edit-source etc + - ^https://github\.com/jaegertracing/documentation/tree/main/content/docs/v2/_dev/operations/metrics-reference\.md # Valid URL, whether canonical (before reorg) or not (and handled via a redirect) - ^/docs/1.[6-9]\d/sampling/ # Valid URLs, but servers yield 403 or similar errors diff --git a/Makefile b/Makefile index e5123af8..d71907dc 100644 --- a/Makefile +++ b/Makefile @@ -65,6 +65,9 @@ fetch-blog-feed: fetch-roadmap: python3 scripts/generate_roadmap.py +fetch-metrics: + python3 scripts/fetch_metrics_reference.py + # only x.y.0 semver values are valid for kicking off a new release. SEMVER_REGEX := ^([0-9]+\.){2}0$$ VALID_VERSION := $(shell echo "$(VERSION)" | grep -E "$(SEMVER_REGEX)") diff --git a/content/docs/v2/_dev/operations/_index.md b/content/docs/v2/_dev/operations/_index.md index 33328243..2e0141a1 100644 --- a/content/docs/v2/_dev/operations/_index.md +++ b/content/docs/v2/_dev/operations/_index.md @@ -10,6 +10,8 @@ children: url: performance-tuning - title: Tools url: tools +- title: Metrics Reference (v2) + url: metrics-reference --- Jaeger provides the foundational components to operate your installation. Please note that backups and lifecycle of the datastores must be handled outside of Jaeger. We provide pointers to components within the [storage backends](../architecture/) guides. \ No newline at end of file diff --git a/content/docs/v2/_dev/operations/metrics-reference.md b/content/docs/v2/_dev/operations/metrics-reference.md new file mode 100644 index 00000000..e43c7c25 --- /dev/null +++ b/content/docs/v2/_dev/operations/metrics-reference.md @@ -0,0 +1,13 @@ +--- +title: Metrics Reference (v2) +navtitle: Metrics Reference +hasparent: true +--- + +This page is intended to provide a reference of all metrics exposed by Jaeger v2. Once +populated, it is used to track **backwards compatibility across Jaeger v2 releases** — +i.e. ensuring metric names and labels do not change unexpectedly between versions. + +> **Note:** The full metrics table is generated as part of the Jaeger release process and +> is not committed verbatim to this repository. Run `make fetch-metrics` after a release +> to populate this page with up-to-date data. diff --git a/scripts/fetch_metrics_reference.py b/scripts/fetch_metrics_reference.py new file mode 100755 index 00000000..b4b0d84f --- /dev/null +++ b/scripts/fetch_metrics_reference.py @@ -0,0 +1,168 @@ +#!/usr/bin/env python3 + +# Copyright (c) 2024 The Jaeger Authors. +# SPDX-License-Identifier: Apache-2.0 + +# This script fetches the auto-generated metrics reports from the jaegertracing/jaeger +# repository and publishes a reference page of current Jaeger v2 metrics. +# It is intended to be run as part of the RELEASE PROCESS so that the committed +# metrics-reference.md always reflects the state of a specific release tag. +# The purpose is to track BACKWARDS COMPATIBILITY of metrics across Jaeger v2 releases. + +import logging +import os +import re +import sys +import urllib.error +import urllib.request +from pathlib import Path + +# Set up logging +logging.basicConfig(level=logging.INFO) +logger = logging.getLogger(__name__) + +# Base URL template for the v2 metrics reference docs stored in the jaeger repository +# under cmd/jaeger/docs/migration/. Note: these are committed markdown files, not CI artifacts; +# Set the JAEGER_METRICS_REF environment variable to a specific release tag/branch +# if you need reproducible output; it defaults to "main". +BASE_RAW_URL_TEMPLATE = "https://raw.githubusercontent.com/jaegertracing/jaeger/{ref}/cmd/jaeger/docs/migration/" +JAEGER_METRICS_REF = os.environ.get("JAEGER_METRICS_REF", "main") + +TARGET_FILES = [ + {"filename": "all-in-one-metrics.md", "title": "Jaeger"}, + {"filename": "badger-metrics.md", "title": "Badger Storage"}, + {"filename": "cassandra-metrics.md", "title": "Cassandra Storage"}, + {"filename": "elasticsearch-metrics.md", "title": "Elasticsearch Storage"}, + {"filename": "opensearch-metrics.md", "title": "OpenSearch Storage"}, +] + + +def fetch_markdown(filename): + url = BASE_RAW_URL_TEMPLATE.format(ref=JAEGER_METRICS_REF) + filename + req = urllib.request.Request(url) + try: + with urllib.request.urlopen(req, timeout=10) as response: + return response.read().decode("utf-8") + except urllib.error.HTTPError as e: + logger.error(f"HTTP Error fetching {filename}: {e.code} {e.reason}") + return None + except Exception as e: + logger.error(f"Error fetching {filename}: {e}") + return None + + +def extract_v2_metrics_table(raw_md): + """Parse the raw markdown and return a new table with only v2 Metric + v2 Labels columns. + + The source files have 4 columns: V1 Metric | V1 Labels | V2 Metric | V2 Labels. + We extract only the columns that matter for v2 backwards-compatibility tracking, + dropping rows where V2 Metric is N/A (metric was removed in v2). + """ + output_lines = [] + in_table = False + + for line in raw_md.split("\n"): + stripped = line.strip() + + # Detect the start of a 4-column metrics table (V1 Metric header) + if "V1 Metric" in stripped and "V2 Metric" in stripped: + in_table = True + # Emit the new v2-only header + output_lines.append("| Metric | Labels |") + output_lines.append("|--------|--------|") + continue + + # Skip the separator row (|---|---:|:---|...) + if in_table and re.fullmatch(r'[\|\-\s:]+', stripped): + continue + + if in_table and stripped.startswith("|"): + # Strip leading/trailing pipes first to avoid empty first column from `|| ...` rows + cols = [c.strip() for c in stripped.strip('|').split("|")] + # cols[0]=V1 Metric, cols[1]=V1 Labels, cols[2]=V2 Metric, cols[3]=V2 Labels + if len(cols) >= 4: + v2_metric = cols[2] + v2_labels = cols[3] + # Skip metrics that don't exist in v2 + if v2_metric and v2_metric.lower() != "n/a": + output_lines.append(f"| {v2_metric} | {v2_labels} |") + elif in_table and stripped == "": + in_table = False + output_lines.append("") + elif not in_table: + # Carry over subsection headings, but downgrade H1 to H3 to avoid multiple page H1s. + # Preserve H2-H6 headings as-is to keep section boundaries clear. + heading_match = re.match(r'^(#{1,6})\s+(.*)', stripped) + if heading_match: + hashes, text = heading_match.groups() + level = len(hashes) + if level == 1: + # Downgrade H1 to H3 + output_lines.append("### " + text.strip()) + else: + # Preserve H2-H6 verbatim + output_lines.append(stripped) + + return "\n".join(output_lines) + + +def generate_metrics_reference(): + content = "---\n" + content += "title: Metrics Reference (v2)\n" + content += "navtitle: Metrics Reference\n" + content += "hasparent: true\n" + content += "---\n\n" + content += ( + "This page is intended to provide a reference of all metrics exposed by Jaeger v2. Once " + "populated, it is used to track **backwards compatibility across Jaeger v2 releases** — " + "i.e. ensuring metric names and labels do not change unexpectedly between versions.\n\n" + ) + content += ( + "> **Note:** The full metrics table is generated as part of the Jaeger release process and\n" + "> is not committed verbatim to this repository. Run `make fetch-metrics` after a release\n" + "> to populate this page with up-to-date data.\n\n" + ) + + missing_files = False + + for item in TARGET_FILES: + logger.info(f"Fetching {item['filename']}...") + raw_md = fetch_markdown(item["filename"]) + if raw_md is not None: + v2_table = extract_v2_metrics_table(raw_md) + content += f"## {item['title']} Metrics\n\n" + content += v2_table.strip() + "\n\n" + else: + logger.warning(f"Skipping {item['filename']} due to fetch failure.") + missing_files = True + + return content, missing_files + + +def save_metrics_reference(content): + # Resolve output path relative to the repository root (parent of the scripts/ dir) + # so the script works correctly regardless of the current working directory. + repo_root = Path(__file__).resolve().parent.parent + target_path = repo_root / "content/docs/v2/_dev/operations/metrics-reference.md" + os.makedirs(target_path.parent, exist_ok=True) + with open(target_path, "w", encoding="utf-8") as f: + f.write(content) + logger.info(f"Successfully saved metrics reference to {target_path}") + + +def main(): + try: + content, missing_files = generate_metrics_reference() + save_metrics_reference(content) + + if missing_files: + logger.error("Failed to fetch one or more metrics files. The generated page may be incomplete.") + sys.exit(1) + + except Exception as e: + logger.error(f"An error occurred: {e}") + sys.exit(1) + + +if __name__ == "__main__": + main() From 4ed1f344c36ca279253747f0c6a093c6730afd4e Mon Sep 17 00:00:00 2001 From: hharshhsaini Date: Sun, 7 Jun 2026 18:23:11 +0530 Subject: [PATCH 2/2] fix: address review feedback (copilot and yurishkuro) - 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 --- content/docs/v2/_dev/operations/_index.md | 2 +- scripts/fetch_metrics_reference.py | 26 ++++++++++++++++++----- 2 files changed, 22 insertions(+), 6 deletions(-) diff --git a/content/docs/v2/_dev/operations/_index.md b/content/docs/v2/_dev/operations/_index.md index 2e0141a1..a2094151 100644 --- a/content/docs/v2/_dev/operations/_index.md +++ b/content/docs/v2/_dev/operations/_index.md @@ -14,4 +14,4 @@ children: url: metrics-reference --- -Jaeger provides the foundational components to operate your installation. Please note that backups and lifecycle of the datastores must be handled outside of Jaeger. We provide pointers to components within the [storage backends](../architecture/) guides. \ No newline at end of file +Jaeger provides the foundational components to operate your installation. Please note that backups and lifecycle of the datastores must be handled outside of Jaeger. We provide pointers to components within the [storage backends](../architecture/) guides. diff --git a/scripts/fetch_metrics_reference.py b/scripts/fetch_metrics_reference.py index b4b0d84f..0e15d1a8 100755 --- a/scripts/fetch_metrics_reference.py +++ b/scripts/fetch_metrics_reference.py @@ -1,13 +1,16 @@ #!/usr/bin/env python3 -# Copyright (c) 2024 The Jaeger Authors. +# Copyright (c) 2026 The Jaeger Authors. # SPDX-License-Identifier: Apache-2.0 -# This script fetches the auto-generated metrics reports from the jaegertracing/jaeger +# This script fetches the v1-to-v2 metrics mapping tables from the jaegertracing/jaeger # repository and publishes a reference page of current Jaeger v2 metrics. # It is intended to be run as part of the RELEASE PROCESS so that the committed # metrics-reference.md always reflects the state of a specific release tag. # The purpose is to track BACKWARDS COMPATIBILITY of metrics across Jaeger v2 releases. +# +# NOTE: The source files under cmd/jaeger/docs/migration/ are v1-to-v2 mapping tables. +# Pin JAEGER_METRICS_REF to a specific release tag for reproducible, up-to-date output. import logging import os @@ -21,10 +24,10 @@ logging.basicConfig(level=logging.INFO) logger = logging.getLogger(__name__) -# Base URL template for the v2 metrics reference docs stored in the jaeger repository -# under cmd/jaeger/docs/migration/. Note: these are committed markdown files, not CI artifacts; +# Base URL template for the v1-to-v2 metrics mapping tables stored in the jaeger repository +# under cmd/jaeger/docs/migration/. These are committed markdown files. # Set the JAEGER_METRICS_REF environment variable to a specific release tag/branch -# if you need reproducible output; it defaults to "main". +# (e.g. export JAEGER_METRICS_REF=v2.1.0) for reproducible output; it defaults to "main". BASE_RAW_URL_TEMPLATE = "https://raw.githubusercontent.com/jaegertracing/jaeger/{ref}/cmd/jaeger/docs/migration/" JAEGER_METRICS_REF = os.environ.get("JAEGER_METRICS_REF", "main") @@ -89,6 +92,19 @@ def extract_v2_metrics_table(raw_md): elif in_table and stripped == "": in_table = False output_lines.append("") + elif in_table and not stripped.startswith("|"): + # A non-pipe, non-empty line ends the table even without a blank separator. + # Exit table mode and fall through to heading/content processing below. + in_table = False + output_lines.append("") + heading_match = re.match(r'^(#{1,6})\s+(.*)', stripped) + if heading_match: + hashes, text = heading_match.groups() + level = len(hashes) + if level == 1: + output_lines.append("### " + text.strip()) + else: + output_lines.append(stripped) elif not in_table: # Carry over subsection headings, but downgrade H1 to H3 to avoid multiple page H1s. # Preserve H2-H6 headings as-is to keep section boundaries clear.