prometheus / prometheus/client_python
OpenMetrics content negotiation: `escaping=underscores` causes name mismatch between `HELP/TYPE` metadata and sample lines for metrics with colons
Nadie ha tomado este issue todavía.
- Lenguaje dominante
- Python
- Estrellas
- 4.4k
- Forks
- 876
- Merge medio
- 8 d 4 h
- PR fusionados (30 d)
- 1
Descripción
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.
Guía de contribución
Primeros pasos
- Lee el issue completo y luego la guía de contribución del proyecto.
- Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
- Haz un fork del repositorio y trabaja en una rama.
- Abre un pull request que haga referencia al número del issue.
Línea de trabajo
Comienza en prometheus_client/openmetrics/exposition.py y sigue cómo se generan los nombres de las métricas para los comentarios HELP/TYPE frente a las líneas de muestras cuando se negocia escaping=underscores. Añade cobertura para un nombre de métrica que contenga dos puntos y verifica que la salida de OpenMetrics use nombres coincidentes y siga siendo válida para analizadores estrictos.
Escrito por el modelo de indexación a partir del texto del issue.
Evaluación
- Stack tecnológico
- python
- Área
- observability
- Tipo de issue
- Error
- Dificultad
- 2/5
- Tiempo estimado
- 1-3 horas
- Estado de actividad
- Tranquilo
- Claridad
- Bien especificado
- Aptitud para principiantes
- 70/100