Files
kumomta/docs/update-metrics.py
Wez Furlong 41291a4afb docs: mark generated pages with an @generated marker
The documentation generators now stamp each page they emit with an
@generated comment so that tooling can tell generated pages apart from
hand-written ones. Update the table-of-contents generator to skip YAML
front matter when picking a page title, since the marker is now stored
there.
2026-10-05 13:22:26 +01:00

108 lines
4.5 KiB
Python
Executable File

#!/usr/bin/env python3
import json
import os
import sys
import textwrap
# Split the marker token across two literals. One literal here would make
# tooling treat this script as a generated file.
GENERATED = "@" + "generated"
def generated_comment(tool, source):
"""Return an HTML comment marking a page as generated by tool from source."""
return f"<!-- {GENERATED} by {tool} from {source} -->\n"
def admonition(kind, body):
"""Format body as an mkdocs admonition of the given kind, wrapped to 80
columns. body must be a single paragraph; any newline within it is
collapsed to a space by the wrap."""
lines = textwrap.wrap(
body, width=80, initial_indent=" ", subsequent_indent=" "
)
return "\n!!! {}\n{}\n".format(kind, "\n".join(lines))
def metrics(service):
source = f"docs/reference/{service}-metrics.json"
with open(source) as f:
metrics = json.load(f)
os.makedirs(f"docs/reference/metrics/{service}", exist_ok=True)
def add_period(s):
if not s.endswith("."):
return f"{s}."
return s
for m in metrics:
name = m["name"]
help = add_period(m["help"])
doc = m["doc"]
mt = m["metric_type"]
labels = m["label_names"]
buckets = m["buckets"]
pruning = m["pruning"] == "Pruning"
with open(f"docs/reference/metrics/{service}/{name}.md", "w") as output:
output.write(generated_comment("docs/update-metrics.py", source))
output.write(f"# {name}\n\n")
output.write("```\n")
output.write(f"Type: {mt}\n")
if len(labels) > 0:
output.write(f"Labels: {', '.join(labels)}\n")
if len(buckets) > 0:
output.write(f"Buckets: {', '.join(str(b) for b in buckets)}\n")
output.write("```\n")
output.write(f"{help}\n\n")
if pruning:
output.write(
admonition(
"note",
"This metric is subject to *pruning*, which means that it may age out and reset to zero when the corresponding internal resources idle out or age out of the system. This is a memory management measure to prevent unbounded growth of memory over time.",
)
)
if len(labels) > 0:
output.write(
admonition(
"info",
"This metric has labels, which means that the system will track the metric for each combination of the possible labels that are active. Certain labels, especially those that correlate with source or destination addresses or domains, can have high cardinality. High cardinality metrics may require some care and attention when provisioning a downstream metrics server.",
)
)
if doc:
output.write(f"\n{doc}\n\n")
if len(buckets) > 0:
output.write("\n## Histogram\n")
output.write(
"This metric is a histogram which means that it is exported as three underlying metrics:\n\n"
)
output.write(
f" * `{name}_count` - a counter tracking how many events have been accumulated into the histogram\n"
)
output.write(
f" * `{name}_sum` - a counter tracking the total value of all of the events have been accumulated into the histogram\n"
)
output.write(
f' * `{name}_bucket` - a counter tracking the number of events that fall within the various buckets shown above. This counter has an additional `le` label that indicates the bucket threshold. For example, the first bucket for this histogram will generate a label `le="{buckets[0]}"` which will keep track of the number of events whose value was *less-or-equal* (le) that value.\n'
)
output.write(
f"\nThe recommended visualization for a histogram is a heatmap based on `{name}_bucket`.\n"
)
output.write(
f"\nWhile it is possible to calculate a mean average for `{name}` by computing `{name}_sum / {name}_count`, it can be difficult to reason about what that value means if the traffic patterns are not uniform since the launch of the process. We strongly recommend using a heatmap visualization instead of computing an average value.\n"
)
metrics("kumod")
metrics("proxy-server")