prometheus / prometheus/client_python

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

Abierto Apto para principiantes
#1,177 1 comentario 0 reacciones 0 asignados Ver en GitHub

Nadie ha tomado este issue todavía.

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

Guía de contribución

Abrir la guía de contribución

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. 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

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.