Skip to content

Commit d31cae8

Browse files
hharshhsainihharshhsaini
committed
feat(docs): add v2 metrics reference for backwards compatibility tracking
Signed-off-by: hharshhsaini <sainiharsh3311@gmail.com>
1 parent fa2e147 commit d31cae8

File tree

6 files changed

+291
-0
lines changed

6 files changed

+291
-0
lines changed

‎.cspell/project-words.txt‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -47,6 +47,7 @@ hugo
4747
ingester
4848
ingester's
4949
ingesters
50+
inuse
5051
istio
5152
istio's
5253
jaegertracing
@@ -64,14 +65,19 @@ logtostderr
6465
logz
6566
lookback
6667
mailgroup
68+
mallocs
6769
markdownify
70+
mcache
71+
memstats
72+
memtable
6873
mentee
6974
mentees
7075
mentorships
7176
metricsquery
7277
metricsstore
7378
metricstore
7479
microsim
80+
mspan
7581
myapp
7682
myappnamespace
7783
mynamespace
@@ -132,6 +138,7 @@ unmarshaling
132138
upsample
133139
usercert
134140
userkey
141+
valueloggc
135142
valuen
136143
vlog
137144
warnf

‎.htmltest.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@ IgnoreURLs:
1111
- ^https://www.jaegertracing.io/js/lunr
1212
# Ignore Docsy-generated GitHub links for now
1313
- ^https?://github\.com/.*?/.*?/(new|edit)/ # view-page, edit-source etc
14+
- ^https://github\.com/jaegertracing/documentation/tree/main/content/docs/v2/_dev/operations/metrics-reference\.md
1415
# Valid URL, whether canonical (before reorg) or not (and handled via a redirect)
1516
- ^/docs/1.[6-9]\d/sampling/
1617
# Valid URLs, but servers yield 403 or similar errors

‎Makefile‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -65,6 +65,9 @@ fetch-blog-feed:
6565
fetch-roadmap:
6666
python3 scripts/generate_roadmap.py
6767

68+
fetch-metrics:
69+
python3 scripts/fetch_metrics_reference.py
70+
6871
# only x.y.0 semver values are valid for kicking off a new release.
6972
SEMVER_REGEX := ^([0-9]+\.){2}0$$
7073
VALID_VERSION := $(shell echo "$(VERSION)" | grep -E "$(SEMVER_REGEX)")

‎content/docs/v2/_dev/operations/_index.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,8 @@ children:
1010
url: performance-tuning
1111
- title: Tools
1212
url: tools
13+
- title: Metrics Reference (v2)
14+
url: metrics-reference
1315
---
1416

1517
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.

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

Lines changed: 133 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,133 @@
1+
---
2+
title: Metrics Reference (v2)
3+
type: docs
4+
weight: 80
5+
---
6+
7+
This page lists all metrics currently exposed by Jaeger v2. These metrics are automatically tracked by the Jaeger CI pipeline to ensure **backwards compatibility across Jaeger v2 releases** — i.e. that metric names and labels do not change unexpectedly between v2 versions.
8+
9+
## All-in-One Component Metrics
10+
11+
### ALL-IN-ONE METRICS
12+
### Combined Metrics
13+
| Metric | Labels |
14+
|--------|--------|
15+
| jaeger_query_latency | operation, result |
16+
| jaeger_query_responses | operation |
17+
| jaeger_query_requests_total | operation, result |
18+
| exporter_send_failed_spans | exporter, service_instance_id, service_name, service_version |
19+
| exporter_sent_spans | exporter, service_instance_id, service_name, service_version |
20+
| process_cpu_seconds | service_instance_id, service_name, service_version |
21+
| process_memory_rss | service_instance_id, service_name, service_version |
22+
| process_runtime_heap_alloc_bytes | service_instance_id, service_name, service_version |
23+
| process_runtime_total_alloc_bytes | service_instance_id, service_name, service_version |
24+
| process_runtime_total_sys_memory_bytes | service_instance_id, service_name, service_version |
25+
| process_uptime | service_instance_id, service_name, service_version |
26+
| processor_batch_batch_send_size | processor, service_instance_id, service_name, service_version |
27+
| processor_batch_batch_send_size_bytes | processor, service_instance_id, service_name, service_version |
28+
| processor_batch_metadata_cardinality | processor, service_instance_id, service_name, service_version |
29+
| processor_batch_timeout_trigger_send | processor, service_instance_id, service_name, service_version |
30+
| receiver_accepted_spans | receiver, service_instance_id, service_name, service_version, transport |
31+
| receiver_refused_spans | receiver, service_instance_id, service_name, service_version, transport |
32+
| rpc_server_duration | rpc_grpc_status_code, rpc_method, rpc_service, rpc_system, service_instance_id, service_name, service_version |
33+
| rpc_server_request_size | rpc_method, rpc_service, rpc_system, service_instance_id, service_name, service_version |
34+
| rpc_server_requests_per_rpc | rpc_grpc_status_code, rpc_method, rpc_service, rpc_system, service_instance_id, service_name, service_version |
35+
| rpc_server_response_size | rpc_method, rpc_service, rpc_system, service_instance_id, service_name, service_version |
36+
| rpc_server_responses_per_rpc | rpc_grpc_status_code, rpc_method, rpc_service, rpc_system, service_instance_id, service_name, service_version |
37+
| target_info | service_instance_id, service_name, service_version |
38+
| Metric | Labels |
39+
|--------|--------|
40+
| receiver_refused_spans | receiver, service_instance_id, service_name, service_version, transport |
41+
| target_info | service_instance_id, service_name, service_version |
42+
43+
## Badger Storage Metrics
44+
45+
### BADGER METRICS
46+
### Combined Metrics
47+
| Metric | Labels |
48+
|--------|--------|
49+
| jaeger_badger_compaction_current_num_lsm | N/A |
50+
| jaeger_badger_get_num_memtable | N/A |
51+
| jaeger_badger_get_num_user | N/A |
52+
| jaeger_badger_get_with_result_num_user | N/A |
53+
| jaeger_badger_iterator_num_user | N/A |
54+
| jaeger_badger_put_num_user | N/A |
55+
| jaeger_badger_read_bytes_lsm | N/A |
56+
| jaeger_badger_read_bytes_vlog | N/A |
57+
| jaeger_badger_read_num_vlog | N/A |
58+
| jaeger_badger_size_bytes_lsm | N/A |
59+
| jaeger_badger_size_bytes_vlog | N/A |
60+
| jaeger_badger_write_bytes_l0 | N/A |
61+
| jaeger_badger_write_bytes_user | N/A |
62+
| jaeger_badger_write_bytes_vlog | N/A |
63+
| jaeger_badger_write_num_vlog | N/A |
64+
| jaeger_badger_write_pending_num_memtable | N/A |
65+
| Metric | Labels |
66+
|--------|--------|
67+
| receiver_refused_spans | receiver, service_instance_id, service_name, service_version, transport |
68+
| target_info | service_instance_id, service_name, service_version |
69+
70+
## Cassandra Storage Metrics
71+
72+
### CASSANDRA METRICS
73+
### Combined Metrics
74+
| Metric | Labels |
75+
|--------|--------|
76+
| jaeger_cassandra_attempts_total | table |
77+
| jaeger_cassandra_errors_total | table |
78+
| jaeger_cassandra_inserts_total | table |
79+
| jaeger_cassandra_latency_err | table |
80+
| jaeger_cassandra_latency_ok | table |
81+
| jaeger_cassandra_read_attempts_total | table |
82+
| jaeger_cassandra_read_errors_total | table |
83+
| jaeger_cassandra_read_inserts_total | table |
84+
| jaeger_cassandra_read_latency_err | table |
85+
| jaeger_cassandra_read_latency_ok | table |
86+
| jaeger_cassandra_tag_index_skipped_total | N/A |
87+
| Metric | Labels |
88+
|--------|--------|
89+
| receiver_refused_spans | receiver, service_instance_id, service_name, service_version, transport |
90+
| target_info | service_instance_id, service_name, service_version |
91+
92+
## Elasticsearch Storage Metrics
93+
94+
### ELASTICSEARCH METRICS
95+
### Combined Metrics
96+
| Metric | Labels |
97+
|--------|--------|
98+
| jaeger_bulk_index_attempts_total | N/A |
99+
| jaeger_bulk_index_errors_total | N/A |
100+
| jaeger_bulk_index_inserts_total | N/A |
101+
| jaeger_bulk_index_latency_err | N/A |
102+
| jaeger_bulk_index_latency_ok | N/A |
103+
| jaeger_index_create_attempts_total | N/A |
104+
| jaeger_index_create_errors_total | N/A |
105+
| jaeger_index_create_inserts_total | N/A |
106+
| jaeger_index_create_latency_err | N/A |
107+
| jaeger_index_create_latency_ok | N/A |
108+
| Metric | Labels |
109+
|--------|--------|
110+
| receiver_refused_spans | receiver, service_instance_id, service_name, service_version, transport |
111+
| target_info | service_instance_id, service_name, service_version |
112+
113+
## OpenSearch Storage Metrics
114+
115+
### OPENSEARCH METRICS
116+
### Combined Metrics
117+
| Metric | Labels |
118+
|--------|--------|
119+
| jaeger_bulk_index_attempts_total | N/A |
120+
| jaeger_bulk_index_errors_total | N/A |
121+
| jaeger_bulk_index_inserts_total | N/A |
122+
| jaeger_bulk_index_latency_err | N/A |
123+
| jaeger_bulk_index_latency_ok | N/A |
124+
| jaeger_index_create_attempts_total | N/A |
125+
| jaeger_index_create_errors_total | N/A |
126+
| jaeger_index_create_inserts_total | N/A |
127+
| jaeger_index_create_latency_err | N/A |
128+
| jaeger_index_create_latency_ok | N/A |
129+
| Metric | Labels |
130+
|--------|--------|
131+
| receiver_refused_spans | receiver, service_instance_id, service_name, service_version, transport |
132+
| target_info | service_instance_id, service_name, service_version |
133+

‎scripts/fetch_metrics_reference.py‎

Lines changed: 145 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,145 @@
1+
#!/usr/bin/env python3
2+
3+
# Copyright (c) 2024 The Jaeger Authors.
4+
# SPDX-License-Identifier: Apache-2.0
5+
6+
# This script fetches the auto-generated metrics reports from the jaegertracing/jaeger
7+
# repository and compiles a reference page of current Jaeger v2 metrics.
8+
# The purpose is to track BACKWARDS COMPATIBILITY of metrics across Jaeger v2 releases.
9+
10+
import logging
11+
import os
12+
import sys
13+
import urllib.error
14+
import urllib.request
15+
16+
# Set up logging
17+
logging.basicConfig(level=logging.INFO)
18+
logger = logging.getLogger(__name__)
19+
20+
# Base URL for the raw markdown files generated by the jaeger E2E workflow
21+
BASE_RAW_URL = "https://raw.githubusercontent.com/jaegertracing/jaeger/main/cmd/jaeger/docs/migration/"
22+
23+
TARGET_FILES = [
24+
{"filename": "all-in-one-metrics.md", "title": "All-in-One Component"},
25+
{"filename": "badger-metrics.md", "title": "Badger Storage"},
26+
{"filename": "cassandra-metrics.md", "title": "Cassandra Storage"},
27+
{"filename": "elasticsearch-metrics.md", "title": "Elasticsearch Storage"},
28+
{"filename": "opensearch-metrics.md", "title": "OpenSearch Storage"},
29+
]
30+
31+
32+
def fetch_markdown(filename):
33+
url = BASE_RAW_URL + filename
34+
req = urllib.request.Request(url)
35+
try:
36+
with urllib.request.urlopen(req, timeout=10) as response:
37+
return response.read().decode("utf-8")
38+
except urllib.error.HTTPError as e:
39+
logger.error(f"HTTP Error fetching {filename}: {e.code} {e.reason}")
40+
return None
41+
except Exception as e:
42+
logger.error(f"Error fetching {filename}: {e}")
43+
return None
44+
45+
46+
def extract_v2_metrics_table(raw_md):
47+
"""Parse the raw markdown and return a new table with only v2 Metric + v2 Labels columns.
48+
49+
The source files have 4 columns: V1 Metric | V1 Labels | V2 Metric | V2 Labels.
50+
We extract only the columns that matter for v2 backwards-compatibility tracking,
51+
dropping rows where V2 Metric is N/A (metric was removed in v2).
52+
"""
53+
output_lines = []
54+
in_table = False
55+
56+
for line in raw_md.split("\n"):
57+
stripped = line.strip()
58+
59+
# Detect the start of a 4-column metrics table (V1 Metric header)
60+
if "V1 Metric" in stripped and "V2 Metric" in stripped:
61+
in_table = True
62+
# Emit the new v2-only header
63+
output_lines.append("| Metric | Labels |")
64+
output_lines.append("|--------|--------|")
65+
continue
66+
67+
# Skip the separator row (|---|---|...)
68+
if in_table and set(stripped.replace("|", "").replace("-", "").strip()) == set():
69+
continue
70+
71+
if in_table and stripped.startswith("|"):
72+
cols = [c.strip() for c in stripped.split("|")]
73+
# cols[0] is empty, cols[1]=V1 Metric, cols[2]=V1 Labels, cols[3]=V2 Metric, cols[4]=V2 Labels
74+
if len(cols) >= 5:
75+
v2_metric = cols[3]
76+
v2_labels = cols[4]
77+
# Skip metrics that don't exist in v2
78+
if v2_metric and v2_metric.lower() != "n/a":
79+
output_lines.append(f"| {v2_metric} | {v2_labels} |")
80+
elif in_table and stripped == "":
81+
in_table = False
82+
output_lines.append("")
83+
elif not in_table:
84+
# Carry over subsection headings, but downgrade H1 to H3
85+
if stripped.startswith("# ") or (stripped.startswith("#") and not stripped.startswith("##")):
86+
output_lines.append("### " + stripped.lstrip("#").strip())
87+
elif stripped.startswith("##"):
88+
output_lines.append(stripped)
89+
90+
return "\n".join(output_lines)
91+
92+
93+
def generate_metrics_reference():
94+
content = "---\n"
95+
content += "title: Metrics Reference (v2)\n"
96+
content += "type: docs\n"
97+
content += "weight: 80\n"
98+
content += "---\n\n"
99+
content += (
100+
"This page lists all metrics currently exposed by Jaeger v2. "
101+
"These metrics are automatically tracked by the Jaeger CI pipeline to ensure "
102+
"**backwards compatibility across Jaeger v2 releases** — i.e. that metric names and labels "
103+
"do not change unexpectedly between v2 versions.\n\n"
104+
)
105+
106+
missing_files = False
107+
108+
for item in TARGET_FILES:
109+
logger.info(f"Fetching {item['filename']}...")
110+
raw_md = fetch_markdown(item["filename"])
111+
if raw_md:
112+
v2_table = extract_v2_metrics_table(raw_md)
113+
content += f"## {item['title']} Metrics\n\n"
114+
content += v2_table.strip() + "\n\n"
115+
else:
116+
logger.warning(f"Skipping {item['filename']} due to fetch failure.")
117+
missing_files = True
118+
119+
return content, missing_files
120+
121+
122+
def save_metrics_reference(content):
123+
target_path = "content/docs/v2/_dev/operations/metrics-reference.md"
124+
os.makedirs(os.path.dirname(target_path), exist_ok=True)
125+
with open(target_path, "w", encoding="utf-8") as f:
126+
f.write(content)
127+
logger.info(f"Successfully saved metrics reference to {target_path}")
128+
129+
130+
def main():
131+
try:
132+
content, missing_files = generate_metrics_reference()
133+
save_metrics_reference(content)
134+
135+
if missing_files:
136+
logger.error("Failed to fetch one or more metrics files. The generated page may be incomplete.")
137+
sys.exit(1)
138+
139+
except Exception as e:
140+
logger.error(f"An error occurred: {e}")
141+
sys.exit(1)
142+
143+
144+
if __name__ == "__main__":
145+
main()

0 commit comments

Comments
 (0)