prometheus / prometheus/client_python
OpenMetrics content negotiation: `escaping=underscores` causes name mismatch between `HELP/TYPE` metadata and sample lines for metrics with colons
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 4.4k
- Forks
- 876
- Avg merge
- 8d 4h
- Merged PRs (30d)
- 1
Description
Description
When exposing metrics in the OpenMetrics format using content negotiation (via Accept: application/openmetrics-text; version=1.0.0), metrics containing colons (:) have their names escaped in the sample lines but remain unescaped in the # HELP and # TYPE lines.
This produces mismatched exposition output that violates the OpenMetrics standard, causing strict standard parsers (including promtool check metrics and downstream ingesters) to fail or treat them as completely separate metrics (an orphaned metadata set and an untyped metric).
Steps to Reproduce
- Create a simple Python server using
prometheus_client:
from http.server import BaseHTTPRequestHandler, HTTPServer
from prometheus_client import CollectorRegistry, Gauge
from prometheus_client.exposition import choose_encoder
registry = CollectorRegistry()
token_usage = Gauge(
name="sglang:token_usage",
documentation="Total token usage.",
registry=registry,
)
token_usage.set(42.0)
class MetricsHandler(BaseHTTPRequestHandler):
def do_GET(self):
if self.path == "/metrics":
accept_header = self.headers.get("Accept", "")
encoder, content_type = choose_encoder(accept_header)
data = encoder(registry)
self.send_response(200)
self.send_header("Content-Type", content_type)
self.end_headers()
self.wfile.write(data)
if __name__ == "__main__":
server = HTTPServer(("0.0.0.0", 8000), MetricsHandler)
server.serve_forever()
- Query the endpoint requesting OpenMetrics formatting:
curl -i -H "Accept: application/openmetrics-text; version=1.0.0" http://localhost:8000/metrics
Actual Output
Notice that the Content-Type is negotiated with escaping=underscores, but the comment lines mismatch the sample line:
HTTP/1.0 200 OK
Content-Type: application/openmetrics-text; version=1.0.0; charset=utf-8; escaping=underscores
# HELP sglang:token_usage Total token usage.
# TYPE sglang:token_usage gauge
sglang_token_usage 42.0
# EOF
Expected Output
The metric name inside the # HELP and # TYPE comment blocks should match the name used in the sample line:
# HELP sglang_token_usage Total token usage.
# TYPE sglang_token_usage gauge
sglang_token_usage 42.0
# EOF
Root Cause
In prometheus_client/openmetrics/exposition.py:
- The comment generator uses the unescaped
metric.namedirectly (since a colon is treated as legacy-valid under default validation checks). - The sample line generator, however, strictly sanitizes the sample's name against the narrower OpenMetrics name requirements, replacing the colon with an underscore under
escaping=underscores.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start in prometheus_client/openmetrics/exposition.py and trace how metric names are produced for HELP/TYPE comments versus sample lines when escaping=underscores is negotiated. Add coverage for a metric name containing a colon and verify the OpenMetrics output uses matching names and remains valid for strict parsers.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- observability
- Issue type
- Bug
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Quiet
- Clarity
- Clearly specified
- Newbie friendliness
- 70/100