prometheus / prometheus/client_python

OpenMetrics content negotiation: `escaping=underscores` causes name mismatch between `HELP/TYPE` metadata and sample lines for metrics with colons

Open Beginner friendly
#1,177 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

bug
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
  1. 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()
  1. 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.name directly (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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.